Merge pull request #17 from OpenPaymentNetwork/main

Compatibility with both Pydantic 1 and 2

Author: mike-oakley

README.md

@@ -3,7 +3,7 @@
 [![PyPI](https://img.shields.io/pypi/v/openapi-pydantic)](https://pypi.org/project/openapi-pydantic/)
 [![PyPI - License](https://img.shields.io/pypi/l/openapi-pydantic)](https://github.com/mike-oakley/openapi-pydantic/blob/main/LICENSE)
 
-OpenAPI schema implemented in [Pydantic](https://github.com/samuelcolvin/pydantic).
+OpenAPI schema implemented in [Pydantic](https://github.com/samuelcolvin/pydantic). Both Pydantic 1.8+ and 2.x are supported.
 
 The naming of the classes follows the schema in 
 [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schema).
@@ -37,7 +37,8 @@ open_api = OpenAPI(
         )
     },
 )
-print(open_api.json(by_alias=True, exclude_none=True, indent=2))
+# Note: for Pydantic 1.x, replace `model_dump_json` with `json`
+print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))
 ```
 
 Result:
@@ -71,7 +72,7 @@ Result:
 
 ## Take advantage of Pydantic
 
-Pydantic is a great tool, allow you to use object / dict / mixed data for for input.
+Pydantic is a great tool. It allows you to use object / dict / mixed data for input.
 
 The following examples give the same OpenAPI result as above:
 
@@ -80,6 +81,7 @@ from openapi_pydantic import parse_obj, OpenAPI, PathItem, Response
 
 # Construct OpenAPI from dict, inferring the correct schema version
 open_api = parse_obj({
+    "openapi": "3.1.0",
     "info": {"title": "My own API", "version": "v0.0.1"},
     "paths": {
         "/ping": {
@@ -90,7 +92,8 @@ open_api = parse_obj({
 
 
 # Construct OpenAPI v3.1.0 schema from dict
-open_api = OpenAPI.parse_obj({
+# Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
+open_api = OpenAPI.model_validate({
     "info": {"title": "My own API", "version": "v0.0.1"},
     "paths": {
         "/ping": {
@@ -100,7 +103,8 @@ open_api = OpenAPI.parse_obj({
 })
 
 # Construct OpenAPI with mix of dict/object
-open_api = OpenAPI.parse_obj({
+# Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
+open_api = OpenAPI.model_validate({
     "info": {"title": "My own API", "version": "v0.0.1"},
     "paths": {
         "/ping": PathItem(
@@ -113,10 +117,10 @@ open_api = OpenAPI.parse_obj({
 ## Use Pydantic classes as schema
 
 - The [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject)
-  in OpenAPI has definitions and tweaks in JSON Schema, which is hard to comprehend and define a good data class
-- Pydantic already has a good way to [create JSON schema](https://pydantic-docs.helpmanual.io/usage/schema/),
-  let's not re-invent the wheel
-  
+  in OpenAPI has definitions and tweaks in JSON Schema, which are hard to comprehend and define a good data class
+- Pydantic already has a good way to [create JSON schema](https://pydantic-docs.helpmanual.io/usage/schema/).
+  Let's not reinvent the wheel.
+
 The approach to deal with this:
 
 1. Use `PydanticSchema` objects to represent the `Schema` in `OpenAPI` object
@@ -129,7 +133,8 @@ from openapi_pydantic import OpenAPI
 from openapi_pydantic.util import PydanticSchema, construct_open_api_with_schema_class
 
 def construct_base_open_api() -> OpenAPI:
-    return OpenAPI.parse_obj({
+    # Note: for Pydantic 1.x, replace `model_validate` with `parse_obj`
+    return OpenAPI.model_validate({
         "info": {"title": "My own API", "version": "v0.0.1"},
         "paths": {
             "/ping": {
@@ -162,7 +167,8 @@ open_api = construct_base_open_api()
 open_api = construct_open_api_with_schema_class(open_api)
 
 # print the result openapi.json
-print(open_api.json(by_alias=True, exclude_none=True, indent=2))
+# Note: for Pydantic 1.x, replace `model_dump_json` with `json`
+print(open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2))
 ```
 
 Result:
@@ -259,21 +265,24 @@ Result:
 
 ## Notes
 
-### Use of OpenAPI.json() / OpenAPI.dict()
+### Use of OpenAPI.model_dump() / OpenAPI.model_dump_json() / OpenAPI.json() / OpenAPI.dict()
 
-When using `OpenAPI.json()` / `OpenAPI.dict()` function,
-arguments `by_alias=True, exclude_none=True` has to be in place.
-Otherwise the result json will not fit the OpenAPI standard.
+When using `OpenAPI.model_dump()` / `OpenAPI.model_dump_json()` / `OpenAPI.json()` / `OpenAPI.dict()` functions,
+the arguments `by_alias=True, exclude_none=True` have to be in place.
+Otherwise the resulting json will not fit the OpenAPI standard.
 
 ```python
-# OK
+# OK (Pydantic 2)
+open_api.model_dump_json(by_alias=True, exclude_none=True, indent=2)
+# OK (Pydantic 1)
 open_api.json(by_alias=True, exclude_none=True, indent=2)
 
 # Not good
+open_api.model_dump_json(indent=2)
 open_api.json(indent=2)
 ```
 
-More info about field alias:
+More info about field aliases:
 
 | OpenAPI version | Field alias info |
 | --------------- | ---------------- |
@@ -293,13 +302,17 @@ Please refer to the following for more info:
 ### Use OpenAPI 3.0.3 instead of 3.1.0
 
 Some UI renderings (e.g. Swagger) still do not support OpenAPI 3.1.0.
-It is allowed to use the old 3.0.3 version by importing from different paths:
+The old 3.0.3 version is available by importing from different paths:
 
 ```python
 from openapi_pydantic.v3.v3_0_3 import OpenAPI, ...
 from openapi_pydantic.v3.v3_0_3.util import PydanticSchema, construct_open_api_with_schema_class
 ```
 
+### Pydantic version compatibility
+
+Compatibility with both major versions of Pydantic (1.8+ and 2.*) is mostly achieved using a module called `compat.py`. It detects the installed version of Pydantic and exports version-specific symbols for use by the rest of the package. It also provides all symbols necessary for type checking. The `compat.py` module is not intended to be imported by other packages, but other packages may find it helpful as an example of how to span major versions of Pydantic.
+
 ## Credits
 
 This library is based from the original implementation by Kuimono of [OpenAPI Schema Pydantic](https://github.com/kuimono/openapi-schema-pydantic) which is no longer actively maintained.

openapi_pydantic/__init__.py

@@ -33,5 +33,6 @@
 from .v3 import ServerVariable as ServerVariable
 from .v3 import Tag as Tag
 from .v3 import parse_obj as parse_obj
+from .v3 import schema_validate as schema_validate
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())

openapi_pydantic/compat.py

@@ -0,0 +1,118 @@
+"""Compatibility layer to make this package usable with Pydantic 1 or 2"""
+
+from typing import TYPE_CHECKING
+
+from pydantic.version import VERSION as PYDANTIC_VERSION
+
+__all__ = [
+    "PYDANTIC_V2",
+    "ConfigDict",
+    "JsonSchemaMode",
+    "models_json_schema",
+    "RootModel",
+    "Extra",
+    "v1_schema",
+    "DEFS_KEY",
+    "min_length_arg",
+]
+
+PYDANTIC_MAJOR_VERSION = int(PYDANTIC_VERSION.split(".", 1)[0])
+PYDANTIC_V2 = PYDANTIC_MAJOR_VERSION >= 2
+
+if TYPE_CHECKING:
+    # Provide stubs for either version of Pydantic
+
+    from enum import Enum
+    from typing import Any, Literal, Type, TypedDict
+
+    from pydantic import BaseModel
+    from pydantic import ConfigDict as PydanticConfigDict
+
+    def ConfigDict(
+        extra: Literal["allow", "ignore", "forbid"] = "allow",
+        json_schema_extra: dict[str, Any] | None = None,
+        populate_by_name: bool = True,
+    ) -> PydanticConfigDict:
+        """Stub for pydantic.ConfigDict in Pydantic 2"""
+        ...
+
+    class Extra(Enum):
+        """Stub for pydantic.Extra in Pydantic 1"""
+
+        allow = "allow"
+        ignore = "ignore"
+        forbid = "forbid"
+
+    class RootModel(BaseModel):
+        """Stub for pydantic.RootModel in Pydantic 2"""
+
+    JsonSchemaMode = Literal["validation", "serialization"]
+
+    def models_json_schema(
+        models: list[tuple[Type[BaseModel], JsonSchemaMode]],
+        *,
+        by_alias: bool = True,
+        ref_template: str = "#/$defs/{model}",
+        schema_generator: type | None = None,
+    ) -> tuple[dict, dict[str, Any]]:
+        """Stub for pydantic.json_schema.models_json_schema in Pydantic 2"""
+        ...
+
+    def v1_schema(
+        models: list[Type[BaseModel]],
+        *,
+        by_alias: bool = True,
+        ref_prefix: str = "#/$defs",
+    ) -> dict[str, Any]:
+        """Stub for pydantic.schema.schema in Pydantic 1"""
+        ...
+
+    DEFS_KEY = "$defs"
+
+    class MinLengthArg(TypedDict):
+        pass
+
+    def min_length_arg(min_length: int) -> MinLengthArg:
+        """Generate a min_length or min_items parameter for Field(...)"""
+        ...
+
+elif PYDANTIC_V2:
+    from typing import TypedDict
+
+    from pydantic import ConfigDict, RootModel
+    from pydantic.json_schema import JsonSchemaMode, models_json_schema
+
+    # Pydantic 2 renders JSON schemas using the keyword "$defs"
+    DEFS_KEY = "$defs"
+
+    class MinLengthArg(TypedDict):
+        min_length: int
+
+    def min_length_arg(min_length: int) -> MinLengthArg:
+        return {"min_length": min_length}
+
+    # Create V1 stubs. These should not be used when PYDANTIC_V2 is true.
+    Extra = None
+    v1_schema = None
+
+
+else:
+    from typing import TypedDict
+
+    from pydantic import Extra
+    from pydantic.schema import schema as v1_schema
+
+    # Pydantic 1 renders JSON schemas using the keyword "definitions"
+    DEFS_KEY = "definitions"
+
+    class MinLengthArg(TypedDict):
+        min_items: int
+
+    def min_length_arg(min_length: int) -> MinLengthArg:
+        return {"min_items": min_length}
+
+    # Create V2 stubs. These should not be used when PYDANTIC_V2 is false.
+    ConfigDict = None
+    models_json_schema = None
+    JsonSchemaMode = None
+    RootModel = None