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.
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 stringpath, or anaddorreplacewithout avalue(Effect writesundefinedthere; Python has noundefined). - Any
opother thanaddorremoveis applied as areplace. RFC 6902'stest,moveandcopyare not supported, so atestoperation 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.
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.