Skip to content

Commit 5e960b4

Browse files
committed
Require documenting Any uses
Closes: python#12428
1 parent 2aeb777 commit 5e960b4

File tree

1 file changed

+13
-5
lines changed

1 file changed

+13
-5
lines changed

CONTRIBUTING.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -460,6 +460,14 @@ unless:
460460
* they use the form ``from library import *`` which means all names
461461
from that library are exported.
462462

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+
463471
When adding type hints, avoid using the `Any` type when possible. Reserve
464472
the use of `Any` for when:
465473
* 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
469477
that some function can accept literally anything: in those cases use
470478
`object` instead.
471479

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.
477485

478486
### Context managers
479487

0 commit comments

Comments
 (0)