===============
Model API参考
===============

:作者: Django 团队
:译者: weizhong2004@gmail.com
:翻译开始日期: 2006-04-06
:翻译完成日期: 2006-04-06
:最后修订日期: 2006-05-06
:原文版本: 2800

一个 model 就是一个你要处理的数据的源代码形式表现的原型.
通常,一个 model 对应一个表. (数据库中的表). 它包含你要储存的数据的一些基础字段及其行为.

基本概念:

    * 每个 model 都是一个 ``django.db.models.Model`` 类或它的子类 .
    * model 的每个属性表示一个字段
    * Model 元数据 (非字段信息) 保存在一个名为 ``Meta`` 的内嵌类中.
    * 用于 admin site 的元数据保存在名为 ``Admin`` 的内嵌类中.
    * Django 自动生成一系列数据访问 API, 关于该API的详情,参阅 `Database API reference`_.

本文档的详细解释见 `official repository of model examples`_.

.. _Database API reference: http://www.djangoproject.com/documentation/db_api/
.. _official repository of model examples: http://www.djangoproject.com/documentation/models/

快速示例
=============

本例子中定义了一个 ``Person``, 它拥有一个 ``first_name`` 和一个 ``last_name``::

    from django.db import models

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

``first_name`` 和 ``last_name``  是该 model 的 *字段* .这些字段以类属性的形式定义在 model 中,对应着数据库表的一个列.
上面定义的 ``Person`` 模型会创建下面这样一个 SQL 表::

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

三个技术关注点:

    * 表的名字, ``myapp_person``, 根据某些模型元数据自动生成,也可以被覆盖. 参阅下文中的 _`Table names` .
    * 一个 ``id`` 字段被自动添加到表中, 这个行为也是可以被覆盖的.参阅下文中的 _`Automatic primary key fields` .
    * 这里示例的 ``CREATE TABLE`` 语句是 PostgreSQL 语法格式. Django 会根据 配置文件_ 中定义的后端数据库引擎自动生成合适的SQL语句.
    
.. _配置文件: http://www.djangoproject.com/documentation/settings/

字段
======

一个模型最重要的部分--也是唯一必需的部分--就是定义的数据库字段列表. 字段以类属性的形式定义.

示例::

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

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

字段名限制
-----------------------

Django 对模型的字段名仅有两个小小的限制:

    1. 字段名不能是 Python 保留字, 否则显然会导致 Python 语法错误::

           class Example(models.Model):
               pass = models.IntegerField() # 'pass' is a reserved word!

    2. 字段名中至多只允许有一个下划线, 否则 Django 查询语法就会出错::

           class Example(models.Model):
               foo__bar = models.IntegerField() 'foo__bar' has two underscores!

Django允许模型中使用的字段名可以与数据库中实际使用的不同,因此这些限制其实也不是绝对的.参阅下文中的 `db_column`_ .

SQL 保留字,比如 ``join``, ``where`` 或 ``select``, *都* 允许在模型字段名中使用( Django 在生成SQL语句时会给表名及字段名加上引号,从而保证SQL语句的正确执行).

字段类型
-----------

你的 model 中的每个字段都必须是相关 ``Field`` 类的实例. Django 使用该字段的 class types 来得到以下信息:

    * 数据库的列类型(e.g. ``INTEGER``, ``VARCHAR``).
    * Django 的 admin 要使用的控件类型 (e.g. ``<input type="text">``, ``<select>``).
    * Django 的 admin 及 操纵器(manipulators) 的最低校验要求.

下面列出了所有可用的字段类型:

``AutoField``
    一个 ``IntegerField``, 添加记录时它会自动增长.  你通常不需要直接使用这个字段; 如果你不指定主键的话,系统会自动添加一个主键字段到你的 model.(参阅 _自动主键字段)

``BooleanField``
    A true/false field.
    admin 用 checkbox 来表示此类字段.

``CharField``
    字符串字段, 用于较短的字符串.

    如果要保存大量文本, 使用 ``TextField``.

    admin 用一个 ``<input type="text">`` 来表示此类字段 (单行输入).

    ``CharField`` 要求必须有一个参数 ``maxlength``, 用于从数据库层和Django校验层限制该字段所允许的最大字符数.

``CommaSeparatedIntegerField``
    用于存放逗号分隔的整数值. 类似 ``CharField``, 必须要有 ``maxlength`` 参数.

