<commit_before>======
Models
======

.. module:: django.db.models

A model is the single, definitive source of data about your data. It contains
the essential fields and behaviors of the data you're storing. Generally, each
model maps to a single database table.

The basics:

* Each model is a Python class that subclasses
  :class:`django.db.models.Model`.

* Each attribute of the model represents a database field.

* With all of this, Django gives you an automatically-generated
  database-access API; see :doc:`/topics/db/queries`.


Quick example
=============

This example model defines a ``Person``, which has a ``first_name`` and
``last_name``::

    from django.db import models

    class Person(models.Model):
        first_name = models.CharField(max_length=30)
        last_name = models.CharField(max_length=30)

``first_name`` and ``last_name`` are fields_ of the model. Each field is
specified as a class attribute, and each attribute maps to a database column.

The above ``Person`` model would create a database table like this:

.. code-block:: sql

    CREATE TABLE myapp_person (
        "id" serial NOT NULL PRIMARY KEY,
        "first_name" varchar(30) NOT NULL,
        "last_name" varchar(30) NOT NULL
    );

Some technical notes:

* The name of the table, ``myapp_person``, is automatically derived from
  some model metadata but can be overridden. See :ref:`table-names` for more
  details..

* An ``id`` field is added automatically, but this behavior can be
  overridden. See :ref:`automatic-primary-key-fields`.

* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
  syntax, but it's worth noting Django uses SQL tailored to the database
  backend specified in your :doc:`settings file </topics/settings>`.

Using models
============

Once you have defined your models, you need to tell Django you're going to *use*
those models. Do this by editing your settings file and changing the
:setting:`INSTALLED_APPS` setting to add the name of the module that contains
your ``models.py``.

For example, if the models for your application live in the module
``mysite.myapp.models`` (the package structure that is created for an
application by the :djadmin:`manage.py startapp <startapp>` script),
:setting:`INSTALLED_APPS` should read, in part::

    INSTALLED_APPS = (
        #...
        'mysite.myapp',
        #...
    )

When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
:djadmin:`manage.py syncdb <syncdb>`.

Fields
======

The most important part of a model -- and the only required part of a model --
is the list of database fields it defines. Fields are specified by class
attributes.

Example::

    class Musician(models.Model):
        first_name = models.CharField(max_length=50)
        last_name = models.CharField(max_length=50)
        instrument = models.CharField(max_length=100)

    class Album(models.Model):
        artist = models.ForeignKey(Musician)
        name = models.CharField(max_length=100)
        release_date = models.DateField()
        num_stars = models.IntegerField()

Field types
-----------

Each field in your model should be an instance of the appropriate
:class:`~django.db.models.Field` class. Django uses the field class types to
determine a few things:

* The database column type (e.g. ``INTEGER``, ``VARCHAR``).

* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form
  field (e.g. ``<input type="text">``, ``<select>``).

* The minimal validation requirements, used in Django's admin and in<commit_msg>Fixed #16588 - Warned about field names that conflict with the model API<commit_after>======
Models
======

.. module:: django.db.models

A model is the single, definitive source of data about your data. It contains
the essential fields and behaviors of the data you're storing. Generally, each
model maps to a single database table.

The basics:

* Each model is a Python class that subclasses
  :class:`django.db.models.Model`.

* Each attribute of the model represents a database field.

* With all of this, Django gives you an automatically-generated
  database-access API; see :doc:`/topics/db/queries`.


Quick example
=============

This example model defines a ``Person``, which has a ``first_name`` and
``last_name``::

    from django.db import models

    class Person(models.Model):
        first_name = models.CharField(max_length=30)
        last_name = models.CharField(max_length=30)

``first_name`` and ``last_name`` are fields_ of the model. Each field is
specified as a class attribute, and each attribute maps to a database column.

The above ``Person`` model would create a database table like this:

.. code-block:: sql

    CREATE TABLE myapp_person (
        "id" serial NOT NULL PRIMARY KEY,
        "first_name" varchar(30) NOT NULL,
        "last_name" varchar(30) NOT NULL
    );

Some technical notes:

* The name of the table, ``myapp_person``, is automatically derived from
  some model metadata but can be overridden. See :ref:`table-names` for more
  details..

* An ``id`` field is added automatically, but this behavior can be
  overridden. See :ref:`automatic-primary-key-fields`.

* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
  syntax, but it's worth noting Django uses SQL tailored to the database
  backend specified in your :doc:`settings file </topics/settings>`.

Using models
============

Once you have defined your models, you need to tell Django you're going to *use*
those models. Do this by editing your settings file and changing the
:setting:`INSTALLED_APPS` setting to add the name of the module that contains
your ``models.py``.

For example, if the models for your application live in the module
``mysite.myapp.models`` (the package structure that is created for an
application by the :djadmin:`manage.py startapp <startapp>` script),
:setting:`INSTALLED_APPS` should read, in part::

    INSTALLED_APPS = (
        #...
        'mysite.myapp',
        #...
    )

When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
:djadmin:`manage.py syncdb <syncdb>`.

Fields
======

The most important part of a model -- and the only required part of a model --
is the list of database fields it defines. Fields are specified by class
attributes. Be careful not to choose field names that conflict with the
:doc:`models API </ref/models/instances>` like ``clean``, ``save``, or
``delete``.

Example::

    class Musician(models.Model):
        first_name = models.CharField(max_length=50)
        last_name = models.CharField(max_length=50)
        instrument = models.CharField(max_length=100)

    class Album(models.Model):
        artist = models.ForeignKey(Musician)
        name = models.CharField(max_length=100)
        release_date = models.DateField()
        num_stars = models.IntegerField()

Field types
-----------

Each field in your model should be an instance of the appropriate
:class:`~django.db.models.Field` class. Django uses the field class types to
determine a few things:

* The database column type (e.g. ``INTEGER``, ``VARCHAR``).

* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form
  field (e.g. ``<input type="text">``, ``<select>``).

* The minimal validation requirements, used in Django's admin and in
{'fraction_non_alphanumeric': 0.10815262146582487, 'fraction_numerical': 0.005627230304693934, 'mean_word_length': 3.7783606557377047, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 16, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6311821', 'n_tokens_mistral': 2133, 'n_tokens_neox': 2018, 'n_words': 861}