Skip to content

Rework CONTRIBUTING.md: simple parameter defaults are now accepted and encouraged #9665

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 3 commits into from
Feb 3, 2023
Merged

Rework CONTRIBUTING.md: simple parameter defaults are now accepted and encouraged #9665

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4bd6c43
Rework CONTRIBUTING.md: parameter defaults are now accepted and encou…
AlexWaygood Feb 3, 2023
b1961ac
History is useless
AlexWaygood Feb 3, 2023
b98bea0
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 3, 2023
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
24 changes: 17 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,15 +413,25 @@ rule is that they should be as concise as possible. Specifically:
* use variable annotations instead of type comments, even for stubs
that target older versions of Python.

Stub files should only contain information necessary for the type
checker, and leave out unnecessary detail:
* for arguments with a default, use `...` instead of the actual
default;
* for arguments that default to `None`, use `Foo | None` explicitly
(see below for details);
* use `float` instead of `int | float`.
The primary users for stub files are type checkers,
so stub files should generally only contain information necessary for the type
checker, and leave out unnecessary detail.
However, stubs also have other use cases:
* stub files are often used as a data source for IDEs,
which will often use the signature in a stub to provide information
on functions or classes in tooltip messages.
* stubs can serve as useful documentation to human readers,
as well as machine-readable sources of data.

As such, we recommend that default values be retained for "simple" default values
(e.g. bools, ints, bytes, strings, and floats are all permitted).
Use `= ...` for more complex default values,
rather than trying to exactly reproduce the default at runtime.

Some further tips for good type hints:
* for arguments that default to `None`, use `Foo | None` explicitly for the type annotation;
* use `float` instead of `int | float` for parameter annotations
(see [PEP 484](https://peps.python.org/pep-0484/#the-numeric-tower) for motivation).
* use built-in generics (`list`, `dict`, `tuple`, `set`), instead
of importing them from `typing`.
* use `X | Y` instead of `Union[X, Y]` and `X | None`, instead of
Expand Down