Skip to content

api-attr.rst

Latest commit

 

History

History
248 lines (154 loc) · 5.37 KB

api-attr.rst

File metadata and controls

248 lines (154 loc) · 5.37 KB
Raw

API Reference for the attr Namespace

Note

These are the traditional APIs whose creation predates type annotations. They are not deprecated, but we suggest using the :mod:`attrs` namespace for new code, because they look nicer and have better defaults.

See also :doc:`names`.

.. module:: attr

Core

.. autofunction:: 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)

   For example:

   .. doctest::

      >>> 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)



.. autofunction:: attr.ib

   .. note::

      *attrs* also comes with a serious-business alias ``attr.attrib``.

   The object returned by `attr.ib` also allows for setting the default and the validator using decorators:

   .. doctest::

      >>> @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


.. function:: attrs

   Serious business alias for `attr.s`.


.. function:: define

   Same as `attrs.define`.


.. function:: mutable

   Same as `attrs.mutable`.


.. function:: frozen

   Same as `attrs.frozen`.


.. function:: field

   Same as `attrs.field`.

Same as attrs.Attribute.

.. function:: make_class

   Same as `attrs.make_class`.


.. autoclass:: Factory
   :noindex:

   Same as `attrs.Factory`.



.. data:: NOTHING

   Same as `attrs.NOTHING`.

Exceptions

.. module:: attr.exceptions

All exceptions are available from both attr.exceptions and attrs.exceptions (it's the same module in a different namespace).

Please refer to attrs.exceptions for details.

Helpers

.. currentmodule:: attr


.. function:: cmp_using

   Same as `attrs.cmp_using`.


.. function:: fields

   Same as `attrs.fields`.


.. function:: fields_dict

   Same as `attrs.fields_dict`.


.. function:: has

   Same as `attrs.has`.


.. function:: resolve_types

   Same as `attrs.resolve_types`.


.. autofunction:: asdict

.. autofunction:: astuple


.. module:: attr.filters


.. function:: include

   Same as `attrs.filters.include`.


.. function:: exclude

   Same as `attrs.filters.exclude`.

See :func:`attrs.asdict` for examples.

All objects from attrs.filters are also available in attr.filters.

.. currentmodule:: attr


.. function:: evolve

   Same as `attrs.evolve`.


.. function:: validate

   Same as `attrs.validate`.

Validators

.. module:: attr.validators

All objects from attrs.validators are also available in attr.validators. Please refer to the former for details.

Converters

.. module:: attr.converters

All objects from attrs.converters are also available from attr.converters. Please refer to the former for details.

Setters

.. module:: attr.setters

All objects from attrs.setters are also available in attr.setters. Please refer to the former for details.

Deprecated APIs

.. currentmodule:: attr

To help you write backward compatible code that doesn't throw warnings on modern releases, the attr module has an __version_info__ attribute as of version 19.2.0. It behaves similarly to sys.version_info and is an instance of attr.VersionInfo:

.. autoclass:: VersionInfo

   With its help you can write code like this:

   >>> 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



.. autofunction:: assoc

Before attrs got attrs.validators.set_disabled and attrs.validators.set_disabled, it had the following APIs to globally enable and disable validators. They won't be removed, but are discouraged to use:

.. autofunction:: set_run_validators

.. autofunction:: get_run_validators

The serious-business aliases used to be called attr.attributes and attr.attr. There are no plans to remove them but they shouldn't be used in new code.