diff --git a/third_party/2and3/attr/__init__.pyi b/third_party/2and3/attr/__init__.pyi index eaf0900ce03a..ea788ea3c0f7 100644 --- a/third_party/2and3/attr/__init__.pyi +++ b/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 diff --git a/third_party/2and3/attr/converters.pyi b/third_party/2and3/attr/converters.pyi index 9e31677e79c3..63b2a3866e31 100644 --- a/third_party/2and3/attr/converters.pyi +++ b/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]: ... diff --git a/third_party/2and3/attr/exceptions.pyi b/third_party/2and3/attr/exceptions.pyi index 4a2904fc25b1..48fffcc1e2df 100644 --- a/third_party/2and3/attr/exceptions.pyi +++ b/third_party/2and3/attr/exceptions.pyi @@ -1,5 +1,6 @@ class FrozenInstanceError(AttributeError): msg: str = ... + class AttrsAttributeNotFoundError(ValueError): ... class NotAnAttrsClassError(ValueError): ... class DefaultAlreadySetError(RuntimeError): ... diff --git a/third_party/2and3/attr/filters.pyi b/third_party/2and3/attr/filters.pyi index a618140c2d1b..68368fe2b92d 100644 --- a/third_party/2and3/attr/filters.pyi +++ b/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]: ... diff --git a/third_party/2and3/attr/validators.pyi b/third_party/2and3/attr/validators.pyi index 3fc34377c2c6..01af06845ec3 100644 --- a/third_party/2and3/attr/validators.pyi +++ b/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]: ...