[jsonschema] Improve stubs

stubs/jsonschema/@tests/stubtest_allowlist.txt

@@ -0,0 +1,93 @@
+# Testing modules are not included in type stubs:
+jsonschema.tests.*
+jsonschema.benchmarks.*
+
+# When importing this module, SystemExit: 2 is thrown:
+jsonschema.__main__
+
+# Autogenerated methods using @attr.* decorators:
+jsonschema.Draft201909Validator.__attrs_attrs__
+jsonschema.Draft201909Validator.__attrs_own_setattr__
+jsonschema.Draft201909Validator.__attrs_post_init__
+jsonschema.Draft201909Validator.__match_args__
+jsonschema.Draft202012Validator.__attrs_attrs__
+jsonschema.Draft202012Validator.__attrs_own_setattr__
+jsonschema.Draft202012Validator.__attrs_post_init__
+jsonschema.Draft202012Validator.__match_args__
+jsonschema.Draft3Validator.__attrs_attrs__
+jsonschema.Draft3Validator.__attrs_own_setattr__
+jsonschema.Draft3Validator.__attrs_post_init__
+jsonschema.Draft3Validator.__match_args__
+jsonschema.Draft4Validator.__attrs_attrs__
+jsonschema.Draft4Validator.__attrs_own_setattr__
+jsonschema.Draft4Validator.__attrs_post_init__
+jsonschema.Draft4Validator.__match_args__
+jsonschema.Draft6Validator.__attrs_attrs__
+jsonschema.Draft6Validator.__attrs_own_setattr__
+jsonschema.Draft6Validator.__attrs_post_init__
+jsonschema.Draft6Validator.__match_args__
+jsonschema.Draft7Validator.__attrs_attrs__
+jsonschema.Draft7Validator.__attrs_own_setattr__
+jsonschema.Draft7Validator.__attrs_post_init__
+jsonschema.Draft7Validator.__match_args__
+jsonschema.RefResolutionError.__attrs_attrs__
+jsonschema.RefResolutionError.__match_args__
+jsonschema.TypeChecker.__attrs_attrs__
+jsonschema.TypeChecker.__match_args__
+jsonschema._types.TypeChecker.__attrs_attrs__
+jsonschema._types.TypeChecker.__match_args__
+jsonschema.cli._Outputter.__attrs_attrs__
+jsonschema.cli._Outputter.__attrs_own_setattr__
+jsonschema.cli._Outputter.__match_args__
+jsonschema.cli._PlainFormatter.__attrs_attrs__
+jsonschema.cli._PlainFormatter.__attrs_own_setattr__
+jsonschema.cli._PlainFormatter.__match_args__
+jsonschema.cli._PrettyFormatter.__attrs_attrs__
+jsonschema.cli._PrettyFormatter.__attrs_own_setattr__
+jsonschema.cli._PrettyFormatter.__match_args__
+jsonschema.exceptions.RefResolutionError.__attrs_attrs__
+jsonschema.exceptions.RefResolutionError.__match_args__
+jsonschema.validators.Draft201909Validator.__attrs_attrs__
+jsonschema.validators.Draft201909Validator.__attrs_own_setattr__
+jsonschema.validators.Draft201909Validator.__attrs_post_init__
+jsonschema.validators.Draft201909Validator.__match_args__
+jsonschema.validators.Draft202012Validator.__attrs_attrs__
+jsonschema.validators.Draft202012Validator.__attrs_own_setattr__
+jsonschema.validators.Draft202012Validator.__attrs_post_init__
+jsonschema.validators.Draft202012Validator.__match_args__
+jsonschema.validators.Draft3Validator.__attrs_attrs__
+jsonschema.validators.Draft3Validator.__attrs_own_setattr__
+jsonschema.validators.Draft3Validator.__attrs_post_init__
+jsonschema.validators.Draft3Validator.__match_args__
+jsonschema.validators.Draft4Validator.__attrs_attrs__
+jsonschema.validators.Draft4Validator.__attrs_own_setattr__
+jsonschema.validators.Draft4Validator.__attrs_post_init__
+jsonschema.validators.Draft4Validator.__match_args__
+jsonschema.validators.Draft6Validator.__attrs_attrs__
+jsonschema.validators.Draft6Validator.__attrs_own_setattr__
+jsonschema.validators.Draft6Validator.__attrs_post_init__
+jsonschema.validators.Draft6Validator.__match_args__
+jsonschema.validators.Draft7Validator.__attrs_attrs__
+jsonschema.validators.Draft7Validator.__attrs_own_setattr__
+jsonschema.validators.Draft7Validator.__attrs_post_init__
+jsonschema.validators.Draft7Validator.__match_args__
+# >= Python 3.13
+jsonschema.Draft201909Validator.__replace__
+jsonschema.Draft202012Validator.__replace__
+jsonschema.Draft3Validator.__replace__
+jsonschema.Draft4Validator.__replace__
+jsonschema.Draft6Validator.__replace__
+jsonschema.Draft7Validator.__replace__
+jsonschema.RefResolutionError.__replace__
+jsonschema.TypeChecker.__replace__
+jsonschema._types.TypeChecker.__replace__
+jsonschema.cli._Outputter.__replace__
+jsonschema.cli._PlainFormatter.__replace__
+jsonschema.cli._PrettyFormatter.__replace__
+jsonschema.exceptions.RefResolutionError.__replace__
+jsonschema.validators.Draft201909Validator.__replace__
+jsonschema.validators.Draft202012Validator.__replace__
+jsonschema.validators.Draft3Validator.__replace__
+jsonschema.validators.Draft4Validator.__replace__
+jsonschema.validators.Draft6Validator.__replace__
+jsonschema.validators.Draft7Validator.__replace__

