From 124c20cde0c7099494449e62f56781c8cb499570 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Wed, 6 Oct 2021 12:21:36 +0200 Subject: [PATCH] Document Attribute.eq_key & .order_key (#847) * Document Attribute.eq_key & .order_key Fixes #839 Signed-off-by: Hynek Schlawack * Add for example --- docs/api.rst | 2 ++ docs/comparison.rst | 2 ++ src/attr/_make.py | 23 +++++++++++++++-------- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 817c60c6..c25e5d54 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -99,6 +99,8 @@ Core .. autoclass:: attr.Attribute :members: evolve + For example: + .. doctest:: >>> import attr diff --git a/docs/comparison.rst b/docs/comparison.rst index b2b457ba..c82f014b 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -7,6 +7,8 @@ For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you. Additionally, if you pass ``order=True`` (which is the default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined fields: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. +.. _custom-comparison: + Customization ------------- diff --git a/src/attr/_make.py b/src/attr/_make.py index ac6bbc10..9dba4e83 100644 --- a/src/attr/_make.py +++ b/src/attr/_make.py @@ -2573,19 +2573,26 @@ class Attribute(object): """ *Read-only* representation of an attribute. + The class has *all* arguments of `attr.ib` (except for ``factory`` + which is only syntactic sugar for ``default=Factory(...)`` plus the + following: + + - ``name`` (`str`): The name of the attribute. + - ``inherited`` (`bool`): Whether or not that attribute has been inherited + from a base class. + - ``eq_key`` and ``order_key`` (`typing.Callable` or `None`): The callables + that are used for comparing and ordering objects by this attribute, + respectively. These are set by passing a callable to `attr.ib`'s ``eq``, + ``order``, or ``cmp`` arguments. See also :ref:`comparison customization + `. + Instances of this class are frequently used for introspection purposes like: - `fields` returns a tuple of them. - Validators get them passed as the first argument. - - The *field transformer* hook receives a list of them. - - :attribute name: The name of the attribute. - :attribute inherited: Whether or not that attribute has been inherited from - a base class. - - Plus *all* arguments of `attr.ib` (except for ``factory`` - which is only syntactic sugar for ``default=Factory(...)``. + - The :ref:`field transformer ` hook receives a list of + them. .. versionadded:: 20.1.0 *inherited* .. versionadded:: 20.1.0 *on_setattr*