``DateField``
    一个日期字段. 共有下列额外的可选参数:

        ======================  ===================================================
        Argument                描述
        ======================  ===================================================
        ``auto_now``            当对象被保存时,自动将该字段的值设置为当前时间.通常
                                用于表示 "last-modified" 时间戳.

        ``auto_now_add``        当对象首次被创建时,自动将该字段的值设置为当前时间.通
                                常用于表示对象创建时间.
        ======================  ===================================================

    admin 用一个文本框 ``<input type="text">`` 来表示该字段数据(附带一个 JavaScript
    日历和一个"Today"快键.

``DateTimeField``
     一个日期时间字段. 类似 ``DateField`` 支持同样的附加选项.

    admin 用两上文本框 ``<input type="text">`` 表示该字段顺序(附带JavaScript shortcuts).

``EmailField``
    一个带有检查 Email 合法性的 ``CharField``,不接受 ``maxlength`` 参数.

``FileField``
    一个文件上传字段.

    要求一个必须有的参数: ``upload_to``, 一个用于保存上载文件的本地文件系统路径.
    这个路径必须包含 `strftime formatting`_,
    该格式将被上载文件的 date/time 替换(so that
    uploaded files don't fill up the given directory).

    admin 用一个``<input type="file">``部件表示该字段保存的数据(一个文件上传部件) .


    在一个 model 中使用 ``FileField`` 或 ``ImageField`` 需要以下步骤:

    1. 在你的 settings 文件中, 定义一个完整路径给 ``MEDIA_ROOT`` 以便让 Django在此处保存上传文件.  (出于性能考虑,这些文件并不保存到数据库.)
       定义 ``MEDIA_URL`` 作为该目录的公共 URL. 要确保该目录对 WEB 服务器用户帐号是可写的.

    2. 在你的 model 中添加 ``FileField`` 或 ``ImageField``, 并确保定义了 ``upload_to`` 选项,以告诉 Django 使用 ``MEDIA_ROOT`` 的哪个子目录保存上传文件.

    3. 你的数据库中要保存的只是文件的路径(相对于 ``MEDIA_ROOT``). 出于习惯你一定很想使用 Django 提供的 ``get_<fieldname>_url`` 函数.举例来说,如果你的 ``ImageField`` 叫作 ``mug_shot``, 你就可以在模板中以 ``{{ object.get_mug_shot_url }}`` 这样的方式得到图像的绝对路径.

    .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941

``FilePathField``
    可选项目为某个特定目录下的文件名. 支持三个特殊的参数, 其中第一个是必须提供的.

        ======================  ===================================================
        参数                       描述
        ======================  ===================================================
        ``path``                必需参数. 一个目录的绝对文件系统路径. ``FilePathField``
                                据此得到可选项目. Example: ``"/home/images"``.

        ``match``               可选参数. 一个正则表达式, 作为一个字符串, ``FilePathField`` 将使用它过滤文件名.
                                注意这个正则表达式只会应用到 base filename 而不是路径全名. Example:
                                ``"foo.*\.txt^"``, 将匹配文件 ``foo23.txt`` 却不匹配 ``bar.txt`` 或 ``foo23.gif``.

        ``recursive``           可选参数.要么 ``True`` 要么 ``False``. 默认值是
                                ``False``. 是否包括 ``path`` 下面的全部子目录.
        ======================  ===================================================

    这三个参数可以同时使用.

    我已经告诉过你 ``match`` 仅应用于 base filename, 而不是路径全名. 那么,这个例子::

        FilePathField(path="/home/images", match="foo.*", recursive=True)

    ...会匹配 ``/home/images/foo.gif`` 而不匹配 ``/home/images/foo/bar.gif``

``FloatField``
    一个浮点数. 必须 **提供两个** 参数:

        ======================  ===================================================
        参数                       描述
        ======================  ===================================================
        ``max_digits``          总位数(不包括小数点和符号)

        ``decimal_places``      小数位数
        ======================  ===================================================

    举例来说, 要保存最大值为 999 (小数点后保存2位),你要这样定义字段::

        models.FloatField(..., max_digits=5, decimal_places=2)

    要保存最大值一百万(小数点后保存10位)的话,你要这样定义::

        models.FloatField(..., max_digits=19, decimal_places=10)

    admin 用一个文本框(``<input type="text">``)表示该字段保存的数据.

``ImageField``
    类似 ``FileField``, 不过要校验上传对象是否是一个合法图片.它有两个可选参数:``height_field`` 和 ``width_field``,如果提供这两个参数,则图片将按提供的高度和宽度规格保存. 

    该字段要求 `Python Imaging Library`_.

    .. _Python Imaging Library: http://www.pythonware.com/products/pil/

``IntegerField``
    用于保存一个整数.

    admin 用一个``<input type="text">``表示该字段保存的数据(一个单行编辑框)

``IPAddressField``
    一个字符串形式的 IP 地址,  (i.e. "24.124.1.30").

    admin 用一个``<input type="text">``表示该字段保存的数据(一个单行编辑框)

``NullBooleanField``
    类似 ``BooleanField``, 不过允许 ``NULL`` 作为其中一个选项. 推荐使用这个字段而不要用 ``BooleanField`` 加 ``null=True`` 选项.

    admin 用一个选择框 ``<select>`` (三个可选择的值: "Unknown", "Yes" 和 "No" ) 来表示这种字段数据.

``PhoneNumberField``
    一个带有合法美国风格电话号码校验的 ``CharField``(格式: ``XXX-XXX-XXXX``).

``PositiveIntegerField``
    类似 ``IntegerField``, 但取值范围为非负整数(这个字段应该是允许0值的....所以字段名字取得不太好,无符号整数就对了嘛).

``PositiveSmallIntegerField``
    类似 ``PositiveIntegerField``, 取值范围较小(数据库相关)

``SlugField``
    "Slug" 是一个报纸术语. slug 是某个东西的小小标记(短签), 只包含字母,数字,下划线和连字符.它们通常用于URLs.

    若你使用 Django 开发版本,你可以指定 ``maxlength``. 若 ``maxlength`` 未指定, Django 会使用默认长度: 50. 在以前的 Django 版本,没有任何办法改变 50 这个长度.

    这暗示了 ``db_index=True``.

    它接受一个额外的参数: ``prepopulate_from``, which is a list of fields
    from which to auto-populate the slug, via JavaScript, in the object's admin
    form::

        models.SlugField(prepopulate_from=("pre_name", "name"))

    ``prepopulate_from`` 不接受 DateTimeFields.

    admin 用一个``<input type="text">``表示 ``SlugField`` 字段数据(一个单行编辑框)

``SmallIntegerField``
    类似 ``IntegerField``, 不过只允许某个取值范围内的整数.(依赖数据库)

``TextField``
    一个容量很大的文本字段.

    admin 用一个 ``<textarea>`` (文本区域)表示该字段数据.(一个多行编辑框).

``TimeField``
    A time. Accepts the same auto-population options as ``DateField`` 和
    ``DateTimeField``.

    admin 用一个 ``<input type="text">`` 文本框表示该字段保存的数据(附加一些JavaScript shortcuts).

``URLField``
    用于保存 URL. 若 ``verify_exists`` 参数为 ``True`` (默认),
    给定的 URL 会预先检查是否存在(即URL是否被有效装入且没有返回404响应).

    admin 用一个 ``<input type="text">`` 文本框表示该字段保存的数据(一个单行编辑框)

``USStateField``
    一个两字母的美国州名缩写.

    admin 用一个 ``<input type="text">`` 文本框表示该字段保存的数据(一个单行编辑框) 

``XMLField``
    一个校验值是否为合法XML的 ``TextField``,必须提供参数: ``schema_path``, 它是一个用来校验文本的 RelaxNG_ schema 的文件系统路径.

    .. _RelaxNG: http://www.relaxng.org/

字段选项
---------------------

以下参数对所有字段类型可用, 所有参数都是可选的:

``null``
~~~~~~~~~~~~~~~~~
    若值为 ``True``, Django 将在数据库中以空值当作 ``NULL`` 保存. 默认值是 ``False``.

    注意空字符串并不是 ``NULL`` -- 因此可以对非字符串类型的字段如整型, 逻辑型和日期型字段使用 ``null=True`` 

    避免在类似字符串的字段(如 ``CharField`` 和 ``TextField``)中使用使用 ``null`` , 除非你有一个服人的理由.如果对一个类字符串字段使用 ``null=True`` 参数, 就意味着有两个可能的值对应着"没有数据":
    ``NULL``, 和 空串. 在绝大多数情况下, 同一种情形("没有数据")却有两个可能的值不但不必要而且容易引起混乱.Django惯例是使用空串,而不是 ``NULL``.

``blank``
~~~~~~~~~~~~~~~~~
    若值为 ``True``, 该字段允许留空.

    注意这与 ``null`` 不同. ``null`` 是纯数据库概念, 而 ``blank`` 是验证相关概念. 如果一个字段使用 ``blank=True`` 参数, Django 的admin site将允许该字段不填写数据.而如果一个字段使用 ``blank=False`` 参数, 则该字段必须要有一个适当的值.

``choices``
~~~~~~~~~~~~~~~~~
    一个 2-元素 tuple 的列表, 用来表示该字段的可选值.

    如果提供该参数, Django 的 admin 会使用一个 select box (不用标准文本框)来限制用户输入.

    一个 choices 列表就象下面这样::

        YEAR_IN_SCHOOL_CHOICES = (
            ('FR', 'Freshman'),
            ('SO', 'Sophomore'),
            ('JR', 'Junior'),
            ('SR', 'Senior'),
            ('GR', 'Graduate'),
        )

    每个 tuple 的第一个元素是要保存的真实值. 第二个元素则是第一个元素的更易理解的描述.

    这个选择列表可以是 model 类的一部分::

        class Foo(models.Model):
            GENDER_CHOICES = (
                ('M', 'Male'),
                ('F', 'Female'),
            )
            gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)

    也可以 model 类之外定义::

        GENDER_CHOICES = (
            ('M', 'Male'),
            ('F', 'Female'),
        )
        class Foo(models.Model):
            gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)

