Merge branch 'feature/UpdateAttrs' into develop

CHANGES.md

@@ -1,5 +1,6 @@
 ### 0.23.0 (2019-xx-xx xx:xx:xx UTC)
 
+* Update attr 20.1.0.dev0 (4bd6827) to 20.2.0 (4f74fba)
 
 
 [develop changelog]

lib/attr/__init__.py

@@ -1,10 +1,12 @@
 from __future__ import absolute_import, division, print_function
 
+import sys
+
 from functools import partial
 
-from . import converters, exceptions, filters, validators
+from . import converters, exceptions, filters, setters, validators
 from ._config import get_run_validators, set_run_validators
-from ._funcs import asdict, assoc, astuple, evolve, has
+from ._funcs import asdict, assoc, astuple, evolve, has, resolve_types
 from ._make import (
     NOTHING,
     Attribute,
@@ -19,7 +21,7 @@ from ._make import (
 from ._version_info import VersionInfo
 
 
-__version__ = "20.1.0.dev0"
+__version__ = "20.2.0"
 __version_info__ = VersionInfo._from_version_string(__version__)
 
 __title__ = "attrs"
@@ -39,7 +41,6 @@ s = attributes = attrs
 ib = attr = attrib
 dataclass = partial(attrs, auto_attribs=True)  # happy Easter ;)
 
-
 __all__ = [
     "Attribute",
     "Factory",
@@ -61,8 +62,15 @@ __all__ = [
     "has",
     "ib",
     "make_class",
+    "resolve_types",
     "s",
     "set_run_validators",
+    "setters",
     "validate",
     "validators",
 ]
+
+if sys.version_info[:2] >= (3, 6):
+    from ._next_gen import define, field, frozen, mutable
+
+    __all__.extend((define, field, frozen, mutable))

lib/attr/__init__.pyi

@@ -18,6 +18,7 @@ from typing import (
 from . import exceptions as exceptions
 from . import filters as filters
 from . import converters as converters
+from . import setters as setters
 from . import validators as validators
 
 from ._version_info import VersionInfo
@@ -37,20 +38,25 @@ _T = TypeVar("_T")
 _C = TypeVar("_C", bound=type)
 
 _ValidatorType = Callable[[Any, Attribute[_T], _T], Any]
-_ConverterType = Callable[[Any], _T]
+_ConverterType = Callable[[Any], Any]
 _FilterType = Callable[[Attribute[_T], _T], bool]
 _ReprType = Callable[[Any], str]
 _ReprArgType = Union[bool, _ReprType]
-# FIXME: in reality, if multiple validators are passed they must be in a list or tuple,
+_OnSetAttrType = Callable[[Any, Attribute[Any], Any], Any]
-# but those are invariant and so would prevent subtypes of _ValidatorType from working
+_OnSetAttrArgType = Union[
-# when passed in a list or tuple.
+    _OnSetAttrType, List[_OnSetAttrType], setters._NoOpType
+]
+# FIXME: in reality, if multiple validators are passed they must be in a list
+# or tuple, but those are invariant and so would prevent subtypes of
+# _ValidatorType from working when passed in a list or tuple.
 _ValidatorArgType = Union[_ValidatorType[_T], Sequence[_ValidatorType[_T]]]
 
 # _make --
 
 NOTHING: object
 
-# NOTE: Factory lies about its return type to make this possible: `x: List[int] = Factory(list)`
+# NOTE: Factory lies about its return type to make this possible:
+# `x: List[int] # = Factory(list)`
 # Work around mypy issue #4554 in the common case by using an overload.
 @overload
 def Factory(factory: Callable[[], _T]) -> _T: ...
@@ -70,16 +76,17 @@ class Attribute(Generic[_T]):
     order: bool
     hash: Optional[bool]
     init: bool
-    converter: Optional[_ConverterType[_T]]
+    converter: Optional[_ConverterType]
     metadata: Dict[Any, Any]
     type: Optional[Type[_T]]
     kw_only: bool
+    on_setattr: _OnSetAttrType
 
 # NOTE: We had several choices for the annotation to use for type arg:
 # 1) Type[_T]
 #   - Pros: Handles simple cases correctly
-#   - Cons: Might produce less informative errors in the case of conflicting TypeVars
+#   - Cons: Might produce less informative errors in the case of conflicting
-#   e.g. `attr.ib(default='bad', type=int)`
+#     TypeVars e.g. `attr.ib(default='bad', type=int)`
 # 2) Callable[..., _T]
 #   - Pros: Better error messages than #1 for conflicting TypeVars
 #   - Cons: Terrible error messages for validator checks.
@@ -97,7 +104,8 @@ class Attribute(Generic[_T]):
 # This makes this type of assignments possible:
 #     x: int = attr(8)
 #
-# This form catches explicit None or no default but with no other arguments returns Any.
+# This form catches explicit None or no default but with no other arguments
+# returns Any.
 @overload
 def attrib(
     default: None = ...,
@@ -113,9 +121,11 @@ def attrib(
     kw_only: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> Any: ...
 
-# This form catches an explicit None or no default and infers the type from the other arguments.
+# This form catches an explicit None or no default and infers the type from the
+# other arguments.
 @overload
 def attrib(
     default: None = ...,
@@ -126,11 +136,12 @@ def attrib(
     init: bool = ...,
     metadata: Optional[Mapping[Any, Any]] = ...,
     type: Optional[Type[_T]] = ...,
-    converter: Optional[_ConverterType[_T]] = ...,
+    converter: Optional[_ConverterType] = ...,
     factory: Optional[Callable[[], _T]] = ...,
     kw_only: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> _T: ...
 
 # This form catches an explicit default argument.
@@ -144,11 +155,12 @@ def attrib(
     init: bool = ...,
     metadata: Optional[Mapping[Any, Any]] = ...,
     type: Optional[Type[_T]] = ...,
-    converter: Optional[_ConverterType[_T]] = ...,
+    converter: Optional[_ConverterType] = ...,
     factory: Optional[Callable[[], _T]] = ...,
     kw_only: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> _T: ...
 
 # This form covers type=non-Type: e.g. forward references (str), Any
@@ -162,11 +174,83 @@ def attrib(
     init: bool = ...,
     metadata: Optional[Mapping[Any, Any]] = ...,
     type: object = ...,
-    converter: Optional[_ConverterType[_T]] = ...,
+    converter: Optional[_ConverterType] = ...,
     factory: Optional[Callable[[], _T]] = ...,
     kw_only: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> Any: ...
+@overload
+def field(
+    *,
+    default: None = ...,
+    validator: None = ...,
+    repr: _ReprArgType = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    converter: None = ...,
+    factory: None = ...,
+    kw_only: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> Any: ...
+
+# This form catches an explicit None or no default and infers the type from the
+# other arguments.
+@overload
+def field(
+    *,
+    default: None = ...,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: _ReprArgType = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    converter: Optional[_ConverterType] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> _T: ...
+
+# This form catches an explicit default argument.
+@overload
+def field(
+    *,
+    default: _T,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: _ReprArgType = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    converter: Optional[_ConverterType] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> _T: ...
+
+# This form covers type=non-Type: e.g. forward references (str), Any
+@overload
+def field(
+    *,
+    default: Optional[_T] = ...,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: _ReprArgType = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    converter: Optional[_ConverterType] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> Any: ...
 @overload
 def attrs(
@@ -187,6 +271,9 @@ def attrs(
     auto_exc: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    auto_detect: bool = ...,
+    getstate_setstate: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> _C: ...
 @overload
 def attrs(
@@ -207,8 +294,58 @@ def attrs(
     auto_exc: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    auto_detect: bool = ...,
+    getstate_setstate: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> Callable[[_C], _C]: ...
+@overload
+def define(
+    maybe_cls: _C,
+    *,
+    these: Optional[Dict[str, Any]] = ...,
+    repr: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+    auto_exc: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    auto_detect: bool = ...,
+    getstate_setstate: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
+) -> _C: ...
+@overload
+def define(
+    maybe_cls: None = ...,
+    *,
+    these: Optional[Dict[str, Any]] = ...,
+    repr: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+    auto_exc: bool = ...,
+    eq: Optional[bool] = ...,
+    order: Optional[bool] = ...,
+    auto_detect: bool = ...,
+    getstate_setstate: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> Callable[[_C], _C]: ...
 
+mutable = define
+frozen = define  # they differ only in their defaults
+
 # TODO: add support for returning NamedTuple from the mypy plugin
 class _Fields(Tuple[Attribute[Any], ...]):
     def __getattr__(self, name: str) -> Attribute[Any]: ...
@@ -216,9 +353,15 @@ class _Fields(Tuple[Attribute[Any], ...]):
 def fields(cls: type) -> _Fields: ...
 def fields_dict(cls: type) -> Dict[str, Attribute[Any]]: ...
 def validate(inst: Any) -> None: ...
+def resolve_types(
+    cls: _C,
+    globalns: Optional[Dict[str, Any]] = ...,
+    localns: Optional[Dict[str, Any]] = ...,
+) -> _C: ...
 
 # TODO: add support for returning a proper attrs class from the mypy plugin
-# we use Any instead of _CountingAttr so that e.g. `make_class('Foo', [attr.ib()])` is valid
+# we use Any instead of _CountingAttr so that e.g. `make_class('Foo',
+# [attr.ib()])` is valid
 def make_class(
     name: str,
     attrs: Union[List[str], Tuple[str, ...], Dict[str, Any]],
@@ -238,12 +381,14 @@ def make_class(
     auto_exc: bool = ...,
     eq: Optional[bool] = ...,
     order: Optional[bool] = ...,
+    on_setattr: Optional[_OnSetAttrArgType] = ...,
 ) -> type: ...
 
 # _funcs --
 
 # TODO: add support for returning TypedDict from the mypy plugin
-# FIXME: asdict/astuple do not honor their factory args.  waiting on one of these:
+# FIXME: asdict/astuple do not honor their factory args. Waiting on one of
+# these:
 # https://github.com/python/mypy/issues/4236
 # https://github.com/python/typing/issues/253
 def asdict(

lib/attr/_compat.py

@@ -19,9 +19,10 @@ else:
 
 
 if PY2:
-    from UserDict import IterableUserDict
     from collections import Mapping, Sequence
 
+    from UserDict import IterableUserDict
+
     # We 'bundle' isclass instead of using inspect as importing inspect is
     # fairly expensive (order of 10-15 ms for a modern machine in 2016)
     def isclass(klass):

lib/attr/_funcs.py

@@ -287,4 +287,52 @@ def evolve(inst, **changes):
         init_name = attr_name if attr_name[0] != "_" else attr_name[1:]
         if init_name not in changes:
             changes[init_name] = getattr(inst, attr_name)
+
     return cls(**changes)
+
+
+def resolve_types(cls, globalns=None, localns=None):
+    """
+    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.
+
+    :raise TypeError: If *cls* is not a class.
+    :raise attr.exceptions.NotAnAttrsClassError: If *cls* is not an ``attrs``
+        class.
+    :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** `attr.s`. That means
+        the decorator has to come in the line **before** `attr.s`.
+
+    ..  versionadded:: 20.1.0
+    """
+    try:
+        # Since calling get_type_hints is expensive we cache whether we've
+        # done it already.
+        cls.__attrs_types_resolved__
+    except AttributeError:
+        import typing
+
+        hints = typing.get_type_hints(cls, globalns=globalns, localns=localns)
+        for field in fields(cls):
+            if field.name in hints:
+                # Since fields have been frozen we must work around it.
+                _obj_setattr(field, "type", hints[field.name])
+        cls.__attrs_types_resolved__ = True
+
+    # Return the class so you can use it as a decorator too.
+    return cls

lib/attr/_next_gen.py

@@ -0,0 +1,158 @@
+"""
+This is a Python 3.6 and later-only, keyword-only, and **provisional** API that
+calls `attr.s` with different default values.
+
+Provisional APIs that shall become "import attrs" one glorious day.
+"""
+
+from functools import partial
+
+from attr.exceptions import UnannotatedAttributeError
+
+from . import setters
+from ._make import NOTHING, _frozen_setattrs, attrib, attrs
+
+
+def define(
+    maybe_cls=None,
+    *,
+    these=None,
+    repr=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,
+):
+    r"""
+    The only behavioral differences are the handling of the *auto_attribs*
+    option:
+
+    :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 all attributes are annotated and no `attr.ib` is found, it assumes
+          *auto_attribs=True*.
+       2. Otherwise it assumes *auto_attribs=False* and tries to collect
+          `attr.ib`\ s.
+
+    and that mutable classes (``frozen=False``) validate on ``__setattr__``.
+
+    .. versionadded:: 20.1.0
+    """
+
+    def do_it(cls, auto_attribs):
+        return attrs(
+            maybe_cls=cls,
+            these=these,
+            repr=repr,
+            hash=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,
+        )
+
+    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)
+
+        # By default, mutable classes validate on setattr.
+        if frozen is False and on_setattr is None:
+            on_setattr = setters.validate
+
+        # However, if we subclass a frozen class, we inherit the immutability
+        # and disable 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)
+
+    # maybe_cls's type depends on the usage of the decorator.  It's a class
+    # if it's used as `@attrs` but ``None`` if used as `@attrs()`.
+    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,
+    converter=None,
+    factory=None,
+    kw_only=False,
+    eq=None,
+    order=None,
+    on_setattr=None,
+):
+    """
+    Identical to `attr.ib`, except keyword-only and with some arguments
+    removed.
+
+    .. versionadded:: 20.1.0
+    """
+    return attrib(
+        default=default,
+        validator=validator,
+        repr=repr,
+        hash=hash,
+        init=init,
+        metadata=metadata,
+        converter=converter,
+        factory=factory,
+        kw_only=kw_only,
+        eq=eq,
+        order=order,
+        on_setattr=on_setattr,
+    )

lib/attr/converters.py

@@ -4,11 +4,11 @@ Commonly useful converters.
 
 from __future__ import absolute_import, division, print_function
 
-from ._make import NOTHING, Factory, chain
+from ._make import NOTHING, Factory, pipe
 
 
 __all__ = [
-    "chain",
+    "pipe",
     "optional",
     "default_if_none",
 ]

lib/attr/converters.pyi

@@ -3,11 +3,9 @@ from . import _ConverterType
 
 _T = TypeVar("_T")
 
-def chain(*validators: _ConverterType[_T]) -> _ConverterType[_T]: ...
+def pipe(*validators: _ConverterType) -> _ConverterType: ...
-def optional(
+def optional(converter: _ConverterType) -> _ConverterType: ...
-    converter: _ConverterType[_T],
-) -> _ConverterType[Optional[_T]]: ...
 @overload
-def default_if_none(default: _T) -> _ConverterType[_T]: ...
+def default_if_none(default: _T) -> _ConverterType: ...
 @overload
-def default_if_none(*, factory: Callable[[], _T]) -> _ConverterType[_T]: ...
+def default_if_none(*, factory: Callable[[], _T]) -> _ConverterType: ...

lib/attr/exceptions.py

@@ -1,20 +1,37 @@
 from __future__ import absolute_import, division, print_function
 
 
-class FrozenInstanceError(AttributeError):
+class FrozenError(AttributeError):
     """
-    A frozen/immutable instance has been attempted to be modified.
+    A frozen/immutable instance or attribute haave been attempted to be
+    modified.
 
     It mirrors the behavior of ``namedtuples`` by using the same error message
     and subclassing `AttributeError`.
 
-    .. versionadded:: 16.1.0
+    .. versionadded:: 20.1.0
     """
 
     msg = "can't set attribute"
     args = [msg]
 
 
+class FrozenInstanceError(FrozenError):
+    """
+    A frozen instance has been attempted to be modified.
+
+    .. versionadded:: 16.1.0
+    """
+
+
+class FrozenAttributeError(FrozenError):
+    """
+    A frozen attribute has been attempted to be modified.
+
+    .. versionadded:: 20.1.0
+    """
+
+
 class AttrsAttributeNotFoundError(ValueError):
     """
     An ``attrs`` function couldn't find an attribute that the user asked for.
@@ -51,7 +68,8 @@ class UnannotatedAttributeError(RuntimeError):
 
 class PythonTooOldError(RuntimeError):
     """
-    An ``attrs`` feature requiring a more recent python version has been used.
+    It was attempted to use an ``attrs`` feature that requires a newer Python
+    version.
 
     .. versionadded:: 18.2.0
     """

lib/attr/exceptions.pyi

@@ -1,8 +1,10 @@
 from typing import Any
 
-class FrozenInstanceError(AttributeError):
+class FrozenError(AttributeError):
     msg: str = ...
 
+class FrozenInstanceError(FrozenError): ...
+class FrozenAttributeError(FrozenError): ...
 class AttrsAttributeNotFoundError(ValueError): ...
 class NotAnAttrsClassError(ValueError): ...
 class DefaultAlreadySetError(RuntimeError): ...

lib/attr/setters.py

@@ -0,0 +1,77 @@
+"""
+Commonly used hooks for on_setattr.
+"""
+
+from __future__ import absolute_import, division, print_function
+
+from . import _config
+from .exceptions import FrozenAttributeError
+
+
+def pipe(*setters):
+    """
+    Run all *setters* and return the return value of the last one.
+
+    .. versionadded:: 20.1.0
+    """
+
+    def wrapped_pipe(instance, attrib, new_value):
+        rv = new_value
+
+        for setter in setters:
+            rv = setter(instance, attrib, rv)
+
+        return rv
+
+    return wrapped_pipe
+
+
+def frozen(_, __, ___):
+    """
+    Prevent an attribute to be modified.
+
+    .. versionadded:: 20.1.0
+    """
+    raise FrozenAttributeError()
+
+
+def validate(instance, attrib, new_value):
+    """
+    Run *attrib*'s validator on *new_value* if it has one.
+
+    .. versionadded:: 20.1.0
+    """
+    if _config._run_validators is False:
+        return new_value
+
+    v = attrib.validator
+    if not v:
+        return new_value
+
+    v(instance, attrib, new_value)
+
+    return new_value
+
+
+def convert(instance, attrib, new_value):
+    """
+    Run *attrib*'s converter -- if it has one --  on *new_value* and return the
+    result.
+
+    .. versionadded:: 20.1.0
+    """
+    c = attrib.converter
+    if c:
+        return c(new_value)
+
+    return new_value
+
+
+NO_OP = object()
+"""
+Sentinel for disabling class-wide *on_setattr* hooks for certain attributes.
+
+Does not work in `pipe` or within lists.
+
+.. versionadded:: 20.1.0
+"""

lib/attr/setters.pyi

@@ -0,0 +1,18 @@
+from . import _OnSetAttrType, Attribute
+from typing import TypeVar, Any, NewType, NoReturn, cast
+
+_T = TypeVar("_T")
+
+def frozen(
+    instance: Any, attribute: Attribute, new_value: Any
+) -> NoReturn: ...
+def pipe(*setters: _OnSetAttrType) -> _OnSetAttrType: ...
+def validate(instance: Any, attribute: Attribute[_T], new_value: _T) -> _T: ...
+
+# convert is allowed to return Any, because they can be chained using pipe.
+def convert(
+    instance: Any, attribute: Attribute[Any], new_value: Any
+) -> Any: ...
+
+_NoOpType = NewType("_NoOpType", object)
+NO_OP: _NoOpType

lib/attr/validators.py

@@ -67,7 +67,7 @@ def instance_of(type):
     return _InstanceOfValidator(type)
 
 
-@attrs(repr=False, frozen=True)
+@attrs(repr=False, frozen=True, slots=True)
 class _MatchesReValidator(object):
     regex = attrib()
     flags = attrib()
@@ -171,7 +171,8 @@ def provides(interface):
     performed using ``interface.providedBy(value)`` (see `zope.interface
     <https://zopeinterface.readthedocs.io/en/latest/>`_).
 
-    :param zope.interface.Interface interface: The interface to check for.
+    :param interface: The interface to check for.
+    :type interface: ``zope.interface.Interface``
 
     :raises TypeError: With a human readable error message, the attribute
         (of type `attr.Attribute`), the expected interface, and the