run stubtest on _pydantic_core.pyi (#702)

Author: davidhewitt

.github/workflows/ci.yml

@@ -172,7 +172,7 @@ jobs:
 
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       # used to lint js code
       - uses: actions/setup-node@v3

.mypy-stubtest-allowlist

@@ -0,0 +1,4 @@
+# TODO: __init__ signature inherited from BaseException, probably needs investigating
+pydantic_core._pydantic_core.PydanticOmit.__init__
+# TODO: don't want to expose this staticmethod, requires https://github.com/PyO3/pyo3/issues/2384
+pydantic_core._pydantic_core.PydanticUndefinedType.new

Makefile

@@ -1,6 +1,7 @@
 .DEFAULT_GOAL := all
 black = black python/pydantic_core tests generate_self_schema.py wasm-preview/run_tests.py
 ruff = ruff python/pydantic_core tests generate_self_schema.py wasm-preview/run_tests.py
+mypy-stubtest = python -m mypy.stubtest pydantic_core._pydantic_core --allowlist .mypy-stubtest-allowlist
 
 .PHONY: install
 install:
@@ -46,6 +47,7 @@ format:
 lint-python:
 	$(ruff)
 	$(black) --check --diff
+	$(mypy-stubtest)
 	griffe dump -f -d google -LWARNING -o/dev/null python/pydantic_core
 
 .PHONY: lint-rust

python/pydantic_core/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import sys as _sys
 from typing import Any as _Any
 
@@ -21,7 +23,7 @@
     to_json,
     to_jsonable_python,
 )
-from .core_schema import CoreConfig, CoreSchema, CoreSchemaType
+from .core_schema import CoreConfig, CoreSchema, CoreSchemaType, ErrorType
 
 if _sys.version_info < (3, 11):
     from typing_extensions import NotRequired as _NotRequired
@@ -33,7 +35,7 @@
 else:
     from typing import TypedDict as _TypedDict
 
-__all__ = (
+__all__ = [
     '__version__',
     'CoreConfig',
     'CoreSchema',
@@ -57,19 +59,35 @@
     'PydanticSerializationUnexpectedValue',
     'to_json',
     'to_jsonable_python',
-)
+]
 
 
 class ErrorDetails(_TypedDict):
     type: str
-    loc: 'tuple[int | str, ...]'
+    loc: tuple[int | str, ...]
     msg: str
     input: _Any
-    ctx: _NotRequired['dict[str, str | int | float]']
+    ctx: _NotRequired[dict[str, str | int | float]]
 
 
 class InitErrorDetails(_TypedDict):
-    type: 'str | PydanticCustomError'
-    loc: _NotRequired['tuple[int | str, ...]']
+    type: str | PydanticCustomError
+    loc: _NotRequired[tuple[int | str, ...]]
     input: _Any
-    ctx: _NotRequired['dict[str, str | int | float]']
+    ctx: _NotRequired[dict[str, str | int | float]]
+
+
+class ErrorTypeInfo(_TypedDict):
+    type: ErrorType
+    message_template_python: str
+    example_message_python: str
+    message_template_json: _NotRequired[str]
+    example_message_json: _NotRequired[str]
+    example_context: dict[str, str | int | float] | None
+
+
+class MultiHostHost(_TypedDict):
+    username: str | None
+    password: str | None
+    host: str | None
+    port: int | None

python/pydantic_core/_pydantic_core.pyi

@@ -1,25 +1,26 @@
 import decimal
 import sys
-from typing import Any, Callable, Generic, TypeVar
+from typing import Any, Callable, Generic, Type, TypeVar
 
-from pydantic_core import ErrorDetails, InitErrorDetails
+from pydantic_core import ErrorDetails, ErrorTypeInfo, InitErrorDetails, MultiHostHost
 from pydantic_core.core_schema import CoreConfig, CoreSchema, ErrorType
 
-if sys.version_info < (3, 9):
-    from typing_extensions import TypedDict
+if sys.version_info < (3, 8):
+    from typing_extensions import final
 else:
-    from typing import TypedDict
+    from typing import final
 
 if sys.version_info < (3, 11):
-    from typing_extensions import Literal, LiteralString, NotRequired, TypeAlias
+    from typing_extensions import Literal, LiteralString, Self, TypeAlias
 else:
-    from typing import Literal, LiteralString, NotRequired, TypeAlias
+    from typing import Literal, LiteralString, Self, TypeAlias
 
 from _typeshed import SupportsAllComparisons
 
