pydantic-json-patch 0.6.0__tar.gz → 0.6.2__tar.gz

{pydantic_json_patch-0.6.0 → pydantic_json_patch-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydantic_json_patch
-Version: 0.6.0
+Version: 0.6.2
 Summary: Pydantic models for implementing JSON Patch.
 Author: Jonathan Sharpe
 Author-email: Jonathan Sharpe <mail@jonrshar.pe>
@@ -81,7 +81,7 @@ ReplaceOp[str](op='replace', path='/foo/bar', value='hello')
 
 Additionally, there are two compound types:
 
-- `Operation` is the union of all the operators; and
+- `Operation` is the union of all the operations; and
 - `JsonPatch` is a Pydantic `RootModel` representing a sequence of operations.
 
 `JsonPatch` can be used directly for validation:
@@ -152,6 +152,32 @@ and list the models along with the other schemas:
 
 [![Screenshot of Swagger UI schema list][swagger-schemas]][swagger-schemas]
 
+### Value type validation
+
+You can also use a more specific type to apply type validation to the value properties:
+
+```python
+import typing as tp
+from uuid import UUID
+
+from fastapi import Body, FastAPI
+from pydantic import Discriminator
+
+from pydantic_json_patch import AddOp, TestOp
+
+app = FastAPI()
+
+
+@app.patch("/resource/{resource_id}")
+def _(
+    resource_id: UUID,
+    operations: tp.Annotated[list[tp.Annotated[AddOp[int] | TestOp[int], Discriminator("op")]], Body()],
+) -> ...:
+    ...
+```
+
+**Note**: explicitly specifying the [discriminator][pydantic-discriminator] gives better results on _failed_ validation for unions of operations.
+
 ## Development
 
 This project uses [uv] for managing dependencies.
@@ -198,6 +224,7 @@ This will auto-restart as you make changes.
   [json patch]: https://datatracker.ietf.org/doc/html/rfc6902/
   [json pointer]: https://datatracker.ietf.org/doc/html/rfc6901/
   [pydantic]: https://docs.pydantic.dev/latest/
+  [pydantic-discriminator]: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions-with-str-discriminators
   [pypi]: https://pypi.org/
   [pypi-badge]: https://img.shields.io/pypi/v/pydantic-json-patch?logo=python&logoColor=white&label=PyPI
   [pypi-page]: https://pypi.org/project/pydantic-json-patch/

{pydantic_json_patch-0.6.0 → pydantic_json_patch-0.6.2}/README.md

@@ -49,7 +49,7 @@ ReplaceOp[str](op='replace', path='/foo/bar', value='hello')
 
 Additionally, there are two compound types:
 
-- `Operation` is the union of all the operators; and
+- `Operation` is the union of all the operations; and
 - `JsonPatch` is a Pydantic `RootModel` representing a sequence of operations.
 
 `JsonPatch` can be used directly for validation:
@@ -120,6 +120,32 @@ and list the models along with the other schemas:
 
 [![Screenshot of Swagger UI schema list][swagger-schemas]][swagger-schemas]
 
+### Value type validation
+
+You can also use a more specific type to apply type validation to the value properties:
+
+```python
+import typing as tp
+from uuid import UUID
+
+from fastapi import Body, FastAPI
+from pydantic import Discriminator
+
+from pydantic_json_patch import AddOp, TestOp
+
+app = FastAPI()
+
+
+@app.patch("/resource/{resource_id}")
+def _(
+    resource_id: UUID,
+    operations: tp.Annotated[list[tp.Annotated[AddOp[int] | TestOp[int], Discriminator("op")]], Body()],
+) -> ...:
+    ...
+```
+
+**Note**: explicitly specifying the [discriminator][pydantic-discriminator] gives better results on _failed_ validation for unions of operations.
+
 ## Development
 
 This project uses [uv] for managing dependencies.
@@ -166,6 +192,7 @@ This will auto-restart as you make changes.
   [json patch]: https://datatracker.ietf.org/doc/html/rfc6902/
   [json pointer]: https://datatracker.ietf.org/doc/html/rfc6901/
   [pydantic]: https://docs.pydantic.dev/latest/
+  [pydantic-discriminator]: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions-with-str-discriminators
   [pypi]: https://pypi.org/
   [pypi-badge]: https://img.shields.io/pypi/v/pydantic-json-patch?logo=python&logoColor=white&label=PyPI
   [pypi-page]: https://pypi.org/project/pydantic-json-patch/

{pydantic_json_patch-0.6.0 → pydantic_json_patch-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic_json_patch"
-version = "0.6.0"
+version = "0.6.2"
 description = "Pydantic models for implementing JSON Patch."
 readme = "README.md"
 authors = [
@@ -72,3 +72,25 @@ profile = "black"
 [tool.pytest.ini_options]
 addopts = "--doctest-glob=*.md"  # validate README examples
 python_classes = []  # avoid trying to run TestOp as a test
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "D203",
+    "D213",
+    "D105",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "ANN201",
+    "ANN401",
+    "C408",
+    "D",
+    "PLR2004",
+    "S101",
+]
+"bin/**/*.py" = [
+    "D",
+]

{pydantic_json_patch-0.6.0 → pydantic_json_patch-0.6.2}/src/pydantic_json_patch/__init__.py

@@ -1,3 +1,9 @@
+"""Pydantic models for implementing `JSON Patch`_.
+
+.. _JSON Patch: https://datatracker.ietf.org/doc/html/rfc6902/
+
+"""
+
 from importlib.metadata import version
 
 from .models import (
@@ -14,7 +20,6 @@ from .models import (
 __version__ = version(__name__)
 
 __all__ = [
-    "__version__",
     "AddOp",
     "CopyOp",
     "JsonPatch",
@@ -23,4 +28,5 @@ __all__ = [
     "RemoveOp",
     "ReplaceOp",
     "TestOp",
+    "__version__",
 ]

{pydantic_json_patch-0.6.0 → pydantic_json_patch-0.6.2}/src/pydantic_json_patch/models.py

@@ -1,6 +1,8 @@
+"""Core models and private implementation."""
+
 import re
 import typing as tp
-from collections.abc import Sequence
+from collections.abc import Iterator, Sequence
 from functools import cached_property, lru_cache
 
 import typing_extensions as tx
@@ -21,14 +23,21 @@ T = tx.TypeVar("T", default=tp.Any)
 # region base models
 
 
+def _generate_title(model: type[tp.Any]) -> str:
+    """Strip any type metadata and expand the shortened name."""
+    name, *_ = model.__name__.partition("[")
+    return f"JsonPatch{name}eration"
+
+
 class _BaseOp(BaseModel):
     model_config = ConfigDict(
         frozen=True,
-        model_title_generator=lambda t: f"JsonPatch{t.__name__}eration",
+        model_title_generator=_generate_title,
     )
 
     @classmethod
-    def create(cls, *, path: str | Sequence[str], **kwargs) -> tx.Self:
+    def create(cls, *, path: str | Sequence[str], **kwargs: tp.Any) -> tx.Self:  # noqa: ANN401
+        """Return an instance of the appropriate operation."""
         (op,) = tp.get_args(cls.model_fields["op"].annotation)
         return cls(op=op, path=cls._dump_pointer(path), **kwargs)
 
@@ -68,8 +77,12 @@ class _BaseOp(BaseModel):
 class _FromOp(_BaseOp):
     @classmethod
     def create(
-        cls, *, path: str | Sequence[str], from_: str | Sequence[str]
+        cls,
+        *,
+        path: str | Sequence[str],
+        from_: str | Sequence[str],
     ) -> tx.Self:  # ty: ignore[invalid-method-override] -- deliberately narrows **kwargs to named params
+        """Return an instance of the appropriate operation."""
         pointer = from_ if isinstance(from_, str) else cls._dump_pointer(from_)
         return super().create(path=path, **{"from": pointer})
 
@@ -78,7 +91,7 @@ class _FromOp(_BaseOp):
 
     @model_validator(mode="before")
     @classmethod
-    def _pre_validate(cls, data: tp.Any, info: ValidationInfo) -> tp.Any:
+    def _pre_validate(cls, data: tp.Any, info: ValidationInfo) -> tp.Any:  # noqa: ANN401
         if (
             info.mode != "json"  # pragma: no mutate
             and isinstance(data, dict)
@@ -97,6 +110,7 @@ class _FromOp(_BaseOp):
 class _ValueOp(_BaseOp, tp.Generic[T]):
     @classmethod
     def create(cls, *, path: str | Sequence[str], value: T) -> tx.Self:  # ty: ignore[invalid-method-override] -- deliberately narrows **kwargs to named params
+        """Return an instance of the appropriate operation."""
         return super().create(path=path, value=value)
 
     value: T = Field(examples=[42])
@@ -109,30 +123,67 @@ class _ValueOp(_BaseOp, tp.Generic[T]):
 
 
 class AddOp(_ValueOp[T], tp.Generic[T]):
+    """Represents the `add`_ operation.
+
+    .. _add: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.1
+
+    """
+
     op: tp.Literal["add"]
 
 
 class CopyOp(_FromOp):
+    """Represents the `copy`_ operation.
+
+    .. _copy: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.5
+
+    """
+
     op: tp.Literal["copy"]
 
 
 class MoveOp(_FromOp):
+    """Represents the `move`_ operation.
+
+    .. _move: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.4
+
+    """
+
     op: tp.Literal["move"]
 
 
 class RemoveOp(_BaseOp):
+    """Represents the `remove`_ operation.
+
+    .. _remove: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.2
+
+    """
+
     @classmethod
     def create(cls, *, path: str | Sequence[str]) -> tx.Self:  # ty: ignore[invalid-method-override] -- deliberately narrows **kwargs to named params
+        """Return an instance of the appropriate operation."""
         return super().create(path=path)
 
     op: tp.Literal["remove"]
 
 
 class ReplaceOp(_ValueOp[T], tp.Generic[T]):
+    """Represents the `replace`_ operation.
+
+    .. _replace: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.3
+
+    """
+
     op: tp.Literal["replace"]
 
 
 class TestOp(_ValueOp[T], tp.Generic[T]):
+    """Represents the `test`_ operation.
+
+    .. _test: https://datatracker.ietf.org/doc/html/rfc6902/#section-4.6
+
+    """
+
     op: tp.Literal["test"]
 
 
@@ -141,16 +192,23 @@ class TestOp(_ValueOp[T], tp.Generic[T]):
 # region compound models
 
 Operation: tp.TypeAlias = tp.Annotated[
-    tp.Union[AddOp, CopyOp, MoveOp, RemoveOp, ReplaceOp, TestOp], Discriminator("op")
+    AddOp | CopyOp | MoveOp | RemoveOp | ReplaceOp | TestOp,
+    Discriminator("op"),
 ]
 
 
 class JsonPatch(RootModel[Sequence[Operation]], Sequence[Operation]):
+    """Represents a full JSON Patch `document`_.
+
+    .. _document: https://datatracker.ietf.org/doc/html/rfc6902/#section-3
+
+    """
+
     model_config = ConfigDict(frozen=True)
 
     @model_validator(mode="before")
     @classmethod
-    def _coerce_to_tuple(cls, value: tp.Any) -> tuple[tp.Any, ...]:
+    def _coerce_to_tuple(cls, value: tp.Any) -> tuple[tp.Any, ...]:  # noqa: ANN401
         if isinstance(value, Sequence) and not isinstance(value, tuple):
             return tuple(value)
         return value
@@ -164,7 +222,7 @@ class JsonPatch(RootModel[Sequence[Operation]], Sequence[Operation]):
     def __getitem__(self, index):
         return self.root[index]
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Operation]:  # ty: ignore[invalid-method-override] -- dict(model) doesn't make sense for a sequence of non-pairs
         return iter(self.root)
 
     def __len__(self) -> int: