Optics: read and update a part of a value without changing the value
(Effect's Optic)::
from pyfect import optic
likes = optic.Id[State]().key("posts").for_each(lambda post: post.key("likes"))
likes.modify_all(lambda n: n + 1)(state) # a new state; ``state`` is unchangedAn Iso converts both ways, a Lens always finds its focus, a
Prism may not find it but builds a whole from it, an Optional may
fail both ways. Start a chain with Id[T]() and add key,
optional_key, at, tag, check, refine, pick,
omit, not_none and for_each; compose joins two optics.
Failures are schema issues (pyfect.schema.issue). Optics copy dicts,
lists, tuples and values copy.replace supports (dataclasses, schema
classes); anything else raises TypeError when written.
Types#
| Type | Definition | Description |
|---|---|---|
Traversal | type Traversal[T, E] = Optional[T, Sequence[E]] | An optic focusing on several values at once (Effect's |
Classes#
Functions#
entries#
entries[A]() -> Iso[dict[str, A], tuple[tuple[str, A], ...]]A dict as its (key, value) pairs, in order, and back.
Returns Iso[dict[str, A], tuple[tuple[str, A], ...]]
def entries[A]() -> Iso[dict[str, A], tuple[tuple[str, A], ...]]:
"""A dict as its ``(key, value)`` pairs, in order, and back."""
return make_iso(_entries_of, _from_entries)failure#
failure[A, E]() -> Prism[Result[A, E], E]The error of an Err; setting makes one (Effect's Optic.failure).
Returns Prism[Result[A, E], E]
def failure[A, E]() -> Prism[Result[A, E], E]:
"""The error of an ``Err``; setting makes one (Effect's ``Optic.failure``)."""
run = _refined(lambda r: isinstance(r, Err), "a Result.Failure value")
def get(r: Result[A, E]) -> Result[E, Issue]:
return run(r).map(lambda err: err.error)
def set(e: E) -> Result[A, E]:
return Err(e)
return make_prism(get, set)from_checks#
from_checks[T](check, *checks) -> Prism[T, T]The values every check accepts, unchanged (Effect's fromChecks).
| Parameter | Type | Description |
|---|---|---|
check | ast.Check[T] | |
checks | ast.Check[T] = () |
Returns Prism[T, T]
def from_checks[T](check: ast.Check[T], /, *checks: ast.Check[T]) -> Prism[T, T]:
"""The values every check accepts, unchanged (Effect's ``fromChecks``)."""
prism: Prism[T, T] = make((checks_step((check, *checks)),)) # pyright: ignore[reportAssignmentType]
return prismnone#
none[A]() -> Prism[Option[A], None]An empty Option, focused as None; setting gives None.
Returns Prism[Option[A], None]
def none[A]() -> Prism[Option[A], None]:
"""An empty ``Option``, focused as ``None``; setting gives ``None``."""
run = _refined(lambda o: o is None, "a None value")
def get(o: Option[A]) -> Result[None, Issue]:
return run(o).map(_to_none)
return make_prism(get, _to_none)some#
some[A]() -> Prism[Option[A], A]The value of a Some; setting makes one (Effect's Optic.some).
Returns Prism[Option[A], A]
def some[A]() -> Prism[Option[A], A]:
"""The value of a ``Some``; setting makes one (Effect's ``Optic.some``)."""
run = _refined(lambda o: isinstance(o, Some), "a Some value")
def get(o: Option[A]) -> Result[A, Issue]:
return run(o).map(lambda s: s.value)
return make_prism(get, Some)success#
success[A, E]() -> Prism[Result[A, E], A]The value of an Ok; setting makes one (Effect's Optic.success).
Returns Prism[Result[A, E], A]
def success[A, E]() -> Prism[Result[A, E], A]:
"""The value of an ``Ok``; setting makes one (Effect's ``Optic.success``)."""
run = _refined(lambda r: isinstance(r, Ok), "a Result.Success value")
def get(r: Result[A, E]) -> Result[A, Issue]:
return run(r).map(lambda ok: ok.value)
def set(a: A) -> Result[A, E]:
return Ok(a)
return make_prism(get, set)make_iso#
make_iso[T, B](get, set) -> Iso[T, B]An Iso from two conversions that lose nothing (Effect's makeIso).
| Parameter | Type | Description |
|---|---|---|
get | Callable[[T], B] | |
set | Callable[[B], T] |
Returns Iso[T, B]
def make_iso[T, B](get: Callable[[T], B], set: Callable[[B], T], /) -> Iso[T, B]:
"""An ``Iso`` from two conversions that lose nothing (Effect's ``makeIso``)."""
return cast("Iso[T, B]", make((Step("Iso", get, set),)))make_lens#
make_lens[T, B](get, replace) -> Lens[T, B]A Lens from a getter and a replacer (Effect's makeLens).
| Parameter | Type | Description |
|---|---|---|
get | Callable[[T], B] | |
replace | Callable[[B, T], T] |
Returns Lens[T, B]
def make_lens[T, B](get: Callable[[T], B], replace: Callable[[B, T], T], /) -> Lens[T, B]:
"""A ``Lens`` from a getter and a replacer (Effect's ``makeLens``)."""
return cast("Lens[T, B]", make((Step("Lens", get, replace),)))make_optional#
make_optional[T, B](get_result, replace_result) -> Optional[T, B]An Optional from a getter and a replacer that may each fail
(Effect's makeOptional).
| Parameter | Type | Description |
|---|---|---|
get_result | Callable[[T], Result[B, Issue]] | |
replace_result | Callable[[B, T], Result[T, Issue]] |
Returns Optional[T, B]
def make_optional[T, B](
get_result: Callable[[T], Result[B, Issue]],
replace_result: Callable[[B, T], Result[T, Issue]],
/,
) -> Optional[T, B]:
"""An ``Optional`` from a getter and a replacer that may each fail
(Effect's ``makeOptional``)."""
return cast("Optional[T, B]", make((Step("Optional", get_result, replace_result),)))make_prism#
make_prism[T, B](get_result, set) -> Prism[T, B]A Prism from a getter that may fail and a builder (Effect's makePrism).
| Parameter | Type | Description |
|---|---|---|
get_result | Callable[[T], Result[B, Issue]] | |
set | Callable[[B], T] |
Returns Prism[T, B]
def make_prism[T, B](
get_result: Callable[[T], Result[B, Issue]], set: Callable[[B], T], /
) -> Prism[T, B]:
"""A ``Prism`` from a getter that may fail and a builder (Effect's ``makePrism``)."""
return cast("Prism[T, B]", make((Step("Prism", get_result, set),)))