From f94bbfbcc4c3b2b289425ea793beda0822e702f8 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sat, 9 Mar 2024 15:59:15 -0800 Subject: [PATCH] Update the README (#11553) Read through the README and changed anything that no longer made sense. In particular, the documentation of our stub versioning scheme was outdated. --- README.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e4d718097044..914be67b8c5e 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,10 @@ Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people external to those projects. -This data can e.g. be used for static analysis, type checking or type inference. +This data can e.g. be used for static analysis, type checking, type inference, +and autocompletion. -For information on how to use `typeshed`, read below. Information for +For information on how to use typeshed, read below. Information for contributors can be found in [CONTRIBUTING.md](CONTRIBUTING.md). **Please read it before submitting pull requests; do not report issues with annotations to the project the stubs are for, but instead report them here to typeshed.** @@ -30,15 +31,15 @@ If you're just using a type checker ([mypy](https://github.com/python/mypy/), developing it, you don't need to interact with the typeshed repo at all: a copy of standard library part of typeshed is bundled with type checkers. And type stubs for third party packages and modules you are using can -be installed from PyPI. For example, if you are using `six` and `requests`, +be installed from PyPI. For example, if you are using `Pillow` and `requests`, you can install the type stubs using ```bash -$ pip install types-six types-requests +$ pip install types-Pillow types-requests ``` These PyPI packages follow [PEP 561](http://www.python.org/dev/peps/pep-0561/) -and are automatically released (multiple times a day, when needed) by +and are automatically released (up to once a day) by [typeshed internal machinery](https://github.com/typeshed-internal/stub_uploader). Type checkers should be able to use these stub packages when installed. For more @@ -49,13 +50,11 @@ details, see the documentation for your type checker. Version numbers of third-party stub packages consist of at least four parts. All parts of the stub version, except for the last part, correspond to the version of the runtime package being stubbed. For example, if the `types-foo` -package has version `1.2.0.7`, this guarantees that the `types-foo` package +package has version `1.2.0.20240309`, this guarantees that the `types-foo` package contains stubs targeted against `foo==1.2.*` and tested against the latest version of `foo` matching that specifier. In this example, the final element -of the version (7) indicates that this is the eighth revision of the stubs for -`foo==1.2.*`. If an update to the stubs were pushed (but the stubs were still -aiming to provide annotations for `foo==1.2.*`), then the version of -`types-foo` would increment to `1.2.0.8`. +of the version number (20240309) indicates that the stub package was pushed on +March 9, 2024. At typeshed, we try to keep breaking changes to a minimum. However, due to the nature of stubs, any version bump can introduce changes that might make your @@ -100,7 +99,7 @@ a problem arises that can't easily be fixed. ### The `_typeshed` package typeshed includes a package `_typeshed` as part of the standard library. -This package and its submodules contains utility types, but is not +This package and its submodules contain utility types, but are not available at runtime. For more information about how to use this package, [see the `stdlib/_typeshed` directory](https://github.com/python/typeshed/tree/main/stdlib/_typeshed).