pydantic-json-patch 0.1.0__py3-none-any.whl

pydantic_json_patch/__init__.py

@@ -0,0 +1,27 @@
+import typing as tp
+from importlib.metadata import version
+
+from pydantic import Discriminator
+
+from .models import AddOp, CopyOp, MoveOp, Op, RemoveOp, ReplaceOp, TestOp, Tokens
+
+__version__ = version(__name__)
+
+Operation: tp.TypeAlias = tp.Annotated[
+    tp.Union[AddOp, CopyOp, MoveOp, RemoveOp, ReplaceOp, TestOp], Discriminator("op")
+]
+JsonPatch: tp.TypeAlias = list[Operation]
+
+__all__ = [
+    "__version__",
+    "AddOp",
+    "CopyOp",
+    "JsonPatch",
+    "MoveOp",
+    "Op",
+    "Operation",
+    "RemoveOp",
+    "ReplaceOp",
+    "TestOp",
+    "Tokens",
+]

pydantic_json_patch/models.py

@@ -0,0 +1,123 @@
+import re
+import typing as tp
+from functools import cached_property
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, model_validator
+import typing_extensions as tx
+
+_JSON_POINTER = re.compile(r"^(?:/(?:[^/~]|~[01])+)*$")
+
+T = tp.TypeVar("T")
+Op: tp.TypeAlias = tp.Literal["add", "copy", "move", "remove", "replace", "test"]
+Tokens: tp.TypeAlias = tuple[str, ...]
+
+# region base models
+
+
+class _BaseOp(BaseModel):
+    model_config = ConfigDict(
+        frozen=True,
+        model_title_generator=lambda t: f"JsonPatch{t.__name__}eration",
+    )
+
+    @classmethod
+    def create(cls, *, path: str | Tokens, **kwargs) -> tx.Self:
+        (op,) = tp.get_args(cls.model_fields["op"].annotation)
+        pointer = path if isinstance(path, str) else cls._dump_pointer(path)
+        return cls(op=op, path=pointer, **kwargs)
+
+    op: Op
+    """The operation being represented."""
+
+    path: str = Field(examples=["/a/b/c"], pattern=_JSON_POINTER)
+    """A JSON pointer representing the path to apply the operation to."""
+
+    @cached_property
+    def path_tokens(self) -> Tokens:
+        """The decoded tokens in the 'path' JSON pointer."""
+        return self._load_pointer(self.path)
+
+    @staticmethod
+    def _dump_pointer(pointer: Tokens) -> str:
+        return "/".join(
+            ["", *(token.replace("~", "~0").replace("/", "~1") for token in pointer)]
+        )
+
+    @staticmethod
+    def _load_pointer(pointer: str) -> Tokens:
+        return tuple(
+            token.replace("~1", "/").replace("~0", "~")
+            for token in pointer.split("/")[1:]
+        )
+
+
+class _FromOp(_BaseOp):
+    @classmethod
+    def create(cls, *, path: str | Tokens, from_: str | Tokens) -> tx.Self:  # type: ignore[invalid-method-override]
+        pointer = from_ if isinstance(from_, str) else cls._dump_pointer(from_)
+        return super().create(path=path, **{"from": pointer})
+
+    from_: str = Field(alias="from", examples=["/a/b/d"], pattern=_JSON_POINTER)
+    """A JSON pointer representing the path to apply the operation from."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _pre_validate(cls, data: tp.Any, info: ValidationInfo) -> tp.Any:
+        if (
+            info.mode != "json"
+            and isinstance(data, dict)
+            and "from_" in data
+            and "from" not in data
+        ):
+            data["from"] = data.pop("from_")
+        return data
+
+    @cached_property
+    def from_tokens(self) -> Tokens:
+        """The decoded tokens in the 'from' JSON pointer."""
+        return self._load_pointer(self.from_)
+
+
+class _ValueOp(_BaseOp, tp.Generic[T]):
+    @classmethod
+    def create(cls, *, path: str | Tokens, value: T) -> tx.Self:  # type: ignore[invalid-method-override]
+        return super().create(path=path, value=value)
+
+    value: T = Field(examples=[42])
+    """The value to use in the operation."""
+
+
+# endregion
+
+# region public models
+
+
+class AddOp(_ValueOp, tp.Generic[T]):
+    op: tp.Literal["add"]
+
+
+class CopyOp(_FromOp):
+    op: tp.Literal["copy"]
+
+
+class MoveOp(_FromOp):
+    op: tp.Literal["move"]
+
+
+class RemoveOp(_BaseOp):
+    @classmethod
+    def create(cls, *, path: str | Tokens) -> tx.Self:  # type: ignore[invalid-method-override]
+        return super().create(path=path)
+
+    op: tp.Literal["remove"]
+
+
+class ReplaceOp(_ValueOp, tp.Generic[T]):
+    op: tp.Literal["replace"]
+
+
+class TestOp(_ValueOp, tp.Generic[T]):
+    op: tp.Literal["test"]
+
+
+# endregion

pydantic_json_patch-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: pydantic_json_patch
+Version: 0.1.0
+Summary: Pydantic models for implementing JSON Patch.
+Author: Jonathan Sharpe
+Author-email: Jonathan Sharpe <mail@jonrshar.pe>
+License-Expression: ISC
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: File Formats :: JSON
+Classifier: Topic :: File Formats :: JSON :: JSON Schema
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Python: >=3.10
+Project-URL: repository, https://github.com/textbook/pydantic_json_patch
+Project-URL: Issues, https://github.com/textbook/pydantic_json_patch/issues
+Project-URL: Sponsor, https://ko-fi.com/textbook
+Description-Content-Type: text/markdown
+
+# Pydantic JSON Patch
+
+[Pydantic] models for implementing [JSON Patch].
+
+## Installation
+
+_Pydantic JSON Patch_ is published to [PyPI], and can be installed with e.g.:
+
+```shell
+pip install pydantic-json-patch
+```
+
+## Models
+
+A model is provided for each of the six JSON Patch operations:
+
+- `AddOp`
+- `CopyOp`
+- `MoveOp`
+- `RemoveOp`
+- `ReplaceOp`
+- `TestOp`
+
+As repeating the op is a bit awkward (`CopyOp(op="copy", ...)`), a `create` factory method is available:
+
+```pycon
+>>> from pydantic_json_patch import AddOp
+>>> op = AddOp.create(path="/foo/bar", value=123)
+>>> op
+AddOp(op='add', path='/foo/bar', value=123)
+>>> op.model_dump_json()
+'{"op":"add","path":"/foo/bar","value":123}'
+```
+
+Additionally, there are two compound models:
+
+- `Operation` is the union of all the operators; and
+- `JsonPatch` represents a list of that union type.
+
+### Pointer tokens
+
+The `path` property (and `from` property, where present) of an operation is a [JSON Pointer].
+This means that any `~` or `/` characters in property names need to be properly encoded.
+To aid working with these, the models expose a read-only `path_tokens` property (and, where appropriate, `from_tokens`):
+
+```pycon
+>>> from pydantic_json_patch import CopyOp
+>>> op = CopyOp.model_validate_json('{"op":"copy","path":"/foo/bar~1new","from":"/foo/bar~0old"}')
+>>> op
+CopyOp(op='copy', path='/foo/bar~1new', from_='/foo/bar~0old')
+>>> op.path_tokens
+('foo', 'bar/new')
+>>> op.from_tokens
+('foo', 'bar~old')
+```
+
+Similarly, the `create` factory methods can accept tuples of tokens, and will encode them appropriately:
+
+```pycon
+>>> from pydantic_json_patch import TestOp
+>>> op = TestOp.create(path=("annotations", "scope/value"), value=None)
+>>> op
+TestOp(op='test', path='/annotations/scope~1value', value=None)
+>>> op.model_dump_json()
+'{"op":"test","path":"/annotations/scope~1value","value":null}'
+```
+
+## FastAPI
+
+You can use this package to validate a JSON Patch endpoint in a FastAPI application, for example:
+
+```python
+import typing as tp
+from uuid import UUID
+
+from fastapi import Body, FastAPI
+
+from pydantic_json_patch import JsonPatch
+
+app = FastAPI()
+
+
+@app.patch("/resource/{resource_id}")
+def _(resource_id: UUID, operations: tp.Annotated[JsonPatch, Body()]) -> ...:
+    ...
+```
+
+This will provide a sensible example of the request body:
+
+[![Screenshot of Swagger UI request body example][swagger-example]][swagger-example]
+
+and list the models along with the other schemas:
+
+[![Screenshot of Swagger UI schema list][swagger-schemas]][swagger-schemas]
+
+  [fastapi]: https://fastapi.tiangolo.com/
+  [json patch]: https://datatracker.ietf.org/doc/html/rfc6902/
+  [json pointer]: https://datatracker.ietf.org/doc/html/rfc6901/
+  [pydantic]: https://docs.pydantic.dev/latest/
+  [pypi]: https://pypi.org/
+  [swagger-example]: docs/swagger-example.png
+  [swagger-schemas]: docs/swagger-schemas.png

pydantic_json_patch-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+pydantic_json_patch/__init__.py,sha256=yLGECB55CsaTCxMxRbPCGPLDZQlGSB3KJmx6KBlRjt8,563
+pydantic_json_patch/models.py,sha256=Sy_ZFBwf9ft-h1U0KbDAeAnvS9rF0Ejpi2D-tVxK6Q8,3443
+pydantic_json_patch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydantic_json_patch-0.1.0.dist-info/WHEEL,sha256=jROcLULcdzropX2J55opKw4UHhPFREZax2XzS-Mvpxs,80
+pydantic_json_patch-0.1.0.dist-info/METADATA,sha256=QGt2XbptttDMqnDWraK0tbm4Io4oG66NDg1l8cZphsc,3972
+pydantic_json_patch-0.1.0.dist-info/RECORD,,

pydantic_json_patch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.0
+Root-Is-Purelib: true
+Tag: py3-none-any