`attr` 命名空间API参考¶

备注

这些是传统的 API，其创建早于类型注解。它们不是被弃用，但我们建议在新代码中使用 attrs 命名空间，因为它们看起来更美观，且具有更好的默认值。

核心(Core)¶

attr.s(these=None, repr_ns=None, repr=None, cmp=None, hash=None, init=None, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False, eq=None, order=None, auto_detect=False, collect_by_mro=False, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True, unsafe_hash=None)¶

一个类装饰器，根据指定的属性使用 attr.ib 或 these 参数添加双下划线方法。

考虑在新代码中使用 attrs.define / attrs.frozen ( attr.s 将永远不会消失)。

参数:: repr_ns (str) -- 在使用嵌套类时，Python 2 中没有办法自动检测这一点。此参数允许设置一个自定义名称以获得更有意义的 repr 输出。此参数在 Python 3 中是无用的，因此被弃用。

小心

请参考 attrs.define 的其余参数，但请注意它们可能有不同的默认值。

特别是，on_setattr 保持为 None 将不会添加任何钩子。

Added in version 16.0.0: slots

Added in version 16.1.0: frozen

Added in version 16.3.0: str

Added in version 16.3.0: 支持 __attrs_post_init__。

在 17.1.0 版本发生变更: hash 现在支持 None 作为值，这也是默认值。

Added in version 17.3.0: auto_attribs

在 18.1.0 版本发生变更: 如果传递了 these ，则不会从类体中删除任何属性。

在 18.1.0 版本发生变更: 如果 these 是有序的，则保留顺序。

Added in version 18.2.0: weakref_slot

自 18.2.0 版本弃用: __lt__, __le__, __gt__, 和 __ge__ 现在如果被比较的类是彼此的子类，将引发 DeprecationWarning。__eq 和 __ne__ 从未尝试比较子类。

在 19.2.0 版本发生变更: __lt__, __le__, __gt__, 和 __ge__ 现在不再认为子类可比较。

Added in version 18.2.0: kw_only

Added in version 18.2.0: cache_hash

Added in version 19.1.0: auto_exc

自 19.2.0 版本弃用: cmp 在 2021-06-01 或之后将被移除。

Added in version 19.2.0: eq 和 order

Added in version 20.1.0: auto_detect

Added in version 20.1.0: collect_by_mro

Added in version 20.1.0: getstate_setstate

Added in version 20.1.0: on_setattr

Added in version 20.3.0: field_transformer

在 21.1.0 版本发生变更: init=False 注入 __attrs_init__

在 21.1.0 版本发生变更: 支持 __attrs_pre_init__

在 21.1.0 版本发生变更: cmp 重新引入

Added in version 21.3.0: match_args

Added in version 22.2.0: unsafe_hash 作为 hash 的别名(符合 PEP 681)。

自 24.1.0 版本弃用: repr_ns

在 24.1.0 版本发生变更: 实例不再作为属性的元组进行比较，而是使用一个大的 and 条件。这更快，并且对于不可比较的值(如 math.nan)具有更正确的行为。

Added in version 24.1.0: 如果一个类有一个 继承的 类方法 __attrs_init_subclass__，则在类创建后执行。

自 24.1.0 版本弃用: hash 被弃用，取而代之的是 unsafe_hash。

例如:

>>> import attr
>>> @attr.s
... class C:
...     _private = attr.ib()
>>> C(private=42)
C(_private=42)
>>> class D:
...     def __init__(self, x):
...         self.x = x
>>> D(1)
<D object at ...>
>>> D = attr.s(these={"x": attr.ib()}, init=False)(D)
>>> D(1)
D(x=1)
>>> @attr.s(auto_exc=True)
... class Error(Exception):
...     x = attr.ib()
...     y = attr.ib(default=42, init=False)
>>> Error("foo")
Error(x='foo', y=42)
>>> raise Error("foo")
Traceback (most recent call last):
   ...
Error: ('foo', 42)
>>> raise ValueError("foo", 42)   # for comparison
Traceback (most recent call last):
   ...
ValueError: ('foo', 42)

attr.ib(default=NOTHING, validator=None, repr=True, cmp=None, hash=None, init=True, metadata=None, type=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, alias=None)¶

在类上创建一个新的字段 / 属性。

与 attrs.field 相同，只是它不是仅限关键字。

考虑在新代码中使用 attrs.field ( attr.ib 将永远不会消失)。

警告

除非类也被装饰为 attr.s (或类似的)，否则 不执行任何操作!

Added in version 15.2.0: convert

Added in version 16.3.0: metadata

在 17.1.0 版本发生变更: validator 现在可以是 list。

在 17.1.0 版本发生变更: hash 为 None，因此默认与 eq 镜像。

