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/ 轉載需帶上此聲明。