Debian Codegraph @

docs/ref/models/meta.txt

raw
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>]