@@ -460,6 +460,14 @@ unless:
460
460
* they use the form ``from library import *`` which means all names
461
461
from that library are exported.
462
462
463
+ Stub files support forward references natively. In other words, the
464
+ order of class declarations and type aliases does not matter in
465
+ a stub file. You can also use the name of the class within its own
466
+ body. Focus on making your stubs clear to the reader. Avoid using
467
+ string literals in type annotations.
468
+
469
+ ### Using `Any` and `object`
470
+
463
471
When adding type hints, avoid using the `Any` type when possible. Reserve
464
472
the use of `Any` for when:
465
473
* the correct type cannot be expressed in the current type system; and
@@ -469,11 +477,11 @@ Note that `Any` is not the correct type to use if you want to indicate
469
477
that some function can accept literally anything: in those cases use
470
478
`object` instead.
471
479
472
- Stub files support forward references natively. In other words, the
473
- order of class declarations and type aliases does not matter in
474
- a stub file. You can also use the name of the class within its own
475
- body. Focus on making your stubs clear to the reader. Avoid using
476
- string literals in type annotations .
480
+ When using `Any`, document the reason for using it in a comment. Ideally,
481
+ document what types could be used. The `_typeshed` module also provides
482
+ a few aliases to `Any` — like `Incomplete` and `MaybeNone` (see below) —
483
+ that should be used instead of `Any` in appropriate situations and double
484
+ as documentation .
477
485
478
486
### Context managers
479
487
0 commit comments