.config/coc/extensions/coc-python-data/languageServer.0.5.59/Typeshed/third_party/2and3/attr/__init__.pyi

   1 from typing import Any, Callable, Dict, Generic, List, Optional, Sequence, Mapping, Tuple, Type, TypeVar, Union, overload\r
   2 # `import X as X` is required to make these public\r
   3 from . import exceptions as exceptions\r
   4 from . import filters as filters\r
   5 from . import converters as converters\r
   6 from . import validators as validators\r
   7 \r
   8 _T = TypeVar('_T')\r
   9 _C = TypeVar('_C', bound=type)\r
  10 \r
  11 _ValidatorType = Callable[[Any, Attribute, _T], Any]\r
  12 _ConverterType = Callable[[Any], _T]\r
  13 _FilterType = Callable[[Attribute, Any], bool]\r
  14 # FIXME: in reality, if multiple validators are passed they must be in a list or tuple,\r
  15 # but those are invariant and so would prevent subtypes of _ValidatorType from working\r
  16 # when passed in a list or tuple.\r
  17 _ValidatorArgType = Union[_ValidatorType[_T], Sequence[_ValidatorType[_T]]]\r
  18 \r
  19 # _make --\r
  20 \r
  21 NOTHING: object\r
  22 \r
  23 # NOTE: Factory lies about its return type to make this possible: `x: List[int] = Factory(list)`\r
  24 # Work around mypy issue #4554 in the common case by using an overload.\r
  25 @overload\r
  26 def Factory(factory: Callable[[], _T]) -> _T: ...\r
  27 @overload\r
  28 def Factory(factory: Union[Callable[[Any], _T], Callable[[], _T]], takes_self: bool = ...) -> _T: ...\r
  29 \r
  30 class Attribute(Generic[_T]):\r
  31     name: str\r
  32     default: Optional[_T]\r
  33     validator: Optional[_ValidatorType[_T]]\r
  34     repr: bool\r
  35     cmp: bool\r
  36     hash: Optional[bool]\r
  37     init: bool\r
  38     converter: Optional[_ConverterType[_T]]\r
  39     metadata: Dict[Any, Any]\r
  40     type: Optional[Type[_T]]\r
  41     def __lt__(self, x: Attribute) -> bool: ...\r
  42     def __le__(self, x: Attribute) -> bool: ...\r
  43     def __gt__(self, x: Attribute) -> bool: ...\r
  44     def __ge__(self, x: Attribute) -> bool: ...\r
  45 \r
  46 \r
  47 # NOTE: We had several choices for the annotation to use for type arg:\r
  48 # 1) Type[_T]\r
  49 #   - Pros: works in PyCharm without plugin support\r
  50 #   - Cons: produces less informative error in the case of conflicting TypeVars\r
  51 #     e.g. `attr.ib(default='bad', type=int)`\r
  52 # 2) Callable[..., _T]\r
  53 #   - Pros: more informative errors than #1\r
  54 #   - Cons: validator tests results in confusing error.\r
  55 #     e.g. `attr.ib(type=int, validator=validate_str)`\r
  56 # 3) type (and do all of the work in the mypy plugin)\r
  57 #   - Pros: in mypy, the behavior of type argument is exactly the same as with\r
  58 #     annotations.\r
  59 #   - Cons: completely disables type inspections in PyCharm when using the\r
  60 #     type arg.\r
  61 # We chose option #1 until either PyCharm adds support for attrs, or python 2\r
  62 # reaches EOL.\r
  63 \r
  64 # NOTE: If you update these, update `ib` and `attr` below.\r
  65 \r
  66 # `attr` lies about its return type to make the following possible:\r
  67 #     attr()    -> Any\r
  68 #     attr(8)   -> int\r
  69 #     attr(validator=<some callable>)  -> Whatever the callable expects.\r
  70 # This makes this type of assignments possible:\r
  71 #     x: int = attr(8)\r
  72 #\r
  73 # This form catches explicit None or no default but with no other arguments returns Any.\r
  74 @overload\r
  75 def attrib(default: None = ...,\r
  76            validator: None = ...,\r
  77            repr: bool = ...,\r
  78            cmp: bool = ...,\r
  79            hash: Optional[bool] = ...,\r
  80            init: bool = ...,\r
  81            convert: None = ...,\r
  82            metadata: Optional[Mapping[Any, Any]] = ...,\r
  83            type: None = ...,\r
  84            converter: None = ...,\r
  85            factory: None = ...,\r
  86            ) -> Any: ...\r
  87 # This form catches an explicit None or no default and infers the type from the other arguments.\r
  88 @overload\r
  89 def attrib(default: None = ...,\r
  90            validator: Optional[_ValidatorArgType[_T]] = ...,\r
  91            repr: bool = ...,\r
  92            cmp: bool = ...,\r
  93            hash: Optional[bool] = ...,\r
  94            init: bool = ...,\r
  95            convert: Optional[_ConverterType[_T]] = ...,\r
  96            metadata: Optional[Mapping[Any, Any]] = ...,\r
  97            type: Optional[Type[_T]] = ...,\r
  98            converter: Optional[_ConverterType[_T]] = ...,\r
  99            factory: Optional[Callable[[], _T]] = ...,\r
 100            ) -> _T: ...\r
 101 # This form catches an explicit default argument.\r
 102 @overload\r
 103 def attrib(default: _T,\r
 104            validator: Optional[_ValidatorArgType[_T]] = ...,\r
 105            repr: bool = ...,\r
 106            cmp: bool = ...,\r
 107            hash: Optional[bool] = ...,\r
 108            init: bool = ...,\r
 109            convert: Optional[_ConverterType[_T]] = ...,\r
 110            metadata: Optional[Mapping[Any, Any]] = ...,\r
 111            type: Optional[Type[_T]] = ...,\r
 112            converter: Optional[_ConverterType[_T]] = ...,\r
 113            factory: Optional[Callable[[], _T]] = ...,\r
 114            ) -> _T: ...\r
 115 # This form covers type=non-Type: e.g. forward references (str), Any\r
 116 @overload\r
 117 def attrib(default: Optional[_T] = ...,\r
 118            validator: Optional[_ValidatorArgType[_T]] = ...,\r
 119            repr: bool = ...,\r
 120            cmp: bool = ...,\r
 121            hash: Optional[bool] = ...,\r
 122            init: bool = ...,\r
 123            convert: Optional[_ConverterType[_T]] = ...,\r
 124            metadata: Optional[Mapping[Any, Any]] = ...,\r
 125            type: object = ...,\r
 126            converter: Optional[_ConverterType[_T]] = ...,\r
 127            factory: Optional[Callable[[], _T]] = ...,\r
 128            ) -> Any: ...\r
 129 \r
 130 \r
 131 # NOTE: If you update these, update `s` and `attributes` below.\r
 132 @overload\r
 133 def attrs(maybe_cls: _C,\r
 134           these: Optional[Dict[str, Any]] = ...,\r
 135           repr_ns: Optional[str] = ...,\r
 136           repr: bool = ...,\r
 137           cmp: bool = ...,\r
 138           hash: Optional[bool] = ...,\r
 139           init: bool = ...,\r
 140           slots: bool = ...,\r
 141           frozen: bool = ...,\r
 142           str: bool = ...,\r
 143           auto_attribs: bool = ...) -> _C: ...\r
 144 @overload\r
 145 def attrs(maybe_cls: None = ...,\r
 146           these: Optional[Dict[str, Any]] = ...,\r
 147           repr_ns: Optional[str] = ...,\r
 148           repr: bool = ...,\r
 149           cmp: bool = ...,\r
 150           hash: Optional[bool] = ...,\r
 151           init: bool = ...,\r
 152           slots: bool = ...,\r
 153           frozen: bool = ...,\r
 154           str: bool = ...,\r
 155           auto_attribs: bool = ...) -> Callable[[_C], _C]: ...\r
 156 \r
 157 \r
 158 # TODO: add support for returning NamedTuple from the mypy plugin\r
 159 class _Fields(Tuple[Attribute, ...]):\r
 160     def __getattr__(self, name: str) -> Attribute: ...\r
 161 \r
 162 def fields(cls: type) -> _Fields: ...\r
 163 def fields_dict(cls: type) -> Dict[str, Attribute]: ...\r
 164 def validate(inst: Any) -> None: ...\r
 165 \r
 166 # TODO: add support for returning a proper attrs class from the mypy plugin\r
 167 # we use Any instead of _CountingAttr so that e.g. `make_class('Foo', [attr.ib()])` is valid\r
 168 def make_class(name: str,\r
 169                attrs: Union[List[str], Tuple[str, ...], Dict[str, Any]],\r
 170                bases: Tuple[type, ...] = ...,\r
 171                repr_ns: Optional[str] = ...,\r
 172                repr: bool = ...,\r
 173                cmp: bool = ...,\r
 174                hash: Optional[bool] = ...,\r
 175                init: bool = ...,\r
 176                slots: bool = ...,\r
 177                frozen: bool = ...,\r
 178                str: bool = ...,\r
 179                auto_attribs: bool = ...) -> type: ...\r
 180 \r
 181 # _funcs --\r
 182 \r
 183 # TODO: add support for returning TypedDict from the mypy plugin\r
 184 # FIXME: asdict/astuple do not honor their factory args.  waiting on one of these:\r
 185 # https://github.com/python/mypy/issues/4236\r
 186 # https://github.com/python/typing/issues/253\r
 187 def asdict(inst: Any,\r
 188            recurse: bool = ...,\r
 189            filter: Optional[_FilterType] = ...,\r
 190            dict_factory: Type[Mapping[Any, Any]] = ...,\r
 191            retain_collection_types: bool = ...) -> Dict[str, Any]: ...\r
 192 # TODO: add support for returning NamedTuple from the mypy plugin\r
 193 def astuple(inst: Any,\r
 194             recurse: bool = ...,\r
 195             filter: Optional[_FilterType] = ...,\r
 196             tuple_factory: Type[Sequence] = ...,\r
 197             retain_collection_types: bool = ...) -> Tuple[Any, ...]: ...\r
 198 def has(cls: type) -> bool: ...\r
 199 def assoc(inst: _T, **changes: Any) -> _T: ...\r
 200 def evolve(inst: _T, **changes: Any) -> _T: ...\r
 201 \r
 202 # _config --\r
 203 \r
 204 def set_run_validators(run: bool) -> None: ...\r
 205 def get_run_validators() -> bool: ...\r
 206 \r
 207 \r
 208 # aliases --\r
 209 \r
 210 s = attributes = attrs\r
 211 ib = attr = attrib\r
 212 dataclass = attrs  # Technically, partial(attrs, auto_attribs=True) ;)\r