Properly rebuild Pydantic models if necessary (openapi-generators#1176)

This is the alternative approach I mentioned in
openapi-generators#1171 (comment).

Instead of trying to rebuild the models in their respective modules
(which requires weird patterns, such as unused imports or importing
after the model is defined), we set `defer_build` to `True` for every
model where we know a forward reference will fail to resolve (so that we
don't try to build a model if we know it will fail).

I added comments each time to justify the use of `defer_build`, but
unfortunately this isn't always straightforward (e.g. sometimes you
makes use of a model as annotation which itself has `defer_build` set;
in this case we also want to defer build. Another case is when making
use of the `Callback` type alias; it isn't directly visible but it uses
an unresolvable forward reference).

Ultimately, in the module's `__init__.py`, we call `model_rebuild` on
all the necessary models. I know this isn't ideal as well, as you need
to manually check for every exported model here if the build was
successful.

This library is a clear example that inter-dependent types across
different modules is challenging, and Pydantic does not make it easy. We
are trying to think about ways to simplify the process.

Note that on top of fixing things for Pydantic 2.10, this also ensures
every model is successfully built when the `openapi_schema_pydantic`
module is imported. Currently on `main` (with Pydantic 2.9.2), some
models such as `Components` are not built. While this can still work in
some cases, it is advised not to do so (when `Components` is going to be
instantiated, Pydantic will implicitly try to rebuild it if it wasn't
already. However, we use the namespace where the instantiation call
happened to rebuilt it, so depending on _where_ you first instantiate
the model, this can lead to a failed model rebuild and thus a runtime
exception).

---

A note on `model_rebuild`: you can either provide an explicit namespace:

```python
PathItem.model_rebuild(_types_namespace={Operation: "Operation", "Header": Header})
```

Or let `model_rebuild` use the namespace where it was called (in our
case, all the imports are available, so it works).

---------

Co-authored-by: Dylan Anthony <dbanty@users.noreply.github.com>
Co-authored-by: Dylan Anthony <43723790+dbanty@users.noreply.github.com>

Author: Viicos

.changeset/properly_rebuild_pydantic_models_if_necessary.md

@@ -0,0 +1,10 @@
+---
+default: patch
+---
+
+# Fix compatibility with Pydantic 2.10+
+
+#1176 by @Viicos
+
+Set `defer_build` to models that we know will fail to build, and call `model_rebuild`
+in the `__init__.py` file.

openapi_python_client/schema/openapi_schema_pydantic/__init__.py

@@ -70,3 +70,14 @@
 from .server_variable import ServerVariable
 from .tag import Tag
 from .xml import XML
+
+PathItem.model_rebuild()
+Operation.model_rebuild()
+Components.model_rebuild()
+Encoding.model_rebuild()
+MediaType.model_rebuild()
+OpenAPI.model_rebuild()
+Parameter.model_rebuild()
+Header.model_rebuild()
+RequestBody.model_rebuild()
+Response.model_rebuild()

openapi_python_client/schema/openapi_schema_pydantic/components.py

@@ -35,6 +35,8 @@ class Components(BaseModel):
     links: Optional[dict[str, Union[Link, Reference]]] = None
     callbacks: Optional[dict[str, Union[Callback, Reference]]] = None
     model_config = ConfigDict(
+        # `Callback` contains an unresolvable forward reference, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         json_schema_extra={
             "examples": [

openapi_python_client/schema/openapi_schema_pydantic/encoding.py

@@ -6,8 +6,6 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     from .header import Header
-else:
-    Header = "Header"
 
 
 class Encoding(BaseModel):
@@ -19,11 +17,13 @@ class Encoding(BaseModel):
     """
 
     contentType: Optional[str] = None
-    headers: Optional[dict[str, Union[Header, Reference]]] = None
+    headers: Optional[dict[str, Union["Header", Reference]]] = None
     style: Optional[str] = None
     explode: bool = False
     allowReserved: bool = False
     model_config = ConfigDict(
+        # `Header` is an unresolvable forward reference, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         json_schema_extra={
             "examples": [

openapi_python_client/schema/openapi_schema_pydantic/header.py

@@ -21,6 +21,8 @@ class Header(Parameter):
     name: str = Field(default="")
     param_in: ParameterLocation = Field(default=ParameterLocation.HEADER, alias="in")
     model_config = ConfigDict(
+        # `Parameter` is not build yet, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         populate_by_name=True,
         json_schema_extra={

openapi_python_client/schema/openapi_schema_pydantic/media_type.py

@@ -21,6 +21,8 @@ class MediaType(BaseModel):
     examples: Optional[dict[str, Union[Example, Reference]]] = None
     encoding: Optional[dict[str, Encoding]] = None
     model_config = ConfigDict(
+        # `Encoding` is not build yet, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         populate_by_name=True,
         json_schema_extra={

openapi_python_client/schema/openapi_schema_pydantic/open_api.py

@@ -5,9 +5,6 @@
 from .components import Components
 from .external_documentation import ExternalDocumentation
 from .info import Info
-
-# Required to update forward ref after object creation
-from .path_item import PathItem  # noqa: F401
 from .paths import Paths
 from .security_requirement import SecurityRequirement
 from .server import Server
@@ -32,7 +29,11 @@ class OpenAPI(BaseModel):
     tags: Optional[list[Tag]] = None
     externalDocs: Optional[ExternalDocumentation] = None
     openapi: str
-    model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(
+        # `Components` is not build yet, will rebuild in `__init__.py`:
+        defer_build=True,
+        extra="allow",
+    )
 
     @field_validator("openapi")
     @classmethod
@@ -46,6 +47,3 @@ def check_openapi_version(cls, value: str) -> str:
         if int(parts[1]) > 1:
             raise ValueError(f"Only OpenAPI versions 3.1.* are supported, got {value}")
         return value
-
-
-OpenAPI.model_rebuild()

openapi_python_client/schema/openapi_schema_pydantic/operation.py

@@ -4,11 +4,7 @@
 
 from .callback import Callback
 from .external_documentation import ExternalDocumentation
-from .header import Header  # noqa: F401
 from .parameter import Parameter
-
-# Required to update forward ref after object creation, as this is not imported yet
-from .path_item import PathItem  # noqa: F401
 from .reference import Reference
 from .request_body import RequestBody
 from .responses import Responses
@@ -38,6 +34,8 @@ class Operation(BaseModel):
     security: Optional[list[SecurityRequirement]] = None
     servers: Optional[list[Server]] = None
     model_config = ConfigDict(
+        # `Callback` contains an unresolvable forward reference, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         json_schema_extra={
             "examples": [
@@ -89,7 +87,3 @@ class Operation(BaseModel):
             ]
         },
     )
-
-
-# PathItem in Callback uses Operation, so we need to update forward refs due to circular dependency
-Operation.model_rebuild()

openapi_python_client/schema/openapi_schema_pydantic/parameter.py

@@ -35,6 +35,8 @@ class Parameter(BaseModel):
     examples: Optional[dict[str, Union[Example, Reference]]] = None
     content: Optional[dict[str, MediaType]] = None
     model_config = ConfigDict(
+        # `MediaType` is not build yet, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         populate_by_name=True,
         json_schema_extra={

openapi_python_client/schema/openapi_schema_pydantic/path_item.py

@@ -1,11 +1,14 @@
-from typing import Optional, Union
+from typing import TYPE_CHECKING, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
 from .parameter import Parameter
 from .reference import Reference
 from .server import Server
 
+if TYPE_CHECKING:
+    from .operation import Operation  # pragma: no cover
+
 
 class PathItem(BaseModel):
     """
@@ -33,6 +36,8 @@ class PathItem(BaseModel):
     servers: Optional[list[Server]] = None
     parameters: Optional[list[Union[Parameter, Reference]]] = None
     model_config = ConfigDict(
+        # `Operation` is an unresolvable forward reference, will rebuild in `__init__.py`:
+        defer_build=True,
         extra="allow",
         populate_by_name=True,
         json_schema_extra={
@@ -69,9 +74,3 @@ class PathItem(BaseModel):
             ]
         },
     )
-
-
-# Operation uses PathItem via Callback, so we need late import and to update forward refs due to circular dependency
-from .operation import Operation  # noqa: E402
-
-PathItem.model_rebuild()