Install & Compatibility
Where this runs
tested against v2.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.920 runs
installs and imports cleanly · install 0.0s · import 0.487s · 18.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.473s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SchemaNode
✓ from colander import SchemaNode
MappingSchema
✓ from colander import MappingSchema
SequenceSchema
✓ from colander import SequenceSchema
String
✓ from colander import String
Int
✓ from colander import Int
Float
✓ from colander import Float
Boolean
✓ from colander import Boolean
Range
✓ from colander import Range
✗ from colander.validators import Range
While Range is a validator, it's typically imported directly from the top-level 'colander' package for convenience and consistency.
Invalid
✓ from colander import Invalid
✗ from colander.exceptions import Invalid
The primary exception for validation failures is exposed directly under the top-level 'colander' package.
null
✓ from colander import null
'null' is a special singleton value used in Colander to represent missing or explicit null data, distinct from Python's None.
This quickstart demonstrates how to define a schema using `colander.MappingSchema` and `colander.SchemaNode`. It shows how to use various types (String, Int) and validators (Range, Email). The example covers both deserializing incoming data, including handling validation errors via `colander.Invalid`, and serializing Python application structures back into schema-compliant data. It also illustrates the use of `colander.drop` for optional fields.
import colander
class UserSchema(colander.MappingSchema):
name = colander.SchemaNode(colander.String())
age = colander.SchemaNode(colander.Int(), validator=colander.Range(min=0, max=150))
email = colander.SchemaNode(colander.String(), validator=colander.Email(), missing=colander.drop)
# --- Deserialization (Input Validation) ---
# Valid data
appstruct = {'name': 'Alice', 'age': 30, 'email': 'alice@example.com'}
schema = UserSchema()
try:
deserialized_data = schema.deserialize(appstruct)
print(f"Successfully deserialized: {deserialized_data}")
except colander.Invalid as e:
print(f"Deserialization failed: {e.asdict()}")
# Invalid data (age out of range, missing required name, invalid email)
appstruct_invalid = {'name': 'Bob', 'age': 200, 'email': 'invalid-email'}
try:
schema.deserialize(appstruct_invalid)
except colander.Invalid as e:
print(f"Deserialization failed with errors: {e.asdict()}")
# Data with 'missing=colander.drop' field omitted
appstruct_partial = {'name': 'Charlie', 'age': 25}
try:
deserialized_partial = schema.deserialize(appstruct_partial)
print(f"Deserialized partial data: {deserialized_partial}")
except colander.Invalid as e:
print(f"Deserialization of partial data failed: {e.asdict()}")
# --- Serialization (Output Generation) ---
# Python application structure
python_data = {'name': 'Dave', 'age': 40}
serialized_data = schema.serialize(python_data)
print(f"Successfully serialized: {serialized_data}")
python_data_full = {'name': 'Eve', 'age': 22, 'email': 'eve@example.com'}
serialized_data_full = schema.serialize(python_data_full)
print(f"Successfully serialized full data: {serialized_data_full}")
Errors
Common errors & fixes
TypeError: sequence item 1: expected str instance, NoneType found
This error typically occurs when `colander.Invalid.asdict()` is called and one of the validation messages (`Invalid.msg`) in the error tree is `None` or a list of strings, which older versions of Colander's `colander.All` validator did not handle gracefully.
fixUpgrade to Colander 2.0 or later. If using custom validators with `colander.All` in older versions, ensure they consistently return string messages for `Invalid.msg`.
colander.Invalid: {'field_name': 'Error message for field'}
This is the standard exception raised by Colander when input data fails to meet the requirements defined by the schema (e.g., wrong data type, missing a required field, value outside a specified range, or failing a custom validator).
fixCatch the `colander.Invalid` exception and use its `asdict()` method to get a dictionary of specific error messages. Adjust the input data to conform to the schema's rules based on these messages.
Output contains 'b'' prefix (e.g., b'my_value') when serializing strings.
In Colander 2.0, when a `bytes` object is provided to a `colander.String` schema node with `encoding` specified, it's passed through Python's `str()` function before processing, which adds the `b''` prefix if the object is still `bytes`.
fixBefore passing `bytes` data to a `colander.String` schema node for serialization, explicitly decode it to a Python `str` (e.g., `my_bytes_value.decode('utf-8')`). Upgrade
Version history
2.0latest on PyPI · released Jan 3, 2023
Audit
Dependencies
No dependency data recorded yet.