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