Probatio

https://probatio.frenck.dev
Admin
Probatio is a data validation library for Python that provides a clean-room, drop-in replacement for...
Tokens:100,560
Snippets:876
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Probatio with uv, pip, or Poetry

Source: https://probatio.frenck.dev/getting-started/installation

Install Probatio with your preferred package manager. The core has zero runtime dependencies and no build step.

```bash
uv add probatio
```

```bash
pip install probatio
```

```bash
poetry add probatio
```

--------------------------------

### Install pytest-probatio

Source: https://probatio.frenck.dev/guides/testing-with-pytest

Install the pytest-probatio package via pip. The plugin registers itself with pytest automatically; no configuration is needed.

```bash
pip install pytest-probatio
```

--------------------------------

### Schema.infer from example data

Source: https://probatio.frenck.dev/reference

Builds a schema from concrete example data using Schema.infer. Each value becomes its type, recursing into mappings and lists. Keyword arguments pass through to Schema.

```python
from probatio import Schema, Required


Schema.infer(
    {"name": "app", "port": 80}
)  # == Schema({Required("name"): str, Required("port"): int})

```

--------------------------------

### Example schema using probatio imports

Source: https://probatio.frenck.dev/getting-started/migrating-from-voluptuous

Shows that existing schemas remain unchanged after switching the import. Uses Schema, Required, Optional, All, and Range.

```python
from probatio import Schema, Required, Optional, All, Range


schema = Schema(
    {
        Required("name"): str,
        Optional("port"): All(int, Range(min=1, max=65535)),
    }
)

```

--------------------------------

### Replace the import from voluptuous to probatio

Source: https://probatio.frenck.dev/getting-started/migrating-from-voluptuous

Shows the one-line import change needed to migrate. The before and after blocks are displayed together as a single example.

```python
# Before
from voluptuous import Schema, Required, Optional, All, Any, Coerce, Invalid

```

```python
# After
from probatio import Schema, Required, Optional, All, Any, Coerce, Invalid

```

--------------------------------

### Check filesystem paths with IsDir, IsFile, and PathExists

Source: https://probatio.frenck.dev/guides/validators

Checks filesystem paths with IsDir, IsFile, and PathExists. The example creates a temporary directory and file first because these validators touch the real filesystem.

```python
import os
import tempfile
from probatio import Schema, IsDir, IsFile, PathExists


with tempfile.TemporaryDirectory() as path:
    file_path = os.path.join(path, "config.yaml")
    open(file_path, "w").close()


    Schema(IsDir())(path)  # an existing directory
    Schema(IsFile())(file_path)  # an existing file
    Schema(PathExists())(path)  # any existing path
```

--------------------------------

### Round trip: to_json_schema then from_json_schema

Source: https://probatio.frenck.dev/guides/json-schema

Shows a small round trip: render a schema to JSON Schema, build it back, and validate. The example demonstrates that the validatable shape survives the conversion.

```python
from probatio import Schema, Required, to_json_schema, from_json_schema


original = Schema({Required("name"): str, Required("age"): int})
rebuilt = from_json_schema(to_json_schema(original))
rebuilt({"name": "Ada", "age": 37})  # {'name': 'Ada', 'age': 37}
```

--------------------------------

### Perform device and sensor arithmetic conversions

Source: https://probatio.frenck.dev/recipes/cookbook

Examples of using arithmetic mutators like Divide, Scale, Remap, and Map to process raw sensor readings.

```python
from probatio import Schema, All, Divide, Scale, Remap, Clamp, Round, Map


# Milliunits to units (millivolts to volts, milliseconds to seconds).
Schema(Divide(1000))(21500)  # 21.5


# A 0..255 byte to a 0..100 percentage.
Schema(All(Remap(0, 255, 0, 100), Round(0)))(128)  # 50.0


# Celsius to Fahrenheit, the affine transform in one call (value * 9 / 5 + 32).
Schema(Scale(9, divisor=5, offset=32))(20)  # 68.0


# A device status code to a name (you own the table).
Schema(Map({0: "off", 1: "on", 2: "auto"}))(2)  # 'auto'
```

--------------------------------

### Enable return validation with returns=True

Source: https://probatio.frenck.dev/guides/probatio-decorator

