Add partial_stub metadata field (python#10157)

sobolevn · May 10, 2023 · db01498 · db01498
1 parent ff700e1
commit db01498
Show file tree

Hide file tree

Showing 51 changed files with 68 additions and 1 deletion.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -193,6 +193,10 @@ supported:
 * `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](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:

diff --git a/stubs/Flask-Cors/METADATA.toml b/stubs/Flask-Cors/METADATA.toml
@@ -1,6 +1,7 @@
 version = "3.0.*"
 # Requires a version of flask with a `py.typed` file
 requires = ["Flask>=2.0.0"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/Flask-Migrate/METADATA.toml b/stubs/Flask-Migrate/METADATA.toml
@@ -1,6 +1,7 @@
 version = "4.0.*"
 # Requires a version of flask with a `py.typed` file
 requires = ["Flask>=2.0.0", "types-Flask-SQLAlchemy"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/Flask-SQLAlchemy/METADATA.toml b/stubs/Flask-SQLAlchemy/METADATA.toml
@@ -1,6 +1,7 @@
 version = "2.5.*"
 requires = ["types-SQLAlchemy"]
 obsolete_since = "3.0.1" # Released on 2022-10-11
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/Markdown/METADATA.toml b/stubs/Markdown/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.4.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/Pillow/METADATA.toml b/stubs/Pillow/METADATA.toml
@@ -1,4 +1,5 @@
 version = "9.5.*"
+partial_stub = true
 
 [tool.stubtest]
 stubtest_requirements = ["olefile"]

diff --git a/stubs/PyMySQL/METADATA.toml b/stubs/PyMySQL/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.0.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/Pygments/METADATA.toml b/stubs/Pygments/METADATA.toml
@@ -1,5 +1,6 @@
 version = "2.15.*"
 requires = ["types-docutils", "types-setuptools"]
+partial_stub = true
 
 [tool.stubtest]
 stubtest_requirements = ["sphinx"]

diff --git a/stubs/Send2Trash/METADATA.toml b/stubs/Send2Trash/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.8.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/aws-xray-sdk/METADATA.toml b/stubs/aws-xray-sdk/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.12.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/babel/METADATA.toml b/stubs/babel/METADATA.toml
@@ -1,6 +1,7 @@
 version = "2.11.*"
 requires = ["types-pytz"]
 obsolete_since = "2.12.1" # Released on 2023-02-28
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/beautifulsoup4/METADATA.toml b/stubs/beautifulsoup4/METADATA.toml
@@ -1,5 +1,6 @@
 version = "4.12.*"
 requires = ["types-html5lib"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/bleach/METADATA.toml b/stubs/bleach/METADATA.toml
@@ -1,4 +1,5 @@
 version = "6.0.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/boto/METADATA.toml b/stubs/boto/METADATA.toml
@@ -1,5 +1,6 @@
 version = "2.49.*"
 requires = []
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/braintree/METADATA.toml b/stubs/braintree/METADATA.toml
@@ -1,4 +1,5 @@
 version = "4.19.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/caldav/METADATA.toml b/stubs/caldav/METADATA.toml
@@ -1,6 +1,7 @@
 version = "1.2.*"
 # also types-lxml and types-icalendar when those stubs are added
 requires = ["types-requests", "types-vobject"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/chardet/METADATA.toml b/stubs/chardet/METADATA.toml
@@ -1,5 +1,6 @@
 version = "5.0.*"
 obsolete_since = "5.1.0" # Released on 2022-12-01
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/commonmark/METADATA.toml b/stubs/commonmark/METADATA.toml
@@ -1,4 +1,5 @@
 version = "0.9.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/docutils/METADATA.toml b/stubs/docutils/METADATA.toml
@@ -1,4 +1,5 @@
 version = "0.20.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-bugbear/METADATA.toml b/stubs/flake8-bugbear/METADATA.toml
@@ -1,4 +1,5 @@
 version = "23.5.9"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-builtins/METADATA.toml b/stubs/flake8-builtins/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.1.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-docstrings/METADATA.toml b/stubs/flake8-docstrings/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.7.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-plugin-utils/METADATA.toml b/stubs/flake8-plugin-utils/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.3.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-rst-docstrings/METADATA.toml b/stubs/flake8-rst-docstrings/METADATA.toml
@@ -1,4 +1,5 @@
 version = "0.3.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-simplify/METADATA.toml b/stubs/flake8-simplify/METADATA.toml
@@ -1,4 +1,5 @@
 version = "0.20.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/flake8-typing-imports/METADATA.toml b/stubs/flake8-typing-imports/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.14.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/google-cloud-ndb/METADATA.toml b/stubs/google-cloud-ndb/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.1.*"
+partial_stub = true
 
 [tool.stubtest]
 stubtest_requirements = ["protobuf==3.20.2"]

diff --git a/stubs/html5lib/METADATA.toml b/stubs/html5lib/METADATA.toml
@@ -1,4 +1,5 @@
 version = "1.1.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/invoke/METADATA.toml b/stubs/invoke/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.0.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/jsonschema/METADATA.toml b/stubs/jsonschema/METADATA.toml
@@ -1,4 +1,5 @@
 version = "4.17.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/ldap3/METADATA.toml b/stubs/ldap3/METADATA.toml
@@ -1,5 +1,6 @@
 version = "2.9.*"
 requires = ["types-pyasn1"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/oauthlib/METADATA.toml b/stubs/oauthlib/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.2.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/openpyxl/METADATA.toml b/stubs/openpyxl/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.1.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/opentracing/METADATA.toml b/stubs/opentracing/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.4.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/paramiko/METADATA.toml b/stubs/paramiko/METADATA.toml
@@ -1,6 +1,7 @@
 version = "3.0.*"
 # Requires a version of cryptography where cryptography.hazmat.primitives.ciphers.Cipher is generic
 requires = ["cryptography>=37.0.0"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/pep8-naming/METADATA.toml b/stubs/pep8-naming/METADATA.toml
@@ -1,4 +1,5 @@
 version = "0.13.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/protobuf/METADATA.toml b/stubs/protobuf/METADATA.toml
@@ -1,5 +1,6 @@
 version = "4.23.*"
 extra_description = "Generated with aid from mypy-protobuf v3.4.0"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/psycopg2/METADATA.toml b/stubs/psycopg2/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.9.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/pyOpenSSL/METADATA.toml b/stubs/pyOpenSSL/METADATA.toml
@@ -1,6 +1,7 @@
 version = "23.1.*"
 # Requires a version of cryptography with a `py.typed` file
 requires = ["cryptography>=35.0.0"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/pyflakes/METADATA.toml b/stubs/pyflakes/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.0.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/python-datemath/METADATA.toml b/stubs/python-datemath/METADATA.toml
@@ -1,6 +1,7 @@
 version = "1.5.*"
 # Requires a version of arrow with a `py.typed` file
 requires = ["arrow>=1.0.1"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/python-dateutil/METADATA.toml b/stubs/python-dateutil/METADATA.toml
@@ -1,4 +1,5 @@
 version = "2.8.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/pyvmomi/METADATA.toml b/stubs/pyvmomi/METADATA.toml
@@ -1,5 +1,6 @@
 version = "8.0.0.*"
 obsolete_since = "8.0.1.0" # Released on 2023-05-05
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/redis/METADATA.toml b/stubs/redis/METADATA.toml
@@ -1,6 +1,7 @@
 version = "4.5.5"
 # Requires a version of cryptography with a `py.typed` file
 requires = ["cryptography>=35.0.0", "types-pyOpenSSL"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/setuptools/METADATA.toml b/stubs/setuptools/METADATA.toml
@@ -1,4 +1,5 @@
 version = "67.7.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/simplejson/METADATA.toml b/stubs/simplejson/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.19.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/stripe/METADATA.toml b/stubs/stripe/METADATA.toml
@@ -1,4 +1,5 @@
 version = "3.5.*"
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/tensorflow/METADATA.toml b/stubs/tensorflow/METADATA.toml
@@ -1,6 +1,7 @@
 version = "2.12.*"
 # requires a version of numpy with a `py.typed` file
 requires = ["numpy>=1.20", "types-protobuf"]
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true
diff --git a/stubs/urllib3/METADATA.toml b/stubs/urllib3/METADATA.toml
@@ -1,5 +1,6 @@
 version = "1.26.*"
 obsolete_since = "2.0.0" # Released on 2023-04-26
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/stubs/waitress/METADATA.toml b/stubs/waitress/METADATA.toml
@@ -1,5 +1,6 @@
 version = "2.1.*"
 requires = []
+partial_stub = true
 
 [tool.stubtest]
 ignore_missing_stub = true

diff --git a/tests/parse_metadata.py b/tests/parse_metadata.py
@@ -123,11 +123,22 @@ class StubMetadata:
     obsolete_since: Annotated[str, "A string representing a specific version"] | None
     no_longer_updated: bool
     uploaded_to_pypi: Annotated[bool, "Whether or not a distribution is uploaded to PyPI"]
+    partial_stub: Annotated[bool, "Whether this is a partial type stub package as per PEP 561."]
     stubtest_settings: StubtestSettings
 
 
 _KNOWN_METADATA_FIELDS: Final = frozenset(
-    {"version", "requires", "extra_description", "stub_distribution", "obsolete_since", "no_longer_updated", "upload", "tool"}
+    {
+        "version",
+        "requires",
+        "extra_description",
+        "stub_distribution",
+        "obsolete_since",
+        "no_longer_updated",
+        "upload",
+        "tool",
+        "partial_stub",
+    }
 )
 _KNOWN_METADATA_TOOL_FIELDS: Final = {
     "stubtest": {
@@ -190,6 +201,8 @@ def read_metadata(distribution: str) -> StubMetadata:
     assert type(no_longer_updated) is bool
     uploaded_to_pypi: object = data.get("upload", True)
     assert type(uploaded_to_pypi) is bool
+    partial_stub: object = data.get("partial_stub", True)
+    assert type(partial_stub) is bool
 
     empty_tools: dict[object, object] = {}
     tools_settings: object = data.get("tool", empty_tools)
@@ -209,6 +222,7 @@ def read_metadata(distribution: str) -> StubMetadata:
         obsolete_since=obsolete_since,
         no_longer_updated=no_longer_updated,
         uploaded_to_pypi=uploaded_to_pypi,
+        partial_stub=partial_stub,
         stubtest_settings=read_stubtest_settings(distribution),
     )