django model API参考

最新推荐文章于 2024-08-05 10:23:16 发布

阳光下的小博

最新推荐文章于 2024-08-05 10:23:16 发布

阅读量1k

点赞数

分类专栏： python相关文章标签： django api 数据库 input null javascript

本文链接：https://blog.csdn.net/shuxiaomeng/article/details/6544306

版权

python相关专栏收录该内容

7 篇文章 0 订阅

订阅专栏

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

基本概念:

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

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

快速示例

本例子中定义了一个 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语句.

字段

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

示例:

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 对模型的字段名仅有两个小小的限制:

字段名不能是 Python 保留字, 否则显然会导致 Python 语法错误:
class Example(models.Model):

     pass = models.IntegerField() # 'pass' is a reserved word!
字段名中至多只允许有一个下划线, 否则 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 当对象首次被创建时,自动将该字段的值设置为当前时间.通常用于表示对象创建时间.

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 需要以下步骤:

在你的 settings 文件中, 定义一个完整路径给 MEDIA_ROOT 以便让 Django在此处保存上传文件. (出于性能考虑,这些文件并不保存到数据库.) 定义 MEDIA_URL 作为该目录的公共 URL. 要确保该目录对 WEB 服务器用户帐号是可写的.
在你的 model 中添加 FileField 或 ImageField , 并确保定义了 upload_to 选项,以告诉 Django 使用 MEDIA_ROOT 的哪个子目录保存上传文件.
你的数据库中要保存的只是文件的路径(相对于 MEDIA_ROOT ). 出于习惯你一定很想使用 Django 提供的 get_<fieldname>_url 函数.举例来说,如果你的 ImageField 叫作 mug_shot , 你就可以在模板中以 {{ object.get_mug_shot_url }} 这样的方式得到图像的绝对路径.

FilePathField

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

参数描述
path 必需参数. 一个目录的绝对文件系统路径. FilePathField 据此得到可选项目. Example: "/home/images" .
match 可选参数. 一个正则表达式, 作为一个字符串, FilePathField 将使用它过滤文件名. 注意这个正则表达式只会应用到 base filename 而不是路径全名. Example: "foo.*/.txt^" , 将匹配文件 foo23.txt 却不匹配 bar.txt 或 foo23.gif .
recursive 可选参数.要么 True 要么 False . 默认值是 False . 是否包括 path 下面的全部子目录.

参数	描述
`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 小数位数

参数	描述
`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 .

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 的文件系统路径.

字段选项

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

`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 的第一个元素是要保存的真实值. 第二个元素则是第一个元素的更易理解的描述.