字段¶

用法¶

字段被定义为 Model 类对象的属性

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=255)

参考¶

以下是可用字段的列表，其中包含这些字段的自定义选项

基本字段¶

class tortoise.fields.base.Field(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[source]¶

基本字段类型。

参数:¶

source_field=None¶

如果数据库列名称需要特定名称，而不是根据字段名称生成，则提供 source_field 名称。

generated=False¶

此字段是否为数据库生成？

primary_key=None¶

此字段是否是主键？模型上只能有一个这样的字段，如果没有指定，它将自动生成一个名为 id 的默认主键。

null=False¶

此字段是否可为空？

default=None¶

如果在创建模型时未指定，则为字段设置默认值。这也可以是动态默认值的调用，在这种情况下，我们将调用它。默认值不会成为模式的一部分。

unique=False¶

此字段是否唯一？

db_index=None¶

此字段是否应由自身索引？

description=None¶

字段描述。还将显示在 Tortoise.describe_model() 中，并作为生成的 DDL 中的 DB 注释。

validators=None¶

此字段的验证器。

类属性：定义实际字段类型时需要定义这些属性。

field_type Type[Any]¶

字段的 Python 类型。如果添加类型作为 mixin，_FieldMeta 会自动将其设置为该类型。

indexable bool = True¶

字段是否可索引？如果此字段无法可靠地索引，则设置为 False。

has_db_field bool = True¶

此字段是否有直接对应的 DB 列？或者字段是否虚拟化？

skip_to_python_if_native bool = False¶

如果 DB 驱动程序本机支持此 Python 类型，我们是否应该跳过它？这仅用于优化目的，我们不需要在 Python 和 DB 之间强制进行类型转换。

allows_generated bool = False¶

此字段是否能够由 DB 生成？

function_cast Optional[pypika.Term] = None¶

如果 DB 需要仿真帮助，我们需要应用的转换项。

SQL_TYPE str¶

数据库将使用的 SQL 类型（字符串形式）。

GENERATED_SQL str¶

指示数据库自动生成此字段的 SQL。如果 allows_generated 为 True，则此项为必填项。

按数据库进行覆盖

可以按数据库指定任何类属性或 to_db_value 或 to_python_value 方法的覆盖。

为此，请指定一个内部类，形式为 class _db__SQL_DIALECT:，如下所示

class _db_sqlite:
    SQL_TYPE = "VARCHAR(40)"
    skip_to_python_if_native = False

    def function_cast(self, term: Term) -> Term:
        return functions.Cast(term, SqlTypes.NUMERIC)

然后，Tortoise 将针对该方言使用覆盖的属性/函数。如果需要动态属性，可以使用属性。

property constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

describe(serializable)[source]¶

描述字段。

参数:¶

serializable¶

如果想要原始 Python 对象，则为 False，如果想要可 JSON 序列化的数据，则为 True。（默认为 True）

返回类型:¶

dict

返回:¶

包含字段描述的字典。

（这假定 serializable=True，这是默认值）

{
    "name":         str     # Field name
    "field_type":   str     # Field type
    "db_column":    str     # Name of DB column
                            #  Optional: Only for pk/data fields
    "raw_field":    str     # Name of raw field of the Foreign Key
                            #  Optional: Only for Foreign Keys
    "db_field_types": dict  # DB Field types for default and DB overrides
    "python_type":  str     # Python type
    "generated":    bool    # Is the field generated by the DB?
    "nullable":     bool    # Is the column nullable?
    "unique":       bool    # Is the field unique?
    "indexed":      bool    # Is the field indexed?
    "default":      ...     # The default value (coerced to int/float/str/bool/null)
    "description":  str     # Description of the field (nullable)
    "docstring":    str     # Field docstring (nullable)
}

当指定 serializable=False 时，某些字段不会强制转换为有效的 JSON 类型。更改如下

{
    "field_type":   Field   # The Field class used
    "python_type":  Type    # The actual Python type
    "default":      ...     # The default value as native type OR a callable
}

get_db_field_types()[source]¶

返回此字段的数据库类型。

返回类型:¶

Optional[Dict[str, str]]

返回:¶

按方言键入的字典。空白方言 “” 表示它是默认数据库字段类型。

get_for_dialect(dialect, key)[source]¶

按方言覆盖返回字段。

参数:¶

dialect¶

请求的 SQL 方言。

key¶

属性/方法名称。

返回类型:¶

任意

property required : bool¶

如果必须提供该字段，则返回 True。

它需要是不可为空的，并且没有默认值或由数据库生成才能是必需的。

返回类型:¶

bool

to_db_value(value, instance)[source]¶

从 Python 类型转换为数据库类型。

参数:¶

value¶

模型中的当前 Python 值。

instance¶

提供要查找的模型类或模型实例。

由于元编码，要可靠地确定这是实例，请执行

if hasattr(instance, "_saved_in_db"):

返回类型:¶

任意

to_python_value(value)[source]¶

从 DB 类型转换为 Python 类型。

参数:¶

value¶

来自 DB 的值

返回类型:¶

任意

validate(value)[source]¶

验证给定值是否有效

参数:¶

value¶

要验证的值

引发:¶

ValidationError – 如果未通过验证器检查

class tortoise.fields.base.OnDelete(value)[source]¶

枚举。

CASCADE = 'CASCADE'¶

NO_ACTION = 'NO ACTION'¶

RESTRICT = 'RESTRICT'¶

SET_DEFAULT = 'SET DEFAULT'¶

SET_NULL = 'SET NULL'¶

class tortoise.fields.base.StrEnum(value)[source]¶

枚举。

数据字段¶

class tortoise.fields.data.BigIntField(primary_key=None, **kwargs)[source]¶

大整数字段。（64 位有符号整数）

primary_key (布尔值)

如果字段是主键，则为 True。

property constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

类 tortoise.fields.data.BinaryField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

二进制字段。

用于存储 bytes 对象。请注意，不支持过滤器或查询集更新操作。

field_type¶

bytes 的别名

类 tortoise.fields.data.BooleanField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

布尔字段。

field_type¶

bool 的别名

tortoise.fields.data.CharEnumField(enum_type, description=None, max_length=0, **kwargs)[源代码]¶

字符枚举字段

表示字符枚举的字段。

警告：如果未指定 max_length 或其等于零，则会自动检测表示的字符字段的大小。因此，如果你稍后更新枚举，则还需要更新表架构。

注意： enum_type 的有效 str 值是可接受的。

enum_type:

枚举类

description:

字段的描述。如果未指定为“名称：值”对的多行列表，则会自动设置。

max_length:

创建的 CharField 的长度。如果为零，则会从 enum_type 自动检测。

返回类型:¶

枚举

class tortoise.fields.data.CharField(max_length, **kwargs)[source]¶

字符字段。

你必须提供以下内容

max_length (int)

字段的最大长度（以字符为单位）。

property constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

field_type¶

str 的别名

类 tortoise.fields.data.DateField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

日期字段。

field_type¶

date 的别名

类 tortoise.fields.data.DatetimeField(auto_now=False, auto_now_add=False, **kwargs)[源代码]¶

Datetime 字段。

auto_now 和 auto_now_add 是互斥的。你可以选择不设置或仅设置其中一个。

auto_now (bool)

始终在保存时设置为 datetime.utcnow()。

auto_now_add (bool)

仅在首次保存时设置为 datetime.utcnow()。

property constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

describe(serializable)[source]¶

描述字段。

参数:¶

serializable¶

如果想要原始 Python 对象，则为 False，如果想要可 JSON 序列化的数据，则为 True。（默认为 True）

返回类型:¶

dict

返回:¶

包含字段描述的字典。

（这假定 serializable=True，这是默认值）

{
    "name":         str     # Field name
    "field_type":   str     # Field type
    "db_column":    str     # Name of DB column
                            #  Optional: Only for pk/data fields
    "raw_field":    str     # Name of raw field of the Foreign Key
                            #  Optional: Only for Foreign Keys
    "db_field_types": dict  # DB Field types for default and DB overrides
    "python_type":  str     # Python type
    "generated":    bool    # Is the field generated by the DB?
    "nullable":     bool    # Is the column nullable?
    "unique":       bool    # Is the field unique?
    "indexed":      bool    # Is the field indexed?
    "default":      ...     # The default value (coerced to int/float/str/bool/null)
    "description":  str     # Description of the field (nullable)
    "docstring":    str     # Field docstring (nullable)
}

当指定 serializable=False 时，某些字段不会强制转换为有效的 JSON 类型。更改如下

{
    "field_type":   Field   # The Field class used
    "python_type":  Type    # The actual Python type
    "default":      ...     # The default value as native type OR a callable
}

field_type¶

datetime 的别名

class tortoise.fields.data.DecimalField(max_digits, decimal_places, **kwargs)[source]¶

精确的小数字段。

你必须提供以下内容

max_digits (int)

小数字段的有效数字的最大位数。

decimal_places (int)

小数点后有效数字的位数。

field_type¶

Decimal 的别名

类 tortoise.fields.data.FloatField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

浮点（双精度）字段。

field_type¶

float 的别名

tortoise.fields.data.IntEnumField(enum_type, description=None, **kwargs)[源代码]¶

枚举字段

表示整数枚举的字段。

如果未指定为多行“名称：值”对列表，则自动设置字段的描述。

注意：enum_type 的有效 int 值是可接受的。

enum_type:

枚举类

description:

字段的描述。如果未指定为“名称：值”对的多行列表，则会自动设置。

返回类型:¶

IntEnum

class tortoise.fields.data.IntField(primary_key=None, **kwargs)[source]¶

整数字段。（32 位有符号）

primary_key (布尔值)

如果字段是主键，则为 True。

property constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

field_type¶

int 的别名

class tortoise.fields.data.JSONField(encoder=<function <lambda>>, decoder=<built-in function loads>, **kwargs)[source]¶

JSON 字段。

此字段可以存储任何 JSON 兼容结构的字典或列表。

你可以指定你自己的自定义 JSON 编码器/解码器，保留默认值应该可以很好地工作。如果你安装了 orjson，我们默认使用它，否则将使用默认的 json 模块。

encoder:

自定义 JSON 编码器。

decoder:

自定义 JSON 解码器。

类 tortoise.fields.data.SmallIntField(primary_key=None, **kwargs)[源代码]¶

小整数字段。（16 位有符号）

primary_key (布尔值)

如果字段是主键，则为 True。

属性 constraints : dict¶

返回一个包含 Pydantic/JSONSchema 格式中定义的约束的字典。

返回类型:¶

dict

类 tortoise.fields.data.TextField(primary_key=None, unique=False, db_index=False, **kwargs)[源代码]¶

大文本字段。

field_type¶

str 的别名

类 tortoise.fields.data.TimeDeltaField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

用于存储时间差的字段。

类 tortoise.fields.data.UUIDField(**kwargs)[源代码]¶

UUID 字段

此字段可以存储 uuid 值。

如果用作主键，它将默认自动生成 UUID4。

field_type¶

UUID 的别名

关系字段¶

tortoise.fields.relational.ForeignKeyField(model_name: str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, *, null: True, **kwargs: Any) → ForeignKeyFieldInstance[MODEL] | None[source]¶

tortoise.fields.relational.ForeignKeyField(model_name: str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, null: False = False, **kwargs: Any) → ForeignKeyFieldInstance[MODEL]

外键关系字段。

此字段表示与另一个模型的外键关系。

有关用法信息，请参见外键。

你必须提供以下内容

model_name:

相关模型的名称，格式为'app.model'。

以下内容是可选的

related_name:

相关模型上的属性名称，用于反向解析外键。

on_delete:

其中之一

field.CASCADE:

指示如果删除相关模型，则应级联删除该模型。

field.RESTRICT:

指示只要外键指向相关模型，则将限制删除相关模型。

field.SET_NULL:

如果删除相关模型，则将字段重置为 NULL。仅当字段已设置null=True时才能设置。

field.SET_DEFAULT:

如果删除相关模型，则将字段重置为default值。仅当字段已设置default时才能设置。

field.NO_ACTION:

不采取任何操作。

to_field:

相关模型上的属性名称，用于建立外键关系。如果未设置，则使用 pk

db_constraint:

控制是否应为此外键在数据库中创建约束。默认值为 True，这几乎肯定是你想要的；将其设置为 False 可能对数据完整性非常不利。

tortoise.fields.relational.ManyToManyField(model_name, through=None, forward_key=None, backward_key='', related_name='', on_delete=OnDelete.CASCADE, db_constraint=True, create_unique_index=True, **kwargs)[source]¶

多对多关系字段。

此字段表示此模型与另一个模型之间的多对多关系。

有关用法信息，请参见多对多。

你必须提供以下内容

model_name:

相关模型的名称，格式为'app.model'。

以下内容是可选的

through:

表示中间表的数据库表。默认值通常是安全的。

forward_key:

中间表上的正向查找键。默认值通常是安全的。

backward_key:

中间表上的反向查找键。默认值通常是安全的。

related_name:

相关模型上的属性名称，用于反向解析多对多关系。

db_constraint:

控制是否应为此外键在数据库中创建约束。默认值为 True，这几乎肯定是你想要的；将其设置为 False 可能对数据完整性非常不利。

on_delete:

其中之一

field.CASCADE:

指示如果删除相关模型，则应级联删除该模型。

field.RESTRICT:

指示只要外键指向相关模型，则将限制删除相关模型。

field.SET_NULL:

如果删除相关模型，则将字段重置为 NULL。仅当字段已设置null=True时才能设置。

field.SET_DEFAULT:

如果删除相关模型，则将字段重置为default值。仅当字段已设置default时才能设置。

field.NO_ACTION:

不采取任何操作。

create_unique_index:

控制是否应在数据库中创建唯一索引以加快选择查询。默认值为 True。如果您希望允许重复记录，请将其设置为 False。

返回类型:¶

ManyToManyRelation[Any]

tortoise.fields.relational.OneToOneField(model_name: str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, *, null: True, **kwargs: Any) → OneToOneFieldInstance[MODEL] | None[source]¶

tortoise.fields.relational.OneToOneField(model_name: str, related_name: str | None | False = None, on_delete: OnDelete = CASCADE, db_constraint: bool = True, null: False = False, **kwargs: Any) → OneToOneFieldInstance[MODEL]

一对一关系字段。

此字段表示与另一个模型的外键关系。

有关用法信息，请参见 一对一。

你必须提供以下内容

model_name:

相关模型的名称，格式为'app.model'。

以下内容是可选的

related_name:

相关模型上的属性名称，用于反向解析外键。

on_delete:

其中之一

field.CASCADE:

指示如果删除相关模型，则应级联删除该模型。

field.RESTRICT:

指示只要外键指向相关模型，则将限制删除相关模型。

field.SET_NULL:

如果删除相关模型，则将字段重置为 NULL。仅当字段已设置null=True时才能设置。

field.SET_DEFAULT:

如果删除相关模型，则将字段重置为default值。仅当字段已设置default时才能设置。

field.NO_ACTION:

不采取任何操作。

to_field:

相关模型上的属性名称，用于建立外键关系。如果未设置，则使用 pk

db_constraint:

控制是否应为此外键在数据库中创建约束。默认值为 True，这几乎肯定是你想要的；将其设置为 False 可能对数据完整性非常不利。

特定于数据库的字段¶

MySQL¶

类 tortoise.contrib.mysql.fields.GeometryField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

类 tortoise.contrib.mysql.fields.UUIDField(binary_compression=True, **kwargs)[源代码]¶

UUID 字段

此字段可以存储 uuid 值，但可以选择添加二进制压缩。

如果用作主键，它将默认自动生成 UUID4。

binary_compression (布尔值)

如果为 True，则 UUID 将以二进制格式存储。这将在数据库中为每个 UUID 节省 6 个字节。注意：这是一个仅限 MySQL 的功能。有关更多详细信息，请参阅 https://dev.mysqlserver.cn/blog-archive/mysql-8-0-uuid-support/。

to_db_value(value, instance)[source]¶

从 Python 类型转换为数据库类型。

参数:¶

value¶

模型中的当前 Python 值。

instance¶

提供要查找的模型类或模型实例。

由于元编码，要可靠地确定这是实例，请执行

if hasattr(instance, "_saved_in_db"):

返回类型:¶

Union[str, bytes, None]

to_python_value(value)[source]¶

从 DB 类型转换为 Python 类型。

参数:¶

value¶

来自 DB 的值

返回类型:¶

Optional[UUID]

Postgres¶

类 tortoise.contrib.postgres.fields.TSVectorField(source_field=None, generated=False, primary_key=None, null=False, default=None, unique=False, db_index=None, description=None, model=None, validators=None, **kwargs)[源代码]¶

扩展字段¶

可以对字段进行子类化，允许使用任意类型，只要它们可以用与数据库兼容的格式表示即可。一个示例是围绕 CharField 的一个简单包装器，用于存储和查询枚举类型。

from enum import Enum
from typing import Type

from tortoise import ConfigurationError
from tortoise.fields import CharField


class EnumField(CharField):
    """
    An example extension to CharField that serializes Enums
    to and from a str representation in the DB.
    """

    def __init__(self, enum_type: Type[Enum], **kwargs):
        super().__init__(128, **kwargs)
        if not issubclass(enum_type, Enum):
            raise ConfigurationError("{} is not a subclass of Enum!".format(enum_type))
        self._enum_type = enum_type

    def to_db_value(self, value: Enum, instance) -> str:
        return value.value

    def to_python_value(self, value: str) -> Enum:
        try:
            return self._enum_type(value)
        except Exception:
            raise ValueError(
                "Database value {} does not exist on Enum {}.".format(value, self._enum_type)
            )

在进行子类化时，请确保 to_db_value 返回与超类相同的类型（在 CharField 的情况下，即 str），并且 to_python_value 自然接受值参数中相同的类型（也为 str）。