Opt in to return validation with `returns=True` to check the result against the `-> R` annotation. The example validates that the return value satisfies `Range(min=0)` and prints 5.

```python
from typing import Annotated


from probatio import probatio, Range




@probatio(returns=True)
def clamp(value: int) -> Annotated[int, Range(min=0)]:
    return value




clamp(5)  # 5

```

--------------------------------

### from_json_schema: Build a Probatio schema from JSON Schema

Source: https://probatio.frenck.dev/guides/json-schema

Builds a Schema back from a JSON Schema dictionary. The example shows a JSON Schema with a required string and an optional integer with a minimum, and validates a document against the resulting schema.

```python
from probatio import from_json_schema


document = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0},
    },
    "required": ["name"],
}
schema = from_json_schema(document)
schema({"name": "Ada", "age": 37})  # {'name': 'Ada', 'age': 37}
```

--------------------------------

### Enforce sequence bounds with All and Length

Source: https://probatio.frenck.dev/guides/sequence-schemas

Compose All with Length to validate each element and then check the sequence size. The example defines a tags schema that accepts a list of strings with a length between 1 and 3, and shows a successful validation.

```python
from probatio import Schema, All, Length


tags = Schema(All([str], Length(min=1, max=3)))


tags(["a", "b"])  # ['a', 'b']
```

--------------------------------

### Set validator returns a real set with unstable ordering

Source: https://probatio.frenck.dev/guides/validators

Set returns a real set, so its repr ordering is not stable. The example converts a list with duplicates into a set and then sorts it to get a stable order.

```python
from probatio import Schema, Set


result = Schema(Set())([1, 2, 2, 3])
sorted(result)  # [1, 2, 3]
```

--------------------------------

### Write a JSON config file

Source: https://probatio.frenck.dev/recipes/config-file

Creates a sample JSON configuration file on disk, including a string-based port value to demonstrate later coercion.

```python
import json
from pathlib import Path


config = {
    "name": "my-app",
    "server": {"host": "localhost", "port": "9000"},
}
_ = Path("config.json").write_text(json.dumps(config, indent=2))
```

--------------------------------

### Install Probatio as voluptuous with install_as_voluptuous

Source: https://probatio.frenck.dev/getting-started/compatibility

Call this once, very early in process startup, before anything imports voluptuous. It registers Probatio and a small set of voluptuous-shaped submodules into sys.modules under the voluptuous name, so later imports resolve to Probatio. The call is idempotent but has no teardown, shadows a real voluptuous already imported, and aliases process-wide; it is meant for an application or test harness that owns the process, not for library code.

```python
from probatio.compat import install_as_voluptuous


install_as_voluptuous()

```

--------------------------------

### Using All, Any, and SomeOf combinators

Source: https://probatio.frenck.dev/reference

Shows how to use the All, Any, and SomeOf combinators with Schema. All applies validators in sequence, Any returns the first successful result, and SomeOf requires a minimum number of validators to pass. The output values are shown as comments.

```python
from probatio import All, Any, SomeOf, Range, Schema


Schema(All(str, str.strip))("  hi  ")  # 'hi'
Schema(Any(int, str))("a")  # 'a'
Schema(SomeOf(min_valid=2, validators=[Range(1, 5), int, 3]))(3)  # 3
```

--------------------------------

### Coerce failure example: Schema(Coerce(int))("not a number")

Source: https://probatio.frenck.dev/guides/validators

Coerce raises when the value cannot be converted. This example attempts to coerce the string "not a number" to int, which fails and raises CoerceInvalid.

```python
from probatio import Schema, Coerce


Schema(Coerce(int))("not a number")
```

--------------------------------

### Lazy schema validation

Source: https://probatio.frenck.dev/guides/lazy-building

Example of a schema that is registered at startup but only compiles upon its first validation.

```python
from probatio import Schema, Required, BuildPolicy, set_build_policy


set_build_policy(BuildPolicy.LAZY)


# Registered at startup; the walk is deferred.
schema = Schema({Required("resource"): str})


# ... much later, only if this command is ever invoked:
schema({"resource": "sensor.sun"})  # compiles now, then validates
```

--------------------------------

### Schema.infer

Source: https://probatio.frenck.dev/reference

The infer class method builds a schema from concrete example data, converting each value to its type and recursing into mappings and lists.