``core``
~~~~~~~~~~~~~~~~~
    表明该字段必须在一个关系对象内进行编辑.

    在Django admin中, 如果一个内联编辑对象的所有的 "core" 字段都被清除, 该内联编辑对象就被自动删除.

    一个内关编辑对象必须至少有一个``core=True``字段.

``db_column``
~~~~~~~~~~~~~~~~~
    针对该字段数据库要使用的字段名. 如果没有提供该参数, Django 就使用该字段属性的属性名.

    如果你的指定的 db_column 是一个SQL保留字,或包含Python 变量名规则中不允许的字符--特别是连字符(-)--没问题！Django 会在幕后自动用引号将字段名和表名引起来．

``db_index``
~~~~~~~~~~~~~~~~~
    若值为 ``True``, ``django-admin.py sqlindexes`` 将为此字段输出一个 ``CREATE INDEX`` 语句．

``default``
~~~~~~~~~~~~~~~~~
    该字段的默认值．

``editable``
~~~~~~~~~~~~~~~~~
    若 ``False``, 在 admin site 该字段不可修改. 默认值是  ``True``.

``help_text``
~~~~~~~~~~~~~~~~~
    在该对象的 admin 表单中在字段的下边显示的额外 "帮助" 文本．当你的对象没有一个管理表单时，它就是很有用的文档信息了．

``primary_key``
~~~~~~~~~~~~~~~~~
    若值为 ``True``, 这个字段是该 model 的主键．

    若你的model中没有一个字段使用 ``primary_key=True`` 参数, Django 会自动添加这样一个字段::

        id = models.AutoField('ID', primary_key=True)

    因此, 你不需要在字段列表中设置 ``primary_key=True`` 参数,除非你想改变系统的这种默认行为.

    ``primary_key=True`` 自动意味着 ``blank=False``, ``null=False`` 和 ``unique=True``. 一个 model 对象只允许有一个主键.

``radio_admin``
~~~~~~~~~~~~~~~~~
    默认的, 对 ``ForeignKey`` 字段或拥有 ``choices`` 参数的字段, Django 的 admin 对其使用一个 select-box 界面(<select>). 然而若你指定 ``radio_admin=True``, Django 就使用 radio-button 界面代替 select-box 界面(<select>).

    除非该字段是 ``ForeignKey`` 或者拥有 ``choices`` 参数,否则不要使用该参数.
    该参数默认值为 ``False``.

``unique``
~~~~~~~~~~~~~~~~~
    若值为 ``True``, 这个字段的取值在整个表中必须是独一无二的.
    Django将在数据库层次和 Django 管理表单层次限制该字段的取值.

``unique_for_date``
~~~~~~~~~~~~~~~~~~~~~
    当要求该字段在同一记录所记载的日期内不允许有重复值时,可以将 ``unique_for_date`` 的值设置为一个 ``DateField`` 或 ``DateTimeField`` 字段. 

    举例来说, 如果你有一个字段 ``title`` 使用了 ``unique_for_date="pub_date"`` 参数, Django 将不允许拥有同样 ``title`` 和 ``pub_date`` 的两条记录同时在数据表中存在.

    Django 的管理表单层会限制你的取值,但数据库层并无此限制.

``unique_for_month``
~~~~~~~~~~~~~~~~~~~~~
    就象 ``unique_for_date``, 不过要求该字段在同一记录所记载的月份内不许有重复值.

``unique_for_year``
~~~~~~~~~~~~~~~~~~~~~
    class似 ``unique_for_date`` 和 ``unique_for_month``.

``validator_list``
~~~~~~~~~~~~~~~~~~~~~
    应用在该字段上的一个校验器的列表.每一个校验器都应该是一个可调用对象(该对象接受``field_data, all_data ``作为参数并在出错时引发`` django.core.validators.ValidationError``).参见 `validator docs`_.

    Django 自带了一些校验器. 它们定义在 ``django.core.validators``.

.. _validator docs: http://www.djangoproject.com/documentation/forms/#validators


表间关系
-------------

谁都知道,关系型数据库的威力就在于表间的关系. Django 提供了便利的方式定义最常见的三种关系类型: Many-to-one, many-to-many 和 one-to-one.

Many-to-one 关系
~~~~~~~~~~~~~~~~~~~~~~~~~

