Python SDK
The yosoi package gives Python applications Pydantic models for documents,
locator plans, policies, Contracts, and requests. The native extension uses
Rust to parse documents, compile and evaluate locators, group raw Contract
evidence, acquire URLs, discover candidates, and validate Policies. Python
Contract records are then constructed and checked by Pydantic.
Use import yosoi as ys for the package-level authoring surface. For example,
a Contract is a Pydantic model whose fields bind names to explicit locators:
import yosoi as ys
class Product(ys.Contract):
"""One catalog product."""
root = ys.css("article.product")
name: str = ys.Field("Product name", locator=ys.css("h2"))
price: str = ys.Field("Price text", locator=ys.css(".price"))
document = ys.Document.html(
"catalog",
"<article class='product'><h2>Tea</h2><span class='price'>$4.50</span></article>",
)
products = ys.extract(document, Product)
assert len(products) == 1
assert products[0].name == "Tea"
assert products[0].price == "$4.50"
Ordinary extraction returns list[Product]. Pydantic applies the model’s field
types, constraints, aliases, defaults, validators, and serializers. Use
ys.extract_report(document, Product) when you need rejected candidates,
validation errors, or the source evidence retained beside each record.
[!NOTE] Python
A Python Contract’s identity covers its native transport schema, not its Pydantic types or validators. Use
RuntimeContractwhen the Rust-owned string conversion rules and portable Rust archive format are needed.
For managed recipes, borrowed browser leases, typed assertions and explicit JavaScript permission, see Python browser workflows.
| I want to… | Read |
|---|---|
| Install the Python package for a supported interpreter | Installation |
| Create documents, plans, and inspect locator evidence | Documents and locators |
| Define a Pydantic Contract and handle its outcomes | Contracts |
| Bind Policy and run Requests, Map, or Search | Workflows |
| Understand errors, absence, and resource limits | Errors and limits |
| Review interpreter, browser, and parity evidence | Compatibility and parity, parity report |
The interpreter range is >=3.12,<3.16. Normal CPython 3.12–3.15 use
separate ABI wheels; free-threaded CPython 3.14.8 and 3.15.0 use the cp314t
and cp315t ABIs. Wheel availability remains specific to the release, operating system, and
architecture. See installation before selecting an
artifact.
The browser capability is a Rust build feature. A wheel built with that feature still needs a regular Chrome or Chromium executable installed on the machine. The Python package does not ship the browser executable.
Review examples
Section titled “Review examples”From a source checkout, use the current script to inspect Contracts or a loopback Requests/Map workflow:
uv run --no-sync python python/examples/review.py contracts
uv run --no-sync python python/examples/review.py local
These commands describe the source-checkout review surface. The recorded wheel matrix applies to named earlier SDK snapshots. See compatibility for that historical evidence boundary and Install for the shared current learning path.