```APIDOC
## Schema.infer

### Description
Builds a schema from concrete example data: each value becomes its type, recursing into mappings and lists, so an API response can seed a schema. Keyword arguments pass through to `Schema`.

### Method
Class Method

### Endpoint
`infer(cls, data, **kwargs) -> Schema`

### Parameters
#### Method Parameters
- **data** (any) - Required - The example data to infer the schema from.
- **kwargs** - Optional - Additional keyword arguments passed to `Schema`.

### Request Example
```python
from probatio import Schema, Required

Schema.infer(
    {"name": "app", "port": 80}
)  # == Schema({Required("name"): str, Required("port"): int})
```

### Response
#### Success Response
Returns a `Schema` instance inferred from the example data.
```

--------------------------------

### Home Assistant config schema with probatio as vol

Source: https://probatio.frenck.dev/recipes/home-assistant

A minimal Home Assistant configuration schema written against the probatio vol namespace. It runs on Probatio as-is and produces the expected default for the optional port.

```python
import probatio as vol


CONFIG_SCHEMA = vol.Schema(
    {
        vol.Required("name"): str,
        vol.Optional("port", default=8123): int,
    }
)


CONFIG_SCHEMA({"name": "living-room"})  # {'name': 'living-room', 'port': 8123}

```

--------------------------------

### Implement custom-serializer hook

Source: https://probatio.frenck.dev/guides/field-lists

Example of a custom_serializer hook that overrides the default rendering for a Port type while deferring other nodes to the default handler.

```python
from probatio import Schema, Required, Port, to_field_list, UNSUPPORTED




def render_port(node):
    if isinstance(node, Port):
        return {"type": "port"}
    return UNSUPPORTED




schema = Schema({Required("host"): str, Required("port"): Port()})
to_field_list(schema, custom_serializer=render_port)
# [{'type': 'string', 'name': 'host', 'required': True}, {'type': 'port', 'name': 'port', 'required': True}]
```

--------------------------------

### Define schema with Required and Optional keys

Source: https://probatio.frenck.dev/guides/dict-schemas-and-markers

Shows how to create a dict schema where 'name' is required and 'nickname' is optional. Unknown keys are rejected by default.

```python
from probatio import Schema, Required, Optional


schema = Schema(
    {
        Required("name"): str,
        Optional("nickname"): str,
    }
)


schema({"name": "Frenck"})  # {'name': 'Frenck'}

```

--------------------------------

### Forbidden key failure example

Source: https://probatio.frenck.dev/guides/dict-schemas-and-markers

Shows the failure when a forbidden key is present. The validation error is "key not allowed at 'password'".

```python
from probatio import Schema, Forbidden


schema = Schema({Forbidden("password"): object})


schema({"password": "secret"})  # key not allowed at 'password'

```

--------------------------------

### Key-group presence rules: AtLeastOne, AtMostOne, ExactlyOne, AllOrNone

Source: https://probatio.frenck.dev/guides/validators

Key-group presence rules: AtLeastOne requires one or more, AtMostOne allows at most one, ExactlyOne requires exactly one, AllOrNone requires all or none. A non-mapping is rejected by default; pass require_mapping=False to leave it untouched.

```python
from probatio import Schema, AtLeastOne, AtMostOne, ExactlyOne, AllOrNone


Schema(AtLeastOne("host", "url"))({"host": "nas"})  # unchanged
Schema(AtMostOne("include", "exclude"))({"include": 1})  # unchanged
Schema(ExactlyOne("token", "password"))({"token": "t"})  # unchanged
Schema(AllOrNone("lat", "lon"))({"lat": 1, "lon": 2})  # unchanged
```

--------------------------------

### Sorted validator requires pre-ordered collection

Source: https://probatio.frenck.dev/guides/validators

Sorted requires a collection to already be in order; it does not reorder the input. The example validates a sorted list successfully.

```python
from probatio import Schema, Sorted


Schema(Sorted())([1, 2, 3])  # [1, 2, 3]
```

--------------------------------

### Run rough benchmark against voluptuous

Source: https://probatio.frenck.dev/reference/performance

Runs the rough comparison against voluptuous. Prints a small table of per-validation times and ratios. Run it a few times because absolute numbers wander.

```bash
just bench
```

--------------------------------

### Load and validate YAML config

Source: https://probatio.frenck.dev/recipes/config-file

