@@ -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