Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

__init__.pyi 17KB

1 year ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571
  1. import enum
  2. import sys
  3. from typing import (
  4. Any,
  5. Callable,
  6. Dict,
  7. Generic,
  8. List,
  9. Mapping,
  10. Optional,
  11. Protocol,
  12. Sequence,
  13. Tuple,
  14. Type,
  15. TypeVar,
  16. Union,
  17. overload,
  18. )
  19. # `import X as X` is required to make these public
  20. from . import converters as converters
  21. from . import exceptions as exceptions
  22. from . import filters as filters
  23. from . import setters as setters
  24. from . import validators as validators
  25. from ._cmp import cmp_using as cmp_using
  26. from ._typing_compat import AttrsInstance_
  27. from ._version_info import VersionInfo
  28. if sys.version_info >= (3, 10):
  29. from typing import TypeGuard
  30. else:
  31. from typing_extensions import TypeGuard
  32. __version__: str
  33. __version_info__: VersionInfo
  34. __title__: str
  35. __description__: str
  36. __url__: str
  37. __uri__: str
  38. __author__: str
  39. __email__: str
  40. __license__: str
  41. __copyright__: str
  42. _T = TypeVar("_T")
  43. _C = TypeVar("_C", bound=type)
  44. _EqOrderType = Union[bool, Callable[[Any], Any]]
  45. _ValidatorType = Callable[[Any, "Attribute[_T]", _T], Any]
  46. _ConverterType = Callable[[Any], Any]
  47. _FilterType = Callable[["Attribute[_T]", _T], bool]
  48. _ReprType = Callable[[Any], str]
  49. _ReprArgType = Union[bool, _ReprType]
  50. _OnSetAttrType = Callable[[Any, "Attribute[Any]", Any], Any]
  51. _OnSetAttrArgType = Union[
  52. _OnSetAttrType, List[_OnSetAttrType], setters._NoOpType
  53. ]
  54. _FieldTransformer = Callable[
  55. [type, List["Attribute[Any]"]], List["Attribute[Any]"]
  56. ]
  57. # FIXME: in reality, if multiple validators are passed they must be in a list
  58. # or tuple, but those are invariant and so would prevent subtypes of
  59. # _ValidatorType from working when passed in a list or tuple.
  60. _ValidatorArgType = Union[_ValidatorType[_T], Sequence[_ValidatorType[_T]]]
  61. # We subclass this here to keep the protocol's qualified name clean.
  62. class AttrsInstance(AttrsInstance_, Protocol):
  63. pass
  64. _A = TypeVar("_A", bound=AttrsInstance)
  65. # _make --
  66. class _Nothing(enum.Enum):
  67. NOTHING = enum.auto()
  68. NOTHING = _Nothing.NOTHING
  69. # NOTE: Factory lies about its return type to make this possible:
  70. # `x: List[int] # = Factory(list)`
  71. # Work around mypy issue #4554 in the common case by using an overload.
  72. if sys.version_info >= (3, 8):
  73. from typing import Literal
  74. @overload
  75. def Factory(factory: Callable[[], _T]) -> _T: ...
  76. @overload
  77. def Factory(
  78. factory: Callable[[Any], _T],
  79. takes_self: Literal[True],
  80. ) -> _T: ...
  81. @overload
  82. def Factory(
  83. factory: Callable[[], _T],
  84. takes_self: Literal[False],
  85. ) -> _T: ...
  86. else:
  87. @overload
  88. def Factory(factory: Callable[[], _T]) -> _T: ...
  89. @overload
  90. def Factory(
  91. factory: Union[Callable[[Any], _T], Callable[[], _T]],
  92. takes_self: bool = ...,
  93. ) -> _T: ...
  94. # Static type inference support via __dataclass_transform__ implemented as per:
  95. # https://github.com/microsoft/pyright/blob/1.1.135/specs/dataclass_transforms.md
  96. # This annotation must be applied to all overloads of "define" and "attrs"
  97. #
  98. # NOTE: This is a typing construct and does not exist at runtime. Extensions
  99. # wrapping attrs decorators should declare a separate __dataclass_transform__
  100. # signature in the extension module using the specification linked above to
  101. # provide pyright support.
  102. def __dataclass_transform__(
  103. *,
  104. eq_default: bool = True,
  105. order_default: bool = False,
  106. kw_only_default: bool = False,
  107. frozen_default: bool = False,
  108. field_descriptors: Tuple[Union[type, Callable[..., Any]], ...] = (()),
  109. ) -> Callable[[_T], _T]: ...
  110. class Attribute(Generic[_T]):
  111. name: str
  112. default: Optional[_T]
  113. validator: Optional[_ValidatorType[_T]]
  114. repr: _ReprArgType
  115. cmp: _EqOrderType
  116. eq: _EqOrderType
  117. order: _EqOrderType
  118. hash: Optional[bool]
  119. init: bool
  120. converter: Optional[_ConverterType]
  121. metadata: Dict[Any, Any]
  122. type: Optional[Type[_T]]
  123. kw_only: bool
  124. on_setattr: _OnSetAttrType
  125. alias: Optional[str]
  126. def evolve(self, **changes: Any) -> "Attribute[Any]": ...
  127. # NOTE: We had several choices for the annotation to use for type arg:
  128. # 1) Type[_T]
  129. # - Pros: Handles simple cases correctly
  130. # - Cons: Might produce less informative errors in the case of conflicting
  131. # TypeVars e.g. `attr.ib(default='bad', type=int)`
  132. # 2) Callable[..., _T]
  133. # - Pros: Better error messages than #1 for conflicting TypeVars
  134. # - Cons: Terrible error messages for validator checks.
  135. # e.g. attr.ib(type=int, validator=validate_str)
  136. # -> error: Cannot infer function type argument
  137. # 3) type (and do all of the work in the mypy plugin)
  138. # - Pros: Simple here, and we could customize the plugin with our own errors.
  139. # - Cons: Would need to write mypy plugin code to handle all the cases.
  140. # We chose option #1.
  141. # `attr` lies about its return type to make the following possible:
  142. # attr() -> Any
  143. # attr(8) -> int
  144. # attr(validator=<some callable>) -> Whatever the callable expects.
  145. # This makes this type of assignments possible:
  146. # x: int = attr(8)
  147. #
  148. # This form catches explicit None or no default but with no other arguments
  149. # returns Any.
  150. @overload
  151. def attrib(
  152. default: None = ...,
  153. validator: None = ...,
  154. repr: _ReprArgType = ...,
  155. cmp: Optional[_EqOrderType] = ...,
  156. hash: Optional[bool] = ...,
  157. init: bool = ...,
  158. metadata: Optional[Mapping[Any, Any]] = ...,
  159. type: None = ...,
  160. converter: None = ...,
  161. factory: None = ...,
  162. kw_only: bool = ...,
  163. eq: Optional[_EqOrderType] = ...,
  164. order: Optional[_EqOrderType] = ...,
  165. on_setattr: Optional[_OnSetAttrArgType] = ...,
  166. alias: Optional[str] = ...,
  167. ) -> Any: ...
  168. # This form catches an explicit None or no default and infers the type from the
  169. # other arguments.
  170. @overload
  171. def attrib(
  172. default: None = ...,
  173. validator: Optional[_ValidatorArgType[_T]] = ...,
  174. repr: _ReprArgType = ...,
  175. cmp: Optional[_EqOrderType] = ...,
  176. hash: Optional[bool] = ...,
  177. init: bool = ...,
  178. metadata: Optional[Mapping[Any, Any]] = ...,
  179. type: Optional[Type[_T]] = ...,
  180. converter: Optional[_ConverterType] = ...,
  181. factory: Optional[Callable[[], _T]] = ...,
  182. kw_only: bool = ...,
  183. eq: Optional[_EqOrderType] = ...,
  184. order: Optional[_EqOrderType] = ...,
  185. on_setattr: Optional[_OnSetAttrArgType] = ...,
  186. alias: Optional[str] = ...,
  187. ) -> _T: ...
  188. # This form catches an explicit default argument.
  189. @overload
  190. def attrib(
  191. default: _T,
  192. validator: Optional[_ValidatorArgType[_T]] = ...,
  193. repr: _ReprArgType = ...,
  194. cmp: Optional[_EqOrderType] = ...,
  195. hash: Optional[bool] = ...,
  196. init: bool = ...,
  197. metadata: Optional[Mapping[Any, Any]] = ...,
  198. type: Optional[Type[_T]] = ...,
  199. converter: Optional[_ConverterType] = ...,
  200. factory: Optional[Callable[[], _T]] = ...,
  201. kw_only: bool = ...,
  202. eq: Optional[_EqOrderType] = ...,
  203. order: Optional[_EqOrderType] = ...,
  204. on_setattr: Optional[_OnSetAttrArgType] = ...,
  205. alias: Optional[str] = ...,
  206. ) -> _T: ...
  207. # This form covers type=non-Type: e.g. forward references (str), Any
  208. @overload
  209. def attrib(
  210. default: Optional[_T] = ...,
  211. validator: Optional[_ValidatorArgType[_T]] = ...,
  212. repr: _ReprArgType = ...,
  213. cmp: Optional[_EqOrderType] = ...,
  214. hash: Optional[bool] = ...,
  215. init: bool = ...,
  216. metadata: Optional[Mapping[Any, Any]] = ...,
  217. type: object = ...,
  218. converter: Optional[_ConverterType] = ...,
  219. factory: Optional[Callable[[], _T]] = ...,
  220. kw_only: bool = ...,
  221. eq: Optional[_EqOrderType] = ...,
  222. order: Optional[_EqOrderType] = ...,
  223. on_setattr: Optional[_OnSetAttrArgType] = ...,
  224. alias: Optional[str] = ...,
  225. ) -> Any: ...
  226. @overload
  227. def field(
  228. *,
  229. default: None = ...,
  230. validator: None = ...,
  231. repr: _ReprArgType = ...,
  232. hash: Optional[bool] = ...,
  233. init: bool = ...,
  234. metadata: Optional[Mapping[Any, Any]] = ...,
  235. converter: None = ...,
  236. factory: None = ...,
  237. kw_only: bool = ...,
  238. eq: Optional[bool] = ...,
  239. order: Optional[bool] = ...,
  240. on_setattr: Optional[_OnSetAttrArgType] = ...,
  241. alias: Optional[str] = ...,
  242. type: Optional[type] = ...,
  243. ) -> Any: ...
  244. # This form catches an explicit None or no default and infers the type from the
  245. # other arguments.
  246. @overload
  247. def field(
  248. *,
  249. default: None = ...,
  250. validator: Optional[_ValidatorArgType[_T]] = ...,
  251. repr: _ReprArgType = ...,
  252. hash: Optional[bool] = ...,
  253. init: bool = ...,
  254. metadata: Optional[Mapping[Any, Any]] = ...,
  255. converter: Optional[_ConverterType] = ...,
  256. factory: Optional[Callable[[], _T]] = ...,
  257. kw_only: bool = ...,
  258. eq: Optional[_EqOrderType] = ...,
  259. order: Optional[_EqOrderType] = ...,
  260. on_setattr: Optional[_OnSetAttrArgType] = ...,
  261. alias: Optional[str] = ...,
  262. type: Optional[type] = ...,
  263. ) -> _T: ...
  264. # This form catches an explicit default argument.
  265. @overload
  266. def field(
  267. *,
  268. default: _T,
  269. validator: Optional[_ValidatorArgType[_T]] = ...,
  270. repr: _ReprArgType = ...,
  271. hash: Optional[bool] = ...,
  272. init: bool = ...,
  273. metadata: Optional[Mapping[Any, Any]] = ...,
  274. converter: Optional[_ConverterType] = ...,
  275. factory: Optional[Callable[[], _T]] = ...,
  276. kw_only: bool = ...,
  277. eq: Optional[_EqOrderType] = ...,
  278. order: Optional[_EqOrderType] = ...,
  279. on_setattr: Optional[_OnSetAttrArgType] = ...,
  280. alias: Optional[str] = ...,
  281. type: Optional[type] = ...,
  282. ) -> _T: ...
  283. # This form covers type=non-Type: e.g. forward references (str), Any
  284. @overload
  285. def field(
  286. *,
  287. default: Optional[_T] = ...,
  288. validator: Optional[_ValidatorArgType[_T]] = ...,
  289. repr: _ReprArgType = ...,
  290. hash: Optional[bool] = ...,
  291. init: bool = ...,
  292. metadata: Optional[Mapping[Any, Any]] = ...,
  293. converter: Optional[_ConverterType] = ...,
  294. factory: Optional[Callable[[], _T]] = ...,
  295. kw_only: bool = ...,
  296. eq: Optional[_EqOrderType] = ...,
  297. order: Optional[_EqOrderType] = ...,
  298. on_setattr: Optional[_OnSetAttrArgType] = ...,
  299. alias: Optional[str] = ...,
  300. type: Optional[type] = ...,
  301. ) -> Any: ...
  302. @overload
  303. @__dataclass_transform__(order_default=True, field_descriptors=(attrib, field))
  304. def attrs(
  305. maybe_cls: _C,
  306. these: Optional[Dict[str, Any]] = ...,
  307. repr_ns: Optional[str] = ...,
  308. repr: bool = ...,
  309. cmp: Optional[_EqOrderType] = ...,
  310. hash: Optional[bool] = ...,
  311. init: bool = ...,
  312. slots: bool = ...,
  313. frozen: bool = ...,
  314. weakref_slot: bool = ...,
  315. str: bool = ...,
  316. auto_attribs: bool = ...,
  317. kw_only: bool = ...,
  318. cache_hash: bool = ...,
  319. auto_exc: bool = ...,
  320. eq: Optional[_EqOrderType] = ...,
  321. order: Optional[_EqOrderType] = ...,
  322. auto_detect: bool = ...,
  323. collect_by_mro: bool = ...,
  324. getstate_setstate: Optional[bool] = ...,
  325. on_setattr: Optional[_OnSetAttrArgType] = ...,
  326. field_transformer: Optional[_FieldTransformer] = ...,
  327. match_args: bool = ...,
  328. unsafe_hash: Optional[bool] = ...,
  329. ) -> _C: ...
  330. @overload
  331. @__dataclass_transform__(order_default=True, field_descriptors=(attrib, field))
  332. def attrs(
  333. maybe_cls: None = ...,
  334. these: Optional[Dict[str, Any]] = ...,
  335. repr_ns: Optional[str] = ...,
  336. repr: bool = ...,
  337. cmp: Optional[_EqOrderType] = ...,
  338. hash: Optional[bool] = ...,
  339. init: bool = ...,
  340. slots: bool = ...,
  341. frozen: bool = ...,
  342. weakref_slot: bool = ...,
  343. str: bool = ...,
  344. auto_attribs: bool = ...,
  345. kw_only: bool = ...,
  346. cache_hash: bool = ...,
  347. auto_exc: bool = ...,
  348. eq: Optional[_EqOrderType] = ...,
  349. order: Optional[_EqOrderType] = ...,
  350. auto_detect: bool = ...,
  351. collect_by_mro: bool = ...,
  352. getstate_setstate: Optional[bool] = ...,
  353. on_setattr: Optional[_OnSetAttrArgType] = ...,
  354. field_transformer: Optional[_FieldTransformer] = ...,
  355. match_args: bool = ...,
  356. unsafe_hash: Optional[bool] = ...,
  357. ) -> Callable[[_C], _C]: ...
  358. @overload
  359. @__dataclass_transform__(field_descriptors=(attrib, field))
  360. def define(
  361. maybe_cls: _C,
  362. *,
  363. these: Optional[Dict[str, Any]] = ...,
  364. repr: bool = ...,
  365. unsafe_hash: Optional[bool] = ...,
  366. hash: Optional[bool] = ...,
  367. init: bool = ...,
  368. slots: bool = ...,
  369. frozen: bool = ...,
  370. weakref_slot: bool = ...,
  371. str: bool = ...,
  372. auto_attribs: bool = ...,
  373. kw_only: bool = ...,
  374. cache_hash: bool = ...,
  375. auto_exc: bool = ...,
  376. eq: Optional[bool] = ...,
  377. order: Optional[bool] = ...,
  378. auto_detect: bool = ...,
  379. getstate_setstate: Optional[bool] = ...,
  380. on_setattr: Optional[_OnSetAttrArgType] = ...,
  381. field_transformer: Optional[_FieldTransformer] = ...,
  382. match_args: bool = ...,
  383. ) -> _C: ...
  384. @overload
  385. @__dataclass_transform__(field_descriptors=(attrib, field))
  386. def define(
  387. maybe_cls: None = ...,
  388. *,
  389. these: Optional[Dict[str, Any]] = ...,
  390. repr: bool = ...,
  391. unsafe_hash: Optional[bool] = ...,
  392. hash: Optional[bool] = ...,
  393. init: bool = ...,
  394. slots: bool = ...,
  395. frozen: bool = ...,
  396. weakref_slot: bool = ...,
  397. str: bool = ...,
  398. auto_attribs: bool = ...,
  399. kw_only: bool = ...,
  400. cache_hash: bool = ...,
  401. auto_exc: bool = ...,
  402. eq: Optional[bool] = ...,
  403. order: Optional[bool] = ...,
  404. auto_detect: bool = ...,
  405. getstate_setstate: Optional[bool] = ...,
  406. on_setattr: Optional[_OnSetAttrArgType] = ...,
  407. field_transformer: Optional[_FieldTransformer] = ...,
  408. match_args: bool = ...,
  409. ) -> Callable[[_C], _C]: ...
  410. mutable = define
  411. @overload
  412. @__dataclass_transform__(
  413. frozen_default=True, field_descriptors=(attrib, field)
  414. )
  415. def frozen(
  416. maybe_cls: _C,
  417. *,
  418. these: Optional[Dict[str, Any]] = ...,
  419. repr: bool = ...,
  420. unsafe_hash: Optional[bool] = ...,
  421. hash: Optional[bool] = ...,
  422. init: bool = ...,
  423. slots: bool = ...,
  424. frozen: bool = ...,
  425. weakref_slot: bool = ...,
  426. str: bool = ...,
  427. auto_attribs: bool = ...,
  428. kw_only: bool = ...,
  429. cache_hash: bool = ...,
  430. auto_exc: bool = ...,
  431. eq: Optional[bool] = ...,
  432. order: Optional[bool] = ...,
  433. auto_detect: bool = ...,
  434. getstate_setstate: Optional[bool] = ...,
  435. on_setattr: Optional[_OnSetAttrArgType] = ...,
  436. field_transformer: Optional[_FieldTransformer] = ...,
  437. match_args: bool = ...,
  438. ) -> _C: ...
  439. @overload
  440. @__dataclass_transform__(
  441. frozen_default=True, field_descriptors=(attrib, field)
  442. )
  443. def frozen(
  444. maybe_cls: None = ...,
  445. *,
  446. these: Optional[Dict[str, Any]] = ...,
  447. repr: bool = ...,
  448. unsafe_hash: Optional[bool] = ...,
  449. hash: Optional[bool] = ...,
  450. init: bool = ...,
  451. slots: bool = ...,
  452. frozen: bool = ...,
  453. weakref_slot: bool = ...,
  454. str: bool = ...,
  455. auto_attribs: bool = ...,
  456. kw_only: bool = ...,
  457. cache_hash: bool = ...,
  458. auto_exc: bool = ...,
  459. eq: Optional[bool] = ...,
  460. order: Optional[bool] = ...,
  461. auto_detect: bool = ...,
  462. getstate_setstate: Optional[bool] = ...,
  463. on_setattr: Optional[_OnSetAttrArgType] = ...,
  464. field_transformer: Optional[_FieldTransformer] = ...,
  465. match_args: bool = ...,
  466. ) -> Callable[[_C], _C]: ...
  467. def fields(cls: Type[AttrsInstance]) -> Any: ...
  468. def fields_dict(cls: Type[AttrsInstance]) -> Dict[str, Attribute[Any]]: ...
  469. def validate(inst: AttrsInstance) -> None: ...
  470. def resolve_types(
  471. cls: _A,
  472. globalns: Optional[Dict[str, Any]] = ...,
  473. localns: Optional[Dict[str, Any]] = ...,
  474. attribs: Optional[List[Attribute[Any]]] = ...,
  475. include_extras: bool = ...,
  476. ) -> _A: ...
  477. # TODO: add support for returning a proper attrs class from the mypy plugin
  478. # we use Any instead of _CountingAttr so that e.g. `make_class('Foo',
  479. # [attr.ib()])` is valid
  480. def make_class(
  481. name: str,
  482. attrs: Union[List[str], Tuple[str, ...], Dict[str, Any]],
  483. bases: Tuple[type, ...] = ...,
  484. repr_ns: Optional[str] = ...,
  485. repr: bool = ...,
  486. cmp: Optional[_EqOrderType] = ...,
  487. hash: Optional[bool] = ...,
  488. init: bool = ...,
  489. slots: bool = ...,
  490. frozen: bool = ...,
  491. weakref_slot: bool = ...,
  492. str: bool = ...,
  493. auto_attribs: bool = ...,
  494. kw_only: bool = ...,
  495. cache_hash: bool = ...,
  496. auto_exc: bool = ...,
  497. eq: Optional[_EqOrderType] = ...,
  498. order: Optional[_EqOrderType] = ...,
  499. collect_by_mro: bool = ...,
  500. on_setattr: Optional[_OnSetAttrArgType] = ...,
  501. field_transformer: Optional[_FieldTransformer] = ...,
  502. ) -> type: ...
  503. # _funcs --
  504. # TODO: add support for returning TypedDict from the mypy plugin
  505. # FIXME: asdict/astuple do not honor their factory args. Waiting on one of
  506. # these:
  507. # https://github.com/python/mypy/issues/4236
  508. # https://github.com/python/typing/issues/253
  509. # XXX: remember to fix attrs.asdict/astuple too!
  510. def asdict(
  511. inst: AttrsInstance,
  512. recurse: bool = ...,
  513. filter: Optional[_FilterType[Any]] = ...,
  514. dict_factory: Type[Mapping[Any, Any]] = ...,
  515. retain_collection_types: bool = ...,
  516. value_serializer: Optional[
  517. Callable[[type, Attribute[Any], Any], Any]
  518. ] = ...,
  519. tuple_keys: Optional[bool] = ...,
  520. ) -> Dict[str, Any]: ...
  521. # TODO: add support for returning NamedTuple from the mypy plugin
  522. def astuple(
  523. inst: AttrsInstance,
  524. recurse: bool = ...,
  525. filter: Optional[_FilterType[Any]] = ...,
  526. tuple_factory: Type[Sequence[Any]] = ...,
  527. retain_collection_types: bool = ...,
  528. ) -> Tuple[Any, ...]: ...
  529. def has(cls: type) -> TypeGuard[Type[AttrsInstance]]: ...
  530. def assoc(inst: _T, **changes: Any) -> _T: ...
  531. def evolve(inst: _T, **changes: Any) -> _T: ...
  532. # _config --
  533. def set_run_validators(run: bool) -> None: ...
  534. def get_run_validators() -> bool: ...
  535. # aliases --
  536. s = attributes = attrs
  537. ib = attr = attrib
  538. dataclass = attrs # Technically, partial(attrs, auto_attribs=True) ;)