pydoc > attrs

Help on package attrs:

NAME
    attrs - # SPDX-License-Identifier: MIT

PACKAGE CONTENTS
    converters
    exceptions
    filters
    setters
    validators

CLASSES
    builtins.object
        attr._make.Attribute
        attr._make.Factory
    typing.Protocol(typing.Generic)
        attr.AttrsInstance

    class Attribute(builtins.object)
     |  Attribute(name, default, validator, repr, cmp, hash, init, inherited, metadata=None, type=None, converter=None, kw_only=False, eq=None, eq_key=None, order=None, order_key=None, on_setattr=None, alias=None)
     |
     |  *Read-only* representation of an attribute.
     |
     |  .. warning::
     |
     |     You should never instantiate this class yourself.
     |
     |  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.
     |  - ``alias`` (`str`): The __init__ parameter name of the attribute, after
     |    any explicit overrides and default private-attribute-name handling.
     |  - ``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
     |    <custom-comparison>`.
     |
     |  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 :ref:`field transformer <transform-fields>` hook receives a list of
     |    them.
     |  - The ``alias`` property exposes the __init__ parameter name of the field,
     |    with any overrides and default private-attribute handling applied.
     |
     |
     |  .. versionadded:: 20.1.0 *inherited*
     |  .. versionadded:: 20.1.0 *on_setattr*
     |  .. versionchanged:: 20.2.0 *inherited* is not taken into account for
     |      equality checks and hashing anymore.
     |  .. versionadded:: 21.1.0 *eq_key* and *order_key*
     |  .. versionadded:: 22.2.0 *alias*
     |
     |  For the full version history of the fields, see `attr.ib`.
     |
     |  Methods defined here:
     |
     |  __eq__(self, other)
     |
     |  __getstate__(self)
     |      Play nice with pickle.
     |
     |  __hash__(self)
     |
     |  __init__(self, name, default, validator, repr, cmp, hash, init, inherited, metadata=None, type=None, converter=None, kw_only=False, eq=None, eq_key=None, order=None, order_key=None, on_setattr=None, alias=None)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |
     |  __ne__(self, other) from attr._make._make_ne.<locals>
     |      Check equality and either forward a NotImplemented or
     |      return the result negated.
     |
     |  __repr__(self)
     |
     |  __setattr__(self, name, value)
     |      Implement setattr(self, name, value).
     |
     |  __setstate__(self, state)
     |      Play nice with pickle.
     |
     |  evolve(self, **changes)
     |      Copy *self* and apply *changes*.
     |
     |      This works similarly to `attrs.evolve` but that function does not work
     |      with `Attribute`.
     |
     |      It is mainly meant to be used for `transform-fields`.
     |
     |      .. versionadded:: 20.3.0
     |
     |  ----------------------------------------------------------------------
     |  Class methods defined here:
     |
     |  from_counting_attr(name, ca, type=None)
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  alias
     |
     |  converter
     |
     |  default
     |
     |  eq
     |
     |  eq_key
     |
     |  hash
     |
     |  inherited
     |
     |  init
     |
     |  kw_only
     |
     |  metadata
     |
     |  name
     |
     |  on_setattr
     |
     |  order
     |
     |  order_key
     |
     |  repr
     |
     |  type
     |
     |  validator

    class AttrsInstance(typing.Protocol)
     |  AttrsInstance(*args, **kwargs)
     |
     |  Method resolution order:
     |      AttrsInstance
     |      typing.Protocol
     |      typing.Generic
     |      builtins.object
     |
     |  Methods defined here:
     |
     |  __init__ = _no_init_or_replace_init(self, *args, **kwargs) from typing
     |
     |  ----------------------------------------------------------------------
     |  Class methods defined here:
     |
     |  __subclasshook__ = _proto_hook(other) from typing
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  __dict__
     |      dictionary for instance variables
     |
     |  __weakref__
     |      list of weak references to the object
     |
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |
     |  __abstractmethods__ = frozenset()
     |
     |  __annotations__ = {}
     |
     |  __parameters__ = ()
     |
     |  __protocol_attrs__ = set()
     |
     |  ----------------------------------------------------------------------
     |  Class methods inherited from typing.Protocol:
     |
     |  __init_subclass__(*args, **kwargs)
     |      Function to initialize subclasses.
     |
     |  ----------------------------------------------------------------------
     |  Class methods inherited from typing.Generic:
     |
     |  __class_getitem__(...)
     |      Parameterizes a generic class.
     |
     |      At least, parameterizing a generic class is the *main* thing this
     |      method does. For example, for some generic class `Foo`, this is called
     |      when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
     |
     |      However, note that this method is also called when defining generic
     |      classes in the first place with `class Foo[T]: ...`.

    class Factory(builtins.object)
     |  Factory(factory, takes_self=False)
     |
     |  Stores a factory callable.
     |
     |  If passed as the default value to `attrs.field`, the factory is used to
     |  generate a new value.
     |
     |  :param callable factory: A callable that takes either none or exactly one
     |      mandatory positional argument depending on *takes_self*.
     |  :param bool takes_self: Pass the partially initialized instance that is
     |      being initialized as a positional argument.
     |
     |  .. versionadded:: 17.1.0  *takes_self*
     |
     |  Methods defined here:
     |
     |  __eq__(self, other)
     |
     |  __getstate__(self)
     |      Play nice with pickle.
     |
     |  __hash__(self)
     |
     |  __init__(self, factory, takes_self=False)
     |      Initialize self.  See help(type(self)) for accurate signature.
     |
     |  __ne__(self, other) from attr._make._make_ne.<locals>
     |      Check equality and either forward a NotImplemented or
     |      return the result negated.
     |
     |  __repr__(self)
     |
     |  __setstate__(self, state)
     |      Play nice with pickle.
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  factory
     |
     |  takes_self

FUNCTIONS
    __getattr__(name: str) -> str

    asdict(inst, *, recurse=True, filter=None, value_serializer=None)
        Same as `attr.asdict`, except that collections types are always retained
        and dict is always used as *dict_factory*.

        .. versionadded:: 21.3.0

    assoc(inst, **changes)
        Copy *inst* and apply *changes*.

        This is different from `evolve` that applies the changes to the arguments
        that create the new instance.

        `evolve`'s behavior is preferable, but there are `edge cases`_ where it
        doesn't work. Therefore `assoc` is deprecated, but will not be removed.

        .. _`edge cases`: https://github.com/python-attrs/attrs/issues/251

        :param inst: Instance of a class with *attrs* attributes.
        :param changes: Keyword changes in the new copy.

        :return: A copy of inst with *changes* incorporated.

        :raise attrs.exceptions.AttrsAttributeNotFoundError: If *attr_name*
            couldn't be found on *cls*.
        :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
            class.

        ..  deprecated:: 17.1.0
            Use `attrs.evolve` instead if you can.
            This function will not be removed du to the slightly different approach
            compared to `attrs.evolve`.

    astuple(inst, *, recurse=True, filter=None)
        Same as `attr.astuple`, except that collections types are always retained
        and `tuple` is always used as the *tuple_factory*.

        .. versionadded:: 21.3.0

    cmp_using(eq=None, lt=None, le=None, gt=None, ge=None, require_same_type=True, class_name='Comparable')
        Create a class that can be passed into `attrs.field`'s ``eq``, ``order``,
        and ``cmp`` arguments to customize field comparison.

        The resulting class will have a full set of ordering methods if at least
        one of ``{lt, le, gt, ge}`` and ``eq``  are provided.

        :param Optional[callable] eq: `callable` used to evaluate equality of two
            objects.
        :param Optional[callable] lt: `callable` used to evaluate whether one
            object is less than another object.
        :param Optional[callable] le: `callable` used to evaluate whether one
            object is less than or equal to another object.
        :param Optional[callable] gt: `callable` used to evaluate whether one
            object is greater than another object.
        :param Optional[callable] ge: `callable` used to evaluate whether one
            object is greater than or equal to another object.

        :param bool require_same_type: When `True`, equality and ordering methods
            will return `NotImplemented` if objects are not of the same type.

        :param Optional[str] class_name: Name of class. Defaults to 'Comparable'.

        See `comparison` for more details.

        .. versionadded:: 21.1.0

    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 an *attrs* class.

        Differences to the classic `attr.s` that it uses underneath:

        - Automatically detect whether or not *auto_attribs* should be `True` (c.f.
          *auto_attribs* parameter).
        - Converters and validators run when attributes are set by default -- if
          *frozen* is `False`.
        - *slots=True*

          .. caution::

             Usually this has only upsides and few visible effects in everyday
             programming. But it *can* lead to some surprising behaviors, so please
             make sure to read :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.

        Please note that these are all defaults and you can change them as you
        wish.

        :param Optional[bool] auto_attribs: If set to `True` or `False`, it behaves
           exactly like `attr.s`. If left `None`, `attr.s` will try to guess:

           1. If any attributes are annotated and no unannotated `attrs.fields`\ s
              are found, it assumes *auto_attribs=True*.
           2. Otherwise it assumes *auto_attribs=False* and tries to collect
              `attrs.fields`\ s.

        For now, please refer to `attr.s` for the rest of the parameters.

        .. versionadded:: 20.1.0
        .. versionchanged:: 21.3.0 Converters are also run ``on_setattr``.
        .. versionadded:: 22.2.0
           *unsafe_hash* as an alias for *hash* (for :pep:`681` compliance).

    evolve(*args, **changes)
        Create a new instance, based on the first positional argument with
        *changes* applied.

        :param inst: Instance of a class with *attrs* attributes.
        :param changes: Keyword changes in the new copy.

        :return: A copy of inst with *changes* incorporated.

        :raise TypeError: If *attr_name* couldn't be found in the class
            ``__init__``.
        :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
            class.

        .. versionadded:: 17.1.0
        .. deprecated:: 23.1.0
           It is now deprecated to pass the instance using the keyword argument
           *inst*. It will raise a warning until at least April 2024, after which
           it will become an error. Always pass the instance as a positional
           argument.

    field(*, default=NOTHING, validator=None, repr=True, hash=None, init=True, metadata=None, type=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, alias=None)
        Identical to `attr.ib`, except keyword-only and with some arguments
        removed.

        .. versionadded:: 23.1.0
           The *type* parameter has been re-added; mostly for `attrs.make_class`.
           Please note that type checkers ignore this metadata.
        .. versionadded:: 20.1.0

    fields(cls)
        Return the tuple of *attrs* attributes for a class.

        The tuple also allows accessing the fields by their names (see below for
        examples).

        :param type cls: Class to introspect.

        :raise TypeError: If *cls* is not a class.
        :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
            class.

        :rtype: tuple (with name accessors) of `attrs.Attribute`

        .. versionchanged:: 16.2.0 Returned tuple allows accessing the fields
           by name.
        .. versionchanged:: 23.1.0 Add support for generic classes.

    fields_dict(cls)
        Return an ordered dictionary of *attrs* attributes for a class, whose
        keys are the attribute names.

        :param type cls: Class to introspect.

        :raise TypeError: If *cls* is not a class.
        :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
            class.

        :rtype: dict

        .. versionadded:: 18.1.0

    has(cls)
        Check whether *cls* is a class with *attrs* attributes.

        :param type cls: Class to introspect.
        :raise TypeError: If *cls* is not a class.

        :rtype: bool

    make_class(name, attrs, bases=(<class 'object'>,), class_body=None, **attributes_arguments)
        A quick way to create a new class called *name* with *attrs*.

        :param str name: The name for the new class.

        :param attrs: A list of names or a dictionary of mappings of names to
            `attr.ib`\ s / `attrs.field`\ s.

            The order is deduced from the order of the names or attributes inside
            *attrs*.  Otherwise the order of the definition of the attributes is
            used.
        :type attrs: `list` or `dict`

        :param tuple bases: Classes that the new class will subclass.

        :param dict class_body: An optional dictionary of class attributes for the new class.

        :param attributes_arguments: Passed unmodified to `attr.s`.

        :return: A new class with *attrs*.
        :rtype: type

        .. versionadded:: 17.1.0 *bases*
        .. versionchanged:: 18.1.0 If *attrs* is ordered, the order is retained.
        .. versionchanged:: 23.2.0 *class_body*

    mutable = 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 an *attrs* class.

        Differences to the classic `attr.s` that it uses underneath:

        - Automatically detect whether or not *auto_attribs* should be `True` (c.f.
          *auto_attribs* parameter).
        - Converters and validators run when attributes are set by default -- if
          *frozen* is `False`.
        - *slots=True*

          .. caution::

             Usually this has only upsides and few visible effects in everyday
             programming. But it *can* lead to some surprising behaviors, so please
             make sure to read :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.

        Please note that these are all defaults and you can change them as you
        wish.

        :param Optional[bool] auto_attribs: If set to `True` or `False`, it behaves
           exactly like `attr.s`. If left `None`, `attr.s` will try to guess:

           1. If any attributes are annotated and no unannotated `attrs.fields`\ s
              are found, it assumes *auto_attribs=True*.
           2. Otherwise it assumes *auto_attribs=False* and tries to collect
              `attrs.fields`\ s.

        For now, please refer to `attr.s` for the rest of the parameters.

        .. versionadded:: 20.1.0
        .. versionchanged:: 21.3.0 Converters are also run ``on_setattr``.
        .. versionadded:: 22.2.0
           *unsafe_hash* as an alias for *hash* (for :pep:`681` compliance).

    resolve_types(cls, globalns=None, localns=None, attribs=None, include_extras=True)
        Resolve any strings and forward annotations in type annotations.

        This is only required if you need concrete types in `Attribute`'s *type*
        field. In other words, you don't need to resolve your types if you only
        use them for static type checking.

        With no arguments, names will be looked up in the module in which the class
        was created. If this is not what you want, e.g. if the name only exists
        inside a method, you may pass *globalns* or *localns* to specify other
        dictionaries in which to look up these names. See the docs of
        `typing.get_type_hints` for more details.

        :param type cls: Class to resolve.
        :param Optional[dict] globalns: Dictionary containing global variables.
        :param Optional[dict] localns: Dictionary containing local variables.
        :param Optional[list] attribs: List of attribs for the given class.
            This is necessary when calling from inside a ``field_transformer``
            since *cls* is not an *attrs* class yet.
        :param bool include_extras: Resolve more accurately, if possible.
            Pass ``include_extras`` to ``typing.get_hints``, if supported by the
            typing module. On supported Python versions (3.9+), this resolves the
            types more accurately.

        :raise TypeError: If *cls* is not a class.
        :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
            class and you didn't pass any attribs.
        :raise NameError: If types cannot be resolved because of missing variables.

        :returns: *cls* so you can use this function also as a class decorator.
            Please note that you have to apply it **after** `attrs.define`. That
            means the decorator has to come in the line **before** `attrs.define`.

        ..  versionadded:: 20.1.0
        ..  versionadded:: 21.1.0 *attribs*
        ..  versionadded:: 23.1.0 *include_extras*

    validate(inst)
        Validate all attributes on *inst* that have a validator.

        Leaves all exceptions through.

        :param inst: Instance of a class with *attrs* attributes.

DATA
    NOTHING = NOTHING
    __all__ = ['__author__', '__copyright__', '__description__', '__doc__'...
    frozen = functools.partial(<function define at 0x7f5a93a48a40>, frozen...

VERSION
    23.2.0

AUTHOR
    Hynek Schlawack

FILE
    /usr/lib/python3/dist-packages/attrs/__init__.py