GitHub

API reference for filters.

Filters: functions from an input to Ok(pass) | Err(fail) (Effect's Filter module).

Every pyfect combinator that takes a filter (catch_filter, filter_map, Stream.filter_map, ...) takes a plain function of this shape; the helpers here build and combine them::

from pyfect import filters

positive = filters.from_predicate(lambda n: n > 0)
halves = filters.compose(positive, lambda n: Ok(n // 2) if n % 2 == 0 else Err(n))

The module is filters because fx.filter is Effect's Effect.filter.

Values

AttributeTypeDescription
stringFilter[object, str, object]
numberFilter[object, int | float, object]

An int or float, not a bool.

booleanFilter[object, bool, object]
dateFilter[object, datetime, object]

Types

TypeDefinitionDescription
Filtertype Filter[I, P = I, F = I] = Callable[[I], Result[P, F]]
FilterEffecttype FilterEffect[I, P, F, E = Never, R = Never] = Callable[[I], Effect[Result[P, F], E, R]]

Functions

make

make[I, P, F](f) -> Filter[I, P, F]

f itself, typed as a filter.

ParameterTypeDescription
fCallable[[I], Result[P, F]]

Returns Filter[I, P, F]

def make[I, P, F](f: Callable[[I], Result[P, F]]) -> Filter[I, P, F]:
    """``f`` itself, typed as a filter."""
    return f

make_effect

make_effect[I, P, F, E = Never, R = Never](f) -> FilterEffect[I, P, F, E, R]

f itself, typed as an effectful filter.

ParameterTypeDescription
fCallable[[I], Effect[Result[P, F], E, R]]

Returns FilterEffect[I, P, F, E, R]

def make_effect[I, P, F, E = Never, R = Never](
    f: Callable[[I], Effect[Result[P, F], E, R]],
) -> FilterEffect[I, P, F, E, R]:
    """``f`` itself, typed as an effectful filter."""
    return f

map_fail

map_fail[I, P, F, F2](self, f) -> Filter[I, P, F2]
ParameterTypeDescription
selfFilter[I, P, F]
fCallable[[F], F2]

Returns Filter[I, P, F2]

def map_fail[I, P, F, F2](self: Filter[I, P, F], f: Callable[[F], F2]) -> Filter[I, P, F2]:
    return lambda i: self(i).map_error(f)

try_

try_[I, O](f) -> Filter[I, O, I]

Pass f(input); fail with the input if f raises an Exception.

ParameterTypeDescription
fCallable[[I], O]

Returns Filter[I, O, I]

def try_[I, O](f: Callable[[I], O]) -> Filter[I, O, I]:
    """Pass ``f(input)``; fail with the input if ``f`` raises an ``Exception``."""

    def run(i: I) -> Result[O, I]:
        try:
            return Ok(f(i))
        except Exception:
            return Err(i)

    return run

from_predicate

from_predicate[A, B](predicate: Callable[[A], TypeIs[B]]) -> Filter[A, B, A]
from_predicate[A](predicate: Callable[[A], bool]) -> Filter[A, A, A]
ParameterTypeDescription
predicate
@overload
def from_predicate[A, B](predicate: Callable[[A], TypeIs[B]]) -> Filter[A, B, A]: ...
@overload
def from_predicate[A](predicate: Callable[[A], bool]) -> Filter[A, A, A]: ...
def from_predicate(predicate: Callable[[Any], bool]) -> Filter[Any, Any, Any]:
    return lambda i: Ok(i) if predicate(i) else Err(i)

from_predicate_option

from_predicate_option[A, B](f) -> Filter[A, B, A]

Pass the value of f(input); fail with the input when it is None.

ParameterTypeDescription
fCallable[[A], Option[B]]

Returns Filter[A, B, A]

def from_predicate_option[A, B](f: Callable[[A], Option[B]]) -> Filter[A, B, A]:
    """Pass the value of ``f(input)``; fail with the input when it is ``None``."""

    def run(i: A) -> Result[B, A]:
        o = f(i)
        return Err(i) if o is None else Ok(o.value)

    return run

to_predicate

to_predicate[A](self) -> Callable[[A], bool]
ParameterTypeDescription
selfFilter[A, object, object]

Returns Callable[[A], bool]

def to_predicate[A](self: Filter[A, object, object]) -> Callable[[A], bool]:
    return lambda i: isinstance(self(i), Ok)

to_option

to_option[A, P](self) -> Callable[[A], Option[P]]
ParameterTypeDescription
selfFilter[A, P, object]

Returns Callable[[A], Option[P]]

def to_option[A, P](self: Filter[A, P, object]) -> Callable[[A], Option[P]]:
    def run(i: A) -> Option[P]:
        r = self(i)
        return Some(r.value) if isinstance(r, Ok) else None

    return run

to_result

to_result[A, P, F](self) -> Callable[[A], Result[P, F]]
ParameterTypeDescription
selfFilter[A, P, F]

Returns Callable[[A], Result[P, F]]

def to_result[A, P, F](self: Filter[A, P, F]) -> Callable[[A], Result[P, F]]:
    return self

equals

equals[A](value) -> Filter[object, A, object]

Pass value itself for an input equal to it.

ParameterTypeDescription
valueA

Returns Filter[object, A, object]

def equals[A](value: A) -> Filter[object, A, object]:
    """Pass ``value`` itself for an input equal to it."""
    return lambda u: Ok(value) if u == value else Err(u)

has

has[I: Container[Any]](key) -> Filter[I, I, I]

Pass a container holding key.

ParameterTypeDescription
keyobject

Returns Filter[I, I, I]

def has[I: Container[Any]](key: object) -> Filter[I, I, I]:
    """Pass a container holding ``key``."""
    return lambda i: Ok(i) if key in i else Err(i)

instance_of

instance_of[T](cls) -> Filter[object, T, object]
ParameterTypeDescription
clstype[T]

Returns Filter[object, T, object]

def instance_of[T](cls: type[T]) -> Filter[object, T, object]:
    return lambda u: Ok(u) if isinstance(u, cls) else Err(u)

reason

reason[E: HasReason[Any], R](error, reason) -> Filter[object, R, object]

Pass the reason of an error instance whose reason is a reason instance (Effect's Filter.reason(tag, reasonTag)).

ParameterTypeDescription
errortype[E]
reasontype[R]

Returns Filter[object, R, object]

def reason[E: HasReason[Any], R](error: type[E], reason: type[R]) -> Filter[object, R, object]:
    """Pass the ``reason`` of an ``error`` instance whose reason is a
    ``reason`` instance (Effect's ``Filter.reason(tag, reasonTag)``)."""

    def run(u: object) -> Result[R, object]:
        if isinstance(u, error):
            found: object = u.reason
            if isinstance(found, reason):
                return Ok(found)
        return Err(u)

    return run

or_

or_[I, P1, P2, F2](self, that) -> Filter[I, P1 | P2, F2]

self's pass, else whatever that gives for the input.

ParameterTypeDescription
selfFilter[I, P1, object]
thatFilter[I, P2, F2]

Returns Filter[I, P1 | P2, F2]

def or_[I, P1, P2, F2](
    self: Filter[I, P1, object], that: Filter[I, P2, F2]
) -> Filter[I, P1 | P2, F2]:
    """``self``'s pass, else whatever ``that`` gives for the input."""

    def run(i: I) -> Result[P1 | P2, F2]:
        r = self(i)
        return r if isinstance(r, Ok) else that(i)

    return run

zip_with

zip_with[I, PL, FL, PR, FR, A](left, right, f) -> Filter[I, A, FL | FR]

Both filters on the same input; the first failure, or f of both passes.

ParameterTypeDescription
leftFilter[I, PL, FL]
rightFilter[I, PR, FR]
fCallable[[PL, PR], A]

Returns Filter[I, A, FL | FR]

def zip_with[I, PL, FL, PR, FR, A](
    left: Filter[I, PL, FL], right: Filter[I, PR, FR], f: Callable[[PL, PR], A]
) -> Filter[I, A, FL | FR]:
    """Both filters on the same input; the first failure, or ``f`` of both passes."""

    def run(i: I) -> Result[A, FL | FR]:
        lr = left(i)
        if isinstance(lr, Err):
            return lr
        rr = right(i)
        if isinstance(rr, Err):
            return rr
        return Ok(f(lr.value, rr.value))

    return run

zip

zip[I, PL, FL, PR, FR](left, right) -> Filter[I, tuple[PL, PR], FL | FR]
ParameterTypeDescription
leftFilter[I, PL, FL]
rightFilter[I, PR, FR]

Returns Filter[I, tuple[PL, PR], FL | FR]

def zip[I, PL, FL, PR, FR](
    left: Filter[I, PL, FL], right: Filter[I, PR, FR]
) -> Filter[I, tuple[PL, PR], FL | FR]:
    return zip_with(left, right, lambda a, b: (a, b))

and_left

and_left[I, PL, FL, FR](left, right) -> Filter[I, PL, FL | FR]
ParameterTypeDescription
leftFilter[I, PL, FL]
rightFilter[I, object, FR]

Returns Filter[I, PL, FL | FR]

def and_left[I, PL, FL, FR](
    left: Filter[I, PL, FL], right: Filter[I, object, FR]
) -> Filter[I, PL, FL | FR]:
    return zip_with(left, right, lambda a, _: a)

and_right

and_right[I, FL, PR, FR](left, right) -> Filter[I, PR, FL | FR]
ParameterTypeDescription
leftFilter[I, object, FL]
rightFilter[I, PR, FR]

Returns Filter[I, PR, FL | FR]

def and_right[I, FL, PR, FR](
    left: Filter[I, object, FL], right: Filter[I, PR, FR]
) -> Filter[I, PR, FL | FR]:
    return zip_with(left, right, lambda _, b: b)

compose

compose[I, PL, FL, PR, FR](left, right) -> Filter[I, PR, FL | FR]

right on what left passes.

ParameterTypeDescription
leftFilter[I, PL, FL]
rightFilter[PL, PR, FR]

Returns Filter[I, PR, FL | FR]

def compose[I, PL, FL, PR, FR](
    left: Filter[I, PL, FL], right: Filter[PL, PR, FR]
) -> Filter[I, PR, FL | FR]:
    """``right`` on what ``left`` passes."""

    def run(i: I) -> Result[PR, FL | FR]:
        lr = left(i)
        return lr if isinstance(lr, Err) else right(lr.value)

    return run

compose_passthrough

compose_passthrough[I, PL, PR](left, right) -> Filter[I, PR, I]

compose, failing with the original input whichever filter fails.

ParameterTypeDescription
leftFilter[I, PL, object]
rightFilter[PL, PR, object]

Returns Filter[I, PR, I]

def compose_passthrough[I, PL, PR](
    left: Filter[I, PL, object], right: Filter[PL, PR, object]
) -> Filter[I, PR, I]:
    """``compose``, failing with the original input whichever filter fails."""

    def run(i: I) -> Result[PR, I]:
        lr = left(i)
        if isinstance(lr, Err):
            return Err(i)
        rr = right(lr.value)
        return Err(i) if isinstance(rr, Err) else rr

    return run