Sync attr stubs from attrs github repo (#2720)

This include some changes like kw_only and some formatting changes.

third_party/2and3/attr/__init__.pyi

@@ -1,16 +1,31 @@
-from typing import Any, Callable, Dict, Generic, List, Optional, Sequence, Mapping, Tuple, Type, TypeVar, Union, overload
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    Sequence,
+    Mapping,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+)
+
 # `import X as X` is required to make these public
 from . import exceptions as exceptions
 from . import filters as filters
 from . import converters as converters
 from . import validators as validators
 
-_T = TypeVar('_T')
-_C = TypeVar('_C', bound=type)
+_T = TypeVar("_T")
+_C = TypeVar("_C", bound=type)
 
-_ValidatorType = Callable[[Any, Attribute, _T], Any]
+_ValidatorType = Callable[[Any, Attribute[_T], _T], Any]
 _ConverterType = Callable[[Any], _T]
-_FilterType = Callable[[Attribute, Any], bool]
+_FilterType = Callable[[Attribute[_T], _T], bool]
 # 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.
@@ -25,7 +40,10 @@ NOTHING: object
 @overload
 def Factory(factory: Callable[[], _T]) -> _T: ...
 @overload
-def Factory(factory: Union[Callable[[Any], _T], Callable[[], _T]], takes_self: bool = ...) -> _T: ...
+def Factory(
+    factory: Union[Callable[[Any], _T], Callable[[], _T]],
+    takes_self: bool = ...,
+) -> _T: ...
 
 class Attribute(Generic[_T]):
     name: str
@@ -38,30 +56,26 @@ class Attribute(Generic[_T]):
     converter: Optional[_ConverterType[_T]]
     metadata: Dict[Any, Any]
     type: Optional[Type[_T]]
-    def __lt__(self, x: Attribute) -> bool: ...
-    def __le__(self, x: Attribute) -> bool: ...
-    def __gt__(self, x: Attribute) -> bool: ...
-    def __ge__(self, x: Attribute) -> bool: ...
-
+    kw_only: bool
+    def __lt__(self, x: Attribute[_T]) -> bool: ...
+    def __le__(self, x: Attribute[_T]) -> bool: ...
+    def __gt__(self, x: Attribute[_T]) -> bool: ...
+    def __ge__(self, x: Attribute[_T]) -> bool: ...
 
 # NOTE: We had several choices for the annotation to use for type arg:
 # 1) Type[_T]
-#   - Pros: works in PyCharm without plugin support
-#   - Cons: produces less informative error in the case of conflicting TypeVars
-#     e.g. `attr.ib(default='bad', type=int)`
+#   - Pros: Handles simple cases correctly
+#   - Cons: Might produce less informative errors in the case of conflicting TypeVars
+#   e.g. `attr.ib(default='bad', type=int)`
 # 2) Callable[..., _T]
-#   - Pros: more informative errors than #1
-#   - Cons: validator tests results in confusing error.
-#     e.g. `attr.ib(type=int, validator=validate_str)`
+#   - Pros: Better error messages than #1 for conflicting TypeVars
+#   - Cons: Terrible error messages for validator checks.
+#   e.g. attr.ib(type=int, validator=validate_str)
+#        -> error: Cannot infer function type argument
 # 3) type (and do all of the work in the mypy plugin)
-#   - Pros: in mypy, the behavior of type argument is exactly the same as with
-#     annotations.
-#   - Cons: completely disables type inspections in PyCharm when using the
-#     type arg.
-# We chose option #1 until either PyCharm adds support for attrs, or python 2
-# reaches EOL.
-
-# NOTE: If you update these, update `ib` and `attr` below.
+#   - Pros: Simple here, and we could customize the plugin with our own errors.
+#   - Cons: Would need to write mypy plugin code to handle all the cases.
+# We chose option #1.
 
 # `attr` lies about its return type to make the following possible:
 #     attr()    -> Any
@@ -72,111 +86,133 @@ class Attribute(Generic[_T]):
 #
 # This form catches explicit None or no default but with no other arguments returns Any.
 @overload
-def attrib(default: None = ...,
-           validator: None = ...,
-           repr: bool = ...,
-           cmp: bool = ...,
-           hash: Optional[bool] = ...,
-           init: bool = ...,
-           convert: None = ...,
-           metadata: Optional[Mapping[Any, Any]] = ...,
-           type: None = ...,
-           converter: None = ...,
-           factory: None = ...,
-           ) -> Any: ...
+def attrib(
+    default: None = ...,
+    validator: None = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    convert: None = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    type: None = ...,
+    converter: None = ...,
+    factory: None = ...,
+    kw_only: bool = ...,
+) -> Any: ...
+
 # This form catches an explicit None or no default and infers the type from the other arguments.
 @overload