Added in version 17.3.0: type

自 17.4.0 版本弃用: convert

Added in version 17.4.0: converter 作为弃用的 convert 的替代，以实现与其他基于名词的参数的一致性。

Added in version 18.1.0: factory=f 是 default=attr.Factory(f) 的语法糖。

Added in version 18.2.0: kw_only

在 19.2.0 版本发生变更: 移除了 convert 关键字参数。

在 19.2.0 版本发生变更: repr 现在也接受自定义可调用对象。

自 19.2.0 版本弃用: cmp 在 2021-06-01 或之后将被移除。

Added in version 19.2.0: eq 和 order

Added in version 20.1.0: on_setattr

在 20.3.0 版本发生变更: kw_only 回溯到 Python 2

在 21.1.0 版本发生变更: eq, order, 和 cmp 现在也接受自定义可调用对象

在 21.1.0 版本发生变更: cmp 重新引入

Added in version 22.2.0: alias

备注

attrs 还附带一个重要别名 attr.attrib 。

attr.ib 返回的对象还允许使用装饰器设置默认值和验证器：

>>> @attr.s
... class C:
...     x = attr.ib()
...     y = attr.ib()
...     @x.validator
...     def _any_name_except_a_name_of_an_attribute(self, attribute, value):
...         if value < 0:
...             raise ValueError("x must be positive")
...     @y.default
...     def _any_name_except_a_name_of_an_attribute(self):
...         return self.x + 1
>>> C(1)
C(x=1, y=2)
>>> C(-1)
Traceback (most recent call last):
    ...
ValueError: x must be positive

attr.attrs()¶: attr.s 的严肃业务别名。

attr.define()¶: 与 attrs.define 一样.

attr.mutable()¶: 与 attrs.mutable 一样.

attr.frozen()¶: 与 attrs.frozen 一样.

attr.field()¶: 与 attrs.field 一样.

class attr.Attribute¶: 与 attrs.Attribute 一样.

attr.make_class()¶: 与 attrs.make_class 一样.

class attr.Factory(factory, takes_self=False)

存储一个工厂可调用对象(factory callable)。

如果作为默认值传递给 attrs.field ，则该工厂用于生成新值。

参数:

factory (Callable) -- 一个可调用对象，根据 takes_self 的值，可以不接受参数或只接受一个必需的位置参数。
takes_self (bool) -- 将正在初始化的部分初始化实例作为位置参数传递。

Added in version 17.1.0: takes_self

与 attrs.Factory 一样.

attr.NOTHING¶: 与 attrs.NOTHING 一样.

Exceptions¶

所有异常都可以从 attr.exceptions 和 attrs.exceptions 获得（它们是不同命名空间中的相同模块）。

请参阅 attrs.exceptions 了解详情。

Helpers¶

attr.cmp_using()¶: 与 attrs.cmp_using 一样.

attr.fields()¶: 与 attrs.fields 一样.

attr.fields_dict()¶: 与 attrs.fields_dict 一样.

attr.has()¶: 与 attrs.has 一样.

attr.resolve_types()¶: 与 attrs.resolve_types 一样.

attr.asdict(inst, recurse=True, filter=None, dict_factory=<class 'dict'>, retain_collection_types=False, value_serializer=None)¶

返回 inst 的 attrs 属性值作为字典。

可选择递归进入其他 attrs 装饰的类。

参数:

inst -- 一个 attrs 装饰类的实例。
recurse (bool) -- 递归进入也被 attrs 装饰的类。
filter (Callable) -- 一个可调用对象，其返回值决定一个属性或元素是否包含（True）或被丢弃（False）。作为第一个参数调用 attrs.Attribute，第二个参数为值。
dict_factory (Callable) -- 用于生成字典的可调用对象。例如，为了生成有序字典而不是普通的 Python 字典，可以传入 collections.OrderedDict。
retain_collection_types (bool) -- 遇到类型为 tuple 或 set 的属性时，不转换为 list。仅在 recurse 为 True 时有意义。
value_serializer (Callable | None) -- 针对每个属性或字典键/值调用的钩子。它接收当前实例、字段和值，并必须返回（更新后的）值。该钩子在应用可选的 filter 后运行。

返回:

返回类型为 dict_factory。

抛出:

attrs.exceptions.NotAnAttrsClassError -- 如果 cls 不是一个 attrs 类。

Added in version 16.0.0: dict_factory

Added in version 16.1.0: retain_collection_types

Added in version 20.3.0: value_serializer

Added in version 21.3.0: 如果字典中有一个键的集合，则将其序列化为元组。

attr.astuple(inst, recurse=True, filter=None, tuple_factory=<class 'tuple'>, retain_collection_types=False)¶

