2
0

meta.txt 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120
  1. ===================
  2. Model ``_meta`` API
  3. ===================
  4. .. module:: django.db.models.options
  5. :synopsis: Model meta-class layer
  6. .. class:: Options
  7. The model ``_meta`` API is at the core of the Django ORM. It enables other
  8. parts of the system such as lookups, queries, forms, and the admin to
  9. understand the capabilities of each model. The API is accessible through
  10. the ``_meta`` attribute of each model class, which is an instance of an
  11. ``django.db.models.options.Options`` object.
  12. Methods that it provides can be used to:
  13. * Retrieve all field instances of a model
  14. * Retrieve a single field instance of a model by name
  15. .. _model-meta-field-api:
  16. Field access API
  17. ================
  18. Retrieving a single field instance of a model by name
  19. -----------------------------------------------------
  20. .. method:: Options.get_field(field_name)
  21. Returns the field instance given a name of a field.
  22. ``field_name`` can be the name of a field on the model, a field
  23. on an abstract or inherited model, or a field defined on another
  24. model that points to the model. In the latter case, the ``field_name``
  25. will be (in order of preference) the :attr:`~.ForeignKey.related_query_name`
  26. set by the user, the :attr:`~.ForeignKey.related_name` set by the user, or
  27. the name automatically generated by Django.
  28. :attr:`Hidden fields <django.db.models.Field.hidden>` cannot be retrieved
  29. by name.
  30. If a field with the given name is not found a
  31. :class:`~django.core.exceptions.FieldDoesNotExist` exception will be
  32. raised.
  33. .. code-block:: pycon
  34. >>> from django.contrib.auth.models import User
  35. # A field on the model
  36. >>> User._meta.get_field("username")
  37. <django.db.models.fields.CharField: username>
  38. # A field from another model that has a relation with the current model
  39. >>> User._meta.get_field("logentry")
  40. <ManyToOneRel: admin.logentry>
  41. # A non existent field
  42. >>> User._meta.get_field("does_not_exist")
  43. Traceback (most recent call last):
  44. ...
  45. FieldDoesNotExist: User has no field named 'does_not_exist'
  46. Retrieving all field instances of a model
  47. -----------------------------------------
  48. .. method:: Options.get_fields(include_parents=True, include_hidden=False)
  49. Returns a tuple of fields associated with a model. ``get_fields()`` accepts
  50. two parameters that can be used to control which fields are returned:
  51. ``include_parents``
  52. ``True`` by default. Recursively includes fields defined on parent
  53. classes. If set to ``False``, ``get_fields()`` will only search for
  54. fields declared directly on the current model. Fields from models that
  55. directly inherit from abstract models or proxy classes are considered
  56. to be local, not on the parent.
  57. ``include_hidden``
  58. ``False`` by default. If set to ``True``, ``get_fields()`` will include
  59. :attr:`hidden fields <django.db.models.Field.hidden>`.
  60. .. code-block:: pycon
  61. >>> from django.contrib.auth.models import User
  62. >>> User._meta.get_fields()
  63. (<ManyToOneRel: admin.logentry>,
  64. <django.db.models.fields.AutoField: id>,
  65. <django.db.models.fields.CharField: password>,
  66. <django.db.models.fields.DateTimeField: last_login>,
  67. <django.db.models.fields.BooleanField: is_superuser>,
  68. <django.db.models.fields.CharField: username>,
  69. <django.db.models.fields.CharField: first_name>,
  70. <django.db.models.fields.CharField: last_name>,
  71. <django.db.models.fields.EmailField: email>,
  72. <django.db.models.fields.BooleanField: is_staff>,
  73. <django.db.models.fields.BooleanField: is_active>,
  74. <django.db.models.fields.DateTimeField: date_joined>,
  75. <django.db.models.fields.related.ManyToManyField: groups>,
  76. <django.db.models.fields.related.ManyToManyField: user_permissions>)
  77. # Also include hidden fields.
  78. >>> User._meta.get_fields(include_hidden=True)
  79. (<ManyToOneRel: auth.user_groups>,
  80. <ManyToOneRel: auth.user_user_permissions>,
  81. <ManyToOneRel: admin.logentry>,
  82. <django.db.models.fields.AutoField: id>,
  83. <django.db.models.fields.CharField: password>,
  84. <django.db.models.fields.DateTimeField: last_login>,
  85. <django.db.models.fields.BooleanField: is_superuser>,
  86. <django.db.models.fields.CharField: username>,
  87. <django.db.models.fields.CharField: first_name>,
  88. <django.db.models.fields.CharField: last_name>,
  89. <django.db.models.fields.EmailField: email>,
  90. <django.db.models.fields.BooleanField: is_staff>,
  91. <django.db.models.fields.BooleanField: is_active>,
  92. <django.db.models.fields.DateTimeField: date_joined>,
  93. <django.db.models.fields.related.ManyToManyField: groups>,
  94. <django.db.models.fields.related.ManyToManyField: user_permissions>)