heat.db.types 模块

class heat.db.types.Json(*args: Any, **kwargs: Any)[source]

基类: LongText

cache_ok: bool | None = True

指示使用此 ExternalType 的语句是否“可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型语句的缓存，而无需发出警告。当设置为 True 时，该对象的类及其状态中的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中的参数名称对应的属性。上述示例中，“choices”属性成为缓存键的一部分，但“internal_only”则不然，因为没有名为“internal_only”的参数。

可缓存元素的必要条件是它们是可哈希的，并且对于给定缓存值，它们表示相同的 SQL 渲染表达式。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与参数名称对应的属性来使这些对象“可缓存”。例如，接受查找值字典的数据类型可以将此值作为排序后的元组序列发布。给定先前不可缓存的类型如下

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中“lookup”是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果确实设置了这样的缓存键，它将无法使用。我们将获得一个包含字典的元组结构，而该字典本身不能用作 SQLAlchemy 的语句缓存等“缓存字典”中的键，因为 Python 字典不可哈希

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序后的元组的元组分配给“.lookup”属性来使该类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

上述示例中，LookupType({"a": 10, "b": 20}) 的缓存键将为

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

在 1.4.14 版本中添加: - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

在 1.4.28 版本中添加: - 添加了 ExternalType 混合类，该混合类将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

参见

SQL 编译缓存

process_bind_param(value, dialect)[source]

接收要转换的绑定参数值。

自定义的 _types.TypeDecorator 子类应重写此方法，以提供自定义的传入数据行为。此方法在语句执行时调用，并传递与语句中绑定参数关联的字面 Python 数据值。

操作可以是所需的任何操作，例如转换或序列化数据。这也可以用作验证逻辑的钩子。

参数：

  • value – 要操作的数据，可以是子类中此方法期望的任何类型。可以是 None。

  • dialect – 使用的 Dialect。

参见

增强现有类型

_types.TypeDecorator.process_result_value()

process_result_value(value, dialect)[source]

接收要转换的来自结果行中的列值。

自定义的 _types.TypeDecorator 子类应重写此方法，以提供自定义的数据行为，这些数据行为是在从数据库接收结果行时收到的。此方法在结果获取时调用，并传递从数据库结果行中提取的字面 Python 数据值。

操作可以是所需的任何操作，例如转换或反序列化数据。

参数：

  • value – 要操作的数据，可以是子类中此方法期望的任何类型。可以是 None。

  • dialect – 使用的 Dialect。

参见

增强现有类型

_types.TypeDecorator.process_bind_param()

class heat.db.types.List(*args: Any, **kwargs: Any)[source]

基类: TypeDecorator

cache_ok: bool | None = True

指示使用此 ExternalType 的语句是否“可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型语句的缓存，而无需发出警告。当设置为 True 时，该对象的类及其状态中的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中的参数名称对应的属性。上述示例中，“choices”属性成为缓存键的一部分，但“internal_only”则不然，因为没有名为“internal_only”的参数。

可缓存元素的必要条件是它们是可哈希的，并且对于给定缓存值，它们表示相同的 SQL 渲染表达式。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与参数名称对应的属性来使这些对象“可缓存”。例如，接受查找值字典的数据类型可以将此值作为排序后的元组序列发布。给定先前不可缓存的类型如下

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中“lookup”是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果确实设置了这样的缓存键，它将无法使用。我们将获得一个包含字典的元组结构，而该字典本身不能用作 SQLAlchemy 的语句缓存等“缓存字典”中的键，因为 Python 字典不可哈希

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序后的元组的元组分配给“.lookup”属性来使该类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

上述示例中，LookupType({"a": 10, "b": 20}) 的缓存键将为

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

在 1.4.14 版本中添加: - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

在 1.4.28 版本中添加: - 添加了 ExternalType 混合类，该混合类将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

参见

SQL 编译缓存

impl

别名: Text

load_dialect_impl(dialect)[source]

返回与方言对应的 TypeEngine 对象。

这是一个用户覆盖钩子，可用于为给定的方言提供不同的类型。它由 TypeDecorator 实现的 type_engine() 使用，以帮助确定应为给定的 TypeDecorator 返回什么类型。

默认情况下返回 self.impl。

process_bind_param(value, dialect)[source]

接收要转换的绑定参数值。

自定义的 _types.TypeDecorator 子类应重写此方法，以提供自定义的传入数据行为。此方法在语句执行时调用，并传递与语句中绑定参数关联的字面 Python 数据值。

操作可以是所需的任何操作，例如转换或序列化数据。这也可以用作验证逻辑的钩子。

参数：

  • value – 要操作的数据，可以是子类中此方法期望的任何类型。可以是 None。

  • dialect – 使用的 Dialect。

参见

增强现有类型

_types.TypeDecorator.process_result_value()

process_result_value(value, dialect)[source]

接收要转换的来自结果行中的列值。

自定义的 _types.TypeDecorator 子类应重写此方法，以提供自定义的数据行为，这些数据行为是在从数据库接收结果行时收到的。此方法在结果获取时调用，并传递从数据库结果行中提取的字面 Python 数据值。

操作可以是所需的任何操作，例如转换或反序列化数据。

参数：

  • value – 要操作的数据，可以是子类中此方法期望的任何类型。可以是 None。

  • dialect – 使用的 Dialect。

参见

增强现有类型

_types.TypeDecorator.process_bind_param()

class heat.db.types.LongText(*args: Any, **kwargs: Any)[source]

基类: TypeDecorator

cache_ok: bool | None = True

指示使用此 ExternalType 的语句是否“可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型语句的缓存，而无需发出警告。当设置为 True 时，该对象的类及其状态中的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中的参数名称对应的属性。上述示例中，“choices”属性成为缓存键的一部分，但“internal_only”则不然，因为没有名为“internal_only”的参数。

可缓存元素的必要条件是它们是可哈希的，并且对于给定缓存值，它们表示相同的 SQL 渲染表达式。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与参数名称对应的属性来使这些对象“可缓存”。例如，接受查找值字典的数据类型可以将此值作为排序后的元组序列发布。给定先前不可缓存的类型如下

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中“lookup”是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果确实设置了这样的缓存键，它将无法使用。我们将获得一个包含字典的元组结构，而该字典本身不能用作 SQLAlchemy 的语句缓存等“缓存字典”中的键，因为 Python 字典不可哈希

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序后的元组的元组分配给“.lookup”属性来使该类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

上述示例中，LookupType({"a": 10, "b": 20}) 的缓存键将为

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

在 1.4.14 版本中添加: - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

在 1.4.28 版本中添加: - 添加了 ExternalType 混合类，该混合类将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

参见

SQL 编译缓存

impl

别名: Text

load_dialect_impl(dialect)[source]

返回与方言对应的 TypeEngine 对象。

这是一个用户覆盖钩子，可用于为给定的方言提供不同的类型。它由 TypeDecorator 实现的 type_engine() 使用，以帮助确定应为给定的 TypeDecorator 返回什么类型。

默认情况下返回 self.impl。