-def attrib(default: None = ...,
-           validator: Optional[_ValidatorArgType[_T]] = ...,
-           repr: bool = ...,
-           cmp: bool = ...,
-           hash: Optional[bool] = ...,
-           init: bool = ...,
-           convert: Optional[_ConverterType[_T]] = ...,
-           metadata: Optional[Mapping[Any, Any]] = ...,
-           type: Optional[Type[_T]] = ...,
-           converter: Optional[_ConverterType[_T]] = ...,
-           factory: Optional[Callable[[], _T]] = ...,
-           ) -> _T: ...
+def attrib(
+    default: None = ...,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    convert: Optional[_ConverterType[_T]] = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    type: Optional[Type[_T]] = ...,
+    converter: Optional[_ConverterType[_T]] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+) -> _T: ...
+
 # This form catches an explicit default argument.
 @overload
-def attrib(default: _T,
-           validator: Optional[_ValidatorArgType[_T]] = ...,
-           repr: bool = ...,
-           cmp: bool = ...,
-           hash: Optional[bool] = ...,
-           init: bool = ...,
-           convert: Optional[_ConverterType[_T]] = ...,
-           metadata: Optional[Mapping[Any, Any]] = ...,
-           type: Optional[Type[_T]] = ...,
-           converter: Optional[_ConverterType[_T]] = ...,
-           factory: Optional[Callable[[], _T]] = ...,
-           ) -> _T: ...
+def attrib(
+    default: _T,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    convert: Optional[_ConverterType[_T]] = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    type: Optional[Type[_T]] = ...,
+    converter: Optional[_ConverterType[_T]] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+) -> _T: ...
+
 # This form covers type=non-Type: e.g. forward references (str), Any
 @overload
-def attrib(default: Optional[_T] = ...,
-           validator: Optional[_ValidatorArgType[_T]] = ...,
-           repr: bool = ...,
-           cmp: bool = ...,
-           hash: Optional[bool] = ...,
-           init: bool = ...,
-           convert: Optional[_ConverterType[_T]] = ...,
-           metadata: Optional[Mapping[Any, Any]] = ...,
-           type: object = ...,
-           converter: Optional[_ConverterType[_T]] = ...,
-           factory: Optional[Callable[[], _T]] = ...,
-           ) -> Any: ...
-
-
-# NOTE: If you update these, update `s` and `attributes` below.
+def attrib(
+    default: Optional[_T] = ...,
+    validator: Optional[_ValidatorArgType[_T]] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    convert: Optional[_ConverterType[_T]] = ...,
+    metadata: Optional[Mapping[Any, Any]] = ...,
+    type: object = ...,
+    converter: Optional[_ConverterType[_T]] = ...,
+    factory: Optional[Callable[[], _T]] = ...,
+    kw_only: bool = ...,
+) -> Any: ...
 @overload
-def attrs(maybe_cls: _C,
-          these: Optional[Dict[str, Any]] = ...,
-          repr_ns: Optional[str] = ...,
-          repr: bool = ...,
-          cmp: bool = ...,
-          hash: Optional[bool] = ...,
-          init: bool = ...,
-          slots: bool = ...,
-          frozen: bool = ...,
-          str: bool = ...,
-          auto_attribs: bool = ...) -> _C: ...
+def attrs(
+    maybe_cls: _C,
+    these: Optional[Dict[str, Any]] = ...,
+    repr_ns: Optional[str] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+) -> _C: ...
 @overload
-def attrs(maybe_cls: None = ...,
-          these: Optional[Dict[str, Any]] = ...,
-          repr_ns: Optional[str] = ...,
-          repr: bool = ...,
-          cmp: bool = ...,
-          hash: Optional[bool] = ...,
-          init: bool = ...,
-          slots: bool = ...,
-          frozen: bool = ...,
-          str: bool = ...,
-          auto_attribs: bool = ...) -> Callable[[_C], _C]: ...
-
+def attrs(
+    maybe_cls: None = ...,
+    these: Optional[Dict[str, Any]] = ...,
+    repr_ns: Optional[str] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+) -> Callable[[_C], _C]: ...
 
 # TODO: add support for returning NamedTuple from the mypy plugin
-class _Fields(Tuple[Attribute, ...]):
-    def __getattr__(self, name: str) -> Attribute: ...
+class _Fields(Tuple[Attribute[Any], ...]):
+    def __getattr__(self, name: str) -> Attribute[Any]: ...
 
 def fields(cls: type) -> _Fields: ...
-def fields_dict(cls: type) -> Dict[str, Attribute]: ...
+def fields_dict(cls: type) -> Dict[str, Attribute[Any]]: ...
 def validate(inst: Any) -> None: ...
 
 # 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
-def make_class(name: str,
-               attrs: Union[List[str], Tuple[str, ...], Dict[str, Any]],
-               bases: Tuple[type, ...] = ...,
-               repr_ns: Optional[str] = ...,
-               repr: bool = ...,
-               cmp: bool = ...,
-               hash: Optional[bool] = ...,
-               init: bool = ...,
-               slots: bool = ...,
-               frozen: bool = ...,
-               str: bool = ...,
-               auto_attribs: bool = ...) -> type: ...
+def make_class(
+    name: str,
+    attrs: Union[List[str], Tuple[str, ...], Dict[str, Any]],
+    bases: Tuple[type, ...] = ...,
+    repr_ns: Optional[str] = ...,
+    repr: bool = ...,
+    cmp: bool = ...,
+    hash: Optional[bool] = ...,
+    init: bool = ...,
+    slots: bool = ...,
+    frozen: bool = ...,
+    weakref_slot: bool = ...,
+    str: bool = ...,
+    auto_attribs: bool = ...,
+    kw_only: bool = ...,
+    cache_hash: bool = ...,
+) -> type: ...
 
 # _funcs --
 
