===================

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

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