GitHub

Optics and JSON Patch

Read and update a part of a value without changing it, and diff and patch JSON values.

Optics

An optic is a path into a value that reads the part it points at and builds a changed copy of the whole, leaving the original as it was. Start a path with optic.Id[T]() and add steps: key for a key that is always there, at and optional_key for one that may be missing, tag, check, not_none, pick, omit, and for_each for every element of a list. get_result returns Ok(part) or Err(issue), with the issue saying where the path broke, as a schema failure does. replace, modify and modify_all return new values. Optics copy dicts, lists, tuples, dataclasses and schema classes.

optics.py
from typing import Any

from pyfect import optic
from pyfect.result import Err, Ok
from pyfect.schema.issue import format_issue

type Json = dict[str, Any]

response: Json = {"data": {"items": [{"id": 1, "likes": 3}, {"id": 2, "likes": 5}]}}
empty: Json = {"data": {}}

# A path into a value. `at` fails with a schema issue when the key is missing.
items = optic.Id[Json]().at("data").at("items")
for page in [response, empty]:
    match items.get_result(page):
        case Ok(value=found):
            print("items:", len(found))
        case Err(error=issue):
            print("no items:", format_issue(issue))


# `for_each` focuses on every element; `modify_all` returns a changed copy and
# leaves the original as it was.
def like(n: int) -> int:
    return n + 1


likes = items.for_each(lambda item: item.key("likes"))
liked = likes.modify_all(like)(response)
print(likes.get_all(response), "->", likes.get_all(liked))

Iso, Lens, Prism and Optional are Effect's kinds of optic: a lens always finds its part, a prism may not but can build a whole from it, an optional may fail both ways. A path has the kind of its weakest step, so optic.Id[T]().key("a") is a Lens and .at("a") an Optional.

JSON Patch

json_patch.get(before, after) computes the RFC 6902 operations (add, remove and replace) that turn one JSON value into another, and json_patch.apply(patch, value) applies them to a copy (an empty patch returns value itself, as in Effect). An operation that does not fit the value raises ValueError. Patches are plain dicts, ready to store or send as JSON.

apply checks only what it needs to run a patch, as Effect's does:

  • A value that is not a patch raises TypeError: something that is not a list of objects, an operation without a string path, or an add or replace without a value (Effect writes undefined there; Python has no undefined).
  • Any op other than add or remove is applied as a replace. RFC 6902's test, move and copy are not supported, so a test operation overwrites the value it was meant to check instead of failing.

A patch that comes from a client is untrusted input: decode it with a schema that accepts only add, remove and replace before you pass it to apply, and answer anything else with a 400.

patches.py
from pyfect import json_patch
from pyfect.json_patch import JsonValue

before: JsonValue = {"name": "pyfect", "tags": ["effect"], "stars": 10}
after: JsonValue = {"name": "pyfect", "tags": ["effect", "python"], "stars": 12}

# The operations turning one JSON value into another: add, remove, replace.
patch = json_patch.get(before, after)
for op in patch:
    print(op)

# `apply` builds a new value; `before` is unchanged.
assert json_patch.apply(patch, before) == after
assert json_patch.get(after, after) == []

Reference: pyfect.optic, pyfect.json_patch, pyfect.json_pointer.