Make contribution guidelines state when to use (and not use) 'Any' (#2540)

This pull request modifies the contribution guidelines to clarify
when and where 'Any' should be used.

In particular, it clarifies that 'Any' is meant mainly to be used as
a "fallback" -- if it's not possible to express a certain type, if we're not
sure what the correct type in some case is, to avoid Union returns, etc...

It also explicitly notes that 'object' should be used over 'Any' when we
want to indicate that some function can accept literally anything.

Typing stubs this way probably won't impact most people, but does make
life a bit easier for people (like me) who want to restrict/forbid the
use of Any as much as possible.
This commit is contained in:
Michael Lee
2018-12-02 15:16:29 -08:00
committed by GitHub
parent 4fb22f61e4
commit 7b76fb9b20

View File

@@ -228,6 +228,17 @@ unless:
* they use the form ``from library import *`` which means all names
from that library are exported.
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;
* you are contributing a preliminary set of stubs and are not sure
in some cases what the correct types are; and
* to avoid Union returns (see above).
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.
For arguments with type and a default value of `None`, PEP 484
prescribes that the type automatically becomes `Optional`. However we
prefer explicit over implicit in this case, and require the explicit