| 1 |
=================== |
| 2 |
Model ``_meta`` API |
| 3 |
=================== |
| 4 |
|
| 5 |
.. module:: django.db.models.options |
| 6 |
:synopsis: Model meta-class layer |
| 7 |
|
| 8 |
.. class:: Options |
| 9 |
|
| 10 |
The model ``_meta`` API is at the core of the Django ORM. It enables other |
| 11 |
parts of the system such as lookups, queries, forms, and the admin to |
| 12 |
understand the capabilities of each model. The API is accessible through |
| 13 |
the ``_meta`` attribute of each model class, which is an instance of an |
| 14 |
``django.db.models.options.Options`` object. |
| 15 |
|
| 16 |
Methods and attributes that it provides can be used to: |
| 17 |
|
| 18 |
* Retrieve all field instances of a model |
| 19 |
* Retrieve a single field instance of a model by name |
| 20 |
* Retrieve all fields that compose the primary key of a model |
| 21 |
|
| 22 |
.. _model-meta-field-api: |
| 23 |
|
| 24 |
Field access API |
| 25 |
================ |
| 26 |
|
| 27 |
Retrieving a single field instance of a model by name |
| 28 |
----------------------------------------------------- |
| 29 |
|
| 30 |
.. method:: Options.get_field(field_name) |
| 31 |
|
| 32 |
Returns the field instance given a name of a field. |
| 33 |
|
| 34 |
``field_name`` can be the name of a field on the model, a field |
| 35 |
on an abstract or inherited model, or a field defined on another |
| 36 |
model that points to the model. In the latter case, the ``field_name`` |
| 37 |
will be (in order of preference) the :attr:`~.ForeignKey.related_query_name` |
| 38 |
set by the user, the :attr:`~.ForeignKey.related_name` set by the user, or |
| 39 |
the name automatically generated by Django. |
| 40 |
|
| 41 |
:attr:`Hidden fields <django.db.models.Field.hidden>` cannot be retrieved |
| 42 |
by name. |
| 43 |
|
| 44 |
If a field with the given name is not found a |
| 45 |
:class:`~django.core.exceptions.FieldDoesNotExist` exception will be |
| 46 |
raised. |
| 47 |
|
| 48 |
.. code-block:: pycon |
| 49 |
|
| 50 |
>>> from django.contrib.auth.models import User |
| 51 |
|
| 52 |
# A field on the model |
| 53 |
>>> User._meta.get_field("username") |
| 54 |
<django.db.models.fields.CharField: username> |
| 55 |
|
| 56 |
# A field from another model that has a relation with the current model |
| 57 |
>>> User._meta.get_field("logentry") |
| 58 |
<ManyToOneRel: admin.logentry> |
| 59 |
|
| 60 |
# A non existent field |
| 61 |
>>> User._meta.get_field("does_not_exist") |
| 62 |
Traceback (most recent call last): |
| 63 |
... |
| 64 |
FieldDoesNotExist: User has no field named 'does_not_exist' |
| 65 |
|
| 66 |
Retrieving all field instances of a model |
| 67 |
----------------------------------------- |
| 68 |
|
| 69 |
.. method:: Options.get_fields(include_parents=True, include_hidden=False) |
| 70 |
|
| 71 |
Returns a tuple of fields associated with a model. ``get_fields()`` accepts |
| 72 |
two parameters that can be used to control which fields are returned: |
| 73 |
|
| 74 |
``include_parents`` |
| 75 |
``True`` by default. Recursively includes fields defined on parent |
| 76 |
classes. If set to ``False``, ``get_fields()`` will only search for |
| 77 |
fields declared directly on the current model. Fields from models that |
| 78 |
directly inherit from abstract models or proxy classes are considered |
| 79 |
to be local, not on the parent. |
| 80 |
|
| 81 |
``include_hidden`` |
| 82 |
``False`` by default. If set to ``True``, ``get_fields()`` will include |
| 83 |
:attr:`hidden fields <django.db.models.Field.hidden>`. |
| 84 |
|
| 85 |
.. code-block:: pycon |
| 86 |
|
| 87 |
>>> from django.contrib.auth.models import User |
| 88 |
>>> User._meta.get_fields() |
| 89 |
(<ManyToOneRel: admin.logentry>, |
| 90 |
<django.db.models.fields.AutoField: id>, |
| 91 |
<django.db.models.fields.CharField: password>, |
| 92 |
<django.db.models.fields.DateTimeField: last_login>, |
| 93 |
<django.db.models.fields.BooleanField: is_superuser>, |
| 94 |
<django.db.models.fields.CharField: username>, |
| 95 |
<django.db.models.fields.CharField: first_name>, |
| 96 |
<django.db.models.fields.CharField: last_name>, |
| 97 |
<django.db.models.fields.EmailField: email>, |
| 98 |
<django.db.models.fields.BooleanField: is_staff>, |
| 99 |
<django.db.models.fields.BooleanField: is_active>, |
| 100 |
<django.db.models.fields.DateTimeField: date_joined>, |
| 101 |
<django.db.models.fields.related.ManyToManyField: groups>, |
| 102 |
<django.db.models.fields.related.ManyToManyField: user_permissions>) |
| 103 |
|
| 104 |
# Also include hidden fields. |
| 105 |
>>> User._meta.get_fields(include_hidden=True) |
| 106 |
(<ManyToOneRel: auth.user_groups>, |
| 107 |
<ManyToOneRel: auth.user_user_permissions>, |
| 108 |
<ManyToOneRel: admin.logentry>, |
| 109 |
<django.db.models.fields.AutoField: id>, |
| 110 |
<django.db.models.fields.CharField: password>, |
| 111 |
<django.db.models.fields.DateTimeField: last_login>, |
| 112 |
<django.db.models.fields.BooleanField: is_superuser>, |
| 113 |
<django.db.models.fields.CharField: username>, |
| 114 |
<django.db.models.fields.CharField: first_name>, |
| 115 |
<django.db.models.fields.CharField: last_name>, |
| 116 |
<django.db.models.fields.EmailField: email>, |
| 117 |
<django.db.models.fields.BooleanField: is_staff>, |
| 118 |
<django.db.models.fields.BooleanField: is_active>, |
| 119 |
<django.db.models.fields.DateTimeField: date_joined>, |
| 120 |
<django.db.models.fields.related.ManyToManyField: groups>, |
| 121 |
<django.db.models.fields.related.ManyToManyField: user_permissions>) |
| 122 |
|
| 123 |
Retrieving fields composing the primary key of a model |
| 124 |
------------------------------------------------------ |
| 125 |
|
| 126 |
.. versionadded:: 5.2 |
| 127 |
|
| 128 |
.. attribute:: Options.pk_fields |
| 129 |
|
| 130 |
Returns a list of the fields composing the primary key of a model. |
| 131 |
|
| 132 |
When a :class:`composite primary key <django.db.models.CompositePrimaryKey>` |
| 133 |
is defined on a model it will contain all the |
| 134 |
:class:`fields <django.db.models.Field>` referenced by it. |
| 135 |
|
| 136 |
.. code-block:: python |
| 137 |
|
| 138 |
from django.db import models |
| 139 |
|
| 140 |
|
| 141 |
class TenantUser(models.Model): |
| 142 |
pk = models.CompositePrimaryKey("tenant_id", "id") |
| 143 |
tenant_id = models.IntegerField() |
| 144 |
id = models.IntegerField() |
| 145 |
|
| 146 |
.. code-block:: pycon |
| 147 |
|
| 148 |
>>> TenantUser._meta.pk_fields |
| 149 |
[ |
| 150 |
<django.db.models.fields.IntegerField: tenant_id>, |
| 151 |
<django.db.models.fields.IntegerField: id> |
| 152 |
] |
| 153 |
|
| 154 |
Otherwise it will contain the single field declared as the |
| 155 |
:attr:`primary key <django.db.models.Field.primary_key>` of the model. |
| 156 |
|
| 157 |
.. code-block:: pycon |
| 158 |
|
| 159 |
>>> User._meta.pk_fields |
| 160 |
[<django.db.models.fields.AutoField: id>] |