一图看懂 attrs 模块：一个在类定义时可替换 `__init__`, `__eq__`, `__repr__`等方法的样板，资料整理+笔记（大全）

本文由 大侠(AhcaoZhu)原创，转载请声明。
链接: https://blog.csdn.net/Ahcao2008

🧊摘要

• 全文介绍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