Serial

0.0.97 · active · verified Fri Apr 17

The `serial` library provides a framework for simple and powerful serialization and deserialization of Python class instances to and from various data formats like JSON, YAML, and XML. It leverages schema definitions for robust type handling and validation. The current version is 0.0.97, and it maintains an active development pace, though it is still in a pre-1.0 state.

Common errors

```
ModuleNotFoundError: No module named 'serial'
```
cause You are trying to import the `serial` library, but it has not been installed in your current Python environment.

fix Install the library using pip: `pip install serial`
```
AttributeError: module 'serial' has no attribute 'Serial'
```
cause This error often occurs when users confuse this `serial` library (for data serialization) with `pyserial` (for serial port communication). `pyserial` provides a class named `Serial`, whereas this `serial` library provides `Serializer` and `Deserializer`.

fix If you intend to use *this* data serialization library, import `from serial import Serializer` or `from serial import Deserializer`. If you intend to use `pyserial` for serial port communication, ensure `pyserial` is installed (`pip install pyserial`) and then use `import serial` (note the import name for `pyserial` is still `serial`).
```
serial.exceptions.ValidationError: Missing required fields: ['name']
```
cause Your input data is missing one or more fields that are marked as `required=True` in your defined schema.

fix Ensure that all fields marked as required in your `serial.fields` schema are present in the dictionary you are attempting to serialize or deserialize. For example, if 'name' is required, `{'id': 1}` will fail, but `{'id': 1, 'name': 'John'}` will pass.

Warnings

gotcha This `serial` library for data serialization is distinct from `pyserial` (often imported as `serial`), which is used for serial port communication. Users frequently confuse the two due to the similar package name.
Fix: Always confirm the purpose of the library when importing `serial`. If you need serial port communication, install `pyserial` and import `import serial` (it's confusing!). If you need data serialization, install `serial` and import `from serial import Serializer` etc.
breaking The library is in a pre-1.0 state (version 0.0.x), which means breaking changes can occur between minor or even patch versions without adhering to strict semantic versioning.
Fix: Pin your dependency to an exact version (`serial==0.0.97`) to avoid unexpected breakages. Regularly check the GitHub repository for release notes before upgrading.
gotcha Schema validation errors, such as missing required fields or type mismatches, are raised as `serial.exceptions.ValidationError` exceptions.
Fix: Wrap serialization/deserialization calls in `try...except serial.exceptions.ValidationError` blocks to gracefully handle invalid input data. Implement client-side validation where possible to prevent these errors.

Install

pip install serial Install stable version

Imports

Serializer
wrong:
```
from serial.serializer import Serializer
```
correct:
```
from serial import Serializer
```
The Serializer class is directly available from the top-level 'serial' package.
Deserializer
wrong:
```
from serial.deserializer import Deserializer
```
correct:
```
from serial import Deserializer
```
The Deserializer class is directly available from the top-level 'serial' package.
fields
wrong:
```
from serial.fields import *
```
correct:
```
from serial import fields
```
Importing 'fields' directly provides access to all field types (Integer, String, Email, etc.).

Quickstart

This quickstart demonstrates how to define a schema using `serial.fields`, instantiate `Serializer` and `Deserializer` for JSON format, and then serialize a Python dictionary into JSON and deserialize it back. It showcases basic schema validation and default value handling.

from serial import Serializer, Deserializer, fields
import json

# Define a schema for a simple User object
user_schema = {
    "id": fields.Integer(required=True),
    "name": fields.String(required=True),
    "email": fields.Email(required=False),
    "is_active": fields.Boolean(default=True)
}

# Create a serializer instance for JSON
user_serializer = Serializer(user_schema, format="json")

# Create a deserializer instance for JSON
user_deserializer = Deserializer(user_schema, format="json")

# Example data to serialize
user_data = {"id": 1, "name": "Alice Wonderland", "email": "alice@example.com"}

# Serialize the data
serialized_output = user_serializer.serialize(user_data)
print(f"Serialized JSON: {serialized_output}")

# Deserialize the data
deserialized_object = user_deserializer.deserialize(serialized_output)
print(f"Deserialized Object: {deserialized_object}")

view raw JSON →