要定义一个 many-to-one 关系, 使用 ``ForeignKey``. 将它以类属性的方式包括到类中,它就能象访问普通字段一样访问它.

``ForeignKey`` 要求必须提供一个位置参数: 即被关联的 model 类.

举例来说, 如果一个 ``Place`` model 位于一个 ``City`` 中 -- 也就是说, 一个 ``City`` 中包含很多个 places, 但每个 ``Place`` 却只能位于一个 ``City`` -- 用下面的类定义表达这种关系::

    class City(models.Model):
        # ...

    class Place(models.Model):
        # ...
        city = models.ForeignKey(City)

要创建一种递归关系--一个对象与自身有多对一的关系-- 使用 ``models.ForeignKey('self')``.

若需要与一个尚未定义的 model 建立关系, 使用该 model 的名字,而不是 model 对象本身::

    class Place(models.Model):
        # ...
        city = models.ForeignKey("City")

    class City(models.Model):
        # ...

当然你完全可以将 City 类定义在 Place 类之前以避免这种情况发生.

一个 ``ForeignKey`` 的名字 (上例中的 ``city``) 是 model 的名字. Django 会自动添加一个 "_id" 到字段名以创建数据表的列名. 除非你要用自定义SQL,否则你一定不要自己去处理数据表的列名.

参阅 `多对一 关系模型示例`_ 来查看完整的例子.

.. _多对一 关系模型示例: http://www.djangoproject.com/documentation/models/many_to_one/

``ForeignKey`` 字段接受一大堆可选的额外的参数以便定义关系如何运作:

    =======================  ============================================================
        参数                       描述
    =======================  ============================================================
    ``edit_inline``          若取值非假, 这个关联对象就是可内联编辑的.这也意味着这个对象
                             没有自己的管理界面.取值可以是 ``models.TABULAR`` 
                             或 ``models.STACKED``,
                             分别表示内联可编辑对象是显示成表格形式还是一个字段集栈的形式.

    ``limit_choices_to``     一个参数和值的字典(参阅`数据库API参考`_)用来限制 admin 针对该
                             对象的可选项. 使用 ``models.LazyDate`` 值来按日期限制该对象的选
                             择项,举例来说::

                                limit_choices_to = {'pub_date__lte' : models.LazyDate()}

                             只允许关联对象的pub_date在当前日期之前的才可以被选择.

                             本参数与 ``edit_inline`` 不相容.

    ``max_num_in_admin``     对内联编辑对象来说,这是在 amdin 中可显示的关联对象的最大值.
                             这样, 如果说一只比萨饼最多加10种浇头,那么 ``max_num_in_admin=10`` 将
                             确保没有一个超过十种.

                             这并不说是比萨斜塔只有十层高...比萨斜塔是可以有更多层的.这个参数仅仅控制admin界面.

    ``min_num_in_admin``     在admin中显示的关联对象的最小值. 正常情况,在创建阶段
                             显示 ``num_in_admin`` 个内联对象, 在编辑阶段,除了预先存在的关联对象外,
                             显示 ``num_extra_on_change`` 个空对象.不过, 无论何种情况,至少会有
                             ``min_num_in_admin`` 个关联对象被显示出来.

    ``num_extra_on_change``  在编辑阶段显示的额外的空白关联对象字段数.

    ``num_in_admin``         在添加一个对象时显示的其内联对象的默认数量

    ``raw_id_admin``         为即将得到的整数值(id值)显示一个文本框而不是一个下拉菜单. 
                             在关联对象有很多很多行时.使用它就比使用一个 ``<select>`` 更实用.

                             不能与 ``edit_inline`` 一起使用.

    ``related_name``         关系名字.  举例来说, 如果 ``Topping`` 对象拥有字段::

                                    models.ForeignKey(Pizza)

                             ``related_name`` 将会是 "topping_set" (取自 **类** 的名字),  ``Pizza``
                             对象会自动拥有 ``topping_set`` 对象集描述符. 

                             不过若你在 ``Topping`` 类中做如下定义的话::

                                    models.ForeignKey(Pizza, related_name="munchie")

                             则 ``Topping`` 的对象集描述符就变为 ``munchie``.

                             只有当一个对象要被另一个对象关联不止一次时, 这个参数才真正有用.
                             举例来说, 如果一个 ``Story`` 对象既有 ``primary_category`` 字段又有 ``secondary_category`` 字段.
                             为了确保 ``Category`` 对象拥有正确的对象集描述符,你要这样使用这些字段.::

                                    models.ForeignKey(Category, related_name="primary_storys")
                                    models.ForeignKey(Category, related_name="secondary_storys")

                             ...这样 ``Category`` 对象才会自动拥有 ``primary_storys`` 和
                             ``secondary_storys`` 对象集描述符.

    ``to_field``             被关联对象的用于关联的字段. 默认情况, Django 使用被关联对象的主键
    =======================  ============================================================

.. _`数据库API参考`: http://www.djangoproject.com/documentation/db_api/

Many-to-many 关系
~~~~~~~~~~~~~~~~~~~~~~~~~~

要定义一个 many-to-many 关系,使用 ``ManyToManyField``. 将它以类属性的方式包括到类中,它就能象访问普通字段一样访问它.

``ManyToManyField`` 要求必须提供一个位置参数: 即被关联的 model 类.

举例来说, 如果一种 ``Pizza`` 可以有多种 ``Topping`` -- 也即, 一种 ``Topping`` 对应多种 ``Pizza`` 使用并且每种 ``Pizza`` 对应多种 ``Topping``--
要表示这样的关系, 必须这样做::

    class Topping(models.Model):
        # ...

    class Pizza(models.Model):
        # ...
        toppings = models.ManyToManyField(Topping)

类似 ``ForeignKey``, 定义一个与自己的关系使用字符串 ``"self"`` 而不是 model 的名字; 使用一个字符串形式的 ``model`` 名字引用一个尚未定义的 model.

``ManyToManyField`` 字段的名字(上例中是 ``toppings`` )通常是关联 model 的名字的复数(小写).

幕后: Django 会创建一个中间表以表示这种 **多对多** 的关系.

可以由任意一个 model 定义 ``ManyToManyField`` , 但是你只需要在一个 model 中定义 -- 一定不要在两个 model 中同时定义 ``ManyToManyField``.

