From 0dd6f6e4f82653f40b164b8c26b48322daeeb3e5 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 13:36:33 +0100 Subject: [PATCH 1/6] Drop support for Python 3.7 Part of #10113 --- .github/workflows/tests.yml | 2 +- README.md | 4 +--- pyproject.toml | 2 +- test_cases/README.md | 8 ++++---- tests/regr_test.py | 2 +- 5 files changed, 8 insertions(+), 10 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index fb7b893d4d7f..ec840a821d43 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -125,7 +125,7 @@ jobs: strategy: matrix: python-platform: ["Linux", "Windows", "Darwin"] - python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"] + python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"] fail-fast: false steps: - uses: actions/checkout@v4 diff --git a/README.md b/README.md index d679eedf3930..e4d718097044 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,7 @@ the project the stubs are for, but instead report them here to typeshed.** Further documentation on stub files, typeshed, and Python's typing system in general, can also be found at https://typing.readthedocs.io/en/latest/. -Typeshed fully supports Python versions 3.8 and up. Support for Python 3.7 -is limited: see https://github.com/python/typeshed/issues/10113 -for details. +Typeshed supports Python versions 3.8 and up. ## Using diff --git a/pyproject.toml b/pyproject.toml index c3a965984573..fb42a5023fd6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -95,4 +95,4 @@ known-first-party = ["parse_metadata", "utils"] [tool.typeshed] pyright_version = "1.1.342" -oldest_supported_python = "3.7" +oldest_supported_python = "3.8" diff --git a/test_cases/README.md b/test_cases/README.md index 5624290a56df..437ae4552bcb 100644 --- a/test_cases/README.md +++ b/test_cases/README.md @@ -113,12 +113,12 @@ Some tests will only pass on mypy with a specific Python version passed on the command line to the `tests/regr_test.py` script. To mark a test-case file as being skippable on lower versions of Python, append `-py3*` to the filename. -For example, if `foo` is a stdlib feature that's new in Python 3.9, -test cases for `foo` should be put in a file named `test_cases/stdlib/check_foo-py39.py`. +For example, if `foo` is a stdlib feature that's new in Python 3.11, +test cases for `foo` should be put in a file named `test_cases/stdlib/check_foo-py311.py`. This means that mypy will only run the test case -if `--python-version 3.9`, `--python-version 3.10` or `--python-version 3.11` +if `--python-version 3.11`, `--python-version 3.12`, etc. is passed on the command line to `tests/regr_test.py`, -but it *won't* run the test case if `--python-version 3.7` or `--python-version 3.8` +but it _won't_ run the test case if e.g. `--python-version 3.9` is passed on the command line. However, `if sys.version_info >= (3, target):` is still required for `pyright` diff --git a/tests/regr_test.py b/tests/regr_test.py index cc7ede290b9a..3d50aec406ea 100755 --- a/tests/regr_test.py +++ b/tests/regr_test.py @@ -41,7 +41,7 @@ TYPESHED = "typeshed" SUPPORTED_PLATFORMS = ["linux", "darwin", "win32"] -SUPPORTED_VERSIONS = ["3.12", "3.11", "3.10", "3.9", "3.8", "3.7"] +SUPPORTED_VERSIONS = ["3.12", "3.11", "3.10", "3.9", "3.8"] def package_with_test_cases(package_name: str) -> PackageInfo: From 47851fb446ce7c0a0bee5a8f9238969ebed22929 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 13:40:07 +0100 Subject: [PATCH 2/6] Remove obsolete `requires_python` specifiers --- stubs/gevent/METADATA.toml | 1 - stubs/jsonschema/METADATA.toml | 1 - stubs/pyinstaller/METADATA.toml | 1 - 3 files changed, 3 deletions(-) diff --git a/stubs/gevent/METADATA.toml b/stubs/gevent/METADATA.toml index d3aea63af7d4..ea9119a65e59 100644 --- a/stubs/gevent/METADATA.toml +++ b/stubs/gevent/METADATA.toml @@ -1,7 +1,6 @@ version = "23.9.*" upstream_repository = "https://github.com/gevent/gevent" requires = ["types-greenlet", "types-psutil"] -requires_python = ">=3.8" [tool.stubtest] # Run stubtest on all platforms, since there is some platform specific stuff diff --git a/stubs/jsonschema/METADATA.toml b/stubs/jsonschema/METADATA.toml index eae3a4e3ad1a..971a088d551c 100644 --- a/stubs/jsonschema/METADATA.toml +++ b/stubs/jsonschema/METADATA.toml @@ -2,7 +2,6 @@ version = "4.20.*" upstream_repository = "https://github.com/python-jsonschema/jsonschema" requires = ["referencing"] partial_stub = true -requires_python = ">=3.8" [tool.stubtest] ignore_missing_stub = true diff --git a/stubs/pyinstaller/METADATA.toml b/stubs/pyinstaller/METADATA.toml index c48aa14aed3c..5a0b186fbe6b 100644 --- a/stubs/pyinstaller/METADATA.toml +++ b/stubs/pyinstaller/METADATA.toml @@ -1,7 +1,6 @@ version = "6.3.*" upstream_repository = "https://github.com/pyinstaller/pyinstaller" requires = ["types-setuptools"] -requires_python = ">=3.8" [tool.stubtest] extras = ["completion"] From 8fba4d1ae656836ac6ae7041d4cc7c7219b86384 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 13:41:49 +0100 Subject: [PATCH 3/6] Update typing_extensions list in CONTRIBUTING --- CONTRIBUTING.md | 234 ++++++++++++++++++++++++------------------------ 1 file changed, 118 insertions(+), 116 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5800360dfd0c..9a9d36bf45d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,16 +5,15 @@ range of Python users and Python codebases. If you're trying a type checker on your Python code, your experience and what you can contribute are important to the project's success. - ## The contribution process at a glance 1. [Prepare your environment](#preparing-the-environment). 2. Find out [where to make your changes](#where-to-make-changes). 3. [Prepare your changes](#preparing-changes): - * Small fixes and additions can be submitted directly as pull requests, - but [contact us](README.md#discussion) before starting significant work. - * Create your stubs, considering [what to include](#what-to-include) and - conforming to the [coding style](#stub-file-coding-style). + - Small fixes and additions can be submitted directly as pull requests, + but [contact us](README.md#discussion) before starting significant work. + - Create your stubs, considering [what to include](#what-to-include) and + conforming to the [coding style](#stub-file-coding-style). 4. Optionally [format and check your stubs](#code-formatting). 5. Optionally [run the tests](tests/README.md). 6. [Submit your changes](#submitting-changes) by opening a pull request. @@ -91,11 +90,11 @@ Various other autofixes are also performed by [`Ruff`](https://github.com/astral-sh/ruff). The repository is equipped with a [`pre-commit.ci`](https://pre-commit.ci/) -configuration file. This means that you don't *need* to do anything yourself to +configuration file. This means that you don't _need_ to do anything yourself to run the code formatters. When you push a commit, a bot will run those for you right away and add a commit to your PR. -That being said, if you *want* to run the checks locally when you commit, +That being said, if you _want_ to run the checks locally when you commit, you're free to do so. Either run the following manually... ```bash @@ -131,19 +130,21 @@ the versions of Python where the module is available. ### Third-party library stubs We accept stubs for third-party packages into typeshed as long as: -* the package is publicly available on the [Python Package Index](https://pypi.org/); -* the package supports any Python version supported by typeshed; and -* the package does not ship with its own stubs or type annotations. + +- the package is publicly available on the [Python Package Index](https://pypi.org/); +- the package supports any Python version supported by typeshed; and +- the package does not ship with its own stubs or type annotations. The fastest way to generate new stubs is to use `scripts/create_baseline_stubs.py` (see below). Stubs for third-party packages go into `stubs`. Each subdirectory there represents a PyPI distribution, and contains the following: -* `METADATA.toml`, describing the package. See below for details. -* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the + +- `METADATA.toml`, describing the package. See below for details. +- Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the source distribution. -* (Rarely) some docs specific to a given type stub package in `README` file. +- (Rarely) some docs specific to a given type stub package in `README` file. When a third party stub is added or modified, an updated version of the corresponding distribution will be @@ -153,8 +154,8 @@ version level is incremented. For example, if `stubs/foo/METADATA.toml` has `version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` to `types-foo-x.y.n+1`. -*Note:* In its current implementation, typeshed cannot contain stubs for -multiple versions of the same third-party library. Prefer to generate +_Note:_ In its current implementation, typeshed cannot contain stubs for +multiple versions of the same third-party library. Prefer to generate stubs for the latest version released on PyPI at the time of your stubbing. @@ -164,58 +165,59 @@ The metadata file describes the stubs package using the [TOML file format](https://toml.io/en/). Currently, the following keys are supported: -* `version`: The versions of the library that the stubs support. Two +- `version`: The versions of the library that the stubs support. Two formats are supported: - - A concrete version. This is especially suited for libraries that - use [Calendar Versioning](https://calver.org/). - - A version range ending in `.*`. This is suited for libraries that - reflect API changes in the version number only, where the API-independent - part is represented by the asterisk. In the case - of [Semantic Versioning](https://semver.org/), this version could look - like this: `2.7.*`. - When the stubs are updated to a newer version - of the library, the version of the stub should be bumped (note that - previous versions are still available on PyPI). -* `requires` (optional): A list of other stub packages or packages with type + - A concrete version. This is especially suited for libraries that + use [Calendar Versioning](https://calver.org/). + - A version range ending in `.*`. This is suited for libraries that + reflect API changes in the version number only, where the API-independent + part is represented by the asterisk. In the case + of [Semantic Versioning](https://semver.org/), this version could look + like this: `2.7.*`. + When the stubs are updated to a newer version + of the library, the version of the stub should be bumped (note that + previous versions are still available on PyPI). +- `requires` (optional): A list of other stub packages or packages with type information that are imported by the stubs in this package. Only packages generated by typeshed or required by the upstream package are allowed to be listed here, for security reasons. See [this issue](https://github.com/typeshed-internal/stub_uploader/issues/90) for more information about what external dependencies are allowed. -* `extra_description` (optional): Can be used to add a custom description to +- `extra_description` (optional): Can be used to add a custom description to the package's long description. It should be a multi-line string in Markdown format. -* `stub_distribution` (optional): Distribution name to be uploaded to PyPI. +- `stub_distribution` (optional): Distribution name to be uploaded to PyPI. This defaults to `types-` and should only be set in special cases. -* `upstream_repository` (recommended): The URL of the upstream repository. -* `obsolete_since` (optional): This field is part of our process for +- `upstream_repository` (recommended): The URL of the upstream repository. +- `obsolete_since` (optional): This field is part of our process for [removing obsolete third-party libraries](#third-party-library-removal-policy). It contains the first version of the corresponding library that ships its own `py.typed` file. -* `no_longer_updated` (optional): This field is set to `true` before removing +- `no_longer_updated` (optional): This field is set to `true` before removing stubs for other reasons than the upstream library shipping with type information. -* `upload` (optional): This field is set to `false` to prevent automatic +- `upload` (optional): This field is set to `false` to prevent automatic uploads to PyPI. This should only used in special cases, e.g. when the stubs break the upload. -* `partial_stub` (optional): This field marks the type stub package as +- `partial_stub` (optional): This field marks the type stub package as [partial](https://peps.python.org/pep-0561/#partial-stub-packages). This is for 3rd-party stubs that don't cover the entirety of the package's public API. In most cases, this field is identical to `ignore_missing_stub`. In addition, we specify configuration for stubtest in the `tool.stubtest` table. This has the following keys: -* `skip` (default: `false`): Whether stubtest should be run against this + +- `skip` (default: `false`): Whether stubtest should be run against this package. Please avoid setting this to `true`, and add a comment if you have to. -* `apt_dependencies` (default: `[]`): A list of Ubuntu APT packages +- `apt_dependencies` (default: `[]`): A list of Ubuntu APT packages that need to be installed for stubtest to run successfully. -* `brew_dependencies` (default: `[]`): A list of MacOS Homebrew packages +- `brew_dependencies` (default: `[]`): A list of MacOS Homebrew packages that need to be installed for stubtest to run successfully -* `choco_dependencies` (default: `[]`): A list of Windows Chocolatey packages +- `choco_dependencies` (default: `[]`): A list of Windows Chocolatey packages that need to be installed for stubtest to run successfully -* `platforms` (default: `["linux"]`): A list of OSes on which to run stubtest. +- `platforms` (default: `["linux"]`): A list of OSes on which to run stubtest. Can contain `win32`, `linux`, and `darwin` values. If not specified, stubtest is run only on `linux`. Only add extra OSes to the test @@ -227,7 +229,6 @@ distribution. The format of all `METADATA.toml` files can be checked by running `python3 ./tests/check_consistent.py`. - ## Preparing Changes ### Before you begin @@ -239,9 +240,9 @@ with what you'd like to do or have ideas that will help you do it. ### Format -Each Python module is represented by a `.pyi` "stub file". This is a +Each Python module is represented by a `.pyi` "stub file". This is a syntactically valid Python file, although it usually cannot be run by -Python 3 (since forward references don't require string quotes). All +Python 3 (since forward references don't require string quotes). All the methods are empty. Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/)) @@ -279,12 +280,14 @@ new features to the Python type system. In general, new features can be used in typeshed as soon as the PEP has been accepted and implemented and most type checkers support the new feature. -Accepted features that *cannot* yet be used in typeshed include: +Accepted features that _cannot_ yet be used in typeshed include: + - [PEP 570](https://www.python.org/dev/peps/pep-0570/) (positional-only arguments): see [#4972](https://github.com/python/typeshed/issues/4972), use argument names prefixed with `__` instead The following features are partially supported: + - [PEP 702](https://peps.python.org/pep-0702/) (`@deprecated()`) - For now, cannot be used in combination with other decorators (e.g., `@overload`, `@classmethod`, and `@property`) due to bugs in @@ -292,6 +295,7 @@ The following features are partially supported: [stubtest](https://github.com/python/mypy/pull/16457). Supported features include: + - [PEP 544](https://peps.python.org/pep-0544/) (Protocol) - [PEP 585](https://peps.python.org/pep-0585/) (builtin generics) - [PEP 586](https://peps.python.org/pep-0586/) (Literal) @@ -309,10 +313,6 @@ Features from the `typing` module that are not present in all supported Python 3 versions must be imported from `typing_extensions` instead in typeshed stubs. This currently affects: -- `Final` and `@final` (new in Python 3.8) -- `Literal` (new in Python 3.8) -- `SupportsIndex` (new in Python 3.8) -- `TypedDict` (new in Python 3.8) - `Concatenate` (new in Python 3.10) - `ParamSpec` (new in Python 3.10) - `TypeGuard` (new in Python 3.10) @@ -320,10 +320,6 @@ instead in typeshed stubs. This currently affects: - `LiteralString` (new in Python 3.11) - `@deprecated` (new in Python 3.13; in the `warnings` module) -Two exceptions are `Protocol` and `runtime_checkable`: although -these were added in Python 3.8, they can be used in stubs regardless -of Python version. - Some type checkers implicitly promote the `bytearray` and `memoryview` types to `bytes`. [PEP 688](https://www.python.org/dev/peps/pep-0688/) removes @@ -341,14 +337,15 @@ constants, etc.) of the module they cover, but it is not always clear exactly what is part of the interface. The following should always be included: + - All objects listed in the module's documentation. -- All objects included in ``__all__`` (if present). +- All objects included in `__all__` (if present). Other objects may be included if they are being used in practice or if they are not prefixed with an underscore. This means that typeshed will generally accept contributions that add missing objects, even if they are undocumented. Undocumented objects should -be marked with a comment of the form ``# undocumented``. +be marked with a comment of the form `# undocumented`. Example: ```python @@ -367,9 +364,9 @@ can be helpful in pointing out that an incorrect type was used. ### What to do when a project's documentation and implementation disagree Type stubs are meant to be external type annotations for a given -library. While they are useful documentation in its own merit, they +library. While they are useful documentation in its own merit, they augment the project's concrete implementation, not the project's -documentation. Whenever you find them disagreeing, model the type +documentation. Whenever you find them disagreeing, model the type information after the actual implementation and file an issue on the project's tracker to fix their documentation. @@ -377,13 +374,13 @@ project's tracker to fix their documentation. You can use checks like `if sys.version_info >= (3, 12):` to denote new functionality introduced -in a given Python version or solve type differences. When doing so, only use +in a given Python version or solve type differences. When doing so, only use two-tuples. Because of this, if a given functionality was introduced in, say, Python 3.11.4, your check: -* should be expressed as `if sys.version_info >= (3, 11):` -* should NOT be expressed as `if sys.version_info >= (3, 11, 4):` -* should NOT be expressed as `if sys.version_info >= (3, 12):` +- should be expressed as `if sys.version_info >= (3, 11):` +- should NOT be expressed as `if sys.version_info >= (3, 11, 4):` +- should NOT be expressed as `if sys.version_info >= (3, 12):` When your stub contains if statements for different Python versions, always put the code for the most recent Python version first. @@ -415,32 +412,34 @@ class date: ### Conventions -Stub files are *like* Python files and you should generally expect them -to look the same. Your tools should be able to successfully treat them -as regular Python files. However, there are a few important differences +Stub files are _like_ Python files and you should generally expect them +to look the same. Your tools should be able to successfully treat them +as regular Python files. However, there are a few important differences you should know about. Style conventions for stub files are different from PEP 8. The general -rule is that they should be as concise as possible. Specifically: -* all function bodies should be empty; -* prefer ``...`` over ``pass``; -* prefer ``...`` on the same line as the class/function signature; -* avoid vertical whitespace between consecutive module-level functions, +rule is that they should be as concise as possible. Specifically: + +- all function bodies should be empty; +- prefer `...` over `pass`; +- prefer `...` on the same line as the class/function signature; +- avoid vertical whitespace between consecutive module-level functions, names, or methods and fields within a single class; -* use a single blank line between top-level class definitions, or none +- use a single blank line between top-level class definitions, or none if the classes are very small; -* do not use docstrings; -* use variable annotations instead of type comments, even for stubs +- do not use docstrings; +- use variable annotations instead of type comments, even for stubs that target older versions of Python. 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, + +- 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, +- 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 @@ -449,48 +448,51 @@ 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 + +- 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 +- 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 +- use `X | Y` instead of `Union[X, Y]` and `X | None`, instead of `Optional[X]`; -* import collections (`Mapping`, `Iterable`, etc.) +- import collections (`Mapping`, `Iterable`, etc.) from `collections.abc` instead of `typing`; -* avoid invariant collection types (`list`, `dict`) in argument +- avoid invariant collection types (`list`, `dict`) in argument positions, in favor of covariant types like `Mapping` or `Sequence`; -* avoid union return types: https://github.com/python/mypy/issues/1693; -* use platform checks like `if sys.platform == 'win32'` to denote +- avoid union return types: https://github.com/python/mypy/issues/1693; +- use platform checks like `if sys.platform == 'win32'` to denote platform-dependent APIs; -* use mypy error codes for mypy-specific `# type: ignore` annotations, +- use mypy error codes for mypy-specific `# type: ignore` annotations, e.g. `# type: ignore[override]` for Liskov Substitution Principle violations. -* use pyright error codes for pyright-specific suppressions, +- use pyright error codes for pyright-specific suppressions, e.g. `# pyright: ignore[reportGeneralTypeIssues]`. - pyright is configured to discard `# type: ignore` annotations. - If you need both on the same line, mypy's annotation needs to go first, - e.g. `# type: ignore[override] # pyright: ignore[reportGeneralTypeIssues]`. + If you need both on the same line, mypy's annotation needs to go first, + e.g. `# type: ignore[override] # pyright: ignore[reportGeneralTypeIssues]`. Imports in stubs are considered private (not part of the exported API) unless: -* they use the form ``from library import name as name`` (sic, using - explicit ``as`` even if the name stays the same); or -* they use the form ``from library import *`` which means all names + +- they use the form `from library import name as name` (sic, using + explicit `as` even if the name stays the same); or +- 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; and -* to avoid union returns (see above). + +- the correct type cannot be expressed in the current type system; 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. -Stub files support forward references natively. In other words, the +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 +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. ### Context managers @@ -517,11 +519,11 @@ they are not part of the stubbed API. A few guidelines for protocol names below. In cases that don't fall into any of those categories, use your best judgement. -* Use plain names for protocols that represent a clear concept +- Use plain names for protocols that represent a clear concept (e.g. `Iterator`, `Container`). -* Use `SupportsX` for protocols that provide callable methods (e.g. +- Use `SupportsX` for protocols that provide callable methods (e.g. `SupportsInt`, `SupportsRead`, `SupportsReadSeek`). -* Use `HasX` for protocols that have readable and/or writable attributes +- Use `HasX` for protocols that have readable and/or writable attributes or getter/setter methods (e.g. `HasItems`, `HasFileno`). ### `@deprecated` @@ -532,13 +534,13 @@ functionality; see [PEP 702](https://peps.python.org/pep-0702/). A few guidelines for how to use it: -* In the standard library, apply the decorator only in Python versions +- In the standard library, apply the decorator only in Python versions where an appropriate replacement for the deprecated functionality exists. If in doubt, apply the decorator only on versions where the functionality has been explicitly deprecated, either through runtime warnings or in the documentation. Use `if sys.version_info` checks to apply the decorator only to some versions. -* Keep the deprecation message concise, but try to mention the projected +- Keep the deprecation message concise, but try to mention the projected version when the functionality is to be removed, and a suggested replacement. @@ -607,16 +609,16 @@ Match groups are almost always used in this way. Let's now consider typeshed's `-> str | Any` annotation of the `.group()` method: -* `-> Any` would mean "please do not complain" to type checkers. +- `-> Any` would mean "please do not complain" to type checkers. If `name_group` has type `Any`, you will get no error for this. -* `-> str` would mean "will always be a `str`", which is wrong, and would +- `-> str` would mean "will always be a `str`", which is wrong, and would cause type checkers to emit errors for code like `if name_group is None`. -* `-> str | None` means "you must check for None", which is correct but can get +- `-> str | None` means "you must check for None", which is correct but can get annoying for some common patterns. Checks like `assert name_group is not None` would need to be added into various places only to satisfy type checkers, even when it is impossible to actually get a `None` value (type checkers aren't smart enough to know this). -* `-> str | Any` means "must be prepared to handle a `str`". You will get an +- `-> str | Any` means "must be prepared to handle a `str`". You will get an error for `name_group.uper`, because it is not valid when `name_group` is a `str`. But type checkers are happy with `if name_group is None` checks, because we're saying it can also be something else than an `str`. @@ -632,11 +634,11 @@ implementation of a much-needed stub. We'd love to have your contributions. We use the usual GitHub pull-request flow, which may be familiar to -you if you've contributed to other projects on GitHub. For the +you if you've contributed to other projects on GitHub. For the mechanics, see [Mypy's git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). -Anyone interested in type stubs may review your code. One of the +Anyone interested in type stubs may review your code. One of the maintainers will merge your pull request when they think it's ready. For every pull request, we aim to promptly either merge it or say why it's not yet ready; if you go a few days without a reply, please feel @@ -658,8 +660,8 @@ if it consisted of several smaller commits. Third-party stubs are generally removed from typeshed when one of the following criteria is met: -* The upstream package ships a `py.typed` file for at least six months, or -* the package does not support any of the Python versions supported by +- The upstream package ships a `py.typed` file for at least six months, or +- the package does not support any of the Python versions supported by typeshed. If a package ships its own `py.typed` file, please follow these steps: @@ -688,26 +690,26 @@ for any stub obsoletions or removals. ## Maintainer guidelines The process for preparing and submitting changes also applies to -maintainers. This ensures high quality contributions and keeps -everybody on the same page. Avoid direct pushes to the repository. +maintainers. This ensures high quality contributions and keeps +everybody on the same page. Avoid direct pushes to the repository. When reviewing pull requests, follow these guidelines: -* Typing is hard. Try to be helpful and explain issues with the PR, +- Typing is hard. Try to be helpful and explain issues with the PR, especially to new contributors. -* When reviewing auto-generated stubs, just scan for red flags and obvious +- When reviewing auto-generated stubs, just scan for red flags and obvious errors. Leave possible manual improvements for separate PRs. -* When reviewing large, hand-crafted PRs, you only need to look for red flags +- When reviewing large, hand-crafted PRs, you only need to look for red flags and general issues, and do a few spot checks. -* Review smaller, hand-crafted PRs thoroughly. +- Review smaller, hand-crafted PRs thoroughly. When merging pull requests, follow these guidelines: -* Always wait for tests to pass before merging PRs. -* Use "[Squash and merge](https://github.com/blog/2141-squash-your-commits)" to merge PRs. -* Make sure the commit message is meaningful. For example, remove irrelevant +- Always wait for tests to pass before merging PRs. +- Use "[Squash and merge](https://github.com/blog/2141-squash-your-commits)" to merge PRs. +- Make sure the commit message is meaningful. For example, remove irrelevant intermediate commit messages. -* The commit message for third-party stubs is used to generate the changelog. +- The commit message for third-party stubs is used to generate the changelog. It should be valid Markdown, be comprehensive, read like a changelog entry, and assume that the reader has no access to the diff. -* Delete branches for merged PRs (by maintainers pushing to the main repo). +- Delete branches for merged PRs (by maintainers pushing to the main repo). From 3fd095489978a6d026926b428e7585b8832cc771 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 14:30:07 +0100 Subject: [PATCH 4/6] Revert formatting changes --- CONTRIBUTING.md | 226 +++++++++++++++++++++++------------------------- 1 file changed, 108 insertions(+), 118 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a9d36bf45d2..1e342908298a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,15 +5,16 @@ range of Python users and Python codebases. If you're trying a type checker on your Python code, your experience and what you can contribute are important to the project's success. + ## The contribution process at a glance 1. [Prepare your environment](#preparing-the-environment). 2. Find out [where to make your changes](#where-to-make-changes). 3. [Prepare your changes](#preparing-changes): - - Small fixes and additions can be submitted directly as pull requests, - but [contact us](README.md#discussion) before starting significant work. - - Create your stubs, considering [what to include](#what-to-include) and - conforming to the [coding style](#stub-file-coding-style). + * Small fixes and additions can be submitted directly as pull requests, + but [contact us](README.md#discussion) before starting significant work. + * Create your stubs, considering [what to include](#what-to-include) and + conforming to the [coding style](#stub-file-coding-style). 4. Optionally [format and check your stubs](#code-formatting). 5. Optionally [run the tests](tests/README.md). 6. [Submit your changes](#submitting-changes) by opening a pull request. @@ -90,11 +91,11 @@ Various other autofixes are also performed by [`Ruff`](https://github.com/astral-sh/ruff). The repository is equipped with a [`pre-commit.ci`](https://pre-commit.ci/) -configuration file. This means that you don't _need_ to do anything yourself to +configuration file. This means that you don't *need* to do anything yourself to run the code formatters. When you push a commit, a bot will run those for you right away and add a commit to your PR. -That being said, if you _want_ to run the checks locally when you commit, +That being said, if you *want* to run the checks locally when you commit, you're free to do so. Either run the following manually... ```bash @@ -130,21 +131,19 @@ the versions of Python where the module is available. ### Third-party library stubs We accept stubs for third-party packages into typeshed as long as: - -- the package is publicly available on the [Python Package Index](https://pypi.org/); -- the package supports any Python version supported by typeshed; and -- the package does not ship with its own stubs or type annotations. +* the package is publicly available on the [Python Package Index](https://pypi.org/); +* the package supports any Python version supported by typeshed; and +* the package does not ship with its own stubs or type annotations. The fastest way to generate new stubs is to use `scripts/create_baseline_stubs.py` (see below). Stubs for third-party packages go into `stubs`. Each subdirectory there represents a PyPI distribution, and contains the following: - -- `METADATA.toml`, describing the package. See below for details. -- Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the +* `METADATA.toml`, describing the package. See below for details. +* Stubs (i.e. `*.pyi` files) for packages and modules that are shipped in the source distribution. -- (Rarely) some docs specific to a given type stub package in `README` file. +* (Rarely) some docs specific to a given type stub package in `README` file. When a third party stub is added or modified, an updated version of the corresponding distribution will be @@ -154,8 +153,8 @@ version level is incremented. For example, if `stubs/foo/METADATA.toml` has `version = "x.y"` the package on PyPI will be updated from `types-foo-x.y.n` to `types-foo-x.y.n+1`. -_Note:_ In its current implementation, typeshed cannot contain stubs for -multiple versions of the same third-party library. Prefer to generate +*Note:* In its current implementation, typeshed cannot contain stubs for +multiple versions of the same third-party library. Prefer to generate stubs for the latest version released on PyPI at the time of your stubbing. @@ -165,59 +164,58 @@ The metadata file describes the stubs package using the [TOML file format](https://toml.io/en/). Currently, the following keys are supported: -- `version`: The versions of the library that the stubs support. Two +* `version`: The versions of the library that the stubs support. Two formats are supported: - - A concrete version. This is especially suited for libraries that - use [Calendar Versioning](https://calver.org/). - - A version range ending in `.*`. This is suited for libraries that - reflect API changes in the version number only, where the API-independent - part is represented by the asterisk. In the case - of [Semantic Versioning](https://semver.org/), this version could look - like this: `2.7.*`. - When the stubs are updated to a newer version - of the library, the version of the stub should be bumped (note that - previous versions are still available on PyPI). -- `requires` (optional): A list of other stub packages or packages with type + - A concrete version. This is especially suited for libraries that + use [Calendar Versioning](https://calver.org/). + - A version range ending in `.*`. This is suited for libraries that + reflect API changes in the version number only, where the API-independent + part is represented by the asterisk. In the case + of [Semantic Versioning](https://semver.org/), this version could look + like this: `2.7.*`. + When the stubs are updated to a newer version + of the library, the version of the stub should be bumped (note that + previous versions are still available on PyPI). +* `requires` (optional): A list of other stub packages or packages with type information that are imported by the stubs in this package. Only packages generated by typeshed or required by the upstream package are allowed to be listed here, for security reasons. See [this issue](https://github.com/typeshed-internal/stub_uploader/issues/90) for more information about what external dependencies are allowed. -- `extra_description` (optional): Can be used to add a custom description to +* `extra_description` (optional): Can be used to add a custom description to the package's long description. It should be a multi-line string in Markdown format. -- `stub_distribution` (optional): Distribution name to be uploaded to PyPI. +* `stub_distribution` (optional): Distribution name to be uploaded to PyPI. This defaults to `types-` and should only be set in special cases. -- `upstream_repository` (recommended): The URL of the upstream repository. -- `obsolete_since` (optional): This field is part of our process for +* `upstream_repository` (recommended): The URL of the upstream repository. +* `obsolete_since` (optional): This field is part of our process for [removing obsolete third-party libraries](#third-party-library-removal-policy). It contains the first version of the corresponding library that ships its own `py.typed` file. -- `no_longer_updated` (optional): This field is set to `true` before removing +* `no_longer_updated` (optional): This field is set to `true` before removing stubs for other reasons than the upstream library shipping with type information. -- `upload` (optional): This field is set to `false` to prevent automatic +* `upload` (optional): This field is set to `false` to prevent automatic uploads to PyPI. This should only used in special cases, e.g. when the stubs break the upload. -- `partial_stub` (optional): This field marks the type stub package as +* `partial_stub` (optional): This field marks the type stub package as [partial](https://peps.python.org/pep-0561/#partial-stub-packages). This is for 3rd-party stubs that don't cover the entirety of the package's public API. In most cases, this field is identical to `ignore_missing_stub`. In addition, we specify configuration for stubtest in the `tool.stubtest` table. This has the following keys: - -- `skip` (default: `false`): Whether stubtest should be run against this +* `skip` (default: `false`): Whether stubtest should be run against this package. Please avoid setting this to `true`, and add a comment if you have to. -- `apt_dependencies` (default: `[]`): A list of Ubuntu APT packages +* `apt_dependencies` (default: `[]`): A list of Ubuntu APT packages that need to be installed for stubtest to run successfully. -- `brew_dependencies` (default: `[]`): A list of MacOS Homebrew packages +* `brew_dependencies` (default: `[]`): A list of MacOS Homebrew packages that need to be installed for stubtest to run successfully -- `choco_dependencies` (default: `[]`): A list of Windows Chocolatey packages +* `choco_dependencies` (default: `[]`): A list of Windows Chocolatey packages that need to be installed for stubtest to run successfully -- `platforms` (default: `["linux"]`): A list of OSes on which to run stubtest. +* `platforms` (default: `["linux"]`): A list of OSes on which to run stubtest. Can contain `win32`, `linux`, and `darwin` values. If not specified, stubtest is run only on `linux`. Only add extra OSes to the test @@ -229,6 +227,7 @@ distribution. The format of all `METADATA.toml` files can be checked by running `python3 ./tests/check_consistent.py`. + ## Preparing Changes ### Before you begin @@ -240,9 +239,9 @@ with what you'd like to do or have ideas that will help you do it. ### Format -Each Python module is represented by a `.pyi` "stub file". This is a +Each Python module is represented by a `.pyi` "stub file". This is a syntactically valid Python file, although it usually cannot be run by -Python 3 (since forward references don't require string quotes). All +Python 3 (since forward references don't require string quotes). All the methods are empty. Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/)) @@ -280,14 +279,12 @@ new features to the Python type system. In general, new features can be used in typeshed as soon as the PEP has been accepted and implemented and most type checkers support the new feature. -Accepted features that _cannot_ yet be used in typeshed include: - +Accepted features that *cannot* yet be used in typeshed include: - [PEP 570](https://www.python.org/dev/peps/pep-0570/) (positional-only arguments): see [#4972](https://github.com/python/typeshed/issues/4972), use argument names prefixed with `__` instead The following features are partially supported: - - [PEP 702](https://peps.python.org/pep-0702/) (`@deprecated()`) - For now, cannot be used in combination with other decorators (e.g., `@overload`, `@classmethod`, and `@property`) due to bugs in @@ -295,7 +292,6 @@ The following features are partially supported: [stubtest](https://github.com/python/mypy/pull/16457). Supported features include: - - [PEP 544](https://peps.python.org/pep-0544/) (Protocol) - [PEP 585](https://peps.python.org/pep-0585/) (builtin generics) - [PEP 586](https://peps.python.org/pep-0586/) (Literal) @@ -337,15 +333,14 @@ constants, etc.) of the module they cover, but it is not always clear exactly what is part of the interface. The following should always be included: - - All objects listed in the module's documentation. -- All objects included in `__all__` (if present). +- All objects included in ``__all__`` (if present). Other objects may be included if they are being used in practice or if they are not prefixed with an underscore. This means that typeshed will generally accept contributions that add missing objects, even if they are undocumented. Undocumented objects should -be marked with a comment of the form `# undocumented`. +be marked with a comment of the form ``# undocumented``. Example: ```python @@ -364,9 +359,9 @@ can be helpful in pointing out that an incorrect type was used. ### What to do when a project's documentation and implementation disagree Type stubs are meant to be external type annotations for a given -library. While they are useful documentation in its own merit, they +library. While they are useful documentation in its own merit, they augment the project's concrete implementation, not the project's -documentation. Whenever you find them disagreeing, model the type +documentation. Whenever you find them disagreeing, model the type information after the actual implementation and file an issue on the project's tracker to fix their documentation. @@ -374,13 +369,13 @@ project's tracker to fix their documentation. You can use checks like `if sys.version_info >= (3, 12):` to denote new functionality introduced -in a given Python version or solve type differences. When doing so, only use +in a given Python version or solve type differences. When doing so, only use two-tuples. Because of this, if a given functionality was introduced in, say, Python 3.11.4, your check: -- should be expressed as `if sys.version_info >= (3, 11):` -- should NOT be expressed as `if sys.version_info >= (3, 11, 4):` -- should NOT be expressed as `if sys.version_info >= (3, 12):` +* should be expressed as `if sys.version_info >= (3, 11):` +* should NOT be expressed as `if sys.version_info >= (3, 11, 4):` +* should NOT be expressed as `if sys.version_info >= (3, 12):` When your stub contains if statements for different Python versions, always put the code for the most recent Python version first. @@ -412,34 +407,32 @@ class date: ### Conventions -Stub files are _like_ Python files and you should generally expect them -to look the same. Your tools should be able to successfully treat them -as regular Python files. However, there are a few important differences +Stub files are *like* Python files and you should generally expect them +to look the same. Your tools should be able to successfully treat them +as regular Python files. However, there are a few important differences you should know about. Style conventions for stub files are different from PEP 8. The general -rule is that they should be as concise as possible. Specifically: - -- all function bodies should be empty; -- prefer `...` over `pass`; -- prefer `...` on the same line as the class/function signature; -- avoid vertical whitespace between consecutive module-level functions, +rule is that they should be as concise as possible. Specifically: +* all function bodies should be empty; +* prefer ``...`` over ``pass``; +* prefer ``...`` on the same line as the class/function signature; +* avoid vertical whitespace between consecutive module-level functions, names, or methods and fields within a single class; -- use a single blank line between top-level class definitions, or none +* use a single blank line between top-level class definitions, or none if the classes are very small; -- do not use docstrings; -- use variable annotations instead of type comments, even for stubs +* do not use docstrings; +* use variable annotations instead of type comments, even for stubs that target older versions of Python. 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, +* 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, +* 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 @@ -448,51 +441,48 @@ 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 +* 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 +* 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 +* use `X | Y` instead of `Union[X, Y]` and `X | None`, instead of `Optional[X]`; -- import collections (`Mapping`, `Iterable`, etc.) +* import collections (`Mapping`, `Iterable`, etc.) from `collections.abc` instead of `typing`; -- avoid invariant collection types (`list`, `dict`) in argument +* avoid invariant collection types (`list`, `dict`) in argument positions, in favor of covariant types like `Mapping` or `Sequence`; -- avoid union return types: https://github.com/python/mypy/issues/1693; -- use platform checks like `if sys.platform == 'win32'` to denote +* avoid union return types: https://github.com/python/mypy/issues/1693; +* use platform checks like `if sys.platform == 'win32'` to denote platform-dependent APIs; -- use mypy error codes for mypy-specific `# type: ignore` annotations, +* use mypy error codes for mypy-specific `# type: ignore` annotations, e.g. `# type: ignore[override]` for Liskov Substitution Principle violations. -- use pyright error codes for pyright-specific suppressions, +* use pyright error codes for pyright-specific suppressions, e.g. `# pyright: ignore[reportGeneralTypeIssues]`. - pyright is configured to discard `# type: ignore` annotations. - If you need both on the same line, mypy's annotation needs to go first, - e.g. `# type: ignore[override] # pyright: ignore[reportGeneralTypeIssues]`. + If you need both on the same line, mypy's annotation needs to go first, + e.g. `# type: ignore[override] # pyright: ignore[reportGeneralTypeIssues]`. Imports in stubs are considered private (not part of the exported API) unless: - -- they use the form `from library import name as name` (sic, using - explicit `as` even if the name stays the same); or -- they use the form `from library import *` which means all names +* they use the form ``from library import name as name`` (sic, using + explicit ``as`` even if the name stays the same); or +* 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; and -- to avoid union returns (see above). +* the correct type cannot be expressed in the current type system; 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. -Stub files support forward references natively. In other words, the +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 +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. ### Context managers @@ -519,11 +509,11 @@ they are not part of the stubbed API. A few guidelines for protocol names below. In cases that don't fall into any of those categories, use your best judgement. -- Use plain names for protocols that represent a clear concept +* Use plain names for protocols that represent a clear concept (e.g. `Iterator`, `Container`). -- Use `SupportsX` for protocols that provide callable methods (e.g. +* Use `SupportsX` for protocols that provide callable methods (e.g. `SupportsInt`, `SupportsRead`, `SupportsReadSeek`). -- Use `HasX` for protocols that have readable and/or writable attributes +* Use `HasX` for protocols that have readable and/or writable attributes or getter/setter methods (e.g. `HasItems`, `HasFileno`). ### `@deprecated` @@ -534,13 +524,13 @@ functionality; see [PEP 702](https://peps.python.org/pep-0702/). A few guidelines for how to use it: -- In the standard library, apply the decorator only in Python versions +* In the standard library, apply the decorator only in Python versions where an appropriate replacement for the deprecated functionality exists. If in doubt, apply the decorator only on versions where the functionality has been explicitly deprecated, either through runtime warnings or in the documentation. Use `if sys.version_info` checks to apply the decorator only to some versions. -- Keep the deprecation message concise, but try to mention the projected +* Keep the deprecation message concise, but try to mention the projected version when the functionality is to be removed, and a suggested replacement. @@ -609,16 +599,16 @@ Match groups are almost always used in this way. Let's now consider typeshed's `-> str | Any` annotation of the `.group()` method: -- `-> Any` would mean "please do not complain" to type checkers. +* `-> Any` would mean "please do not complain" to type checkers. If `name_group` has type `Any`, you will get no error for this. -- `-> str` would mean "will always be a `str`", which is wrong, and would +* `-> str` would mean "will always be a `str`", which is wrong, and would cause type checkers to emit errors for code like `if name_group is None`. -- `-> str | None` means "you must check for None", which is correct but can get +* `-> str | None` means "you must check for None", which is correct but can get annoying for some common patterns. Checks like `assert name_group is not None` would need to be added into various places only to satisfy type checkers, even when it is impossible to actually get a `None` value (type checkers aren't smart enough to know this). -- `-> str | Any` means "must be prepared to handle a `str`". You will get an +* `-> str | Any` means "must be prepared to handle a `str`". You will get an error for `name_group.uper`, because it is not valid when `name_group` is a `str`. But type checkers are happy with `if name_group is None` checks, because we're saying it can also be something else than an `str`. @@ -634,11 +624,11 @@ implementation of a much-needed stub. We'd love to have your contributions. We use the usual GitHub pull-request flow, which may be familiar to -you if you've contributed to other projects on GitHub. For the +you if you've contributed to other projects on GitHub. For the mechanics, see [Mypy's git and GitHub workflow help page](https://github.com/python/mypy/wiki/Using-Git-And-GitHub), or [GitHub's own documentation](https://help.github.com/articles/using-pull-requests/). -Anyone interested in type stubs may review your code. One of the +Anyone interested in type stubs may review your code. One of the maintainers will merge your pull request when they think it's ready. For every pull request, we aim to promptly either merge it or say why it's not yet ready; if you go a few days without a reply, please feel @@ -660,8 +650,8 @@ if it consisted of several smaller commits. Third-party stubs are generally removed from typeshed when one of the following criteria is met: -- The upstream package ships a `py.typed` file for at least six months, or -- the package does not support any of the Python versions supported by +* The upstream package ships a `py.typed` file for at least six months, or +* the package does not support any of the Python versions supported by typeshed. If a package ships its own `py.typed` file, please follow these steps: @@ -690,26 +680,26 @@ for any stub obsoletions or removals. ## Maintainer guidelines The process for preparing and submitting changes also applies to -maintainers. This ensures high quality contributions and keeps -everybody on the same page. Avoid direct pushes to the repository. +maintainers. This ensures high quality contributions and keeps +everybody on the same page. Avoid direct pushes to the repository. When reviewing pull requests, follow these guidelines: -- Typing is hard. Try to be helpful and explain issues with the PR, +* Typing is hard. Try to be helpful and explain issues with the PR, especially to new contributors. -- When reviewing auto-generated stubs, just scan for red flags and obvious +* When reviewing auto-generated stubs, just scan for red flags and obvious errors. Leave possible manual improvements for separate PRs. -- When reviewing large, hand-crafted PRs, you only need to look for red flags +* When reviewing large, hand-crafted PRs, you only need to look for red flags and general issues, and do a few spot checks. -- Review smaller, hand-crafted PRs thoroughly. +* Review smaller, hand-crafted PRs thoroughly. When merging pull requests, follow these guidelines: -- Always wait for tests to pass before merging PRs. -- Use "[Squash and merge](https://github.com/blog/2141-squash-your-commits)" to merge PRs. -- Make sure the commit message is meaningful. For example, remove irrelevant +* Always wait for tests to pass before merging PRs. +* Use "[Squash and merge](https://github.com/blog/2141-squash-your-commits)" to merge PRs. +* Make sure the commit message is meaningful. For example, remove irrelevant intermediate commit messages. -- The commit message for third-party stubs is used to generate the changelog. +* The commit message for third-party stubs is used to generate the changelog. It should be valid Markdown, be comprehensive, read like a changelog entry, and assume that the reader has no access to the diff. -- Delete branches for merged PRs (by maintainers pushing to the main repo). +* Delete branches for merged PRs (by maintainers pushing to the main repo). From 8d4b3c7f5571aa01eb851f3e410fcfc2c24ba093 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 14:40:16 +0100 Subject: [PATCH 5/6] Remove the PEP 570 finder --- tests/check_new_syntax.py | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/tests/check_new_syntax.py b/tests/check_new_syntax.py index e0564362c9af..830d1f2e5e2f 100755 --- a/tests/check_new_syntax.py +++ b/tests/check_new_syntax.py @@ -26,29 +26,7 @@ def visit_If(self, node: ast.If) -> None: ) self.generic_visit(node) - class PEP570Finder(ast.NodeVisitor): - def __init__(self) -> None: - self.lineno: int | None = None - - def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None: - old_lineno = self.lineno - self.lineno = node.lineno - self.generic_visit(node) - self.lineno = old_lineno - - visit_FunctionDef = visit_AsyncFunctionDef = _visit_function - - def visit_arguments(self, node: ast.arguments) -> None: - if node.posonlyargs: - assert isinstance(self.lineno, int) - errors.append( - f"{path}:{self.lineno}: PEP-570 syntax cannot be used in typeshed yet. " - f"Prefix parameter names with `__` to indicate positional-only parameters" - ) - self.generic_visit(node) - IfFinder().visit(tree) - PEP570Finder().visit(tree) return errors From 70503e02f3c06e274fd52cab730a4b8b540d58e3 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Thu, 4 Jan 2024 14:40:51 +0100 Subject: [PATCH 6/6] PEP 570 in CONTRIBUTING --- CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e342908298a..5779fce3cfa1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -279,11 +279,6 @@ new features to the Python type system. In general, new features can be used in typeshed as soon as the PEP has been accepted and implemented and most type checkers support the new feature. -Accepted features that *cannot* yet be used in typeshed include: -- [PEP 570](https://www.python.org/dev/peps/pep-0570/) (positional-only - arguments): see [#4972](https://github.com/python/typeshed/issues/4972), - use argument names prefixed with `__` instead - The following features are partially supported: - [PEP 702](https://peps.python.org/pep-0702/) (`@deprecated()`) - For now, cannot be used in combination with other decorators