stubs/jsonschema/METADATA.toml

@@ -1,8 +1,6 @@
 version = "4.24.*"
 upstream_repository = "https://github.com/python-jsonschema/jsonschema"
 requires = ["referencing"]
-partial_stub = true
 
 [tool.stubtest]
-ignore_missing_stub = true
 extras = ["format"]

stubs/jsonschema/jsonschema/__init__.pyi

@@ -26,3 +26,17 @@ from jsonschema.validators import (
     RefResolver as RefResolver,
     validate as validate,
 )
+
+__all__ = [
+    "Draft3Validator",
+    "Draft4Validator",
+    "Draft6Validator",
+    "Draft7Validator",
+    "Draft201909Validator",
+    "Draft202012Validator",
+    "FormatChecker",
+    "SchemaError",
+    "TypeChecker",
+    "ValidationError",
+    "validate",
+]

stubs/jsonschema/jsonschema/_types.pyi

@@ -1,13 +1,15 @@
+from _typeshed import Unused
 from collections.abc import Callable, Iterable, Mapping
+from typing import Literal
 
-def is_array(checker, instance) -> bool: ...
-def is_bool(checker, instance) -> bool: ...
-def is_integer(checker, instance) -> bool: ...
-def is_null(checker, instance) -> bool: ...
-def is_number(checker, instance) -> bool: ...
-def is_object(checker, instance) -> bool: ...
-def is_string(checker, instance) -> bool: ...
-def is_any(checker, instance) -> bool: ...
+def is_array(checker: Unused, instance: object) -> bool: ...
+def is_bool(checker: Unused, instance: object) -> bool: ...
+def is_integer(checker: Unused, instance: object) -> bool: ...
+def is_null(checker: Unused, instance: object) -> bool: ...
+def is_number(checker: Unused, instance: object) -> bool: ...
+def is_object(checker: Unused, instance: object) -> bool: ...
+def is_string(checker: Unused, instance: object) -> bool: ...
+def is_any(checker: Unused, instance: Unused) -> Literal[True]: ...
 
 class TypeChecker:
     def __init__(self, type_checkers: Mapping[str, Callable[[object], bool]] = ...) -> None: ...

stubs/jsonschema/jsonschema/_utils.pyi

@@ -1,5 +1,8 @@
-from _typeshed import Incomplete, SupportsKeysAndGetItem, SupportsNext
-from collections.abc import Generator, Iterable, Iterator, Mapping, MutableMapping, Sized
+from _typeshed import Incomplete, SupportsKeysAndGetItem, SupportsNext, SupportsRichComparison
+from collections.abc import Generator, Iterable, Iterator, Mapping, MutableMapping
+from typing import Literal, TypeVar, overload
+
+_T = TypeVar("_T")
 
 class URIDict(MutableMapping[str, str]):
     def normalize(self, uri: str) -> str: ...
@@ -13,15 +16,16 @@ class URIDict(MutableMapping[str, str]):
 
 class Unset: ...
 
-def format_as_index(container: str, indices) -> str: ...
-def find_additional_properties(
-    instance: Iterable[Incomplete], schema: Mapping[Incomplete, Incomplete]
-) -> Generator[Incomplete, None, None]: ...
-def extras_msg(extras: Iterable[Incomplete] | Sized) -> str: ...
-def ensure_list(thing) -> list[Incomplete]: ...
+def format_as_index(container: str, indices: Iterable[Incomplete] | None) -> str: ...
+def find_additional_properties(instance: Iterable[str], schema: Mapping[str, Iterable[str]]) -> Generator[str]: ...
+def extras_msg(extras: Iterable[object]) -> tuple[str, Literal["was", "were"]]: ...  # elements are passed to the repr() function
+@overload
+def ensure_list(thing: str) -> list[str]: ...
+@overload
+def ensure_list(thing: _T) -> _T: ...
 def equal(one, two) -> bool: ...
 def unbool(element, true=..., false=...): ...
-def uniq(container) -> bool: ...
+def uniq(container: Iterable[SupportsRichComparison]) -> bool: ...
 def find_evaluated_item_indexes_by_schema(validator, instance, schema) -> list[Incomplete]: ...
 def find_evaluated_property_keys_by_schema(validator, instance, schema) -> list[Incomplete]: ...
 def is_valid(errs_it: SupportsNext[object]) -> bool: ...

stubs/jsonschema/jsonschema/cli.pyi

