Skip to content

Commit

Permalink
Require documenting Any uses (python#12430)
Browse files Browse the repository at this point in the history
  • Loading branch information
srittau authored Jul 25, 2024
1 parent ac8720b commit 9eae1ae
Showing 1 changed file with 13 additions and 5 deletions.
18 changes: 13 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,14 @@ unless:
* they use the form ``from library import *`` which means all names
from that library are exported.

Stub files support forward references natively. In other words, the
order of class declarations and type aliases does not matter in
a stub file. You can also use the name of the class within its own
body. Focus on making your stubs clear to the reader. Avoid using
string literals in type annotations.

### Using `Any` and `object`

When adding type hints, avoid using the `Any` type when possible. Reserve
the use of `Any` for when:
* the correct type cannot be expressed in the current type system; and
Expand All @@ -469,11 +477,11 @@ Note that `Any` is not the correct type to use if you want to indicate
that some function can accept literally anything: in those cases use
`object` instead.

Stub files support forward references natively. In other words, the
order of class declarations and type aliases does not matter in
a stub file. You can also use the name of the class within its own
body. Focus on making your stubs clear to the reader. Avoid using
string literals in type annotations.
When using `Any`, document the reason for using it in a comment. Ideally,
document what types could be used. The `_typeshed` module also provides
a few aliases to `Any` — like `Incomplete` and `MaybeNone` (see below) —
that should be used instead of `Any` in appropriate situations and double
as documentation.

### Context managers

Expand Down

0 comments on commit 9eae1ae

Please sign in to comment.