通常, ``ManyToManyField`` 实例将参与在 admin 中被编辑的对象.在上面的例子中 ``toppings`` 定义在 ``Pizza`` 中,
这比 ``Topping`` 拥有一个 ``pizzas`` ``ManyToManyField`` 好. 这是因为它更自然: 一种比萨饼有多种浇头很自然,很容易理解.而非要说一种浇头被多种比萨饼使用,则很拗口. 如果象上例中那样定义, 则在 ``Pizza`` 对象的 admin 表单中将允许用户选择 toppings.

参阅 `多对多关系模型示例`_ 以查看一个完整的例子.

.. _多对多关系模型示例: http://www.djangoproject.com/documentation/models/many_to_many/

``ManyToManyField`` 能接受额外的参数以定义这种关系的工作方式, 所有这些参数都是可选的:

    =======================  ============================================================
    参数                     描述
    =======================  ============================================================
    ``related_name``         参阅上文中 ``Foreignkey`` 小节讲到的 ``related_name``

    ``filter_interface``     在 admin 表单中使用适当的 Javascript "过滤" 界面 (界面友好易用)
                             而不使用 ``<select multiple>`` (不易使用). 它的值应该是 
                             ``models.HORIZONTAL`` 或 ``models.VERTICAL`` (也就是界面应该横放还是竖放).

    ``limit_choices_to``     参阅上文中 ``ForeignKey`` 的同名参数

    ``singular``             该字段的唯一名字.  在 ``get_*`` 方法中使用这个名字.在
                             上面的例子里, , Django 提供给 ``Pizza`` 对象一个 ``get_topping_list()`` 
                             方法. 这里 ``topping`` 就是 ``singular`` 参数的默认值(它来自被连接的类的名字的小写)
                             使用 singular 参数可以改变这些自动生成方法的名字, 尤其当你的一个 model 和另一个 model
                             具有多个 ``ManyToMany`` 关系时, 这个参数就会相当有用.

    ``symmetrical``          仅用于 model 定义自身的 ManyToManyFields .
                             假设有下面一个 model:
                             
                             class Person(models.Model):
                                 friends = models.ManyToManyField("self")
                             
                             当 Django 处理该 model 时, Django 会发现这是一个对自己的 ManyToManyField , 
                             因此它不会添加一个 "person_set" 属性. ManyToManyField 是对称的,
                             也就是: 我是你的朋友, 你也就是我的朋友. 这个意思.
                             
                             若你不需要这种对 model 自身的 ManyToMany 关系,设置 ``symmetrical`` 为 False. 
                             这样 Django 会强制给关系的另一方添加一个对象集描述符.从而允许
                             ManyToMany 关系是不对称的.
    =======================  ============================================================

One-to-one 关系
~~~~~~~~~~~~~~~~~~~~~~~~

``OneToOneField`` 用于定义一个 one-to-one 关系 . 将它以类属性的方式包括到类中,它就能象访问普通字段一样访问它.

``ManyToManyField`` 要求必须提供一个位置参数: 即被关联的 model 类.

当一个对象需要在某种形式上 "扩展" 另一个对象时,这种基于主键的关系相当有用.

举例来说, 你正在建设一个 ``Place`` 数据表, 你需要建立该数据库很多标准:如地址,电话号码等等.之后,如果你打算在 ``Place`` 数据表的基础之上建立一个 ``Restaurant`` 数据表, 你不必在 ``Restaurant`` model 中重复那些字段, 你可以让 ``Restaurant`` 有一个 ``OneToOneField`` 字段对应 ``Place`` (因为一个餐馆就是一个地点).

与 ``ForeignKey`` 类似, 一个针对自身的关系使用字符串 ``"self"`` 而不是 model 名字. 引用未定义的 model 使用字符串形式的 model 名字.

这个 ``OneToOneField`` 事实上替换了 ``id`` 主键字段(因为 one-to-one 关系共享地同样的主键), 并且当你在 Admin 界面中编辑一个相关对象时,该字段被显示为只读.


点击 `一对一关系模型示例`_ 可以看到一个完整的例子.

.. _一对一关系模型示例: http://www.djangoproject.com/documentation/models/one_to_one/

Meta 选项
============

通过一个内嵌类 ``"class Meta"`` 给你的 model 定义元数据, 类似下面这样::

    class Foo(models.Model):
        bar = models.CharField(maxlength=30)

        class Meta:
            # ...

Model 元数据就是 "不是一个字段的任何数据" -- 比如排序选项, admin 选项等等.

下面是所有可能用到的 ``Meta`` 选项. 没有一个选项是必需的. 是否添加 ``class Meta`` 到你的 model 完全是可选的.

``db_table``
----------------

    本模块在数据库中对应的表的名字::

        db_table = "pizza_orders"

    若不提供该参数, Django 会使用 ``app_label + '_' + module_name`` 作为表的名字.

    若你的表的名字是一个 SQL 保留字, 或包含 Python 变量名不允许的字符--特别是连字符 --没关系. Django 会自动在幕后替你将列名字和表名字用引号引起来.

``get_latest_by``
    一个 ``DateField`` 或 ``DateTimeField`` 字段的名字. 若提供该选项, 该模块将拥有一个 ``get_latest()`` 函数以得到 "最新的" 对象(依据那个字段)::

        get_latest_by = "order_date"

    点击 获取最新对象_ 可以看到一个完整的例子.

    .. _获取最新对象: http://www.djangoproject.com/documentation/models/get_latest/

``order_with_respect_to``
-------------------------

标记给定字段的对象是 "orderable" 的.它用于关联对象以允许他们以父对象期望的方式排序.举例来说, 如果一个 ``PizzaToppping`` 关联到一个 ``Pizza`` 对象, 这样做::

    order_with_respect_to = 'pizza'

...就允许 toppings 依照相关的 pizza 来排序.

``order_with_respect_to``
    将该对象标记为可按给定字段排序. This is almost always used with related objects to allow them to be ordered with
    respect to a parent object. 举例来说, 如果一个 ``PizzaToppping`` 关联到一个 ``Pizza`` 对象, 你可以使用::

        order_with_respect_to = 'pizza'

    这就允许 toppings 被排序to be ordered 关于相关的 pizza 对象

