Arthur de Jong

Open Source / Free Software developer

summaryrefslogtreecommitdiffstats
path: root/docs/ref/models/meta.txt
blob: 47e47e2c8fee93d0f72cdb22c0351d25c6cf78a9 (plain)
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
===================
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 that it provides can be used to:

* Retrieve all field instances of a model
* Retrieve a single field instance of a model by name

.. _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 the ``related_name`` defined by the user or the name automatically
    generated by Django itself.

    :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:: python

        >>> 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
        fields that are used to back other field's functionality. This will
        also include any fields that have a ``related_name`` (such
        as :class:`~django.db.models.ManyToManyField`, or
        :class:`~django.db.models.ForeignKey`) that start with a "+".

    .. code-block:: python

        >>> 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>)

.. _migrating-old-meta-api:

Migrating from the old API
==========================

As part of the formalization of the ``Model._meta`` API (from the
:class:`django.db.models.options.Options` class), a number of methods and
properties have been deprecated and will be removed in Django 1.10.

These old APIs can be replicated by either:

* invoking :meth:`Options.get_field()
  <django.db.models.options.Options.get_field()>`, or;

* invoking :meth:`Options.get_fields()
  <django.db.models.options.Options.get_fields()>` to retrieve a list of all
  fields, and then filtering this list using the :ref:`field attributes
  <model-field-attributes>` that describe (or retrieve, in the case of
  ``_with_model`` variants) the properties of the desired fields.

Although it's possible to make strictly equivalent replacements of the old
methods, that might not be the best approach. Taking the time to refactor any
field loops to make better use of the new API - and possibly include fields
that were previously excluded - will almost certainly result in better code.

Assuming you have a model named ``MyModel``, the following substitutions
can be made to convert your code to the new API:

* ``MyModel._meta.get_field(name)``::

      f = MyModel._meta.get_field(name)

  then check if:

  - ``f.auto_created == False``, because the new ``get_field()``
    API will find "reverse" relations), and:

  - ``f.is_relation and f.related_model is None``, because the new
    ``get_field()`` API will find
    :class:`~django.contrib.contenttypes.fields.GenericForeignKey` relations;

* ``MyModel._meta.get_field_by_name(name)``:

  ``get_field_by_name()`` returned four values:
  ``(field, model, direct,  m2m)``:

  - ``field`` can be found by ``MyModel._meta.get_field(name)``

  - ``model`` can be found through the
    :attr:`~django.db.models.Field.model` attribute on the field.

  - ``direct`` can be found by: ``not field.auto_created or field.concrete``

    The :attr:`~django.db.models.Field.auto_created` check excludes
    all "forward" and "reverse" relations that are created by Django, but
    this also includes ``AutoField`` and ``OneToOneField`` on proxy models.
    We avoid filtering out these attributes using the
    :attr:`concrete <django.db.models.Field.concrete>` attribute.

  - ``m2m`` can be found through the
    :attr:`~django.db.models.Field.many_to_many` attribute on the field.

* ``MyModel._meta.get_fields_with_model()``::

      [
          (f, f.model if f.model != MyModel else None)
          for f in MyModel._meta.get_fields()
          if not f.is_relation
              or f.one_to_one
              or (f.many_to_one and f.related_model)
      ]

* ``MyModel._meta.get_concrete_fields_with_model()``::

      [
          (f, f.model if f.model != MyModel else None)
          for f in MyModel._meta.get_fields()
          if f.concrete and (
              not f.is_relation
              or f.one_to_one
              or (f.many_to_one and f.related_model)
          )
      ]

* ``MyModel._meta.get_m2m_with_model()``::

      [
          (f, f.model if f.model != MyModel else None)
          for f in MyModel._meta.get_fields()
          if f.many_to_many and not f.auto_created
      ]

* ``MyModel._meta.get_all_related_objects()``::

      [
          f for f in MyModel._meta.get_fields()
          if (f.one_to_many or f.one_to_one) and f.auto_created
      ]

* ``MyModel._meta.get_all_related_objects_with_model()``::

      [
          (f, f.model if f.model != MyModel else None)
          for f in MyModel._meta.get_fields()
          if (f.one_to_many or f.one_to_one) and f.auto_created
      ]

* ``MyModel._meta.get_all_related_many_to_many_objects()``::

      [
          f for f in MyModel._meta.get_fields(include_hidden=True)
          if f.many_to_many and f.auto_created
      ]

* ``MyModel._meta.get_all_related_m2m_objects_with_model()``::

      [
          (f, f.model if f.model != MyModel else None)
          for f in MyModel._meta.get_fields(include_hidden=True)
          if f.many_to_many and f.auto_created
      ]

* ``MyModel._meta.get_all_field_names()``::

      from itertools import chain
      list(set(chain.from_iterable(
          (field.name, field.attname) if hasattr(field, 'attname') else (field.name,)
          for field in MyModel._meta.get_fields()
          # For complete backwards compatibility, you may want to exclude
          # GenericForeignKey from the results.
          if not (field.many_to_one and field.related_model is None)
      )))

  This provides a 100% backwards compatible replacement, ensuring that both
  field names and attribute names ``ForeignKey``\s are included, but fields
  associated with ``GenericForeignKey``\s are not. A simpler version would be::

      [f.name for f in MyModel._meta.get_fields()]

  While this isn't 100% backwards compatible, it may be sufficient in many
  situations.