Python errors and limits
Python reports invalid model input as a Pydantic ValidationError. Native
setup and resource-lifecycle failures use named exceptions from
yosoi.errors:
| Exception | Stage |
|---|---|
DocumentError |
Document ID, profile, or payload authoring |
LocatorError |
Query authoring or Rust validation |
ParseError |
Creating a reusable parsed document |
ClosedResourceError |
Using a parsed handle after closing it |
PolicyError |
Rust policy validation, identity, or resolution |
RequestError, MapError, SearchError |
Operation preparation or initialization |
ContractError |
Contract declaration, schema, or native input parsing |
YosoiError is the common native base class. Import exceptions explicitly,
for example from yosoi.errors import PolicyError. Document, locator,
request, Map, and Search execution results also carry typed statuses; do not
convert those statuses into exceptions or empty collections without deciding
what that means for your application.
Structured error details
Section titled “Structured error details”Supported native authoring errors retain their Rust discriminant and payload:
import yosoi as ys
from yosoi.errors import LocatorError, rust_error_details
try:
ys.css("")
except LocatorError as error:
detail = rust_error_details(error)
if detail is not None:
print(detail.rust_type, detail.variant, detail.details)
rust_error_details() also searches Python exception causes and Pydantic
validation contexts, preserving the original exception category. It returns
None when the binding has no typed metadata. The returned detail is a frozen
view; nested payloads are preserved and source_chain contains only sources
the Rust error actually exposes. Malformed serialized inputs are reported as
serde_json::Error categories rather than guessed domain variants.
For an opaque public Rust error struct, variant is None: its private
implementation is not part of the SDK contract.
Request preparation/send and Map errors use this opaque boundary. Search
query and operation errors expose their public Rust enum variants, and
activity/capture identity parsing preserves invalid UUID, noncanonical, and
non-v4 distinctions.
Document authoring preserves public DocumentError and DocumentProfileError
variants. Parse errors retain the public ParseError variant and nested
DocumentParseError type and message. The nested parser error’s private variant
is not inferred from its message. A transparent Rust error can expose an empty
source chain even when the typed payload contains a nested error.
JSON projections reject NaN and positive or negative infinity, including non-finite numbers nested in arrays or objects. These values cannot be represented by the Rust SDK’s JSON value type.
Request and Search results expose typed diagnostic/reason unions, including
browser failures, transport and redirect failures, artifact families, and
decoding codes. These preserve the Rust tags and payloads. Use their fields or
explicit serialization to inspect them; default displays redact sensitive
request/search content. ys.map.rejection_message(reason) returns Rust’s
human-readable message while retaining the original rejection tag.
The public ys.locators.JsonQuerySyntaxError alias describes the four exact
syntax-error tags carried in nested JSON query errors.
Diagnostic unions describe values rather than callable constructors. To validate an authored diagnostic or decoded payload, use Pydantic’s TypeAdapter:
from pydantic import TypeAdapter
from yosoi.diagnostics import PartialReason
reason = TypeAdapter(PartialReason).validate_python(
{"kind": "browser_artifact_truncated", "family": "rendered_dom"}
)
if reason.kind == "browser_artifact_truncated":
print(reason.family)
Contract outcomes
Section titled “Contract outcomes”ys.contracts.ContractSchemaFailure is a typed view of portable schema-error
variants and their payloads. Invalid-schema failure views accept a nested
schema_error while retaining kind and message. RuntimeContract validates
that native schema before extraction, so schema failures are raised during
authoring rather than emitted as extraction outcomes.
Ordinary ys.extract(document, Product) returns a list of validated Product
models. By default, a rejected candidate raises an error. Use a report when
you need both the accepted values and every rejection:
import yosoi as ys
report = ys.extract_report(document, Product)
for record in report.records:
print(record.value, record.candidate.document_id)
for issue in report.issues:
print(issue.kind, issue.field_ids, issue.errors)
report.records contains immutable evidence wrappers. Their .value is the
mutable Pydantic model and .candidate retains its original findings;
report.accepted_records gives the models directly. An issue exposes
.field_ids, a .kind, the original Pydantic ValidationError in .error,
and safe .errors details without input values. report.require_all() returns
the models only when all candidates and extraction diagnostics pass. A lone
Pydantic rejection from ordinary extraction can raise ValidationError;
combined issues and terminal failures use ys.contracts.ContractIssues.
| Status | Interpretation |
|---|---|
evaluated |
Location completed. Inspect accepted records, rejected candidates, and issues. |
no_match |
Complete location found no candidate; ordinary extraction returns [] when the minimum is zero. |
indeterminate |
Evidence is partial or unknown, so absence cannot be concluded. |
locate_failed |
The plan or locator evaluation failed before record validation. |
extraction_rejected |
Native candidate assembly exceeded an extraction budget or could not proceed. |
validation_rejected |
Native validation preflight exceeded a work budget or could not proceed. |
Record issue kinds include missing_required, excess_candidates,
incomplete_evidence, and validation_error. The last kind retains Pydantic
field and model validation details. on_rejected_record="collect" returns only
accepted models from ordinary extraction; use extract_report if rejected
evidence must remain available. Incomplete, failed, and budget-rejected reports
never become ordinary extraction successes, even with collect.
ExtractionPolicy.minimum_records defaults to zero. Set it to one or higher
when ordinary extraction should fail on an empty result. An optional Pydantic
field still needs an explicit default such as default=None; Pydantic does not
invent that default.
Python Contract outcomes cannot be converted into the portable Rust archive
format because Python models can have custom types and validation behavior.
ContractOutcome.to_archived() raises TypeError; use RuntimeContract when
the Rust String value format and archive are required.
Separate budgets
Section titled “Separate budgets”Rust obtains default Policy values through Policy(). A byte budget does not
also raise a node, depth, match, or retained-evidence budget. Common units are:
| Fields | Unit |
|---|---|
*_bytes, *_utf8_bytes, max_input_bytes, max_output_bytes |
Bytes in the named domain |
maximum_elapsed under Request or Search |
Integer microseconds |
map.limits.maximum_elapsed |
Duration(seconds, nanoseconds) |
max_nodes, max_matches, max_regions, max_requests, max_concurrency |
Nodes, matches, regions, requests, or concurrent operations |
max_depth, max_query_steps, max_link_depth |
Depth or bounded steps |
Request source limits distinguish content-coded bytes, decoded representation bytes, and UTF-8 bytes. They are separate because decoding or decompression can change payload size. The Rust Policy and Limits references list current defaults.
ys.ExtractionPolicy supplies optional extraction_limits and
validation_limits to Product.extract(document, policy=...),
ys.extract(document, Product, policy=...), or ys.extract_report(...).
ExtractionLimits.uniform(n) sets all seven extraction counters to the same
bound. minimum_records and on_rejected_record control result acceptance,
not native work.
For explicit stages, Product.assemble(located, limits=...) groups the raw
findings. extracted.validate(limits=...) returns the Python report. Python preflight bounds candidate counts, schema work, field inputs and retained provenance before user Pydantic hooks run. Its conversion-work budget also charges default slots and alias-container expansion, so an authored AliasPath cannot allocate an unbounded list. Field and record budgets also bound
the validation domain. A global validation-budget rejection withholds accepted records and over-budget issue collections while retaining raw candidates and failure facts. The issue budget is charged after Pydantic errors have
been collected, so it does not interrupt arbitrary work inside a custom
validator.
RuntimeContract keeps the Rust-owned staged path and accepts the same
ExtractionLimits and ValidationLimits. It supports Rust String
conversions. An exhausted native budget remains a typed terminal report with
the relevant limit, maximum, and observed count. Inspect its stage before
adjusting that operation’s budget.