@@ -1,32 +1,53 @@
-from _typeshed import Incomplete
+import argparse
+from _typeshed import ExcInfo, FileDescriptorOrPath, Incomplete, OptExcInfo
+from collections.abc import Mapping, Sequence
+from typing import Any, TextIO
+from typing_extensions import Self, deprecated
 
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
 class _CannotLoadFile(Exception): ...
 
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
 class _Outputter:
-    def __init__(self, formatter, stdout, stderr): ...
+    _formatter: _PlainFormatter | _PrettyFormatter
+    _stdout: TextIO
+    _stderr: TextIO
+
+    def __init__(self, formatter: _PlainFormatter | _PrettyFormatter, stdout: TextIO, stderr: TextIO) -> None: ...
     @classmethod
-    def from_arguments(cls, arguments, stdout, stderr): ...
-    def load(self, path): ...
-    def filenotfound_error(self, **kwargs) -> None: ...
-    def parsing_error(self, **kwargs) -> None: ...
-    def validation_error(self, **kwargs) -> None: ...
-    def validation_success(self, **kwargs) -> None: ...
+    def from_arguments(cls, arguments: Mapping[str, Incomplete], stdout: TextIO, stderr: TextIO) -> Self: ...
+    def load(self, path: FileDescriptorOrPath) -> Any: ...  # result of json.load()
+    def filenotfound_error(self, *, path: FileDescriptorOrPath, exc_info: OptExcInfo) -> None: ...
+    def parsing_error(self, *, path: FileDescriptorOrPath, exc_info: ExcInfo) -> None: ...
+    def validation_error(self, *, instance_path: FileDescriptorOrPath, error: BaseException) -> None: ...
+    def validation_success(self, *, instance_path: FileDescriptorOrPath) -> None: ...
 
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
 class _PrettyFormatter:
-    def filenotfound_error(self, path, exc_info): ...
-    def parsing_error(self, path, exc_info): ...
-    def validation_error(self, instance_path, error): ...
-    def validation_success(self, instance_path): ...
+    _ERROR_MSG: str
+    _SUCCESS_MSG: str
+
+    def __init__(self) -> None: ...
+    def filenotfound_error(self, path: FileDescriptorOrPath, exc_info: OptExcInfo) -> str: ...
+    def parsing_error(self, path: FileDescriptorOrPath, exc_info: ExcInfo) -> str: ...
+    def validation_error(self, instance_path: FileDescriptorOrPath, error: BaseException) -> str: ...
+    def validation_success(self, instance_path: FileDescriptorOrPath) -> str: ...
 
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
 class _PlainFormatter:
-    def __init__(self, error_format): ...
-    def filenotfound_error(self, path, exc_info): ...
-    def parsing_error(self, path, exc_info): ...
-    def validation_error(self, instance_path, error): ...
-    def validation_success(self, instance_path): ...
+    _error_format: str
+
+    def __init__(self, error_format: str) -> None: ...
+    def filenotfound_error(self, path: FileDescriptorOrPath, exc_info: OptExcInfo) -> str: ...
+    def parsing_error(self, path: FileDescriptorOrPath, exc_info: ExcInfo) -> str: ...
+    def validation_error(self, instance_path: FileDescriptorOrPath, error: BaseException) -> str: ...
+    def validation_success(self, instance_path: FileDescriptorOrPath) -> str: ...
 
-parser: Incomplete
+parser: argparse.ArgumentParser
 
-def parse_args(args): ...
-def main(args=...) -> None: ...
-def run(arguments, stdout=..., stderr=..., stdin=...): ...
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
+def parse_args(args: Sequence[str] | None) -> dict[str, Any]: ...  # result of vars(argparse.Namespace())
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
+def main(args: Sequence[str] = ...) -> None: ...
+@deprecated("The jsonschema CLI is deprecated and will be removed in a future version. Please use check-jsonschema instead.")
+def run(arguments: Mapping[str, Incomplete], stdout: TextIO = ..., stderr: TextIO = ..., stdin: TextIO = ...) -> int: ...

stubs/jsonschema/jsonschema/validators.pyi

@@ -54,7 +54,7 @@ class _Validator:
     def iter_errors(self, instance, _schema: Schema | None) -> Generator[Incomplete]: ...
     def descend(
         self, instance, schema: Schema, path: Incomplete | None = ..., schema_path: Incomplete | None = ..., resolver=None
-    ) -> Generator[Incomplete, None, None]: ...
+    ) -> Generator[Incomplete]: ...
     def validate(self, *args, **kwargs) -> None: ...
     def is_type(self, instance, type) -> bool: ...
     @overload
@@ -63,7 +63,7 @@ class _Validator:
     @deprecated("Passing a schema to Validator.is_valid is deprecated and will be removed in a future release.")
     def is_valid(self, instance, _schema: Schema | None) -> bool: ...
 
-def validates(version: str) -> Callable[..., Incomplete]: ...
+def validates(version: str) -> Callable[[_Validator], _Validator]: ...
 def create(
     meta_schema: Schema,
     validators: Mapping[str, _ValidatorCallback] | tuple[()] = (),