【转】Django Model field reference学习总结
Django Model field reference学习总结（一）
本文档包含所有字段选项(field options)的内部细节和Django已经提供的field types。
Field 选项
下列参数对所有字段类型都是有效的，同时这些参数也是可选的。
null
Field.null
如果为True，Django就会将空值(empty)存储为数据库中的NULL。默认值是False。
要注意空字符串(empty string)通常不将其用于字符型字段上，比如CharField,TextField上总是被存储为空字符串，而不是NULL。null=True 只对非字符串字段有意义，比如整数(integer)，布尔值(boolean)，日期(dates)。如果你允许表单提交空值，无论是哪种字段，你还要再设置 blank=True，这是因为null仅仅影响数据库存储(详见blank)。
除非你有很充分的理由，否则不要在字符串字段(比如CharField和TextField)上使用null。在字符串字段上声明null=True，就意味着有两种意义的空值：NULL，和空字符串(empty string)。大多数情况下，存在两种空值是多余的。Django按惯例是使用空字符串，而非NULL。
注意：
在使用Oracle数据库时，null=True选项将被强加到有可能是空值的字符串字段，而且会在数据库中保存NULL，来表示空字符串。
blank
Field.blank
该字段是否可以为空。如果为True，字段允许不填。默认为False 。
要注意该选项与null不同。null纯粹是数据库范畴的概念，而blank是数据验证范畴的。如果某个字段声明了blank=True，那么Django的管理后台就允许该字段填写空值；否则，如果声明为blank=False，该字段就是必填的。
choices
Field.choices
它是一个可迭代的二元组(比如，列表或是元组)，用来给字段提供选择项。如果设置了choices，Django的管理后台就会显示选择框，而不是标准的文本框，而且这个选择框的选项就是 choices 中的元组。
每个元组中的第一个元素，是存储在数据库中的值；第二个元素是该选项更易理解的描述。例如：
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
)
一般来说，最好是在模型类内定义，并为每个值定义一个合适的名字：
from django.db import models
class Student(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
JUNIOR = 'JR'
SENIOR = 'SR'
YEAR_IN_SCHOOL_CHOICES = (
(FRESHMAN, 'Freshman'),
(SOPHOMORE, 'Sophomore'),
(JUNIOR, 'Junior'),
(SENIOR, 'Senior'),
)
year_in_school = models.CharField(max_length=2,
choices=YEAR_IN_SCHOOL_CHOICES,
default=FRESHMAN)
def is_upperclass(self):
return self.year_in_school in (self.JUNIOR, self.SENIOR)
也可以定义在类外面，在不同的类中保持一致。
你也可以将 choices 整理成命名组，这样代码更有条理，结构更清晰：
MEDIA_CHOICES = (
('Audio', (
('vinyl', 'Vinyl'),
('cd', 'CD'),
)
),
('Video', (
('vhs', 'VHS Tape'),
('dvd', 'DVD'),
)
),
('unknown', 'Unknown'),
)
每个元组中的第一个元素会用做组的命名。第二个元素是一个可迭代的二元组，每个二元组都包含一个一个值和一个易于理解的描述。分组选项可以和未分组选项组合在一个单独的列表当中(比如上例中的unknown项)。
Djanog会对设置了choices的字段添加一个方法。这个方法根据该字段的当前值获取它易于理解的描述。详见数据库API文档中的 get_FOO_display()。
最后注意一点，choices可以是任何可迭代的对象，并不仅仅只是列表或是元组。这意味着你可以构造动态的choices，不过你最好通过 ForeignKey使用一张适合的数据表来构造动态choices。毕竟choices适用于变动不大的静态数据。
除非设置了blank=False，否则选择框是一个默认显示的是"---------"的下拉框。需要重写此行为的话，可以使用(None, 'Your String For Display')。或者使用空字符串来代替None——尤其是字符字段（CharField）的时候。
db_column
Field.db_column
该字段在数据库中所使用的列名称。如果没有声明，Django就会以该字段的名称做为列名。
列名称可以是SQL保留字，也可以包含不允许出现在Python变量名的特殊字符，比如连字符。这是因为Django会在幕后给列名和表名加上引号。
db_index
Field.db_index
如果为True，会创建一个索引。运行django-admin.py sqlindexes 会为该字段输出一条CREATE INDEX语句。
db_tablespace
Field.db_tablespace
如果该字段是索引字段，db_tablespace就表示该索引所在的数据库表空间的名称。如果项目配置文件中设定了DEFAULT_INDEX_TABLESPACE，那么默认值就是配置项的值；如果你指定了该model中Meta内嵌类的db_tablespace，那么默认值就是Meta中db_tablespace的值。如果数据库不支持表空间，就会忽略该选项。
default
Field.default
该字段的默认值。它可以是一个值，也可以是一个可调用的对象(这里称之为对象C)。若是后者，那么每次创建一个新对象时，对象C都将被调用。
默认为不可变对象（模型实例、列表、集合等等），作为参照对象将作为所有新模型实例的默认值相同的实例。相反，在一个可调用包装所需的默认。例如，如果你有一个自定义的jsonfield想指定一个字典作为默认值，使用函数如下：
def contact_default():
return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)
注意lambda表达式不能应用于default，因为不能序列化。查看详细
The default value is used when new model instances are created and a value isn’t provided for the field. When the field is a primary key, the default is also used when the field is set to None.
Changed in Django 1.8:
The default wasn’t used for None primary key values in previous versions.
editable
Field.editable
如果为False，那么在Django管理后台中就不会（“不可以”）编辑该字段；同样，在Django自动生成的表单中也不会编辑该字段。默认值是True。
error_messages
Field.error_messages
error_messages参数让你可以重写出错时raise的默认信息。使用字典键值来重写错误信息。
错误信息的key包括null, blank, invalid, invalid_choice, unique, and unique_for_date. Additional error message keys are specified for each field in the Field types section below.
help_text
Field.help_text
附加的提示信息。在管理后台编辑该对象的表单中，它显示在该字段下面。即使你的对象无须在后台管理，对于文档化也是很用的。
注意，在管理后台显示该提示信息时，并不会对其转义。所以你可以在help_text中包含HTML。例如：
help_text="Please use the following format: YYYY-MM-DD."
你也可以使用纯文本，还可以用django.utils.html.escape()转义任何HTML字符。
primary_key
Field.primary_key
如果为True，那么该字段就是model的主键。
如果你没有指定任何一个字段的primary_key=True，Django就会自动添加一个IntegerField做为主键字段。所以除非你想重写默认的主键行为，否则没必要在任何字段上设置primary_key=True。详见自增主键字段 (Automatic primary key fields) 。
primary_key=True意味着null=False和unique=True 。一个对象只能有一个主键。
unique
Field.unique
如果为True，该字段值就必须是全表唯一。
它同时作用于数据库层级以及Django的管理后台和表单层级。如果你保存model时，某个unique字段的值是重复的，那么save()方法就会抛出 django.db.IntegrityError异常。
这个选项在所有的字段上都是可用的，除了ManyToManyField和FileField以外。
unique_for_date
Field.unique_for_date
如果要求在某个日期内，该字段值在数据表中是唯一的(就不存在时期和字段值都相同的记录)，那就可以将 unique_for_date 设置为某个 DateField或DateTimeField的名称。
例如，假设你有一个声明了unique_for_date="pub_date"的title字段，那么Django就不会允许出现title和pub_date相同的两条记录。
它作用于Django的管理后台和表单层级，而非数据库层级。
unique_for_month
Field.unique_for_month
和 unique_for_date 相似，只不过限定的是月分。
unique_for_year
Field.unique_for_year
和 unique_for_date， unique_for_month 相似，只不过限定的是年分。
verbose_name
Field.verbose_name
该字段易于理解的名称。如果没有提供自述名，Django会根据字段的属性名自动创建自述名--就是将属性名称中的空格替换成下划线。详见字段的自述名(Verbose field names).
可以自定义admin中的字段显示名字，如：
cost = models.FloatField(verbose_name=u'游戏时间'）
validators
Field.validators
验证器列表，有效性检查。 点击validators documentation查看更多信息。
Registering and fetching lookups
Field implements the lookup registration API. The API can be used to customize which lookups are available for a field class, and how lookups are fetched from a field.
字段类型
AutoField
class AutoField(**options)
自动递增的整型字段，添加记录时它会自动增长。通常不需要直接使用这个字段；如果你不指定主键的话，系统会自动添加一个主键字段到你的model。(参阅自动主键字段)
BigIntegerField
class BigIntegerField([**options])
一个64位长度的整型字段。该字段的默认窗体是一个TextInput。
BinaryField
class BinaryField([**options])
一个字段来存储二进制数据。它只支持字节分配。注意，这个字段只具有有限的功能。例如，它是不可能在一个binaryfield过滤器值。
滥用binaryfield
虽然你可能想在数据库中存储的文件，认为它是在99%的情况下是坏的设计。这个字段是不是一个合适的静态文件替换处理器。
BooleanField
class BooleanField(**options)
布尔字段，管理工具里会自动将其描述为checkbox。如果你想接受一个null值你可以使用NullBooleanField来代替。当Field.default未被定义时，NullBooleanField字段的默认值为None。
CharField
class CharField(max_length=None[, **options])
字符串字段，单行输入，用于较短的字符串，如要保存大量文本，使用TextField，CharField有一个必填参数：CharField.max_length：字符的最大长度，django会根据这个参数在数据库层和校验层限制该字段所允许的最大字符数。该字段的默认窗体是一个TextInput。
注意：
如果你正在编写一个应用程序必须能够移植到多个后端数据库，你应该知道，有一些max_length后端上的限制。参考数据库后台说明详情。
如果你是MySQL用户，并且使用MySQLdb-1.2.2和utf8_bin。需要看这个文档。
CommaSeparatedIntegerField
class CommaSeparatedIntegerField(max_length=None[, **options])
一个由逗号分隔的整数字段。和CharField字段相同，max_length参数也是必须的，并且需要主要多个数据库后端的匹配。
DateField
class DateField([auto_now=False, auto_now_add=False, **options])
日期字段，admin用一个文本框 来表示该字段数据(附带一个JavaScript日历和一个”Today”快捷按键。和datetime.date对应，有下列额外的可选参数：
DateField.auto_now
当对象被保存时，自动将该字段的值设置为当前时间，通常用于表示“last-modified”时间戳；
DateField.auto_now_add
当对象首次被创建时，自动将该字段的值设置为当前时间，通常用于表示对象创建时间。
注意：
- auto_now_add、auto_now、default是互斥的。混用将导致一个错误；
- 设置auto_now或者auto_now_add将导致设置editable=False及blank=True；
- auto_now或者auto_now_add一般用于记录的更新和创建。如果你需要一些不同的东西，需要考虑重写save()或者使用可调用的默认值；可以用DateTimeField代替DateField然后做格式化处理满足自己的需求。
DateTimeField
class DateTimeField([auto_now=False, auto_now_add=False, **options])
类似 DateField 支持同样的附加选项。和datetime.datetime对应。
DecimalField
class DecimalField(max_digits=None, decimal_places=None[, **options])
固定精度的十进制数，表示在Python的一个小数的实例。有两个必要的参数：
DecimalField.max_digits
最大允许的数字位数的号码。注意，这个数必须大于或等于小数位的大小。其代表的是整个数字的位数。
DecimalField.decimal_places
小数部分的位数。
例如, 如果你想保存最大为999并带两位小数的数字，你应该：
models.DecimalField(..., max_digits=5, decimal_places=2)
小数为10位，最大为10亿：
models.DecimalField(..., max_digits=19, decimal_places=10)
默认窗体为TextInput。
注意：
想详细了解FloatField和DecimalField的不同，请查看文档
DurationField
New in Django 1.8.
class DurationField([**options])
A field for storing periods of time - modeled in Python by timedelta. When used on PostgreSQL, the data type used is an interval and on Oracle the data type is INTERVAL DAY(9) TO SECOND(6). Otherwise a bigint of microseconds is used. 和 timedelta类似，是一个用来存储时间区间的字段。
注意：
Arithmetic with DurationField works in most cases. However on all databases other than PostgreSQL, comparing the value of a DurationField to arithmetic on DateTimeField instances will not work as expected.
EmailField
class EmailField([max_length=254, **options])
一个带有检查Email合法性的CharField，不接受maxlength参数。
FileField
class FileField([upload_to=None, max_length=100, **options])
一个文件上传字段。不支持primary_key和unique参数！否则抛出TypeError错误。
两个重要的参数
FileField.upload_to
一个用于保存上载文件的本地文件系统路径。 此属性提供了一种设置上传目录和文件名的方法，并可以以两种方式设置。所有的都是通过save()方法存储。
注意：
如果你需要一个特殊的字符值，你或许需要考虑strftime()函数，可以达到以下需求：
class MyModel(models.Model):
# file will be uploaded to MEDIA_ROOT/uploads
upload = models.FileField(upload_to='uploads/')
# or...
# file will be saved to MEDIA_ROOT/uploads/2015/01/30
upload = models.FileField(upload_to='uploads/%Y/%m/%d/')
如果你说使用默认的FileSystemStorage，文件将会保存在MEDIA_ROOT目录下，如果不是默认的，请查看对应的文档，了解具体是怎么样处理upload_to的。
upload_to也可能是一个可调用的函数，可以处理upload路径和文件名。此函数必须有两个参数，返回值为UNIX风格的路径。这两个参数为：
| instance | 定义了当前 FileField的model实例。更准确地说，就是以该文件为附件的model实例。 大多数情况下，在保存该文件时，model实例对象还并没有保存到数据库，这是因为它很有可能使用默认的AutoField，而此时它还没有从数据库中获得主键值。 |
| filename | 上传文件的原始名称。在生成最终路径的时候，有可能会用到它。 |
def user_directory_path(instance, filename):
# file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
return 'user_{0}/{1}'.format(instance.user.id, filename)
class MyModel(models.Model):
upload = models.FileField(upload_to=user_directory_path)
FileField.storage
存储对象，处理文件的存储和检索。默认窗体为 ClearableFileInput。
在model中使用FileField或ImageField(稍后会提到)要按照以下的步骤：
- 在你的settings文件中，定义一个完整路径给MEDIA_ROOT以便让Django在此处保存上传文件(出于性能考虑，这些文件并不保存到数据库。)。定义MEDIA_URL作为该目录的公共URL。要确保该目录对WEB服务器用户帐号是可写的。
- 在你的model中添加FileField或ImageField，并确保定义了upload_to选项，以告诉Django使用MEDIA_ROOT的哪个子目录保存上传文件。
- 你的数据库中要保存的只是文件的路径(相对于MEDIA_ROOT)。出于习惯你一定很想使用Django提供的url函数。举例来说，如果你的 ImageField叫作mug_shot，你就可以在模板中以{{ object.mug_shot.url }}这样的方式得到图像的绝对路径。
例如，假设你的MEDIA_ROOT被设为'/home/media'，upload_to被设为'photos/%Y/%m/%d'。upload_to中的'%Y/%m/%d'是一个时间格式字符串 (strftime formatting)；'%Y'是四位的年分，'%m'是两位的月分，'%d'是两位的日子。如果你在2007年01月15号上传了一个文件，那么这个文件就保存在/home/media/photos/2007/01/15目录下。
如果你想得到上传文件的本地文件名称，文件网址，或是文件的大小，你可以使用name、url和size属性；详见管理文件(Managing files)。
注意：在上传文件时，要警惕保存文件的位置和文件的类型，这么做的原因是为了避免安全漏洞。对每一个上传文件都要验证，这样你才能确保上传的文件是你想要的文件。举个例子，如果你盲目地让别人上传文件，而没有对上传文件进行验证，如果保存文件的目录处于web服务器的根目录下，万一有人上传了一个CGI或是PHP脚本，然后通过访问脚本网址来运行上传的脚本，那可就太危险了。千万不要让这样的事情发生！
默认情况下，FileField 实例在数据库中的对应列是 varchar(100) ，和其他字段一样，你可以利用 max_length 参数改变字段的最大长度。
更多参考：点击打开
FilePathField
class FilePathField(path=None[, match=None, recursive=False, max_length=100, **options])
选择指定目录按限制规则选择文件，有三个参数可选，其中”path”必需的，这三个参数可以同时使用，参数描述：
FilePathField.path
必需参数，一个目录的绝对文件系统路径。FilePathField据此得到可选项目。Example： “/home/images”；
FilePathField.match
可选参数，一个正则表达式，作为一个字符串，FilePathField将使用它过滤文件名。注意这个正则表达式只会应用到base filename而不是路径全名。Example： "foo.*\.txt$"， 将匹配文件foo23.txt却不匹配bar.txt 或foo23.gif；
FilePathField.recursive
可选参数，是否包括path下全部子目录，True或False，默认值为False。
FilePathField.allow_files
Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.
FilePathField.allow_folders
Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be True.
当然，这些参数可以混用。
match仅应用于base filename，而不是路径全名。如：
FilePathField(path="/home/images", match="foo.*", recursive=True)
会匹配/home/images/foo.gif而不匹配/home/images/foo/bar.png，因为match应用于filename。
默认最大值为100。
FloatField
class FloatField([**options])
浮点型字段。 必须提供两个参数，参数描述：max_digits：总位数(不包括小数点和符号)decimal_places：小数位数。如：要保存最大值为 999(小数点后保存2位)，你要这样定义字段：models.FloatField(…，max_digits=5，decimal_places=2)，要保存最大值一百万(小数点后保存10位)的话，你要这样定义：models.FloatField(…，max_digits=19， decimal_places=10)
ImageField
class ImageField([upload_to=None, height_field=None, width_field=None, max_length=100, **options])
类似FileField，不过要校验上传对象是否是一个合法图片。它有两个可选参数：height_field和width_field，如果提供这两个参数，则图片将按提供的高度和宽度规格保存。该字段要求Pillow库。
IntegerField
class IntegerField([**options])
用于保存一个整数。默认32位。
GenericIPAddressField
class GenericIPAddressField([protocol=both, unpack_ipv4=False, **options])
一个IPv4或者IPv6地址，以格式化字符串形式输入和展示，默认为TextInput输入框。
The IPv6 address normalization follows RFC 4291 section 2.2, including using the IPv4 format suggested in paragraph 3 of that section, like ::ffff:192.0.2.0. For example, 2001:0::0:01 would be normalized to 2001::1, and ::ffff:0a0a:0a0a to ::ffff:10.10.10.10. All characters are converted to lowercase.
GenericIPAddressField.protocol
协议选择，默认为'both'，可以指定为'IPv4'或者'IPv6'，不区分大小写。
GenericIPAddressField.unpack_ipv4
Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
If you allow for blank values, you have to allow for null values since blank values are stored as null.
NullBooleanField
class NullBooleanField([**options])
类似BooleanField，不过允许NULL作为其中一个选项。推荐使用这个字段而不要用BooleanField加null=True选项。admin用一个选择框(三个可选择的值：“Unknown”，“Yes”和“No”)来表示这种字段数据。
PhoneNumberField
一个带有合法美国风格电话号码校验的 CharField(格式：XXX-XXX-XXXX)。
PositiveIntegerField
class PositiveIntegerField([**options])
类似IntegerField，但取值范围为非负整数（这个字段应该是允许0值的…可以理解为无符号整数）Values from 0 to 2147483647 are safe in all databases supported by Django. The value 0 is accepted for backward compatibility reasons.
PositiveSmallIntegerField
class PositiveSmallIntegerField([**options])
正小整型字段，类似PositiveIntegerField，取值范围较小(数据库相关) Values from 0 to 32767 are safe in all databases supported by Django.
SlugField
class SlugField([max_length=50, **options])
Slug是一个报纸术语。slug是某个东西的小小标记(短签)，只包含字母，数字，下划线和连字符。它们通常用于URLs。
和CharField类似，你可以指定max_length(要注意数据库兼容性和本节提到的max_length)。如果没有指定max_length，Django会默认字段长度为50。
该字段会自动设置Field.db_index为True。
基于其他字段的值来自动填充Slug字段是很有用的。你可以在Django的管理后台中使用prepopulated_fields来做到这一点。
SmallIntegerField
class SmallIntegerField([**options])
类似IntegerField，不过只允许某个取值范围内的整数。(依赖数据库)Values from -32768 to 32767 are safe in all databases supported by Django.
TextField
class TextField([**options])
大文本字段。Django的管理后台使用textarea(一个多行文本框)表示该字段。
MySQL用户请注意
如果你正在使用MySQLdb 1.2.1p2和utf8_bin字符集(非默认设置)，有几点注意事项要格外留意，详见MySQL database notes。
TimeField
class TimeField([auto_now=False, auto_now_add=False, **options])
该字段使用Python的datetime.time实例来表示时间。它和DateField接受同样的自动填充的参数。
Django管理后台使用一个带Javascript快捷链接的input表示该字段。
URLField
class URLField([max_length=200, **options])
用于保存URL的CharField。默认为200的max_length默认为TextInput窗体。若verify_exists参数为True(默认)，给定的URL会预先检查是否存在(即URL是否被有效装入且没有返回404响应)。
UUIDField
class UUIDField([**options])
New in Django 1.8.
一个用于存储全局唯一标识符字段。使用Python的UUID类。当使用PostgreSQL，本店在一个UUID数据类型，否则为一个char(32)。
建议使用默认：
import uuid
from django.db import models
class MyUUIDModel(models.Model):
id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
# other fields
Note that a callable (with the parentheses omitted) is passed to default, not an instance of UUID.
参考文献
申明：
此文章发表于：http://www.ttwshell.com/ 转载需带上此声明。