Demonstrates loading and validating a configuration file using the PyYAML library.

```python
from pathlib import Path


import yaml  # PyYAML


result = schema(yaml.safe_load(Path("config.yaml").read_text()))
```

--------------------------------

### Example failure message for schema mismatch

Source: https://probatio.frenck.dev/guides/testing-with-pytest

Shows the output when a response does not match the schema. The failure names the exact field, even inside a composed list.

```text
data does not match the probatio schema (==):
  users[0].email: expected an email address
```

--------------------------------

### Setting the build policy

Source: https://probatio.frenck.dev/guides/lazy-building

Configuring the process-wide build policy using set_build_policy.

```python
from probatio import BuildPolicy, set_build_policy


set_build_policy(BuildPolicy.LAZY)  # defer every eligible schema to first use
set_build_policy(BuildPolicy.EAGER)  # the default: compile at construction
```

--------------------------------

### Humanize error message with humanize_error

Source: https://probatio.frenck.dev/guides/error-handling

Renders a human-readable error message that includes the failing value. The example prints 'expected int at 'port'. Got 'nope''.

```python
from probatio import Schema, Invalid
from probatio.humanize import humanize_error


data = {"port": "nope"}
schema = Schema({"port": int})


try:
    schema(data)
except Invalid as err:
    print(humanize_error(data, err))  # expected int at 'port'. Got 'nope'
```

--------------------------------

### Access structured error layer with as_dict

Source: https://probatio.frenck.dev/guides/error-handling

Shows the machine-readable error layer: code, context, translation_key, placeholders, and as_dict(). The example prints the code 'type' and the path from as_dict().

```python
from probatio import Schema, Invalid


schema = Schema({"port": int})


try:
    schema({"port": "nope"})
except Invalid as err:
    first = err.errors[0]
    print(first.code)  # type
    print(first.as_dict()["path"])  # ['port']
```

--------------------------------

### Run cross-library benchmark

Source: https://probatio.frenck.dev/reference/performance

Runs the cross-library comparison, syncing the extra libraries on first run. Prints a small table of per-validation times and ratios. Run it a few times because absolute numbers wander.

```bash
just bench-world
```

--------------------------------

### Collect multiple errors with MultipleInvalid

Source: https://probatio.frenck.dev/guides/error-handling

A dict schema collects all failing keys into a MultipleInvalid. The example validates two failing keys and prints the count and each sub-error's path.

```python
from probatio import Schema, MultipleInvalid


schema = Schema({"a": int, "b": int})


try:
    schema({"a": "x", "b": "y"})
except MultipleInvalid as err:
    print(len(err.errors))  # 2
    for sub in err.errors:
        print(sub.path)  # ['a'] then ['b']
```

--------------------------------

### DefaultTo, EmptyToNone, SetTo examples

Source: https://probatio.frenck.dev/guides/validators

Shows the behavior of `DefaultTo`, `EmptyToNone`, and `SetTo`. `DefaultTo` replaces `None` with a default; `EmptyToNone` converts empty strings/containers to `None` but leaves falsy scalars like `0` unchanged; `SetTo` always returns a fixed value.

```python
from probatio import Schema, DefaultTo, EmptyToNone, SetTo


Schema(DefaultTo("fallback"))(None)  # 'fallback'
Schema(DefaultTo("fallback"))("value")  # 'value'
Schema(EmptyToNone())("")  # None
Schema(EmptyToNone())(0)  # 0
Schema(SetTo(42))("anything")  # 42
```

--------------------------------

### Catch Invalid base class

Source: https://probatio.frenck.dev/guides/error-handling

Catches any Probatio validation error by catching Invalid. The example prints the error message 'expected int' when validating 'nope' against an int schema.

```python
from probatio import Schema, Invalid


schema = Schema(int)


try:
    schema("nope")
except Invalid as err:
    print(err)  # expected int
```

--------------------------------

### Define a tool schema with Probatio and render it via to_json_schema

Source: https://probatio.frenck.dev/recipes/llm-tools

Define a Probatio schema with Required and Optional markers, then render it to a JSON Schema dict with to_json_schema. The description on a marker flows into the JSON Schema for the model, and the output includes additionalProperties: False, which strict tool use requires.