-__all__ = (
+__all__ = [
     '__version__',
     'build_profile',
+    'ArgsKwargs',
     'SchemaValidator',
     'SchemaSerializer',
     'Url',
@@ -30,19 +31,29 @@ __all__ = (
     'PydanticKnownError',
     'PydanticOmit',
     'PydanticSerializationError',
+    'PydanticSerializationUnexpectedValue',
+    'PydanticUndefined',
+    'PydanticUndefinedType',
+    'Some',
+    'to_json',
+    'to_jsonable_python',
     'list_all_errors',
-)
+]
 __version__: str
 build_profile: str
 
-T = TypeVar('T', default=Any, covariant=True)
+_T = TypeVar('_T', default=Any, covariant=True)
 
-class Some(Generic[T]):
+@final
+class Some(Generic[_T]):
     __match_args__ = ('value',)
 
     @property
-    def value(self) -> T: ...
+    def value(self) -> _T: ...
+    @classmethod
+    def __class_getitem__(cls, item: Any) -> Type[Self]: ...
 
+@final
 class SchemaValidator:
     def __init__(self, schema: CoreSchema, config: 'CoreConfig | None' = None) -> None: ...
     @property
@@ -85,17 +96,18 @@ class SchemaValidator:
     ) -> 'dict[str, Any]': ...
     def get_default_value(self, *, strict: 'bool | None' = None, context: Any = None) -> Some | None: ...
 
-IncEx: TypeAlias = 'set[int] | set[str] | dict[int, IncEx] | dict[str, IncEx] | None'
+_IncEx: TypeAlias = 'set[int] | set[str] | dict[int, _IncEx] | dict[str, _IncEx] | None'
 
