Improve declaration of private vs public objects in stubs

Author: chadrik

src/attr/__init__.pyi

@@ -1,21 +1,21 @@
 from typing import Any, Callable, Dict, Generic, Iterable, List, Optional, Mapping, Tuple, Type, TypeVar, Union, overload
-from . import exceptions
-from . import filters
-from . import converters
-from . import validators
+# `import X as X` is required to expose these to mypy. otherwise they are invisible
+from . import exceptions as exceptions
+from . import filters as filters
+from . import converters as converters
+from . import validators as validators
 
 # typing --
 
 _T = TypeVar('_T')
-T = TypeVar('T')
 _C = TypeVar('_C', bound=type)
 _M = TypeVar('_M', bound=Mapping)
 _I = TypeVar('_I', bound=Iterable)
 
-ValidatorType = Callable[[object, 'Attribute', Any], Any]
+_ValidatorType = Callable[[Any, 'Attribute', Any], Any]
 # FIXME: Bind to attribute type?
-ConverterType = Callable[[Any], Any]
-FilterType = Callable[['Attribute', Any], bool]
+_ConverterType = Callable[[Any], Any]
+_FilterType = Callable[['Attribute', Any], bool]
 
 # _make --
 
@@ -24,37 +24,37 @@ class _CountingAttr: ...
 NOTHING : object
 
 class Factory(Generic[_T]):
-    factory : Union[Callable[[], _T], Callable[[object], _T]]
+    factory : Union[Callable[[], _T], Callable[[Any], _T]]
     takes_self : bool
-    def __init__(self, factory: Union[Callable[[], _T], Callable[[object], _T]], takes_self: bool = ...) -> None: ...
+    def __init__(self, factory: Union[Callable[[], _T], Callable[[Any], _T]], takes_self: bool = ...) -> None: ...
 
 class Attribute:
     __slots__ = ("name", "default", "validator", "repr", "cmp", "hash", "init", "convert", "metadata", "type")
-    def __init__(self, name: str, default: Any, validator: Optional[Union[ValidatorType, List[ValidatorType]]], repr: bool, cmp: bool, hash: Optional[bool], init: bool, convert: Optional[ConverterType] = ..., metadata: Mapping = ..., type: Union[type, Factory] = ...) -> None: ...
+    def __init__(self, name: str, default: Any, validator: Optional[Union[_ValidatorType, List[_ValidatorType], Tuple[_ValidatorType, ...]]], repr: bool, cmp: bool, hash: Optional[bool], init: bool, convert: Optional[_ConverterType] = ..., metadata: Mapping = ..., type: Union[type, Factory] = ...) -> None: ...
 
 # NOTE: this overload for `attr` returns Any so that static analysis passes when used in the form:  x : int = attr()
-# @overload
-# def attr(default: Any = ..., validator: Optional[Union[ValidatorType, List[ValidatorType]]] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., convert: Optional[ConverterType] = ..., metadata: Mapping = ...) -> Any: ...
-# @overload
-def attr(default: Any = ..., validator: Optional[Union[ValidatorType, List[ValidatorType]]] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., convert: Optional[ConverterType] = ..., metadata: Mapping = ..., type: Type[T] = ...) -> T: ...
+@overload
+def attr(default: Any = ..., validator: Optional[Union[_ValidatorType, List[_ValidatorType], Tuple[_ValidatorType, ...]]] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., convert: Optional[_ConverterType] = ..., metadata: Mapping = ...) -> Any: ...
+@overload
+def attr(default: Any = ..., validator: Optional[Union[_ValidatorType, List[_ValidatorType], Tuple[_ValidatorType, ...]]] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., convert: Optional[_ConverterType] = ..., metadata: Mapping = ..., type: Type[_T] = ...) -> _T: ...
 
 @overload
 def attributes(maybe_cls: _C = ..., these: Optional[Dict[str, _CountingAttr]] = ..., repr_ns: Optional[str] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., slots: bool = ..., frozen: bool = ..., str: bool = ...) -> _C: ...
 @overload
 def attributes(maybe_cls: None = ..., these: Optional[Dict[str, _CountingAttr]] = ..., repr_ns: Optional[str] = ..., repr: bool = ..., cmp: bool = ..., hash: Optional[bool] = ..., init: bool = ..., slots: bool = ..., frozen: bool = ..., str: bool = ...) -> Callable[[_C], _C]: ...
 
 def fields(cls: type) -> Tuple[Attribute, ...]: ...