@@ -184,17 +220,22 @@ def make_class(name: str,
 # 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(inst: Any,
-           recurse: bool = ...,
-           filter: Optional[_FilterType] = ...,
-           dict_factory: Type[Mapping[Any, Any]] = ...,
-           retain_collection_types: bool = ...) -> Dict[str, Any]: ...
+def asdict(
+    inst: Any,
+    recurse: bool = ...,
+    filter: Optional[_FilterType[Any]] = ...,
+    dict_factory: Type[Mapping[Any, Any]] = ...,
+    retain_collection_types: bool = ...,
+) -> Dict[str, Any]: ...
+
 # TODO: add support for returning NamedTuple from the mypy plugin
-def astuple(inst: Any,
-            recurse: bool = ...,
-            filter: Optional[_FilterType] = ...,
-            tuple_factory: Type[Sequence] = ...,
-            retain_collection_types: bool = ...) -> Tuple[Any, ...]: ...
+def astuple(
+    inst: Any,
+    recurse: bool = ...,
+    filter: Optional[_FilterType[Any]] = ...,
+    tuple_factory: Type[Sequence[Any]] = ...,
+    retain_collection_types: bool = ...,
+) -> Tuple[Any, ...]: ...
 def has(cls: type) -> bool: ...
 def assoc(inst: _T, **changes: Any) -> _T: ...
 def evolve(inst: _T, **changes: Any) -> _T: ...
@@ -204,7 +245,6 @@ def evolve(inst: _T, **changes: Any) -> _T: ...
 def set_run_validators(run: bool) -> None: ...
 def get_run_validators() -> bool: ...
 
-
 # aliases --
 
 s = attributes = attrs

third_party/2and3/attr/converters.pyi

@@ -1,6 +1,12 @@
-from typing import TypeVar, Optional
+from typing import TypeVar, Optional, Callable, overload
 from . import _ConverterType
 
-_T = TypeVar('_T')
+_T = TypeVar("_T")
 
-def optional(converter: _ConverterType[_T]) -> _ConverterType[Optional[_T]]: ...
+def optional(
+    converter: _ConverterType[_T]
+) -> _ConverterType[Optional[_T]]: ...
+@overload
+def default_if_none(default: _T) -> _ConverterType[_T]: ...
+@overload
+def default_if_none(*, factory: Callable[[], _T]) -> _ConverterType[_T]: ...

third_party/2and3/attr/exceptions.pyi

@@ -1,5 +1,6 @@
 class FrozenInstanceError(AttributeError):
     msg: str = ...
+
 class AttrsAttributeNotFoundError(ValueError): ...
 class NotAnAttrsClassError(ValueError): ...
 class DefaultAlreadySetError(RuntimeError): ...

third_party/2and3/attr/filters.pyi

@@ -1,5 +1,5 @@
-from typing import Union
+from typing import Union, Any
 from . import Attribute, _FilterType
 
-def include(*what: Union[type, Attribute]) -> _FilterType: ...
-def exclude(*what: Union[type, Attribute]) -> _FilterType: ...
+def include(*what: Union[type, Attribute[Any]]) -> _FilterType[Any]: ...
+def exclude(*what: Union[type, Attribute[Any]]) -> _FilterType[Any]: ...

third_party/2and3/attr/validators.pyi

@@ -1,10 +1,24 @@
 from typing import Container, List, Union, TypeVar, Type, Any, Optional, Tuple
 from . import _ValidatorType
 
-_T = TypeVar('_T')
+_T = TypeVar("_T")
 
-def instance_of(type: Union[Tuple[Type[_T], ...], Type[_T]]) -> _ValidatorType[_T]: ...
+def instance_of(
+    type: Union[Tuple[Type[_T], ...], Type[_T]]
+) -> _ValidatorType[_T]: ...
 def provides(interface: Any) -> _ValidatorType[Any]: ...
-def optional(validator: Union[_ValidatorType[_T], List[_ValidatorType[_T]]]) -> _ValidatorType[Optional[_T]]: ...
+def optional(
+    validator: Union[_ValidatorType[_T], List[_ValidatorType[_T]]]
+) -> _ValidatorType[Optional[_T]]: ...
 def in_(options: Container[_T]) -> _ValidatorType[_T]: ...
 def and_(*validators: _ValidatorType[_T]) -> _ValidatorType[_T]: ...
+def deep_iterable(
+    member_validator: _ValidatorType[_T],
+    iterable_validator: Optional[_ValidatorType[_T]],
+) -> _ValidatorType[_T]: ...
+def deep_mapping(
+    key_validator: _ValidatorType[_T],
+    value_validator: _ValidatorType[_T],
+    mapping_validator: Optional[_ValidatorType[_T]],
+) -> _ValidatorType[_T]: ...
+def is_callable() -> _ValidatorType[_T]: ...