返回 inst 的 attrs 属性值作为元组。

可选择递归进入其他 attrs 装饰的类。

参数:

inst -- attrs 装饰类的实例。
recurse (bool) -- 是否递归进入同样被 attrs 装饰的类。
filter (Callable) -- 一个可调用对象，其返回值决定了属性或元素是被包含（True）还是被丢弃（False）。该函数的第一个参数为 attrs.Attribute，第二个参数为值。
tuple_factory (Callable) -- 用于生成元组的可调用对象。例如，可以生成列表而不是元组。
retain_collection_types (bool) -- 遇到类型为 tuple、dict 或 set 的属性时，不进行转换为 list 或 dict。只有在 recurse 为 True 时才有意义。

返回:

返回 tuple_factory 的类型。

抛出:

attrs.exceptions.NotAnAttrsClassError -- 如果 cls 不是一个 attrs 类。

Added in version 16.2.0.

attr.filters.include()¶: 与 attrs.filters.include 一样.

attr.filters.exclude()¶: 与 attrs.filters.exclude 一样.

参见 attrs.asdict() 查看更多示例.

attr.filters 中的所有对象也可在 attrs.filters 中使用。

attr.evolve()¶: 与 attrs.evolve 一样.

attr.validate()¶: 与 attrs.validate 一样.

Validators¶

所有来自 attrs.validators 的对象也可以在 attr.validators 中找到。详情请参阅前者。

Converters¶

所有来自 attrs.converters 的对象也可以从 attr.converters 获得。请参阅前者了解详情。

Setters¶

所有来自 attrs.setters 的对象也可以在 attr.setters 中使用。请参阅前者以了解详情。

Deprecated APIs¶

为了帮助您编写向后兼容的代码，在现代版本中不会引发警告， attr 模块自 19.2.0 版本起提供了一个 __version_info__ 属性。它的行为类似于 sys.version_info ，并且是 attr.VersionInfo 的一个实例：

class attr.VersionInfo(year: int, minor: int, micro: int, releaselevel: str)¶

可以与长度为 1--4 的元组进行比较的版本对象:

>>> attr.VersionInfo(19, 1, 0, "final")  <= (19, 2)
True
>>> attr.VersionInfo(19, 1, 0, "final") < (19, 1, 1)
True
>>> vi = attr.VersionInfo(19, 2, 0, "final")
>>> vi < (19, 1, 1)
False
>>> vi < (19,)
False
>>> vi == (19, 2,)
True
>>> vi == (19, 2, 1)
False

Added in version 19.2.

在它的帮助下，您可以编写如下代码：

>>> if getattr(attr, "__version_info__", (0,)) >= (19, 2):
...     cmp_off = {"eq": False}
... else:
...     cmp_off = {"cmp": False}
>>> cmp_off == {"eq":  False}
True
>>> @attr.s(**cmp_off)
... class C:
...     pass

attr.assoc(inst, **changes)¶

复制 inst 并应用 changes。

这与 evolve 不同，后者将更改应用于创建新实例的参数。

evolve 的行为是更可取的，但存在一些边缘情况，在这些情况下它不起作用。因此 assoc 被弃用，但不会被移除。

参数:

inst -- 带有 attrs 属性的类的实例。
changes -- 新副本中的关键字更改。

返回:

一个包含 changes 的 inst 的副本。

抛出:

attrs.exceptions.AttrsAttributeNotFoundError -- 如果在 cls 上找不到 attr_name。
attrs.exceptions.NotAnAttrsClassError -- 如果 cls 不是一个 attrs 类。

自 17.1.0 版本弃用: 如果可以，请改用 attrs.evolve。由于与 attrs.evolve 的略微不同的方法，这个函数不会被移除。

在 attrs 获得 attrs.validators.set_disabled 和 attrs.validators.get_disabled 之前，它有以下 API 用于全局启用和禁用验证器。这些 API 不会被移除，但不推荐使用：

attr.set_run_validators(run)¶: 设置是否运行验证器。默认情况下，它们是运行的。

自 21.3.0 版本弃用: 不会被移除，但也不会迁移到新的 attrs 命名空间。请改用 attrs.validators.set_disabled() 。

attr.get_run_validators()¶: 返回验证器是否运行。

自 21.3.0 版本弃用: 不会被移除，但也不会迁移到新的 attrs 命名空间。请改用 attrs.validators.get_disabled() 。

以前，严肃的别名被称为 attr.attributes 和 attr.attr。虽然没有计划移除它们，但不应在新代码中使用。

attr 命名空间API参考¶

核心(Core)¶

Exceptions¶

Helpers¶

Validators¶

Converters¶

Setters¶

Deprecated APIs¶

`attr` 命名空间API参考¶