``ordering``
    默认排序字段及排序方式, 用于得到一个对象列表的任何场合::

        ordering = ['-order_date']

    这是一个 tuple 或一个字符串列表. 每个字符串是一个字段名带及一个可选的前缀 "-" , 这个前缀表示按降序排序(递减). 若没有这个前缀,则表示按升序排序.字符串 "?" 表示随机排序.

    举个例子, 要对 ``pub_date`` 字段以升序排列, 这样做::

        ordering = ['pub_date']

    要降序排列, 这样::

        ordering = ['-pub_date']

    要对 ``pub_date`` 降序,然后对 ``author`` 升序, 这样::

        ordering = ['-pub_date', 'author']

    点击 `指定排序`_ 查看一个完整的例子.
    注意一点,不论你使用了多少个字段排序, admin 只使用第一个字段.

    .. _指定排序: http://www.djangoproject.com/documentation/models/ordering/


``permissions``
    要创建一个对象所需要的额外的权限.
    如果一个对象有 ``admin`` 设置, 则每个对象的添加,删除和改变权限会人(依据该选项)自动创建.下面这个例子指定了一个附加权限: ``can_deliver_pizzas``::

        permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)

    这是一个2-元素 tuple 的tuple或列表, 其中两2-元素 tuple 的格式为:``(permission_code, human_readable_permission_name)``.
    .

``unique_together``
    Sets of field names that, taken together, must be unique::

        unique_together = (("driver", "restaurant"),)

    这是一个字段列表的列表,这些字段的综合值必须是唯一的. 这会在 Django admin 层和数据库层同时做出限制(也就是相关的 ``UNIQUE`` 语句会被包括在    ``CREATE TABLE`` 语句中).

``verbose_name``
    是该对象的一个可读性更好的唯一名字::

        verbose_name = "pizza"

    若未提供该选项, Django 则会用一个类名字的 munged 版本来代替:
    ``CamelCase`` becomes ``camel case``.

``verbose_name_plural``
    对象名字的复数::

        verbose_name_plural = "stories"

    若未提供该选项, Django 会使用 ``verbose_name + "s"``.

========================================
THE REST OF THIS HAS NOT YET BEEN EDITED
========================================

Table names
===========

Automatic primary key fields
============================

Admin 选项
=============

如果你需要你的 model 可以通过自动的管理系统进行管理, 你的 model 必须一个内嵌类 ``"class Admin"``, 就象下面这样::

    class Foo(models.Model):
        bar = models.CharField(maxlength=30)
        # ...
        class Admin:
            # ...

这个 Admin 类告诉 Django 如何使用管理系统显示这个 model.

下面列出了所有可用的 ``Admin`` 选项, 没有一个选项是必须提供的. 换言之, 整个 ``class Admin`` 都是可选的.

``date_hierarchy``
    将 ``date_hierarchy`` 设置为用来过滤对象的日期字段(字符串形式),就能在管理界面中的按这个字段过滤对象.

        date_hierarchy = 'order_date'

``fields``
    在管理页面显示的字段集的列表.  每个字段集是一个 2-元素 tuple, 格式为 ``(name, field_options)``.  其中 ``name`` 是这个字段集的名字,和 ``field_options`` 是一个关于那个字段集中要显示的字段的信息字典 dictionary of information about the fields to be
    displayed in that fieldset. 该字典有以下键:

        ``fields``
            对应的在这个字段集中要显示的字段名的tuple. 如果要在一行中显示多个字段, 就将这些字段封装在它们自己的 tuple 中.

            这个键是该信息字典必须要有的.

        ``classes``
            字段集要使用的附加的 CSS 类.这是一个简单字符串.支持多个 CSS 类,只需要将它们用空格分开即可

            默认定义的两个很有用的 CSS 类 是 ``collapse`` 和 ``wide``.  带有 ``collapse`` 样式的字段集在 admin 将被折叠在一起并被一个很小的 "click to expand" 链接代替.  带有 ``wide`` 样式的字段集会拥有额外的水平空间.

        ``description``
            在字段集标题的下面,在每个字段集的顶部显示的可选的附加文本. 它将被原样显示,因此你可以使用 HTML 代码并且你必须自己负责在该文本内转义任何特殊的 HTML 字符(比如 ``&`` 符号).

    举例来说 (摘自 ``django.contrib.flatpages`` model)::

        class Admin:
            ...
            fields = (
                (None, {
                    'fields': ('url', 'title', 'content', 'sites')
                }),
                ('Advanced options', {
                    'classes': 'collapse',
                    'fields' : ('enable_comments', 'registration_required', 'template_name')
                }),
            )

    在admin界面中它看起来就象这样:

        .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png

    如果未提供 ``fields`` , Django 会在一个字段集中显示不是 ``AutoField`` 且拥有 ``editable=True`` 属性的每个字段, 字段显示的顺序与其在 model 中定义的顺序相同.

``js``
    一个字符串列表, 表示用于(链接到) admin 界面的 JavaScript 文件的URL . 这个选项用来使用 JS 调整给定类型的 admin 页或者提供 "quick links" 来填充某些字段的默认值.

``list_display``
    在 admin 中显示在列表页的字段列表.

    这里有几个特殊场合除了显示给定字段的内容之外,还做了一些份外的事:

        * 若给定字段是一个 ``ForeignKey``, 被关联对象的 ``repr()`` 将被调用将显示其返回值

        * 不支持 ``ManyToManyField`` 字段. 因为那种字段表中的每一行都需要执行一个单独的SQL语句.(原文:because that would  entail executing a separate SQL statement for each row in the table.)

        * 若给定字段是一个 ``BooleanField``, 将显示一个 "on" 或 "off" 图标, 而不是显示 ``True`` 或 ``False``.

        * 若字段名是一个 model 的一个方法, 那么它将被调用, 它的返回值将被显示出来.这个方法应该有一个短小的 ``short_description`` 函数属性, 用来作为该字段的标题.

        * 依托 model 的 ``__str__()`` 函数,使用字符串 ``"__str__"`` 输出一个对象的字符串表示.如果你没有定义 ``list_display``, Django 默认使用 ``__str__`` .

    参见下面的例子.

