GitHub

API reference for issue.

Why a value was rejected (Effect's SchemaIssue): a tree of issues.

Leaves say what went wrong (InvalidType: not a value of the expected kind; InvalidValue: the right kind, a wrong value; MissingKey, UnexpectedKey, Forbidden, OneOf: several union members matched). Pointer says where (a path below the enclosing value), Composite groups several issues of one value, Filter wraps the issue of a failed check, AnyOf the issues of a union's members, and Encoding an issue raised while transforming a value.

input is Some(value) only when parsing ran with report_input=True (the rejected value is then kept and printed); otherwise None. format_issue is Effect's default formatter: each leaf's message, with \n at ["key"][0] below the root.

Values

AttributeTypeDescription
DEFAULT_MAX_FORMATTED_ISSUESLiteral[100] = 100

How many leaves format_issue writes before it counts the rest.

Types

TypeDefinitionDescription
PathKeytype PathKey = Hashable

A key of a path: a mapping key (a str in decoded JSON) or an index.

Pathtype Path = tuple[PathKey, ...]
IssueAnnotationstype IssueAnnotations = Mapping[str, object]

Annotations of a leaf issue; message replaces its text, expected fills "Expected <...>".

Leaftype Leaf = InvalidType | InvalidValue | MissingKey | UnexpectedKey | Forbidden | OneOf
Issuetype Issue = Leaf | Filter | Pointer | Composite | Encoding | AnyOf
Formattertype Formatter[F] = Callable[[Issue], F]

Turns an issue into a report (Effect's SchemaIssue.Formatter).

LeafHooktype LeafHook = Callable[[Leaf], str]

The text of a leaf issue (Effect's LeafHook).

CheckHooktype CheckHook = Callable[[Filter], str | None]

The text of a failed check, None for the default one (Effect's CheckHook).

Classes

Functions

reported

reported(input, options) -> Option[object]

input as an issue keeps it: only under report_input.

ParameterTypeDescription
inputobject
optionsParseOptions

Returns Option[object]

def reported(input: object, options: ParseOptions) -> Option[object]:
    """``input`` as an issue keeps it: only under ``report_input``."""
    return Some(input) if options.get("report_input") else None

is_issue

is_issue(value) -> TypeIs[Issue]
ParameterTypeDescription
valueobject

Returns TypeIs[Issue]

def is_issue(value: object) -> TypeIs[Issue]:
    return isinstance(
        value,
        (
            InvalidType,
            InvalidValue,
            MissingKey,
            UnexpectedKey,
            Forbidden,
            OneOf,
            Filter,
            Pointer,
            Composite,
            Encoding,
            AnyOf,
        ),
    )

has_input

has_input(issue) -> bool

issue keeps the rejected value (Effect's hasInput): parsing ran with report_input=True. A Pointer and a MissingKey never do.

ParameterTypeDescription
issueIssue

Returns bool

def has_input(issue: Issue) -> bool:
    """``issue`` keeps the rejected value (Effect's ``hasInput``): parsing
    ran with ``report_input=True``. A ``Pointer`` and a ``MissingKey``
    never do."""
    match issue:
        case Pointer() | MissingKey():
            return False
        case _:
            return issue.input is not None

format_issue

format_issue(issue, *, max_issues=DEFAULT_MAX_FORMATTED_ISSUES) -> str

Effect's default formatter (SchemaIssue.defaultFormatter): one message per leaf, each followed by \n at <path> below the root. Past max_issues leaves (None: no limit) a last line says how many were left out: each line repeats its whole path, so every leaf of a deep value would make the text (leaves x depth) long (Effect writes them all).

ParameterTypeDescription
issueIssue
max_issuesint | None = DEFAULT_MAX_FORMATTED_ISSUES

Returns str

def format_issue(issue: Issue, *, max_issues: int | None = DEFAULT_MAX_FORMATTED_ISSUES) -> str:
    """Effect's default formatter (``SchemaIssue.defaultFormatter``): one
    message per leaf, each followed by ``\\n  at <path>`` below the root.
    Past ``max_issues`` leaves (``None``: no limit) a last line says how many
    were left out: each line repeats its whole path, so every leaf of a deep
    value would make the text (leaves x depth) long (Effect writes them all)."""
    messages, omitted = _limited_messages(issue, leaf_message, default_check_hook, max_issues)
    lines = [
        "" if message is None else f"{message}\n  at {format_path(path)}" if path else message
        for path, message in messages
    ]
    if omitted:
        lines.append(f"... and {omitted} more issue{'' if omitted == 1 else 's'}")
    return "\n".join(lines)

make_formatter_default

make_formatter_default() -> Formatter[str]

format_issue (Effect's makeFormatterDefault).

Returns Formatter[str]

def make_formatter_default() -> Formatter[str]:
    """``format_issue`` (Effect's ``makeFormatterDefault``)."""
    return format_issue

make_formatter_standard_schema_v1

make_formatter_standard_schema_v1(*, leaf_hook=None, check_hook=None) -> Formatter[StandardFailure]

A formatter writing an issue as a Standard Schema failure: one {"message", "path"} per leaf (Effect's makeFormatterStandardSchemaV1). leaf_hook writes a leaf (leaf_message by default), check_hook a failed check (default_check_hook).

ParameterTypeDescription
leaf_hookLeafHook | None = None
check_hookCheckHook | None = None

Returns Formatter[StandardFailure]

def make_formatter_standard_schema_v1(
    *, leaf_hook: LeafHook | None = None, check_hook: CheckHook | None = None
) -> Formatter[StandardFailure]:
    """A formatter writing an issue as a Standard Schema failure: one
    ``{"message", "path"}`` per leaf (Effect's
    ``makeFormatterStandardSchemaV1``). ``leaf_hook`` writes a leaf
    (``leaf_message`` by default), ``check_hook`` a failed check
    (``default_check_hook``)."""
    leaf = leaf_hook or leaf_message
    check = check_hook or default_check_hook

    def format(issue: Issue) -> StandardFailure:
        return {
            "issues": [
                StandardIssue(message=message, path=path)
                for path, message in _messages(issue, leaf, check)
                if message is not None
            ]
        }

    return format

format_path

format_path(path) -> str

["a"][1]: string keys as JSON strings, any other key (an index) as format_unknown prints it.

ParameterTypeDescription
pathPath

Returns str

def format_path(path: Path) -> str:
    """``["a"][1]``: string keys as JSON strings, any other key (an index)
    as ``format_unknown`` prints it."""
    return "".join(f"[{_format_key(key)}]" for key in path)

leaf_message

leaf_message(issue) -> str

A leaf's text: its message annotation, else the default one (Effect's defaultLeafHook).

ParameterTypeDescription
issueLeaf

Returns str

def leaf_message(issue: Leaf) -> str:
    """A leaf's text: its ``message`` annotation, else the default one
    (Effect's ``defaultLeafHook``)."""
    message = _find_message(issue)
    return message if message is not None else _default_leaf_message(issue)

default_check_hook

default_check_hook(issue) -> str | None

The message of the failed check, else of its inner issue (Effect's defaultCheckHook).

ParameterTypeDescription
issueFilter

Returns str | None

def default_check_hook(issue: Filter) -> str | None:
    """The ``message`` of the failed check, else of its inner issue
    (Effect's ``defaultCheckHook``)."""
    message = _find_message(issue)
    return message if message is not None else _find_message(issue.issue)

filter_message

filter_message(issue, check_hook=default_check_hook) -> str | None

The text of a failed check: check_hook's, then for an InvalidValue "Expected <expected>" from the inner issue or the check.

ParameterTypeDescription
issueFilter
check_hookCheckHook = default_check_hook

Returns str | None

def filter_message(issue: Filter, check_hook: CheckHook = default_check_hook) -> str | None:
    """The text of a failed check: ``check_hook``'s, then for an
    ``InvalidValue`` ``"Expected <expected>"`` from the inner issue or the
    check."""
    message = check_hook(issue)
    if message is not None or not isinstance(issue.issue, InvalidValue):
        return message
    expected = _find_expected(issue.issue)
    if expected is None:
        return _expected_message(format_check(issue.filter), issue.input)
    return _expected_message(expected, issue.issue.input)

format_check

format_check(check) -> str

What a check expects: its expected annotation, <filter>, or a group's members joined by " & ".

ParameterTypeDescription
checkCheck[Any]

Returns str

def format_check(check: Check[Any]) -> str:
    """What a check expects: its ``expected`` annotation, ``<filter>``, or a
    group's members joined by ``" & "``."""
    expected = (check.annotations or {}).get("expected")
    if isinstance(expected, str):
        return expected
    from pyfect.schema.ast import FilterGroup

    if isinstance(check, FilterGroup):
        return " & ".join(format_check(c) for c in check.checks)
    return "<filter>"