| |
|
|
| """ |
| These are keyword-only APIs that call `attr.s` and `attr.ib` with different |
| default values. |
| """ |
|
|
|
|
| from functools import partial |
|
|
| from . import setters |
| from ._funcs import asdict as _asdict |
| from ._funcs import astuple as _astuple |
| from ._make import ( |
| NOTHING, |
| _frozen_setattrs, |
| _ng_default_on_setattr, |
| attrib, |
| attrs, |
| ) |
| from .exceptions import UnannotatedAttributeError |
|
|
|
|
| def 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, |
| ): |
| r""" |
| 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). |
| - If *frozen* is `False`, run converters and validators when setting an |
| attribute by default. |
| - *slots=True* |
| |
| .. caution:: |
| |
| Usually this has only upsides and few visible effects in everyday |
| programming. But it *can* lead to some suprising 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). |
| """ |
|
|
| def do_it(cls, auto_attribs): |
| return attrs( |
| maybe_cls=cls, |
| these=these, |
| repr=repr, |
| hash=hash, |
| unsafe_hash=unsafe_hash, |
| init=init, |
| slots=slots, |
| frozen=frozen, |
| weakref_slot=weakref_slot, |
| str=str, |
| auto_attribs=auto_attribs, |
| kw_only=kw_only, |
| cache_hash=cache_hash, |
| auto_exc=auto_exc, |
| eq=eq, |
| order=order, |
| auto_detect=auto_detect, |
| collect_by_mro=True, |
| getstate_setstate=getstate_setstate, |
| on_setattr=on_setattr, |
| field_transformer=field_transformer, |
| match_args=match_args, |
| ) |
|
|
| def wrap(cls): |
| """ |
| Making this a wrapper ensures this code runs during class creation. |
| |
| We also ensure that frozen-ness of classes is inherited. |
| """ |
| nonlocal frozen, on_setattr |
|
|
| had_on_setattr = on_setattr not in (None, setters.NO_OP) |
|
|
| |
| if frozen is False and on_setattr is None: |
| on_setattr = _ng_default_on_setattr |
|
|
| |
| |
| for base_cls in cls.__bases__: |
| if base_cls.__setattr__ is _frozen_setattrs: |
| if had_on_setattr: |
| raise ValueError( |
| "Frozen classes can't use on_setattr " |
| "(frozen-ness was inherited)." |
| ) |
|
|
| on_setattr = setters.NO_OP |
| break |
|
|
| if auto_attribs is not None: |
| return do_it(cls, auto_attribs) |
|
|
| try: |
| return do_it(cls, True) |
| except UnannotatedAttributeError: |
| return do_it(cls, False) |
|
|
| |
| |
| if maybe_cls is None: |
| return wrap |
| else: |
| return wrap(maybe_cls) |
|
|
|
|
| mutable = define |
| frozen = partial(define, frozen=True, on_setattr=None) |
|
|
|
|
| def 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 |
| {func}`attrs.make_class`. Please note that type checkers ignore this |
| metadata. |
| .. versionadded:: 20.1.0 |
| """ |
| return attrib( |
| default=default, |
| validator=validator, |
| repr=repr, |
| hash=hash, |
| init=init, |
| metadata=metadata, |
| type=type, |
| converter=converter, |
| factory=factory, |
| kw_only=kw_only, |
| eq=eq, |
| order=order, |
| on_setattr=on_setattr, |
| alias=alias, |
| ) |
|
|
|
|
| def 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 |
| """ |
| return _asdict( |
| inst=inst, |
| recurse=recurse, |
| filter=filter, |
| value_serializer=value_serializer, |
| retain_collection_types=True, |
| ) |
|
|
|
|
| def 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 |
| """ |
| return _astuple( |
| inst=inst, recurse=recurse, filter=filter, retain_collection_types=True |
| ) |
|
|