``list_filter``
    需要过滤的字段列表. 每个字段要么是一个 ``BooleanField`` 要么是一个有 ``ManyToOne`` 关系的字段.

    这个例子演示了 ``list_display`` 和 ``list_filter`` 如何工作 (摘自 ``auth.user`` model)::

        class Admin:
            #...
            list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
            list_filter = ('is_staff', 'is_superuser')

    以上代码在 admin 界面中显示效果如下:

        .. image:: http://media.djangoproject.com/img/doc/users_changelist.png

    (这外例子也定义了 ``search_fields`` 参阅下文).

``list_select_related``
    不是 ``True`` 就是 ``False``. 默认值是 ``False``. 若值为 ``True``, admin 使用查询函数得到的 ``select_related`` 数据库 API 参数来改变列表页.
    注意如果 ``list_display`` 字段中有一个字段是 ``ForeignKey`` 的话, Django 只会使用 ``select_related`` (而不考虑这个设置).

``ordering``
    一个列表或一个 tuple 指定一个不同的排序方式用于 admin change 列表 (参阅上文 `Meta 选项`_) .若未提供该选项,就会使用 model 默认的排序方式.

``save_as``
    在对象页允许一个 "save as" 特性. 通常,对象会有三个保存选项: "Save", "Save and continue editing" 和 "Save and add
    another". 若 ``save_as`` 是 ``True``, "Save and add another" 将被一个 "Save as" 按钮代替.
    "Save as" 意味着当前对象将被保存为一个新对象.(带一个新的 ID).

``save_on_top``
    若这个选项为 ``True``, 对页会有一个 save 按钮 across
    the top as well as at the bottom of the page.

``search_fields``
    一个字段名列表以提供一个文本搜索框. 这些字段显然应该是某些类型的文本字段, 比如 ``CharField`` 或 ``TextField``.

管理器
========

管理器是提供给 Django 应用程序的数据库查询操作的接口. Django 应用程序中的每个 model 至少有一个管理器对象.

Django 默认自动给每个 model 添加一个名为 ``objects`` 的管理器.不过如果你需要用 ``objects`` 作为一个字段名的话, 或者你不愿意使用 ``objects`` 这个名字, 也允许为 model 指定自定义名字. 若在 model 中定义一个 models.Manager() 类型的属性, 则该属性就是管理器对象::

    from django.db import models
    
    class Person(models.Model):
        #...
        people = models.Manager()

在这个例子里, ``Person.objects.all()`` 会引发异常,而 ``Person.people.all()`` 会提供一个所有 ``Person`` 对象的列表.

管理器本身也是可以定制的. 通过扩展管理器类, 你可以在你的 model 中创建一个新的自定义的管理器. 通常有两个理由需要定制管理器:第一,为管理器对象添加一个方法.第二,修改管理器提供的初始结果集.

要修改管理器提供的初始结果集, 需要覆盖 ``get_query_set()`` 方法以返回满足你要求的结果集.举例::

    class PersonManager(models.Manager):
        # 为管理器添加一个自定义行为(添加一个方法)
        def move_house(self):
            # Some logic to help a person move house
            
        # 修改管理器对象的初始结果集
        def get_query_set(self):
            return super(Manager, self).get_query_set().filter(name__startswith="Fred")
        
    class Person(models.Model):
        #...
        objects = PersonManager()

在这个例子里, ``Person.objects.all()`` 将返回名字前四个字母为 "Fred" 的记录;并且可以使用 ``Person.objects.move_house()`` 方法.

只要需要,可以给一个 model 定义多个管理器.参阅下例::

    class MaleManager(models.Manager):
        def get_query_set(self):
            return super(Manager, self).get_query_set().filter(sex='M')

    class FemaleManager(models.Manager):
        def get_query_set(self):
            return super(Manager, self).get_query_set().filter(sex='F')
            
    class Person(models.Model):
        #...
        people = models.Manager()
        men = MaleManager()
        women = FemaleManager()

... 用户就可以使用 ``Person.men.all()``, ``Person.women.all()``, 
和 ``Person.people.all()``, 以得到适当的结果集.

若你准备使用自定义管理器, 提醒一下 Django 遇到的第一个管理器会拥有特殊的状态.
Django 认为第一个管理器是默认的管理器.一些特定的操作使用默认的管理器以得到对象列表.因此最好第一个管理器属性能提供完整的结果集(未过滤的结果集).在最后一个例子里, ``people`` 是第一个定义的,因此默认管理器将拥有全部对象.

Model 方法
=============

你可以在 model 对象中定义一系列方法来控制该对象的行为.首先你定义的任何方法都能被实例对象调用. 举例来说::

    class Pizza(models.Model):
        # ...

        def is_disgusting(self):
            return "anchovies" in [topping.name for topping in self.toppings.all()]

这样,每个 ``Pizza`` 对象都会有一个 ``is_disgusting()`` 方法.

值得注意的一点是:自定义方法的作用域被修改为和模块作用域相同. 在 model 模块中, 这些方法无权访问全局变量.还有一点,为了方便起见,允许自定义方法访问一些常用对象:

    * Python 标准库中的 ``datetime`` 模块
    * 来自 ``django.core.db`` 的 ``db`` 对象.它表示数据库连接.通过它使用游标对象你可以直接操纵数据库.参阅下文中的 "运行自定义SQL" .

点击 `Giving models custom methods`_ 可以看到一个完整的例子.

.. _Giving models custom methods: http://www.djangoproject.com/documentation/models/custom_methods/

某些对象方法拥有特殊含义:

``__str__``
    Django 在很多地方使用 ``str(obj)`` 的返回值, 特别是当要显示一个对象时(值被插入到一个模板中).既然这样,你应该总是定义一个返回得体的,友好的字符串的 ``__str__()``.

    尽管定义一个 ``__str__()`` 不是必须要求的,但是强烈鼓励你这么做.

    点击 `Adding str`_ 参阅一个完整的例子.

    .. _Adding str: http://www.djangoproject.com/documentation/models/repr/

``get_absolute_url``
    定义一个 ``get_absolute_url`` 方法以告诉 Django 如何为一个对象计算出它的 URL. 举例来说::

        def get_absolute_url(self):
            return "/pizzas/%i/" % self.id

    Django 会在 admin 界面中使用它. 若一个对象定义了 ``get_absolute_url``, 这个对象的细节页就会有一个 "View on site" 链接.你可以从那儿直接跳到该对象的发布 view.

    在模板中使用 ``get_absolute_url()`` 是一个好主意. 这比你在模板中使用硬编码 URL 灵活性要好的多.

