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#
| Attribute | Type | Description |
|---|---|---|
DEFAULT_MAX_FORMATTED_ISSUES | Literal[100] = 100 | How many leaves |
Types#
| Type | Definition | Description |
|---|---|---|
PathKey | type PathKey = Hashable | A key of a path: a mapping key (a |
Path | type Path = tuple[PathKey, ...] | |
IssueAnnotations | type IssueAnnotations = Mapping[str, object] | Annotations of a leaf issue; |
Leaf | type Leaf = InvalidType | InvalidValue | MissingKey | UnexpectedKey | Forbidden | OneOf | |
Issue | type Issue = Leaf | Filter | Pointer | Composite | Encoding | AnyOf | |
Formatter | type Formatter[F] = Callable[[Issue], F] | Turns an issue into a report (Effect's |
LeafHook | type LeafHook = Callable[[Leaf], str] | The text of a leaf issue (Effect's |
CheckHook | type CheckHook = Callable[[Filter], str | None] | The text of a failed check, |
Classes#
Functions#
reported#
reported(input, options) -> Option[object]input as an issue keeps it: only under report_input.
| Parameter | Type | Description |
|---|---|---|
input | object | |
options | ParseOptions |
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 Noneis_issue#
is_issue(value) -> TypeIs[Issue]| Parameter | Type | Description |
|---|---|---|
value | object |
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) -> boolissue keeps the rejected value (Effect's hasInput): parsing
ran with report_input=True. A Pointer and a MissingKey
never do.
| Parameter | Type | Description |
|---|---|---|
issue | Issue |
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 Noneformat_issue#
format_issue(issue, *, max_issues=DEFAULT_MAX_FORMATTED_ISSUES) -> strEffect'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).
| Parameter | Type | Description |
|---|---|---|
issue | Issue | |
max_issues | int | 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_issuemake_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).
| Parameter | Type | Description |
|---|---|---|
leaf_hook | LeafHook | None = None | |
check_hook | CheckHook | 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 formatformat_path#
format_path(path) -> str["a"][1]: string keys as JSON strings, any other key (an index)
as format_unknown prints it.
| Parameter | Type | Description |
|---|---|---|
path | Path |
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) -> strA leaf's text: its message annotation, else the default one
(Effect's defaultLeafHook).
| Parameter | Type | Description |
|---|---|---|
issue | Leaf |
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 | NoneThe message of the failed check, else of its inner issue
(Effect's defaultCheckHook).
| Parameter | Type | Description |
|---|---|---|
issue | Filter |
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 | NoneThe text of a failed check: check_hook's, then for an
InvalidValue "Expected <expected>" from the inner issue or the
check.
| Parameter | Type | Description |
|---|---|---|
issue | Filter | |
check_hook | CheckHook = 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) -> strWhat a check expects: its expected annotation, <filter>, or a
group's members joined by " & ".
| Parameter | Type | Description |
|---|---|---|
check | Check[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>"