Install & Compatibility
Where this runs
tested against v0.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.343s · 41.9MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 1.9s · import 0.306s · 47MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
serialize
✓ from apischema import serialize
deserialize
✓ from apischema import deserialize
schema
✓ from apischema import schema
schema_json_from_obj
✓ from apischema.json_schema import schema_json_from_obj
✗ from apischema import schema_json
The direct `schema_json` import was deprecated/removed; use `schema_json_from_obj` from `apischema.json_schema` for clarity and consistency.
ValidationError
✓ from apischema.validation.errors import ValidationError
dataclass
✓ from apischema.dataclasses import dataclass
✗ from dataclasses import dataclass # (potentially less features)
While standard `dataclasses.dataclass` works, `apischema.dataclasses.dataclass` provides enhanced features and integration with apischema.
This quickstart demonstrates basic serialization and deserialization of a Python dataclass using `apischema`, including an example of how to handle `ValidationError`.
from dataclasses import dataclass
from apischema import serialize, deserialize
from apischema.validation.errors import ValidationError
@dataclass
class User:
id: int
name: str
email: str | None = None
# Serialization
user_obj = User(id=1, name="Alice", email="alice@example.com")
serialized_data = serialize(user_obj)
print(f"Serialized: {serialized_data}")
# Expected output: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}
# Deserialization
deserialized_obj = deserialize(User, {'id': 2, 'name': 'Bob'})
print(f"Deserialized: {deserialized_obj}")
# Expected output: User(id=2, name='Bob', email=None)
# Handling validation errors
try:
deserialize(User, {'id': 'not-an-int', 'name': 'Charlie'})
except ValidationError as e:
print(f"Validation Error: {e}")
# Expected output: Validation Error: [id]: must be an integer
Errors
Common errors & fixes
TypeError: 'type' object is not subscriptable
Using type hints like `list[str]` or `dict[str, int]` on Python versions older than 3.9, or when `typing-extensions` is not installed on Python 3.8 where it might be needed.
fixEnsure your Python version is 3.9 or newer. If on Python 3.8, ensure `typing-extensions` is installed and updated (`pip install 'typing-extensions>=4.0'`). Alternatively, use `typing.List[str]` syntax for older Python versions.
apischema.validation.errors.ValidationError: [path]: error message
Input data does not conform to the type annotations or validation rules defined in the Python type. This is `apischema`'s way of reporting schema mismatches.
fixExamine the error message to identify the field (`[path]`) and the expected type/format. Adjust the input data to match the Python type definition, or refine the type definition to correctly represent the expected data.
ImportError: cannot import name 'schema_json' from 'apischema'
The `schema_json` function was relocated to `apischema.json_schema.schema_json_from_obj` in newer versions.
fixChange your import statement from `from apischema import schema_json` to `from apischema.json_schema import schema_json_from_obj`.
TypeError: 'ApischemaSettings' object is not callable
In older versions, `apischema.settings` was sometimes used as a callable. In newer versions (e.g., v0.18.0+), `apischema.settings` is an object, and configuration is done through `apischema.confs` or by directly setting attributes on the `apischema.settings` object.
fixIf configuring global settings, use `apischema.confs.set_deserialization_coercion(True)` or similar methods, or directly modify attributes like `apischema.settings.deserialization.coercion = True`. Do not treat `apischema.settings` as a function.
Upgrade
Version history
0.19.0latest on PyPI · released Oct 1, 2024
Audit
Dependencies
typing-extensionsrequiredRequired for Python versions < 3.11 for certain typing features.