+@final
 class SchemaSerializer:
     def __init__(self, schema: CoreSchema, config: 'CoreConfig | None' = None) -> None: ...
     def to_python(
         self,
         value: Any,
         *,
         mode: str | None = None,
-        include: IncEx = None,
-        exclude: IncEx = None,
+        include: _IncEx = None,
+        exclude: _IncEx = None,
         by_alias: bool = True,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -109,8 +121,8 @@ class SchemaSerializer:
         value: Any,
         *,
         indent: int | None = None,
-        include: IncEx = None,
-        exclude: IncEx = None,
+        include: _IncEx = None,
+        exclude: _IncEx = None,
         by_alias: bool = True,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -124,8 +136,8 @@ def to_json(
     value: Any,
     *,
     indent: int | None = None,
-    include: IncEx = None,
-    exclude: IncEx = None,
+    include: _IncEx = None,
+    exclude: _IncEx = None,
     by_alias: bool = True,
     exclude_none: bool = False,
     round_trip: bool = False,
@@ -137,8 +149,8 @@ def to_json(
 def to_jsonable_python(
     value: Any,
     *,
-    include: IncEx = None,
-    exclude: IncEx = None,
+    include: _IncEx = None,
+    exclude: _IncEx = None,
     by_alias: bool = True,
     exclude_none: bool = False,
     round_trip: bool = False,
@@ -171,12 +183,7 @@ class Url(SupportsAllComparisons):
     def unicode_string(self) -> str: ...
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
-
-class MultiHostHost(TypedDict):
-    username: 'str | None'
-    password: 'str | None'
-    host: 'str | None'
-    port: 'int | None'
+    def __deepcopy__(self, memo: dict) -> str: ...
 
 class MultiHostUrl(SupportsAllComparisons):
     def __init__(self, url: str) -> None: ...
@@ -193,16 +200,19 @@ class MultiHostUrl(SupportsAllComparisons):
     def unicode_string(self) -> str: ...
     def __repr__(self) -> str: ...
     def __str__(self) -> str: ...
+    def __deepcopy__(self, memo: dict) -> Self: ...
 
+@final
 class SchemaError(Exception):
     def error_count(self) -> int: ...
     def errors(self) -> 'list[ErrorDetails]': ...
 
+@final
 class ValidationError(ValueError):
     @staticmethod
     def from_exception_data(
         title: str,
-        errors: 'list[InitErrorDetails]',
+        line_errors: 'list[InitErrorDetails]',
         error_mode: Literal['python', 'json'] = 'python',
         hide_input: bool = False,
     ) -> ValidationError:
@@ -218,6 +228,7 @@ class ValidationError(ValueError):
     def errors(self, *, include_url: bool = True, include_context: bool = True) -> 'list[ErrorDetails]': ...
     def json(self, *, indent: 'int | None' = None, include_url: bool = True, include_context: bool = True) -> str: ...
 
+@final
 class PydanticCustomError(ValueError):
     def __init__(
         self, error_type: LiteralString, message_template: LiteralString, context: 'dict[str, Any] | None' = None
@@ -230,6 +241,7 @@ class PydanticCustomError(ValueError):
     def message_template(self) -> str: ...
     def message(self) -> str: ...
 
+@final
 class PydanticKnownError(ValueError):
     def __init__(
         self, error_type: ErrorType, context: 'dict[str, str | int | float | decimal.Decimal] | None' = None
@@ -242,31 +254,30 @@ class PydanticKnownError(ValueError):
     def message_template(self) -> str: ...
     def message(self) -> str: ...
 
+@final
 class PydanticOmit(Exception):
     def __init__(self) -> None: ...
 
+@final
 class PydanticSerializationError(ValueError):
     def __init__(self, message: str) -> None: ...
 
+@final
 class PydanticSerializationUnexpectedValue(ValueError):
     def __init__(self, message: 'str | None' = None) -> None: ...
 
-class ErrorTypeInfo(TypedDict):
-    type: ErrorType
-    message_template_python: str
-    example_message_python: str
-    message_template_json: NotRequired[str]
-    example_message_json: NotRequired[str]
-    example_context: 'dict[str, str | int | float] | None'
-
+@final
 class ArgsKwargs:
     def __init__(self, args: 'tuple[Any, ...]', kwargs: 'dict[str, Any] | None' = None) -> None: ...
     @property
     def args(self) -> 'tuple[Any, ...]': ...
     @property
     def kwargs(self) -> 'dict[str, Any] | None': ...
 
-class PydanticUndefinedType: ...
+@final
+class PydanticUndefinedType:
+    def __copy__(self) -> Self: ...
+    def __deepcopy__(self, memo: Any) -> Self: ...
 
 PydanticUndefined: PydanticUndefinedType
 

python/pydantic_core/core_schema.py

@@ -3,7 +3,7 @@
 import sys
 from collections.abc import Mapping
 from datetime import date, datetime, time, timedelta
-from typing import Any, Callable, Dict, Hashable, List, Optional, Set, Type, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, Hashable, List, Optional, Set, Type, Union
 
 if sys.version_info < (3, 11):
     from typing_extensions import Protocol, Required, TypeAlias
@@ -15,10 +15,16 @@
 else:
     from typing import Literal, TypedDict
 
-try:
+if TYPE_CHECKING:
     from pydantic_core import PydanticUndefined
-except ImportError:
-    PydanticUndefined = object()
+else:
+    # The initial build of pydantic_core requires PydanticUndefined to generate
+    # the core schema; so we need to conditionally skip it. mypy doesn't like
+    # this at all, hence the TYPE_CHECKING branch above.
+    try:
+        from pydantic_core import PydanticUndefined
+    except ImportError:
+        PydanticUndefined = object()
 
 
 def dict_not_none(**kwargs: Any) -> Any:

src/argument_markers.rs

@@ -93,6 +93,7 @@ impl PydanticUndefinedType {
         UNDEFINED_CELL.get(py).unwrap().clone()
     }
 
+    #[pyo3(signature = (_memo, /))]
     fn __deepcopy__(&self, py: Python, _memo: &PyAny) -> Py<Self> {
         self.__copy__(py)
     }

src/url.rs

@@ -142,6 +142,7 @@ impl PyUrl {
         true // an empty string is not a valid URL
     }
 
+    #[pyo3(signature = (_memo, /))]
     pub fn __deepcopy__(&self, py: Python, _memo: &PyDict) -> Py<PyAny> {
         self.clone().into_py(py)
     }

src/validators/mod.rs

@@ -82,7 +82,8 @@ impl PySome {
     }
 
     #[classmethod]
-    pub fn __class_getitem__(cls: &PyType, _args: &PyAny) -> Py<PyType> {
+    #[pyo3(signature = (_item, /))]
+    pub fn __class_getitem__(cls: &PyType, _item: &PyAny) -> Py<PyType> {
         cls.into_py(cls.py())
     }
 

tests/requirements-linting.txt

@@ -2,3 +2,4 @@ black==23.3.0
 griffe==0.27.3
 pyright==1.1.296
 ruff==0.0.264
+mypy==1.4.1