```python
from probatio import Schema, Required, Optional, All, In, Range, to_json_schema


get_weather = Schema(
    {
        Required("location", description="City name, like 'Amsterdam'"): str,
        Optional("unit", default="celsius"): In(["celsius", "fahrenheit"]),
        Optional("days", default=1): All(int, Range(min=1, max=14)),
    }
)


to_json_schema(get_weather)
# {'type': 'object', 'properties': {'location': {'type': 'string', 'description': "City name, like 'Amsterdam'"}, 'unit': {'enum': ['celsius', 'fahrenheit'], 'default': 'celsius'}, 'days': {'type': 'integer', 'minimum': 1, 'maximum': 14, 'default': 1}}, 'additionalProperties': False, 'required': ['location']}
```

--------------------------------

### Create a TypedDict schema with create_typeddict_schema

Source: https://probatio.frenck.dev/guides/typeddict

Builds a plain Schema from a TypedDict type without the class wrapper. The returned schema validates and returns the dict as-is, as shown by the example output.

```python
from typing import TypedDict


from probatio import create_typeddict_schema




class Config(TypedDict):
    port: int
    host: str




create_typeddict_schema(Config)({"port": 8080, "host": "nas"})
# {'port': 8080, 'host': 'nas'}

```

--------------------------------

### Coerce config and environment strings

Source: https://probatio.frenck.dev/recipes/cookbook

Demonstrates using Coerce, Boolean, and All to validate and transform input strings into typed values like integers or booleans.

```python
from probatio import Schema, Coerce, Boolean, All, Range


port = Schema(All(Coerce(int), Range(min=1, max=65535)))
port("9000")  # 9000


flag = Schema(Boolean())
flag("yes")  # True
flag("off")  # False
```

--------------------------------

### Combine argument map and return schema

Source: https://probatio.frenck.dev/guides/probatio-decorator

Combine a map of argument schemas with a return schema in one decorator. The example validates `name` against `Length(min=2)` and the return value against `str`.

```python
from probatio import probatio, Length




@probatio({"name": Length(min=2)}, returns=str)
def shout(name: str) -> str:
    return name.upper()




shout("ada")  # 'ADA'

```

--------------------------------

### Compile once, validate many with Schema and Required

Source: https://probatio.frenck.dev/guides/validation-model

Builds a schema once with Required and reuses it in a loop. Compilation is the expensive step; repeated calls are cheap.

```python
from probatio import Schema, Required


schema = Schema({Required("name"): str})  # compiled


for record in [{"name": "a"}, {"name": "b"}]:
    schema(record)  # cheap, repeated calls
```

--------------------------------

### Run dataclass benchmark against mashumaro

Source: https://probatio.frenck.dev/reference/performance

Runs the dataclass comparison against mashumaro. Prints a small table of per-validation times and ratios. Run it a few times because absolute numbers wander.

```bash
just bench-dataclass
```

--------------------------------

### Fail empty list with All and NonEmpty

Source: https://probatio.frenck.dev/guides/sequence-schemas

Use All with NonEmpty to reject an empty sequence. The example shows that an empty list fails the bound check, producing the error 'value must not be empty'.

```python
from probatio import Schema, All, NonEmpty


Schema(All([str], NonEmpty()))([])  # value must not be empty
```

--------------------------------

### Load and validate JSON config

Source: https://probatio.frenck.dev/recipes/config-file

Reads and parses the JSON file, then validates it against the schema, showing how values are coerced and defaults applied.

```python
result = schema(json.loads(Path("config.json").read_text()))
print(result)
# {'name': 'my-app', 'server': {'host': 'localhost', 'port': 9000}, 'log_level': 'info'}
```

--------------------------------

### Render path with render_path from probatio.error

Source: https://probatio.frenck.dev/reference/errors

Shows how to render a path the same way str(error) does. Use render_path from probatio.error to keep a consumer's own error output consistent with the library's rendering.

```python
from probatio.error import render_path


print(render_path(["server", "ports", 1]))  # server.ports[1]

```

--------------------------------

### Change the import: import voluptuous as vol to import probatio as vol

Source: https://probatio.frenck.dev/recipes/home-assistant

Replace the voluptuous import with probatio in Home Assistant code. The rest of the file remains unchanged, and every vol. reference works as-is.

```python
import voluptuous as vol
import probatio as vol

```
Tokens:
Raw