@@ -16,24 +16,25 @@ Python packages and modules. Stub files serve multiple purposes:
16
16
* They are the only way to add type information to extension modules.
17
17
* They can provide type information for packages that do not wish to
18
18
add them inline.
19
- * They can be distributed separately from the implementation.
19
+ * They can be distributed separately from the package or module that they
20
+ provide types for. The latter is referred to as the *implementation *.
20
21
This allows stubs to be developed at a different pace or by different
21
22
authors, which is especially useful when adding type annotations to
22
23
existing packages.
23
24
* They can act as documentation, succinctly explaining the external
24
- API of a package, without including the implementation or private
25
+ API of a package, without including implementation details or private
25
26
members.
26
27
27
28
Stub files use a subset of the constructs used in Python source files, as
28
29
described in :ref: `stub-file-supported-constructs ` below. Type checkers should
29
30
parse a stub that uses only such constructs without error and not interpret any
30
- construct in a contradictory manner. However, type checkers are not required to
31
- implement checks for all of these constructs and can elect to ignore unsupported
32
- ones. Additionally, type checkers can support constructs not described here.
31
+ construct in a manner contradictory to this specification. However, type
32
+ checkers are not required to implement checks for all of these constructs and
33
+ can elect to ignore unsupported ones. Additionally, type checkers can support
34
+ constructs not described here.
33
35
34
- If a stub
35
- file is found for a module, the type checker should not read the corresponding "real" module.
36
- See :ref: `mro ` for more information.
36
+ If a stub file is found for a module, the type checker should not read the
37
+ corresponding "real" module. See :ref: `mro ` for more information.
37
38
38
39
.. _stub-file-syntax :
39
40
0 commit comments