mirror of
https://github.com/django/django.git
synced 2025-10-30 17:16:10 +00:00
159 lines
6.0 KiB
Plaintext
159 lines
6.0 KiB
Plaintext
===================
|
|
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
|
|
------------------------------------------------------
|
|
|
|
.. 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>]
|