|
|
from __future__ import absolute_import, division, print_function
|
|
|
|
|
|
import hashlib
|
|
|
import linecache
|
|
|
|
|
|
from operator import itemgetter
|
|
|
|
|
|
from . import _config
|
|
|
from ._compat import PY2, iteritems, isclass, iterkeys, metadata_proxy
|
|
|
from .exceptions import (
|
|
|
DefaultAlreadySetError,
|
|
|
FrozenInstanceError,
|
|
|
NotAnAttrsClassError,
|
|
|
)
|
|
|
|
|
|
|
|
|
# This is used at least twice, so cache it here.
|
|
|
_obj_setattr = object.__setattr__
|
|
|
_init_convert_pat = "__attr_convert_{}"
|
|
|
_init_factory_pat = "__attr_factory_{}"
|
|
|
_tuple_property_pat = " {attr_name} = property(itemgetter({index}))"
|
|
|
_empty_metadata_singleton = metadata_proxy({})
|
|
|
|
|
|
|
|
|
class _Nothing(object):
|
|
|
"""
|
|
|
Sentinel class to indicate the lack of a value when ``None`` is ambiguous.
|
|
|
|
|
|
All instances of `_Nothing` are equal.
|
|
|
"""
|
|
|
def __copy__(self):
|
|
|
return self
|
|
|
|
|
|
def __deepcopy__(self, _):
|
|
|
return self
|
|
|
|
|
|
def __eq__(self, other):
|
|
|
return other.__class__ == _Nothing
|
|
|
|
|
|
def __ne__(self, other):
|
|
|
return not self == other
|
|
|
|
|
|
def __repr__(self):
|
|
|
return "NOTHING"
|
|
|
|
|
|
def __hash__(self):
|
|
|
return 0xdeadbeef
|
|
|
|
|
|
|
|
|
NOTHING = _Nothing()
|
|
|
"""
|
|
|
Sentinel to indicate the lack of a value when ``None`` is ambiguous.
|
|
|
"""
|
|
|
|
|
|
|
|
|
def attr(default=NOTHING, validator=None,
|
|
|
repr=True, cmp=True, hash=None, init=True,
|
|
|
convert=None, metadata={}):
|
|
|
r"""
|
|
|
Create a new attribute on a class.
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
Does *not* do anything unless the class is also decorated with
|
|
|
:func:`attr.s`!
|
|
|
|
|
|
:param default: A value that is used if an ``attrs``-generated ``__init__``
|
|
|
is used and no value is passed while instantiating or the attribute is
|
|
|
excluded using ``init=False``.
|
|
|
|
|
|
If the value is an instance of :class:`Factory`, its callable will be
|
|
|
used to construct a new value (useful for mutable datatypes like lists
|
|
|
or dicts).
|
|
|
|
|
|
If a default is not set (or set manually to ``attr.NOTHING``), a value
|
|
|
*must* be supplied when instantiating; otherwise a :exc:`TypeError`
|
|
|
will be raised.
|
|
|
|
|
|
The default can also be set using decorator notation as shown below.
|
|
|
|
|
|
:type default: Any value.
|
|
|
|
|
|
:param validator: :func:`callable` that is called by ``attrs``-generated
|
|
|
``__init__`` methods after the instance has been initialized. They
|
|
|
receive the initialized instance, the :class:`Attribute`, and the
|
|
|
passed value.
|
|
|
|
|
|
The return value is *not* inspected so the validator has to throw an
|
|
|
exception itself.
|
|
|
|
|
|
If a ``list`` is passed, its items are treated as validators and must
|
|
|
all pass.
|
|
|
|
|
|
Validators can be globally disabled and re-enabled using
|
|
|
:func:`get_run_validators`.
|
|
|
|
|
|
The validator can also be set using decorator notation as shown below.
|
|
|
|
|
|
:type validator: ``callable`` or a ``list`` of ``callable``\ s.
|
|
|
|
|
|
:param bool repr: Include this attribute in the generated ``__repr__``
|
|
|
method.
|
|
|
:param bool cmp: Include this attribute in the generated comparison methods
|
|
|
(``__eq__`` et al).
|
|
|
:param hash: Include this attribute in the generated ``__hash__``
|
|
|
method. If ``None`` (default), mirror *cmp*'s value. This is the
|
|
|
correct behavior according the Python spec. Setting this value to
|
|
|
anything else than ``None`` is *discouraged*.
|
|
|
:type hash: ``bool`` or ``None``
|
|
|
:param bool init: Include this attribute in the generated ``__init__``
|
|
|
method. It is possible to set this to ``False`` and set a default
|
|
|
value. In that case this attributed is unconditionally initialized
|
|
|
with the specified default value or factory.
|
|
|
:param callable convert: :func:`callable` that is called by
|
|
|
``attrs``-generated ``__init__`` methods to convert attribute's value
|
|
|
to the desired format. It is given the passed-in value, and the
|
|
|
returned value will be used as the new value of the attribute. The
|
|
|
value is converted before being passed to the validator, if any.
|
|
|
:param metadata: An arbitrary mapping, to be used by third-party
|
|
|
components. See :ref:`extending_metadata`.
|
|
|
|
|
|
.. versionchanged:: 17.1.0 *validator* can be a ``list`` now.
|
|
|
.. versionchanged:: 17.1.0
|
|
|
*hash* is ``None`` and therefore mirrors *cmp* by default .
|
|
|
"""
|
|
|
if hash is not None and hash is not True and hash is not False:
|
|
|
raise TypeError(
|
|
|
"Invalid value for hash. Must be True, False, or None."
|
|
|
)
|
|
|
return _CountingAttr(
|
|
|
default=default,
|
|
|
validator=validator,
|
|
|
repr=repr,
|
|
|
cmp=cmp,
|
|
|
hash=hash,
|
|
|
init=init,
|
|
|
convert=convert,
|
|
|
metadata=metadata,
|
|
|
)
|
|
|
|
|
|
|
|
|
def _make_attr_tuple_class(cls_name, attr_names):
|
|
|
"""
|
|
|
Create a tuple subclass to hold `Attribute`s for an `attrs` class.
|
|
|
|
|
|
The subclass is a bare tuple with properties for names.
|
|
|
|
|
|
class MyClassAttributes(tuple):
|
|
|
__slots__ = ()
|
|
|
x = property(itemgetter(0))
|
|
|
"""
|
|
|
attr_class_name = "{}Attributes".format(cls_name)
|
|
|
attr_class_template = [
|
|
|
"class {}(tuple):".format(attr_class_name),
|
|
|
" __slots__ = ()",
|
|
|
]
|
|
|
if attr_names:
|
|
|
for i, attr_name in enumerate(attr_names):
|
|
|
attr_class_template.append(_tuple_property_pat.format(
|
|
|
index=i,
|
|
|
attr_name=attr_name,
|
|
|
))
|
|
|
else:
|
|
|
attr_class_template.append(" pass")
|
|
|
globs = {"itemgetter": itemgetter}
|
|
|
eval(compile("\n".join(attr_class_template), "", "exec"), globs)
|
|
|
return globs[attr_class_name]
|
|
|
|
|
|
|
|
|
def _transform_attrs(cls, these):
|
|
|
"""
|
|
|
Transforms all `_CountingAttr`s on a class into `Attribute`s and saves the
|
|
|
list in `__attrs_attrs__`.
|
|
|
|
|
|
If *these* is passed, use that and don't look for them on the class.
|
|
|
"""
|
|
|
super_cls = []
|
|
|
for c in reversed(cls.__mro__[1:-1]):
|
|
|
sub_attrs = getattr(c, "__attrs_attrs__", None)
|
|
|
if sub_attrs is not None:
|
|
|
super_cls.extend(a for a in sub_attrs if a not in super_cls)
|
|
|
if these is None:
|
|
|
ca_list = [(name, attr)
|
|
|
for name, attr
|
|
|
in cls.__dict__.items()
|
|
|
if isinstance(attr, _CountingAttr)]
|
|
|
else:
|
|
|
ca_list = [(name, ca)
|
|
|
for name, ca
|
|
|
in iteritems(these)]
|
|
|
|
|
|
non_super_attrs = [
|
|
|
Attribute.from_counting_attr(name=attr_name, ca=ca)
|
|
|
for attr_name, ca
|
|
|
in sorted(ca_list, key=lambda e: e[1].counter)
|
|
|
]
|
|
|
attr_names = [a.name for a in super_cls + non_super_attrs]
|
|
|
|
|
|
AttrsClass = _make_attr_tuple_class(cls.__name__, attr_names)
|
|
|
|
|
|
cls.__attrs_attrs__ = AttrsClass(super_cls + [
|
|
|
Attribute.from_counting_attr(name=attr_name, ca=ca)
|
|
|
for attr_name, ca
|
|
|
in sorted(ca_list, key=lambda e: e[1].counter)
|
|
|
])
|
|
|
|
|
|
had_default = False
|
|
|
for a in cls.__attrs_attrs__:
|
|
|
if these is None and a not in super_cls:
|
|
|
setattr(cls, a.name, a)
|
|
|
if had_default is True and a.default is NOTHING and a.init is True:
|
|
|
raise ValueError(
|
|
|
"No mandatory attributes allowed after an attribute with a "
|
|
|
"default value or factory. Attribute in question: {a!r}"
|
|
|
.format(a=a)
|
|
|
)
|
|
|
elif had_default is False and \
|
|
|
a.default is not NOTHING and \
|
|
|
a.init is not False:
|
|
|
had_default = True
|
|
|
|
|
|
|
|
|
def _frozen_setattrs(self, name, value):
|
|
|
"""
|
|
|
Attached to frozen classes as __setattr__.
|
|
|
"""
|
|
|
raise FrozenInstanceError()
|
|
|
|
|
|
|
|
|
def _frozen_delattrs(self, name):
|
|
|
"""
|
|
|
Attached to frozen classes as __delattr__.
|
|
|
"""
|
|
|
raise FrozenInstanceError()
|
|
|
|
|
|
|
|
|
def attributes(maybe_cls=None, these=None, repr_ns=None,
|
|
|
repr=True, cmp=True, hash=None, init=True,
|
|
|
slots=False, frozen=False, str=False):
|
|
|
r"""
|
|
|
A class decorator that adds `dunder
|
|
|
<https://wiki.python.org/moin/DunderAlias>`_\ -methods according to the
|
|
|
specified attributes using :func:`attr.ib` or the *these* argument.
|
|
|
|
|
|
:param these: A dictionary of name to :func:`attr.ib` mappings. This is
|
|
|
useful to avoid the definition of your attributes within the class body
|
|
|
because you can't (e.g. if you want to add ``__repr__`` methods to
|
|
|
Django models) or don't want to.
|
|
|
|
|
|
If *these* is not ``None``, ``attrs`` will *not* search the class body
|
|
|
for attributes.
|
|
|
|
|
|
:type these: :class:`dict` of :class:`str` to :func:`attr.ib`
|
|
|
|
|
|
:param str repr_ns: When using nested classes, there's no way in Python 2
|
|
|
to automatically detect that. Therefore it's possible to set the
|
|
|
namespace explicitly for a more meaningful ``repr`` output.
|
|
|
:param bool repr: Create a ``__repr__`` method with a human readable
|
|
|
represantation of ``attrs`` attributes..
|
|
|
:param bool str: Create a ``__str__`` method that is identical to
|
|
|
``__repr__``. This is usually not necessary except for
|
|
|
:class:`Exception`\ s.
|
|
|
:param bool cmp: Create ``__eq__``, ``__ne__``, ``__lt__``, ``__le__``,
|
|
|
``__gt__``, and ``__ge__`` methods that compare the class as if it were
|
|
|
a tuple of its ``attrs`` attributes. But the attributes are *only*
|
|
|
compared, if the type of both classes is *identical*!
|
|
|
:param hash: If ``None`` (default), the ``__hash__`` method is generated
|
|
|
according how *cmp* and *frozen* are set.
|
|
|
|
|
|
1. If *both* are True, ``attrs`` will generate a ``__hash__`` for you.
|
|
|
2. If *cmp* is True and *frozen* is False, ``__hash__`` will be set to
|
|
|
None, marking it unhashable (which it is).
|
|
|
3. If *cmp* is False, ``__hash__`` will be left untouched meaning the
|
|
|
``__hash__`` method of the superclass will be used (if superclass is
|
|
|
``object``, this means it will fall back to id-based hashing.).
|
|
|
|
|
|
Although not recommended, you can decide for yourself and force
|
|
|
``attrs`` to create one (e.g. if the class is immutable even though you
|
|
|
didn't freeze it programmatically) by passing ``True`` or not. Both of
|
|
|
these cases are rather special and should be used carefully.
|
|
|
|
|
|
See the `Python documentation \
|
|
|
<https://docs.python.org/3/reference/datamodel.html#object.__hash__>`_
|
|
|
and the `GitHub issue that led to the default behavior \
|
|
|
<https://github.com/python-attrs/attrs/issues/136>`_ for more details.
|
|
|
:type hash: ``bool`` or ``None``
|
|
|
:param bool init: Create a ``__init__`` method that initialiazes the
|
|
|
``attrs`` attributes. Leading underscores are stripped for the
|
|
|
argument name. If a ``__attrs_post_init__`` method exists on the
|
|
|
class, it will be called after the class is fully initialized.
|
|
|
:param bool slots: Create a slots_-style class that's more
|
|
|
memory-efficient. See :ref:`slots` for further ramifications.
|
|
|
:param bool frozen: Make instances immutable after initialization. If
|
|
|
someone attempts to modify a frozen instance,
|
|
|
:exc:`attr.exceptions.FrozenInstanceError` is raised.
|
|
|
|
|
|
Please note:
|
|
|
|
|
|
1. This is achieved by installing a custom ``__setattr__`` method
|
|
|
on your class so you can't implement an own one.
|
|
|
|
|
|
2. True immutability is impossible in Python.
|
|
|
|
|
|
3. This *does* have a minor a runtime performance :ref:`impact
|
|
|
<how-frozen>` when initializing new instances. In other words:
|
|
|
``__init__`` is slightly slower with ``frozen=True``.
|
|
|
|
|
|
4. If a class is frozen, you cannot modify ``self`` in
|
|
|
``__attrs_post_init__`` or a self-written ``__init__``. You can
|
|
|
circumvent that limitation by using
|
|
|
``object.__setattr__(self, "attribute_name", value)``.
|
|
|
|
|
|
.. _slots: https://docs.python.org/3.5/reference/datamodel.html#slots
|
|
|
|
|
|
.. versionadded:: 16.0.0 *slots*
|
|
|
.. versionadded:: 16.1.0 *frozen*
|
|
|
.. versionadded:: 16.3.0 *str*, and support for ``__attrs_post_init__``.
|
|
|
.. versionchanged::
|
|
|
17.1.0 *hash* supports ``None`` as value which is also the default
|
|
|
now.
|
|
|
"""
|
|
|
def wrap(cls):
|
|
|
if getattr(cls, "__class__", None) is None:
|
|
|
raise TypeError("attrs only works with new-style classes.")
|
|
|
|
|
|
if repr is False and str is True:
|
|
|
raise ValueError(
|
|
|
"__str__ can only be generated if a __repr__ exists."
|
|
|
)
|
|
|
|
|
|
if slots:
|
|
|
# Only need this later if we're using slots.
|
|
|
if these is None:
|
|
|
ca_list = [name
|
|
|
for name, attr
|
|
|
in cls.__dict__.items()
|
|
|
if isinstance(attr, _CountingAttr)]
|
|
|
else:
|
|
|
ca_list = list(iterkeys(these))
|
|
|
_transform_attrs(cls, these)
|
|
|
|
|
|
# Can't just re-use frozen name because Python's scoping. :(
|
|
|
# Can't compare function objects because Python 2 is terrible. :(
|
|
|
effectively_frozen = _has_frozen_superclass(cls) or frozen
|
|
|
if repr is True:
|
|
|
cls = _add_repr(cls, ns=repr_ns)
|
|
|
if str is True:
|
|
|
cls.__str__ = cls.__repr__
|
|
|
if cmp is True:
|
|
|
cls = _add_cmp(cls)
|
|
|
|
|
|
if hash is not True and hash is not False and hash is not None:
|
|
|
raise TypeError(
|
|
|
"Invalid value for hash. Must be True, False, or None."
|
|
|
)
|
|
|
elif hash is False or (hash is None and cmp is False):
|
|
|
pass
|
|
|
elif hash is True or (hash is None and cmp is True and frozen is True):
|
|
|
cls = _add_hash(cls)
|
|
|
else:
|
|
|
cls.__hash__ = None
|
|
|
|
|
|
if init is True:
|
|
|
cls = _add_init(cls, effectively_frozen)
|
|
|
if effectively_frozen is True:
|
|
|
cls.__setattr__ = _frozen_setattrs
|
|
|
cls.__delattr__ = _frozen_delattrs
|
|
|
if slots is True:
|
|
|
# slots and frozen require __getstate__/__setstate__ to work
|
|
|
cls = _add_pickle(cls)
|
|
|
if slots is True:
|
|
|
cls_dict = dict(cls.__dict__)
|
|
|
cls_dict["__slots__"] = tuple(ca_list)
|
|
|
for ca_name in ca_list:
|
|
|
# It might not actually be in there, e.g. if using 'these'.
|
|
|
cls_dict.pop(ca_name, None)
|
|
|
cls_dict.pop("__dict__", None)
|
|
|
|
|
|
qualname = getattr(cls, "__qualname__", None)
|
|
|
cls = type(cls)(cls.__name__, cls.__bases__, cls_dict)
|
|
|
if qualname is not None:
|
|
|
cls.__qualname__ = qualname
|
|
|
|
|
|
return cls
|
|
|
|
|
|
# attrs_or class type depends on the usage of the decorator. It's a class
|
|
|
# if it's used as `@attributes` but ``None`` if used # as `@attributes()`.
|
|
|
if maybe_cls is None:
|
|
|
return wrap
|
|
|
else:
|
|
|
return wrap(maybe_cls)
|
|
|
|
|
|
|
|
|
if PY2:
|
|
|
def _has_frozen_superclass(cls):
|
|
|
"""
|
|
|
Check whether *cls* has a frozen ancestor by looking at its
|
|
|
__setattr__.
|
|
|
"""
|
|
|
return (
|
|
|
getattr(
|
|
|
cls.__setattr__, "__module__", None
|
|
|
) == _frozen_setattrs.__module__ and
|
|
|
cls.__setattr__.__name__ == _frozen_setattrs.__name__
|
|
|
)
|
|
|
else:
|
|
|
def _has_frozen_superclass(cls):
|
|
|
"""
|
|
|
Check whether *cls* has a frozen ancestor by looking at its
|
|
|
__setattr__.
|
|
|
"""
|
|
|
return cls.__setattr__ == _frozen_setattrs
|
|
|
|
|
|
|
|
|
def _attrs_to_tuple(obj, attrs):
|
|
|
"""
|
|
|
Create a tuple of all values of *obj*'s *attrs*.
|
|
|
"""
|
|
|
return tuple(getattr(obj, a.name) for a in attrs)
|
|
|
|
|
|
|
|
|
def _add_hash(cls, attrs=None):
|
|
|
"""
|
|
|
Add a hash method to *cls*.
|
|
|
"""
|
|
|
if attrs is None:
|
|
|
attrs = [a
|
|
|
for a in cls.__attrs_attrs__
|
|
|
if a.hash is True or (a.hash is None and a.cmp is True)]
|
|
|
|
|
|
def hash_(self):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
return hash(_attrs_to_tuple(self, attrs))
|
|
|
|
|
|
cls.__hash__ = hash_
|
|
|
return cls
|
|
|
|
|
|
|
|
|
def _add_cmp(cls, attrs=None):
|
|
|
"""
|
|
|
Add comparison methods to *cls*.
|
|
|
"""
|
|
|
if attrs is None:
|
|
|
attrs = [a for a in cls.__attrs_attrs__ if a.cmp]
|
|
|
|
|
|
def attrs_to_tuple(obj):
|
|
|
"""
|
|
|
Save us some typing.
|
|
|
"""
|
|
|
return _attrs_to_tuple(obj, attrs)
|
|
|
|
|
|
def eq(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
if other.__class__ is self.__class__:
|
|
|
return attrs_to_tuple(self) == attrs_to_tuple(other)
|
|
|
else:
|
|
|
return NotImplemented
|
|
|
|
|
|
def ne(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
result = eq(self, other)
|
|
|
if result is NotImplemented:
|
|
|
return NotImplemented
|
|
|
else:
|
|
|
return not result
|
|
|
|
|
|
def lt(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
if isinstance(other, self.__class__):
|
|
|
return attrs_to_tuple(self) < attrs_to_tuple(other)
|
|
|
else:
|
|
|
return NotImplemented
|
|
|
|
|
|
def le(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
if isinstance(other, self.__class__):
|
|
|
return attrs_to_tuple(self) <= attrs_to_tuple(other)
|
|
|
else:
|
|
|
return NotImplemented
|
|
|
|
|
|
def gt(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
if isinstance(other, self.__class__):
|
|
|
return attrs_to_tuple(self) > attrs_to_tuple(other)
|
|
|
else:
|
|
|
return NotImplemented
|
|
|
|
|
|
def ge(self, other):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
if isinstance(other, self.__class__):
|
|
|
return attrs_to_tuple(self) >= attrs_to_tuple(other)
|
|
|
else:
|
|
|
return NotImplemented
|
|
|
|
|
|
cls.__eq__ = eq
|
|
|
cls.__ne__ = ne
|
|
|
cls.__lt__ = lt
|
|
|
cls.__le__ = le
|
|
|
cls.__gt__ = gt
|
|
|
cls.__ge__ = ge
|
|
|
|
|
|
return cls
|
|
|
|
|
|
|
|
|
def _add_repr(cls, ns=None, attrs=None):
|
|
|
"""
|
|
|
Add a repr method to *cls*.
|
|
|
"""
|
|
|
if attrs is None:
|
|
|
attrs = [a for a in cls.__attrs_attrs__ if a.repr]
|
|
|
|
|
|
def repr_(self):
|
|
|
"""
|
|
|
Automatically created by attrs.
|
|
|
"""
|
|
|
real_cls = self.__class__
|
|
|
if ns is None:
|
|
|
qualname = getattr(real_cls, "__qualname__", None)
|
|
|
if qualname is not None:
|
|
|
class_name = qualname.rsplit(">.", 1)[-1]
|
|
|
else:
|
|
|
class_name = real_cls.__name__
|
|
|
else:
|
|
|
class_name = ns + "." + real_cls.__name__
|
|
|
|
|
|
return "{0}({1})".format(
|
|
|
class_name,
|
|
|
", ".join(a.name + "=" + repr(getattr(self, a.name))
|
|
|
for a in attrs)
|
|
|
)
|
|
|
cls.__repr__ = repr_
|
|
|
return cls
|
|
|
|
|
|
|
|
|
def _add_init(cls, frozen):
|
|
|
"""
|
|
|
Add a __init__ method to *cls*. If *frozen* is True, make it immutable.
|
|
|
"""
|
|
|
attrs = [a for a in cls.__attrs_attrs__
|
|
|
if a.init or a.default is not NOTHING]
|
|
|
|
|
|
# We cache the generated init methods for the same kinds of attributes.
|
|
|
sha1 = hashlib.sha1()
|
|
|
r = repr(attrs)
|
|
|
if not isinstance(r, bytes):
|
|
|
r = r.encode('utf-8')
|
|
|
sha1.update(r)
|
|
|
unique_filename = "<attrs generated init {0}>".format(
|
|
|
sha1.hexdigest()
|
|
|
)
|
|
|
|
|
|
script, globs = _attrs_to_script(
|
|
|
attrs,
|
|
|
frozen,
|
|
|
getattr(cls, "__attrs_post_init__", False),
|
|
|
)
|
|
|
locs = {}
|
|
|
bytecode = compile(script, unique_filename, "exec")
|
|
|
attr_dict = dict((a.name, a) for a in attrs)
|
|
|
globs.update({
|
|
|
"NOTHING": NOTHING,
|
|
|
"attr_dict": attr_dict,
|
|
|
})
|
|
|
if frozen is True:
|
|
|
# Save the lookup overhead in __init__ if we need to circumvent
|
|
|
# immutability.
|
|
|
globs["_cached_setattr"] = _obj_setattr
|
|
|
eval(bytecode, globs, locs)
|
|
|
init = locs["__init__"]
|
|
|
|
|
|
# In order of debuggers like PDB being able to step through the code,
|
|
|
# we add a fake linecache entry.
|
|
|
linecache.cache[unique_filename] = (
|
|
|
len(script),
|
|
|
None,
|
|
|
script.splitlines(True),
|
|
|
unique_filename
|
|
|
)
|
|
|
cls.__init__ = init
|
|
|
return cls
|
|
|
|
|
|
|
|
|
def _add_pickle(cls):
|
|
|
"""
|
|
|
Add pickle helpers, needed for frozen and slotted classes
|
|
|
"""
|
|
|
def _slots_getstate__(obj):
|
|
|
"""
|
|
|
Play nice with pickle.
|
|
|
"""
|
|
|
return tuple(getattr(obj, a.name) for a in fields(obj.__class__))
|
|
|
|
|
|
def _slots_setstate__(obj, state):
|
|
|
"""
|
|
|
Play nice with pickle.
|
|
|
"""
|
|
|
__bound_setattr = _obj_setattr.__get__(obj, Attribute)
|
|
|
for a, value in zip(fields(obj.__class__), state):
|
|
|
__bound_setattr(a.name, value)
|
|
|
|
|
|
cls.__getstate__ = _slots_getstate__
|
|
|
cls.__setstate__ = _slots_setstate__
|
|
|
return cls
|
|
|
|
|
|
|
|
|
def fields(cls):
|
|
|
"""
|
|
|
Returns 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 attr.exceptions.NotAnAttrsClassError: If *cls* is not an ``attrs``
|
|
|
class.
|
|
|
|
|
|
:rtype: tuple (with name accesors) of :class:`attr.Attribute`
|
|
|
|
|
|
.. versionchanged:: 16.2.0 Returned tuple allows accessing the fields
|
|
|
by name.
|
|
|
"""
|
|
|
if not isclass(cls):
|
|
|
raise TypeError("Passed object must be a class.")
|
|
|
attrs = getattr(cls, "__attrs_attrs__", None)
|
|
|
if attrs is None:
|
|
|
raise NotAnAttrsClassError(
|
|
|
"{cls!r} is not an attrs-decorated class.".format(cls=cls)
|
|
|
)
|
|
|
return attrs
|
|
|
|
|
|
|
|
|
def validate(inst):
|
|
|
"""
|
|
|
Validate all attributes on *inst* that have a validator.
|
|
|
|
|
|
Leaves all exceptions through.
|
|
|
|
|
|
:param inst: Instance of a class with ``attrs`` attributes.
|
|
|
"""
|
|
|
if _config._run_validators is False:
|
|
|
return
|
|
|
|
|
|
for a in fields(inst.__class__):
|
|
|
v = a.validator
|
|
|
if v is not None:
|
|
|
v(inst, a, getattr(inst, a.name))
|
|
|
|
|
|
|
|
|
def _attrs_to_script(attrs, frozen, post_init):
|
|
|
"""
|
|
|
Return a script of an initializer for *attrs* and a dict of globals.
|
|
|
|
|
|
The globals are expected by the generated script.
|
|
|
|
|
|
If *frozen* is True, we cannot set the attributes directly so we use
|
|
|
a cached ``object.__setattr__``.
|
|
|
"""
|
|
|
lines = []
|
|
|
if frozen is True:
|
|
|
lines.append(
|
|
|
# Circumvent the __setattr__ descriptor to save one lookup per
|
|
|
# assignment.
|
|
|
"_setattr = _cached_setattr.__get__(self, self.__class__)"
|
|
|
)
|
|
|
|
|
|
def fmt_setter(attr_name, value_var):
|
|
|
return "_setattr('%(attr_name)s', %(value_var)s)" % {
|
|
|
"attr_name": attr_name,
|
|
|
"value_var": value_var,
|
|
|
}
|
|
|
|
|
|
def fmt_setter_with_converter(attr_name, value_var):
|
|
|
conv_name = _init_convert_pat.format(attr_name)
|
|
|
return "_setattr('%(attr_name)s', %(conv)s(%(value_var)s))" % {
|
|
|
"attr_name": attr_name,
|
|
|
"value_var": value_var,
|
|
|
"conv": conv_name,
|
|
|
}
|
|
|
else:
|
|
|
def fmt_setter(attr_name, value):
|
|
|
return "self.%(attr_name)s = %(value)s" % {
|
|
|
"attr_name": attr_name,
|
|
|
"value": value,
|
|
|
}
|
|
|
|
|
|
def fmt_setter_with_converter(attr_name, value_var):
|
|
|
conv_name = _init_convert_pat.format(attr_name)
|
|
|
return "self.%(attr_name)s = %(conv)s(%(value_var)s)" % {
|
|
|
"attr_name": attr_name,
|
|
|
"value_var": value_var,
|
|
|
"conv": conv_name,
|
|
|
}
|
|
|
|
|
|
args = []
|
|
|
attrs_to_validate = []
|
|
|
|
|
|
# This is a dictionary of names to validator and converter callables.
|
|
|
# Injecting this into __init__ globals lets us avoid lookups.
|
|
|
names_for_globals = {}
|
|
|
|
|
|
for a in attrs:
|
|
|
if a.validator:
|
|
|
attrs_to_validate.append(a)
|
|
|
attr_name = a.name
|
|
|
arg_name = a.name.lstrip("_")
|
|
|
has_factory = isinstance(a.default, Factory)
|
|
|
if has_factory and a.default.takes_self:
|
|
|
maybe_self = "self"
|
|
|
else:
|
|
|
maybe_self = ""
|
|
|
if a.init is False:
|
|
|
if has_factory:
|
|
|
init_factory_name = _init_factory_pat.format(a.name)
|
|
|
if a.convert is not None:
|
|
|
lines.append(fmt_setter_with_converter(
|
|
|
attr_name,
|
|
|
init_factory_name + "({0})".format(maybe_self)))
|
|
|
conv_name = _init_convert_pat.format(a.name)
|
|
|
names_for_globals[conv_name] = a.convert
|
|
|
else:
|
|
|
lines.append(fmt_setter(
|
|
|
attr_name,
|
|
|
init_factory_name + "({0})".format(maybe_self)
|
|
|
))
|
|
|
names_for_globals[init_factory_name] = a.default.factory
|
|
|
else:
|
|
|
if a.convert is not None:
|
|
|
lines.append(fmt_setter_with_converter(
|
|
|
attr_name,
|
|
|
"attr_dict['{attr_name}'].default"
|
|
|
.format(attr_name=attr_name)
|
|
|
))
|
|
|
conv_name = _init_convert_pat.format(a.name)
|
|
|
names_for_globals[conv_name] = a.convert
|
|
|
else:
|
|
|
lines.append(fmt_setter(
|
|
|
attr_name,
|
|
|
"attr_dict['{attr_name}'].default"
|
|
|
.format(attr_name=attr_name)
|
|
|
))
|
|
|
elif a.default is not NOTHING and not has_factory:
|
|
|
args.append(
|
|
|
"{arg_name}=attr_dict['{attr_name}'].default".format(
|
|
|
arg_name=arg_name,
|
|
|
attr_name=attr_name,
|
|
|
)
|
|
|
)
|
|
|
if a.convert is not None:
|
|
|
lines.append(fmt_setter_with_converter(attr_name, arg_name))
|
|
|
names_for_globals[_init_convert_pat.format(a.name)] = a.convert
|
|
|
else:
|
|
|
lines.append(fmt_setter(attr_name, arg_name))
|
|
|
elif has_factory:
|
|
|
args.append("{arg_name}=NOTHING".format(arg_name=arg_name))
|
|
|
lines.append("if {arg_name} is not NOTHING:"
|
|
|
.format(arg_name=arg_name))
|
|
|
init_factory_name = _init_factory_pat.format(a.name)
|
|
|
if a.convert is not None:
|
|
|
lines.append(" " + fmt_setter_with_converter(attr_name,
|
|
|
arg_name))
|
|
|
lines.append("else:")
|
|
|
lines.append(" " + fmt_setter_with_converter(
|
|
|
attr_name,
|
|
|
init_factory_name + "({0})".format(maybe_self)
|
|
|
))
|
|
|
names_for_globals[_init_convert_pat.format(a.name)] = a.convert
|
|
|
else:
|
|
|
lines.append(" " + fmt_setter(attr_name, arg_name))
|
|
|
lines.append("else:")
|
|
|
lines.append(" " + fmt_setter(
|
|
|
attr_name,
|
|
|
init_factory_name + "({0})".format(maybe_self)
|
|
|
))
|
|
|
names_for_globals[init_factory_name] = a.default.factory
|
|
|
else:
|
|
|
args.append(arg_name)
|
|
|
if a.convert is not None:
|
|
|
lines.append(fmt_setter_with_converter(attr_name, arg_name))
|
|
|
names_for_globals[_init_convert_pat.format(a.name)] = a.convert
|
|
|
else:
|
|
|
lines.append(fmt_setter(attr_name, arg_name))
|
|
|
|
|
|
if attrs_to_validate: # we can skip this if there are no validators.
|
|
|
names_for_globals["_config"] = _config
|
|
|
lines.append("if _config._run_validators is True:")
|
|
|
for a in attrs_to_validate:
|
|
|
val_name = "__attr_validator_{}".format(a.name)
|
|
|
attr_name = "__attr_{}".format(a.name)
|
|
|
lines.append(" {}(self, {}, self.{})".format(
|
|
|
val_name, attr_name, a.name))
|
|
|
names_for_globals[val_name] = a.validator
|
|
|
names_for_globals[attr_name] = a
|
|
|
if post_init:
|
|
|
lines.append("self.__attrs_post_init__()")
|
|
|
|
|
|
return """\
|
|
|
def __init__(self, {args}):
|
|
|
{lines}
|
|
|
""".format(
|
|
|
args=", ".join(args),
|
|
|
lines="\n ".join(lines) if lines else "pass",
|
|
|
), names_for_globals
|
|
|
|
|
|
|
|
|
class Attribute(object):
|
|
|
"""
|
|
|
*Read-only* representation of an attribute.
|
|
|
|
|
|
:attribute name: The name of the attribute.
|
|
|
|
|
|
Plus *all* arguments of :func:`attr.ib`.
|
|
|
"""
|
|
|
__slots__ = (
|
|
|
"name", "default", "validator", "repr", "cmp", "hash", "init",
|
|
|
"convert", "metadata",
|
|
|
)
|
|
|
|
|
|
def __init__(self, name, default, validator, repr, cmp, hash, init,
|
|
|
convert=None, metadata=None):
|
|
|
# Cache this descriptor here to speed things up later.
|
|
|
bound_setattr = _obj_setattr.__get__(self, Attribute)
|
|
|
|
|
|
bound_setattr("name", name)
|
|
|
bound_setattr("default", default)
|
|
|
bound_setattr("validator", validator)
|
|
|
bound_setattr("repr", repr)
|
|
|
bound_setattr("cmp", cmp)
|
|
|
bound_setattr("hash", hash)
|
|
|
bound_setattr("init", init)
|
|
|
bound_setattr("convert", convert)
|
|
|
bound_setattr("metadata", (metadata_proxy(metadata) if metadata
|
|
|
else _empty_metadata_singleton))
|
|
|
|
|
|
def __setattr__(self, name, value):
|
|
|
raise FrozenInstanceError()
|
|
|
|
|
|
@classmethod
|
|
|
def from_counting_attr(cls, name, ca):
|
|
|
inst_dict = {
|
|
|
k: getattr(ca, k)
|
|
|
for k
|
|
|
in Attribute.__slots__
|
|
|
if k not in (
|
|
|
"name", "validator", "default",
|
|
|
) # exclude methods
|
|
|
}
|
|
|
return cls(name=name, validator=ca._validator, default=ca._default,
|
|
|
**inst_dict)
|
|
|
|
|
|
# Don't use _add_pickle since fields(Attribute) doesn't work
|
|
|
def __getstate__(self):
|
|
|
"""
|
|
|
Play nice with pickle.
|
|
|
"""
|
|
|
return tuple(getattr(self, name) if name != "metadata"
|
|
|
else dict(self.metadata)
|
|
|
for name in self.__slots__)
|
|
|
|
|
|
def __setstate__(self, state):
|
|
|
"""
|
|
|
Play nice with pickle.
|
|
|
"""
|
|
|
bound_setattr = _obj_setattr.__get__(self, Attribute)
|
|
|
for name, value in zip(self.__slots__, state):
|
|
|
if name != "metadata":
|
|
|
bound_setattr(name, value)
|
|
|
else:
|
|
|
bound_setattr(name, metadata_proxy(value) if value else
|
|
|
_empty_metadata_singleton)
|
|
|
|
|
|
|
|
|
_a = [Attribute(name=name, default=NOTHING, validator=None,
|
|
|
repr=True, cmp=True, hash=(name != "metadata"), init=True)
|
|
|
for name in Attribute.__slots__]
|
|
|
|
|
|
Attribute = _add_hash(
|
|
|
_add_cmp(_add_repr(Attribute, attrs=_a), attrs=_a),
|
|
|
attrs=[a for a in _a if a.hash]
|
|
|
)
|
|
|
|
|
|
|
|
|
class _CountingAttr(object):
|
|
|
"""
|
|
|
Intermediate representation of attributes that uses a counter to preserve
|
|
|
the order in which the attributes have been defined.
|
|
|
|
|
|
*Internal* data structure of the attrs library. Running into is most
|
|
|
likely the result of a bug like a forgotten `@attr.s` decorator.
|
|
|
"""
|
|
|
__slots__ = ("counter", "_default", "repr", "cmp", "hash", "init",
|
|
|
"metadata", "_validator", "convert")
|
|
|
__attrs_attrs__ = tuple(
|
|
|
Attribute(name=name, default=NOTHING, validator=None,
|
|
|
repr=True, cmp=True, hash=True, init=True)
|
|
|
for name
|
|
|
in ("counter", "_default", "repr", "cmp", "hash", "init",)
|
|
|
) + (
|
|
|
Attribute(name="metadata", default=None, validator=None,
|
|
|
repr=True, cmp=True, hash=False, init=True),
|
|
|
)
|
|
|
cls_counter = 0
|
|
|
|
|
|
def __init__(self, default, validator, repr, cmp, hash, init, convert,
|
|
|
metadata):
|
|
|
_CountingAttr.cls_counter += 1
|
|
|
self.counter = _CountingAttr.cls_counter
|
|
|
self._default = default
|
|
|
# If validator is a list/tuple, wrap it using helper validator.
|
|
|
if validator and isinstance(validator, (list, tuple)):
|
|
|
self._validator = and_(*validator)
|
|
|
else:
|
|
|
self._validator = validator
|
|
|
self.repr = repr
|
|
|
self.cmp = cmp
|
|
|
self.hash = hash
|
|
|
self.init = init
|
|
|
self.convert = convert
|
|
|
self.metadata = metadata
|
|
|
|
|
|
def validator(self, meth):
|
|
|
"""
|
|
|
Decorator that adds *meth* to the list of validators.
|
|
|
|
|
|
Returns *meth* unchanged.
|
|
|
|
|
|
.. versionadded:: 17.1.0
|
|
|
"""
|
|
|
if self._validator is None:
|
|
|
self._validator = meth
|
|
|
else:
|
|
|
self._validator = and_(self._validator, meth)
|
|
|
return meth
|
|
|
|
|
|
def default(self, meth):
|
|
|
"""
|
|
|
Decorator that allows to set the default for an attribute.
|
|
|
|
|
|
Returns *meth* unchanged.
|
|
|
|
|
|
:raises DefaultAlreadySetError: If default has been set before.
|
|
|
|
|
|
.. versionadded:: 17.1.0
|
|
|
"""
|
|
|
if self._default is not NOTHING:
|
|
|
raise DefaultAlreadySetError()
|
|
|
|
|
|
self._default = Factory(meth, takes_self=True)
|
|
|
|
|
|
return meth
|
|
|
|
|
|
|
|
|
_CountingAttr = _add_cmp(_add_repr(_CountingAttr))
|
|
|
|
|
|
|
|
|
@attributes(slots=True, init=False)
|
|
|
class Factory(object):
|
|
|
"""
|
|
|
Stores a factory callable.
|
|
|
|
|
|
If passed as the default value to :func:`attr.ib`, 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*
|
|
|
"""
|
|
|
factory = attr()
|
|
|
takes_self = attr()
|
|
|
|
|
|
def __init__(self, factory, takes_self=False):
|
|
|
"""
|
|
|
`Factory` is part of the default machinery so if we want a default
|
|
|
value here, we have to implement it ourselves.
|
|
|
"""
|
|
|
self.factory = factory
|
|
|
self.takes_self = takes_self
|
|
|
|
|
|
|
|
|
def make_class(name, attrs, bases=(object,), **attributes_arguments):
|
|
|
"""
|
|
|
A quick way to create a new class called *name* with *attrs*.
|
|
|
|
|
|
:param name: The name for the new class.
|
|
|
:type name: str
|
|
|
|
|
|
:param attrs: A list of names or a dictionary of mappings of names to
|
|
|
attributes.
|
|
|
:type attrs: :class:`list` or :class:`dict`
|
|
|
|
|
|
:param tuple bases: Classes that the new class will subclass.
|
|
|
|
|
|
:param attributes_arguments: Passed unmodified to :func:`attr.s`.
|
|
|
|
|
|
:return: A new class with *attrs*.
|
|
|
:rtype: type
|
|
|
|
|
|
.. versionadded:: 17.1.0 *bases*
|
|
|
"""
|
|
|
if isinstance(attrs, dict):
|
|
|
cls_dict = attrs
|
|
|
elif isinstance(attrs, (list, tuple)):
|
|
|
cls_dict = dict((a, attr()) for a in attrs)
|
|
|
else:
|
|
|
raise TypeError("attrs argument must be a dict or a list.")
|
|
|
|
|
|
return attributes(**attributes_arguments)(type(name, bases, cls_dict))
|
|
|
|
|
|
|
|
|
# These are required by whithin this module so we define them here and merely
|
|
|
# import into .validators.
|
|
|
|
|
|
|
|
|
@attributes(slots=True, hash=True)
|
|
|
class _AndValidator(object):
|
|
|
"""
|
|
|
Compose many validators to a single one.
|
|
|
"""
|
|
|
_validators = attr()
|
|
|
|
|
|
def __call__(self, inst, attr, value):
|
|
|
for v in self._validators:
|
|
|
v(inst, attr, value)
|
|
|
|
|
|
|
|
|
def and_(*validators):
|
|
|
"""
|
|
|
A validator that composes multiple validators into one.
|
|
|
|
|
|
When called on a value, it runs all wrapped validators.
|
|
|
|
|
|
:param validators: Arbitrary number of validators.
|
|
|
:type validators: callables
|
|
|
|
|
|
.. versionadded:: 17.1.0
|
|
|
"""
|
|
|
vals = []
|
|
|
for validator in validators:
|
|
|
vals.extend(
|
|
|
validator._validators if isinstance(validator, _AndValidator)
|
|
|
else [validator]
|
|
|
)
|
|
|
|
|
|
return _AndValidator(tuple(vals))
|
|
|
|