-def validate(inst: object) -> None: ...
+def validate(inst: Any) -> None: ...
 
 def make_class(name, attrs: Union[List[_CountingAttr], Dict[str, _CountingAttr]], bases: Tuple[type, ...] = ..., **attributes_arguments) -> type: ...
 
 # _funcs --
 
 # FIXME: having problems assigning a default to the factory typevars
-# def asdict(inst: object, recurse: bool = ..., filter: Optional[FilterType] = ..., dict_factory: Type[_M] = dict, retain_collection_types: bool = ...) -> _M[str, Any]: ...
-# def astuple(inst: object, recurse: bool = ..., filter: Optional[FilterType] = ..., tuple_factory: Type[_I] = tuple, retain_collection_types: bool = ...) -> _I: ...
-def asdict(inst: object, recurse: bool = ..., filter: Optional[FilterType] = ..., dict_factory: Type[_M] = ..., retain_collection_types: bool = ...) -> _M: ...
-def astuple(inst: object, recurse: bool = ..., filter: Optional[FilterType] = ..., tuple_factory: Type[_I] = ..., retain_collection_types: bool = ...) -> _I: ...
+# def asdict(inst: Any, recurse: bool = ..., filter: Optional[_FilterType] = ..., dict_factory: Type[_M] = dict, retain_collection_types: bool = ...) -> _M[str, Any]: ...
+# def astuple(inst: Any, recurse: bool = ..., filter: Optional[_FilterType] = ..., tuple_factory: Type[_I] = tuple, retain_collection_types: bool = ...) -> _I: ...
+def asdict(inst: Any, recurse: bool = ..., filter: Optional[_FilterType] = ..., dict_factory: Type[_M] = ..., retain_collection_types: bool = ...) -> _M: ...
+def astuple(inst: Any, recurse: bool = ..., filter: Optional[_FilterType] = ..., tuple_factory: Type[_I] = ..., retain_collection_types: bool = ...) -> _I: ...
 def has(cls: type) -> bool: ...
 def assoc(inst: _T, **changes) -> _T: ...
 def evolve(inst: _T, **changes) -> _T: ...

src/attr/converters.pyi

@@ -1,3 +1,3 @@
-from . import ConverterType
+from . import _ConverterType
 
-def optional(converter: ConverterType) -> ConverterType: ...
+def optional(converter: _ConverterType) -> _ConverterType: ...

src/attr/filters.pyi

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

src/attr/validators.pyi

@@ -1,8 +1,8 @@
 from typing import Container, Iterable, List, Union
-from . import ValidatorType
+from . import _ValidatorType
 
-def instance_of(type: type) -> ValidatorType: ...
-def provides(interface) -> ValidatorType: ...
-def optional(validator: Union[ValidatorType, List[ValidatorType]]) -> ValidatorType: ...
-def in_(options: Container) -> ValidatorType: ...
-def and_(*validators: Iterable[ValidatorType]) -> ValidatorType: ...
+def instance_of(type: type) -> _ValidatorType: ...
+def provides(interface) -> _ValidatorType: ...
+def optional(validator: Union[_ValidatorType, List[_ValidatorType]]) -> _ValidatorType: ...
+def in_(options: Container) -> _ValidatorType: ...
+def and_(*validators: Iterable[_ValidatorType]) -> _ValidatorType: ...