GitHub

API reference for optic.

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 unchanged

An 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

TypeDefinitionDescription
Traversaltype Traversal[T, E] = Optional[T, Sequence[E]]

An optic focusing on several values at once (Effect's Traversal): an Optional whose focus is a sequence.

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).

ParameterTypeDescription
checkast.Check[T]
checksast.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 prism

none

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).

ParameterTypeDescription
getCallable[[T], B]
setCallable[[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).

ParameterTypeDescription
getCallable[[T], B]
replaceCallable[[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).

ParameterTypeDescription
get_resultCallable[[T], Result[B, Issue]]
replace_resultCallable[[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).

ParameterTypeDescription
get_resultCallable[[T], Result[B, Issue]]
setCallable[[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),)))