本文由 大侠(AhcaoZhu)原创，转载请声明。
链接: https://blog.csdn.net/Ahcao2008
一图看懂 attrs 模块：一个在类定义时可替换 `__init__`, `__eq__`, `__repr__`等方法的样板，资料整理+笔记（大全）
- 🧊摘要
- 🧊模块图
- 🧊类关系图
- 🧊模块全展开
- ☘️【attrs】
- 🔵统计
- 🔵常量
- 🔵模块
- 🌿1 attrs.converters
- 🌿2 attrs.exceptions
- 🌿3 attrs.filters
- 🌿4 attrs.setters
- 🌿5 attrs.validators
- 🔵函数
- 🌿6 assoc(inst, **changes)
- 🌿7 cmp_using(eq=None, lt=None, le=None, gt=None, ge=None, require_same_type=True, class_name='Comparable')
- 🌿8 define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
- 🌿9 evolve(inst, **changes)
- 🌿10 field(*, default=NOTHING, validator=None, repr=True, hash=None, init=True, metadata=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, alias=None)
- 🌿11 fields(cls)
- 🌿12 fields_dict(cls)
- 🌿13 has(cls)
- 🌿14 make_class(name, attrs, bases=(<class 'object'>,), **attributes_arguments)
- 🌿15 define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
- 🌿16 resolve_types(cls, globalns=None, localns=None, attribs=None)
- 🌿17 validate(inst)
- 🌿18 asdict(inst, *, recurse=True, filter=None, value_serializer=None)
- 🌿19 astuple(inst, *, recurse=True, filter=None)
- 🔵类
- 🌿20 attr._make.Attribute
- data
- method
- 18 evolve()
- class method
- 19 from_counting_attr()
- 🌿21 attr.AttrsInstance
- 🌿22 attr._make.Factory
- data
- 🔵剩余
- ☘️【attrs.converters】
- ☘️【attrs.exceptions】
- ☘️【attrs.filters】
- ☘️【attrs.setters】
- ☘️【attrs.validators】
🧊摘要
- 全文介绍python的 attrs 模块（一个在类定义时可替换
__init__,__eq__,__repr__等方法的样板）、函数、类及类的方法和属性。- 它通过代码抓取并经AI智能翻译和人工校对。
- 是一部不可多得的权威字典类工具书。它是系列集的一部分。后续陆续发布、敬请关注。【原创：AhcaoZhu大侠】
🧊模块图
attrs
attrs.converters
attrs.exceptions
attrs.filters
attrs.setters
attrs.validators
🧊类关系图
◆object
◆BaseException
◆Exception
◆AttributeError
attr.exceptions.FrozenError
attr.exceptions.FrozenAttributeError
attr.exceptions.FrozenInstanceError
◆RuntimeError
attr.exceptions.DefaultAlreadySetError
attr.exceptions.PythonTooOldError
attr.exceptions.UnannotatedAttributeError
◆TypeError
attr.exceptions.NotCallableError
◆ValueError
attr.exceptions.AttrsAttributeNotFoundError
attr.exceptions.NotAnAttrsClassError
attr.AttrsInstance
attr._make.Attribute
attr._make.Factory
🧊模块全展开
☘️【attrs】
attrs, fullname=attrs, file=attrs_init_.py
没有样板的类<https://www.attrs.org/>
🔵统计
| 序号 | 类别 | 数量 |
|---|---|---|
| 4 | str | 13 |
| 6 | list | 2 |
| 8 | dict | 1 |
| 9 | module | 5 |
| 10 | class | 3 |
| 11 | function | 14 |
| 13 | residual | 5 |
| 14 | system | 19 |
| 16 | all | 43 |
🔵常量
🔵模块
🌿1 attrs.converters
converters, fullname=attrs.converters, file=attrs\converters.py
🌿2 attrs.exceptions
exceptions, fullname=attrs.exceptions, file=attrs\exceptions.py
🌿3 attrs.filters
filters, fullname=attrs.filters, file=attrs\filters.py
🌿4 attrs.setters
setters, fullname=attrs.setters, file=attrs\setters.py
🌿5 attrs.validators
validators, fullname=attrs.validators, file=attrs\validators.py
🔵函数
🌿6 assoc(inst, **changes)
assoc(inst, **changes), module=attr._funcs, line:302 at site-packages\attr_funcs.py
复制 *inst*和应用 *changes*。
:param inst:具有``attrs``属性的类实例。
:param changes:新副本中关键字的变化。
:return: 包含了*changes*的inst副本。
:raise attr.exceptions.AttrsAttributeNotFoundError: 如果无法在 *cls* 上找到*attr_name*。
:raise attr.exceptions.NotAnAttrsClassError: If *cls*不是一个 ``attrs`` 类。
已弃用: 17.1.0
此函数不会因为与`attrs.evolve`略有不同的方法而被删除。
🌿7 cmp_using(eq=None, lt=None, le=None, gt=None, ge=None, require_same_type=True, class_name=‘Comparable’)
cmp_using(eq=None, lt=None, le=None, gt=None, ge=None, require_same_type=True, class_name=‘Comparable’), module=attr._cmp, line:13 at site-packages\attr_cmp.py
创建一个类，可以传递给`attr.ib`类的参数：``eq``, ``order``, 和 ``cmp``用于定制字段比较。
如果提供了 ``{lt, le, gt, ge}`` 和 ``eq`` 中的至少一个，则生成的类将具有完整的排序方法集。
:param Optional[callable] eq: `callable` 用于计算两个对象的相等性。
:param Optional[callable] lt: `callable` 用于计算一个对象是否小于另一个对象。
:param Optional[callable] le: `callable` 用于计算一个对象是否小于或等于另一个对象。
:param Optional[callable] gt: `callable`用于计算一个对象是否大于另一个对象。
:param Optional[callable] ge: `callable` 用于计算一个对象是否大于或等于另一个对象。
:param bool require_same_type: 当 `True` 时，如果对象不是相同类型，相等和排序方法将返回 `NotImplemented`。
:param Optional[str] class_name: 类名。缺省为 'Comparable'。
详情参见：`comparison`
添加版本: 21.1.0
🌿8 define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True), module=attr._next_gen, line:24 at site-packages\attr_next_gen.py
定义一个``attrs``类。
与它下面使用的经典 `attr.s` 的区别:
-自动检测 *auto_attribs* 是否应该为 `True`。
-如果 *frozen* 为 `False`，默认设置属性时运行转换器和验证器。
- *slots=True*
警告:
通常这在日常编程中只有好处，很少有明显的影响。但它 *可能* 会导致一些令人惊讶的行为，所以请确保阅读 :term:`slotted classes`。
- *auto_exc=True*
- *auto_detect=True*
- *order=False*
- Some options that were only relevant on Python 2 or were kept around for
backwards-compatibility have been removed.
- 一些仅与Python 2相关或为向后兼容而保留的选项已被删除。
请注意，这些都是默认值，您可以根据需要更改它们。
:param Optional[bool] auto_attribs: 如果设置为 `True` 或 `False`，它的行为与 `attr.s` 完全相同。
如果留下 `None`, `attr.s` 会试着猜测:
1. 如果任何属性都有注释，并且没有未注释的 `attrs.fields`字段发现，则假设 *auto attributes =True*。
2. 否则，它假设*auto attributes =False*并尝试收集`attrs.fields`。
目前，请参考 `attr.s` 表示其他参数。
添加版本： 20.1.0
版本变更: 21.3.0 转换器也运行``on_setattr``。
添加版本: 22.2.0
*unsafe_hash* 作为 *hash* 的别名(对于 :pep:`681` 合规)。
🌿9 evolve(inst, **changes)
evolve(inst, **changes), module=attr._funcs, line:340 at site-packages\attr_funcs.py
创建一个新的实例，基于*inst*，应用*changes*。
:param inst:具有“attrs”属性的类实例。
:param changes:新副本中关键字的变化。
:return: 包含了*changes*的inst副本。
:raise TypeError: 如果在类 ``__init__`` 中找不到*attr_name*。
:raise attr.exceptions.NotAnAttrsClassError: If *cls*不是一个``attrs``类。
版本添加: 17.1.0
🌿10 field(*, default=NOTHING, validator=None, repr=True, hash=None, init=True, metadata=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, alias=None)
field(*, default=NOTHING, validator=None, repr=True, hash=None, init=True, metadata=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, alias=None), module=attr._next_gen, line:162 at site-packages\attr_next_gen.py
和 `attr.ib` ，除了仅关键字和删除了一些参数。
添加版本：20.1.0
🌿11 fields(cls)
fields(cls), module=attr._make, line:1901 at site-packages\attr_make.py
返回一个类的``attrs``属性元组。
元组还允许通过名称访问字段(参见下面的示例)。
:param type cls: 要内省的类。
:raise TypeError:如果*cls*不是一个类。
:raise attr.exceptions.NotAnAttrsClassError: 如果 *cls* 不是``attrs``类。
:rtype: `attrs.Attribute`的元组(带名称访问器)
版本变更: 16.2.0 版返回的元组允许按名称访问字段。
🌿12 fields_dict(cls)
fields_dict(cls), module=attr._make, line:1927 at site-packages\attr_make.py
返回一个类的``attrs``属性的有序字典，其键是属性名。
:param type cls: 要内省的类。
:raise TypeError: 如果*cls*不是一个类。
:raise attr.exceptions.NotAnAttrsClassError: 如果 *cls* 不是``attrs``类。
:rtype: 字典
版本添加: 18.1.0
🌿13 has(cls)
has(cls), module=attr._funcs, line:290 at site-packages\attr_funcs.py
检查*cls*是否是带有 ``attrs`` 属性的类。
参数类型cls::引发TypeError: : rtype: bool
:param type cls: 要内省的类。
:raise TypeError: 如果 *cls* 不是一个类。
:rtype: bool
🌿14 make_class(name, attrs, bases=(<class ‘object’>,), **attributes_arguments)
make_class(name, attrs, bases=(<class ‘object’>,), **attributes_arguments), module=attr._make, line:2820 at site-packages\attr_make.py
用 *attrs* 创建一个名为 *name* 的新类的快速方法。
:param attrs::type attrs: ' list '或' dict ':参数元组基:参数:' attrs .s '。
:param str name: 新类的名称。
:param attrs: 名称列表或名称到属性映射的字典。
顺序是从*attrs*中的名称或属性的顺序推断出来的。否则，将使用属性定义的顺序。
:type attrs: `list` or `dict`
:param tuple bases: 新类将继承的类。
:param attributes_arguments: 未经修改传递给 `attr.s`.
:return: 带 *attrs* 的新类。
:rtype: type
版本添加: 17.1.0 *bases*
版本变更: 18.1.0 如果 *attrs* 被排序，则保持顺序。
🌿15 define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
define(maybe_cls=None, *, these=None, repr=None, unsafe_hash=None, hash=None, init=None, slots=True, frozen=False, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True), module=attr._next_gen, line:24 at site-packages\attr_next_gen.py
定义一个``attrs``类。
参见 8 define()
🌿16 resolve_types(cls, globalns=None, localns=None, attribs=None)
resolve_types(cls, globalns=None, localns=None, attribs=None), module=attr._funcs, line:369 at site-packages\attr_funcs.py
解析类型注释中的任何字符串和转发注释。
只有在“Attribute”的“type”字段中需要具体类型时才需要这样做。
换句话说，如果只将类型用于静态类型检查，则不需要解析类型。
如果没有参数，将在创建类的模块中查找名称。
如果这不是你想要的，例如，如果名称只存在于一个方法中，你可以传递*globalns*或*localns*来指定查找这些名称的其他字典。
请参阅`typing.get_type_hints` 文档以获取更多详细信息。
:param type cls: 要解析的类。
:param Optional[dict] globalns: 包含全局变量的字典。
:param Optional[dict] localns: 包含本地变量的字典。
:param Optional[list] attribs: 指定类的属性列表。当从“字段转换器”内部调用时，这是必要的，因为*cls*还不是一个“attrs”类。
:raise TypeError: 如果 *cls* 不是一个类。
:raise attr.exceptions.NotAnAttrsClassError: 如果 *cls* 不是一个类，并且您没有传递任何属性。
:raise NameError: 如果类型无法解析，因为缺少变量。
:returns: *cls*，所以你也可以使用这个函数作为类的装饰器。
请注意，你必须在`attrs.define` 之后提供它。这意味着decorator必须出现在 `attrs.define` 之前的行。
版本添加: 20.1.0
版本添加: 21.1.0 *attribs*
🌿17 validate(inst)
validate(inst), module=attr._make, line:1950 at site-packages\attr_make.py
验证*inst*上所有具有验证器的属性。
保留所有异常。
:param inst: 具有“attrs”属性的类实例。
🌿18 asdict(inst, *, recurse=True, filter=None, value_serializer=None)
asdict(inst, *, recurse=True, filter=None, value_serializer=None), module=attr._next_gen, line:201 at site-packages\attr_next_gen.py
和 `attr.asdict` 一样。除了总是保留集合类型和dict总是被用作 *dict_factory* 之外。
添加版本： 21.3.0
🌿19 astuple(inst, *, recurse=True, filter=None)
astuple(inst, *, recurse=True, filter=None), module=attr._next_gen, line:217 at site-packages\attr_next_gen.py
和`attr.astuple`一样。除了集合类型总是被保留，`tuple` 总是被用 *tuple_factory*。
添加版本： 21.3.0
🔵类
🌿20 attr._make.Attribute
Attribute, attr._make.Attribute, module=attr._make, line:0 at
*属性的只读*表示。
这个类有*所有*参数attr。ib '(除了' factory ' '，它只是' default= factory(…)' '的语法糖)- ' name ' ' (' str '):属性的名称。- ' ' alias ' ' (' str '):属性的初始化参数名称，在任何显式覆盖和默认private-attribute-name处理之后。- ' ' inherited ' ' (' bool '):该属性是否从基类继承。
-“eq键”和“order键”(输入)。Callable '或' None '):可调用对象，分别用于根据此属性对对象进行比较和排序。
这些是通过传递一个可调用对象来设置的。b 's ' ' eq ' '， ' order ' '或' cmp ' '参数。参见:ref: '
比较定制<custom-comparison> '。
- ' fields '-
:ref: ' field transformer <transform-fields> '-“alias”，Versionadded:: 20.1.0 *inherited* ..版本新增:20.1.0 *on setattr* ..Versionchanged:: 20.2.0 *inherited*不再考虑相等性检查和散列。版本新增:21.1.0 *eq键*和*order键* ..Versionadded:: 22.2.0 *alias*
有关字段的完整版本历史记录，请参阅' attri .ib '。
一个属性的 *Read-only* 只读表示。
类具有 `attr.ib` 的全部属性 (除了 ``factory``, 它只是异步函数 ``default=Factory(...)``加上以下内容:
- ``name`` (`str`): 属性名称
- ``alias`` (`str`): 属性的__init__参数名称, 在任何显式覆盖和默认私有属性名称处理之后。
- ``inherited`` (`bool`): 不管该属性是否从基类继承。
- ``eq_key`` 和 ``order_key`` (`typing.Callable` 或 `None`): 分别用于按此属性比较和排序对象的可调用对象。
- `fields` 返回它们的元组。
- 验证器将它们作为第一个参数传递。
- :ref:`field transformer <transform-fields>` 钩子接收一个字段列表。
- ``alias`` 属性暴露了字段的 __init__ 初始化参数名称，任何覆盖和默认私有属性处理应用。
版本添加: 20.1.0 *inherited*
版本添加: 20.1.0 *on_setattr*
版本变更: 20.2.0 *inherited* 不再考虑相等性检查和哈希。
版本添加: 21.1.0 *eq_key* and *order_key*
版本添加: 22.2.0 *alias*
字段的完整历史版本，请参见：`attr.ib`.
data
1 alias=<member ‘alias’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
2 converter=<member ‘converter’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
3 default=<member ‘default’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
4 eq=<member ‘eq’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
5 eq_key=<member ‘eq_key’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
6 hash=<member ‘hash’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
7 inherited=<member ‘inherited’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
8 init=<member ‘init’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
9 kw_only=<member ‘kw_only’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
10 metadata=<member ‘metadata’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
11 name=<member ‘name’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
12 on_setattr=<member ‘on_setattr’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
13 order=<member ‘order’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
14 order_key=<member ‘order_key’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
15 repr=<member ‘repr’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
16 type=<member ‘type’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
17 validator=<member ‘validator’ of ‘Attribute’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Attribute’>
method
18 evolve()
kind=method class=Attribute objtype=function
复制 *self* 和应用 *changes*。
这与 `attr.evolve` 的工作原理类似。但该函数不适用于``Attribute``。
它主要用于`transform-fields`。
添加版本: 20.3.0
class method
19 from_counting_attr()
kind=class method class=Attribute objtype=classmethod
将函数转换为类方法。
🌿21 attr.AttrsInstance
AttrsInstance, attr.AttrsInstance, module=attr, line:0 at
🌿22 attr._make.Factory
Factory, attr._make.Factory, module=attr._make, line:0 at
存储可调用的工厂。
如果作为默认值传递给 `attrs.field` ，则使用工厂来生成新值。
:param callable factory: 一个可调用对象，根据 *takes_self*，它要么不接受，要么只接受一个强制位置参数。
:param bool takes_self: 传递作为位置参数初始化的部分初始化实例。
添加版本: 17.1.0 *takes_self*
data
1 factory=<member ‘factory’ of ‘Factory’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Factory’>
2 takes_self=<member ‘takes_self’ of ‘Factory’ objects> kind:data type:member_descriptor class:<class ‘attr._make.Factory’>
🔵剩余
23 loader <_frozen_importlib_external.SourceFileLoader object at 0x000001924E360E48>
24 spec ModuleSpec(name=‘attrs’, loader=<_frozen_importlib_external.SourceFileLoader object at 0x000001924E360E48>, origin=‘…\lib\site-packages\attrs\init.py’, submodule_search_locations=[‘…\lib\site-packages\attrs’])
25 NOTHING _Nothing.NOTHING
26 version_info VersionInfo(year=22, minor=2, micro=0, releaselevel=‘final’)
27 frozen functools.partial(<function define at 0x000001924E446678>, frozen=True, on_setattr=None)
☘️【attrs.converters】
converters, fullname=attrs.converters, file=attrs\converters.py
☘️【attrs.exceptions】
exceptions, fullname=attrs.exceptions, file=attrs\exceptions.py
☘️【attrs.filters】
filters, fullname=attrs.filters, file=attrs\filters.py
☘️【attrs.setters】
setters, fullname=attrs.setters, file=attrs\setters.py
☘️【attrs.validators】
validators, fullname=attrs.validators, file=attrs\validators.py
