Skip to content

Require documenting Any uses #12430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 25, 2024
Merged

Require documenting Any uses #12430

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention Unused (for parameters that are unused even in subclassing, and ignored callable return types) with the semantic aliases ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unused equals object. Generally speaking, now that Rebecca is moving content into the Writing Stubs guide, we should review our recommendations here and merge them into to that guide as far as possible.


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