VimPlug/typeshed
1
0
Fork 0
mirror of https://github.com/davidhalter/typeshed.git synced 2025-12-24 21:01:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Require documenting Any uses (#12430)

Browse Source
This commit is contained in:
Sebastian Rittau
2024-07-25 17:38:12 +02:00
committed by GitHub
parent ac8720b99d
commit 9eae1ae1a5
1 changed files with 13 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
CONTRIBUTING.md
View File

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