Module-级 方法
--------------------

如果你要添加一个不依赖model实例的 Model 方法,需要使用 Python 的 ``staticmethod`` 和 ``classmethod`` 操作符, 举例来说::

    class Pizza(models.Model):
        # ...

        def get_pizzas_to_deliver():
            return get_list(delivered__exact=False)
        get_pizzas_to_deliver = staticmethod(get_pizzas_to_deliver)
        
或者使用 Python 2.4 修饰符::
    
    # ...
    @staticmethod
    def get_pizzas_to_deliver():
        # ...
        

这样顶级的 ``pizzas`` 模块会拥有一个 ``get_pizzas_to_deliver()`` 方法::

    >>> from pizza_hut.models import Pizza
    >>> Pizza.get_pizzas_to_deliver()
    [ ... ]

Manipulator methods
-------------------

类似的, 你可以给对象的操纵器添加自定义方法.(必须由 "_manipulator_" 开头). 由于操纵器自动调用 "validate" 开头的方法,所以这是为特定字段提供自定义校验器的好方式.::

    class Pizza(models.Model):
        # ...

        def _manipulator_validate_customer_id(self, field_data, all_data):
            from django.core import validators
            from django.conf.settings import BAD_CUSTOMER_IDS

            if int(field_data) in BAD_CUSTOMER_IDS:
                raise validators.ValidationError, "We don't deliver to this customer."

执行自定义SQL
--------------------

在自定义 model 方法和模块级方法里,你可以自由的执行自定义SQL语句. 对象 ``django.db.connection`` 表示当前的数据库连接. 调用 ``connection.cursor()`` 得到一个游标对象. 然后调用 ``cursor.execute(sql, [params])``以执行 SQL 语句, 使用 ``cursor.fetchone()`` 或 ``cursor.fetchall()`` 得到结果集. 下面是一个例子::

    def my_custom_sql(self):
        from django.db import connection
        cursor = connection.cursor()
        cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
        row = cursor.fetchone()
        return row

如果你的SQL语句改变了数据库中的数据 -- 比如你使用了 ``DELETE`` 或 ``UPDATE`` 语句. 你需要调用 ``connection.commit()`` 来使你的修改生效. 例子::

    def my_custom_sql2(self):
        from django.db import connection
        cursor = connection.cursor()
        cursor.execute("DELETE FROM bar WHERE baz = %s", [self.baz])
        connection.commit()

``connection`` 和 ``cursor`` 直接调用 `Python DB-API`_. 如果你对 Python DB-API 不熟悉, 注意``cursor.execute()`` 中的SQL语句使用了占位符 ``"%s"``, 这比直接在 SQL语句中指定参数要灵活. 如果你使用此技术, 后台的数据库会自动的在需要时用引号引并转义你的参数.

最后提醒一下: 如果你想要的仅仅是一个自定义的 ``WHERE`` 子句,你可以在标准查询 API 中通过指定 ``where``, ``tables`` 和 ``params`` 参数来完成同样的功能.参阅 `其它查询选项`_.

.. _Python DB-API: http://www.python.org/peps/pep-0249.html
.. _其它查询选项: http://www.djangoproject.com/documentation/db_api/#extra-params-select-where-tables

应用 models
============

在定义了一个 model 之后, 必须通知 Django 一些技术信息: 编辑你的 settings 文件中 ``INSTALLED_APPS`` tuple, 在其中添加包含你的 models apps名字. 

举个例子, 如果你的 model 在模块 ``project.myapp.models`` (包结构通过 ``django-admin.py startapp`` 脚本创建)中定义, ``INSTALLED_APPS`` 的内容就类似下面这样::

    INSTALLED_APPS = (
        #...
        project.myapp,
        #...
    )

以普通 Python 模块的形式保存你的 model . 将这个模块放到一个叫 "models" 的包中, 这样它就成为你 Python 路径中的一个包的子包. 你的 ``models` 包中的  ``__init__.py`` 应该有一个 ``__all__`` 变量. 它是位于 ``models`` 目录下的 model 模块的一个列表.

举例来说, 如果你在一个名为 ``mymodels.py`` 的模块中保存了你的  models ,下面是一个你可能用到的目录布局::

    myapp/
        __init__.py          # Empty file
        models/
            __init__.py      # Contains "__all__ = ['mymodels']"
            mymodels.py      # Contains your models

如果你觉得这些有点太过复杂, 使用 ``django-admin.py startapp`` -- 它将自动的创建适当的目录结构及 ``__init__.py`` 文件. (参阅`django-admin.py 文档`_ .)
本文档只解释 Django 如何工作.

然后你必须告诉 Django ``myapp`` 已经安装.通过编辑 ``settings`` 文件, 添加 ``"myapp"`` 到 ``INSTALLED_APPS`` tuple.

当添加你的应用程序到 ``INSTALLED_APPS`` 之后, 你可以打开 Python
解释器并测试你的 model::

    >>> from django.models.mymodels import pizzas
    >>> pizzas.get_list()

注意是从 ``django.models`` 导入, 而不是 ``myapp.models``. Django 在 ``django.models`` 中创建了一个 "magic" 模块给每一个已安装的 app. 每个 magic 模块拥有动态的 API. 参阅 `数据库API参考`_ 了解如何使用这些 API.

.. admonition:: 为什么必须设置 INSTALLED_APPS ?

   Model 之间的关联是双向的,动态生成的 Django API 查找也是双向的. 因此 Django 要知道某个特定 model 关联的所有其它模块, 它必须知道已安装的所有 apps.

.. _`django-admin.py 文档`: http://www.djangoproject.com/documentation/django_admin/
.. _`数据库API参考`: http://www.djangoproject.com/documentation/db_api/

跨文件 model 引用
===================

要关联一个 model 到另一个模块中的某个 model, 很容易. 只要在你的 model 模块顶部 import 要关联的 model 所在的模块名, 然后引用需要的该模块中的其它 model 类就可以了,象下面这样::

    from myproject.otherapp import Site

    class MyModel(models.Model):
        # ...
        sites = models.ManyToManyField(Site)