Model _meta API

• class Options[source]
• The model _meta API is at the core of the Django ORM. It enables otherparts of the system such as lookups, queries, forms, and the admin tounderstand the capabilities of each model. The API is accessible throughthe _meta attribute of each model class, which is an instance of andjango.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

Field access API

Retrieving a single field instance of a model by name

• Options.getfield(_field_name)[source]
• Returns the field instance given a name of a field.

field_name can be the name of a field on the model, a fieldon an abstract or inherited model, or a field defined on anothermodel that points to the model. In the latter case, the field_namewill be the related_name defined by the user or the name automaticallygenerated by Django itself.

Hidden fields cannot be retrievedby name.

If a field with the given name is not found aFieldDoesNotExist exception will beraised.

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

• Options.getfields(_include_parents=True, include_hidden=False)[source]

• Returns a tuple of fields associated with a model. get_fields() acceptstwo parameters that can be used to control which fields are returned:

  • include_parents
  • True by default. Recursively includes fields defined on parentclasses. If set to False, get_fields() will only search forfields declared directly on the current model. Fields from models thatdirectly inherit from abstract models or proxy classes are consideredto be local, not on the parent.
  • include_hidden
  • False by default. If set to True, get_fields() will includefields that are used to back other field's functionality. This willalso include any fields that have a related_name (suchas ManyToManyField, orForeignKey) that start with a "+".

>>> 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 from the old API

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

These old APIs can be replicated by either:

• invoking Options.get_field(), or;
• invoking Options.get_fields() to retrieve a list of allfields, and then filtering this list using the 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 oldmethods, that might not be the best approach. Taking the time to refactor anyfield loops to make better use of the new API - and possibly include fieldsthat were previously excluded - will almost certainly result in better code.

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

• MyModel._meta.get_field(name) becomes:

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 newget_field() API will findGenericForeignKey relations.

  • MyModel._meta.get_field_by_name(name) returns a tuple of these fourvalues with the following replacements:

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

• model can be found through themodel attribute on the field.

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

The auto_created check excludesall "forward" and "reverse" relations that are created by Django, butthis also includes AutoField and OneToOneField on proxy models.We avoid filtering out these attributes using theconcrete attribute.

• m2m can be found through themany_to_many attribute on the field.

• MyModel._meta.get_fields_with_model() becomes:

[
    (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() becomes:

[
    (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() becomes:

[
    (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() becomes:

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

• MyModel._meta.get_all_related_objects_with_model() becomes:

[
    (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 and not f.concrete
]

• MyModel._meta.get_all_related_many_to_many_objects() becomes:

[
    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() becomes:

[
    (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() becomes:

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 bothfield names and attribute names ForeignKeys are included, but fieldsassociated with GenericForeignKeys 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 manysituations.