From 4bd6c43caa327127bd767d92a32852255fa42eff Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Fri, 3 Feb 2023 11:36:37 +0000 Subject: [PATCH 1/3] Rework CONTRIBUTING.md: parameter defaults are now accepted and encouraged --- CONTRIBUTING.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1908ea6a8e10..e3f8b6d22a49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -413,15 +413,28 @@ 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, typeshed's policy on some issues of style has been revised. +Whereas typeshed used to recommend omitting default values +for function and method parameters, +we now recommend that default values be retained for "simple" default values +(e.g. bools, ints, bytes, strings, and floats are all now permitted). +For more complex default values, we recommend to use `= ...` +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 From b1961ac06754444b4e1e4097efaa383b9d24a2f6 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Fri, 3 Feb 2023 11:56:31 +0000 Subject: [PATCH 2/3] History is useless --- CONTRIBUTING.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3f8b6d22a49..0d937b689bc4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -423,12 +423,9 @@ However, stubs also have other use cases: * stubs can serve as useful documentation to human readers, as well as machine-readable sources of data. -As such, typeshed's policy on some issues of style has been revised. -Whereas typeshed used to recommend omitting default values -for function and method parameters, -we now recommend that default values be retained for "simple" default values -(e.g. bools, ints, bytes, strings, and floats are all now permitted). -For more complex default values, we recommend to use `= ...` +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: From b98bea05f7afd9e93a140959c00c44fef0a91d14 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 3 Feb 2023 11:57:45 +0000 Subject: [PATCH 3/3] [pre-commit.ci] auto fixes from pre-commit.com hooks --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d937b689bc4..cef22cb67aba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -425,7 +425,7 @@ However, stubs also have other use cases: 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, +Use `= ...` for more complex default values, rather than trying to exactly reproduce the default at runtime. Some further tips for good type hints: