API_SPECIFICATION.md

serialization - API Specification

Version: v1.2.3 | Status: Active | Last Updated: March 2026

Overview

The serialization module provides data serialization and deserialization utilities supporting JSON, YAML, TOML, pickle, and MessagePack formats.

Classes

Serializer

Multi-format data serializer.

from codomyrmex.serialization import Serializer

Constructor

Serializer(format: str = "json")

Parameter	Type	Default	Description
format	str	"json"	Serialization format: "json", "yaml", "toml", "pickle", "msgpack"

Methods

serialize

def serialize(data: Any) -> bytes

Serialize data to bytes.

Parameter	Type	Description
data	Any	Data to serialize

Returns: bytes - Serialized data

Raises: SerializationError if serialization fails

deserialize

def deserialize(data: bytes) -> Any

Deserialize bytes to data.

Parameter	Type	Description
data	bytes	Serialized data

Returns: Any - Deserialized data

Raises: SerializationError if deserialization fails

serialize_to_file

def serialize_to_file(data: Any, path: str) -> bool

Serialize data and write to file.

deserialize_from_file

def deserialize_from_file(path: str) -> Any

Read file and deserialize.

---

SerializationManager

High-level serialization management with format detection.

from codomyrmex.serialization import SerializationManager

Methods

detect_format

def detect_format(path: str) -> str

Detect serialization format from file extension.

auto_serialize

def auto_serialize(data: Any, path: str) -> bool

Automatically serialize based on file extension.

auto_deserialize

def auto_deserialize(path: str) -> Any

Automatically deserialize based on file extension.

---

Exceptions

SerializationError

from codomyrmex.serialization import SerializationError

Raised when serialization operations fail. Inherits from CodomyrmexError.

---

Usage Examples

JSON Serialization

from codomyrmex.serialization import Serializer

serializer = Serializer("json")

data = {"name": "example", "values": [1, 2, 3]}
serialized = serializer.serialize(data)

restored = serializer.deserialize(serialized)
assert restored == data

YAML Serialization

from codomyrmex.serialization import Serializer

serializer = Serializer("yaml")

config = {
    "database": {"host": "localhost", "port": 5432},
    "debug": True
}

serializer.serialize_to_file(config, "config.yaml")
loaded = serializer.deserialize_from_file("config.yaml")

Auto-Detection

from codomyrmex.serialization import SerializationManager

manager = SerializationManager()

# Automatically uses YAML format based on extension
manager.auto_serialize(data, "output.yaml")

# Automatically detects format and deserializes
data = manager.auto_deserialize("config.toml")

---

Supported Formats

Format	Extension	Description
JSON	.json	JavaScript Object Notation
YAML	.yaml, .yml	YAML Ain't Markup Language
TOML	.toml	Tom's Obvious Minimal Language
Pickle	.pkl, .pickle	Python object serialization
MessagePack	.msgpack, .mp	Binary JSON alternative

---

Integration

Dependencies

• Python standard library (json, pickle)
• pyyaml - YAML support
• toml - TOML support (optional)
• msgpack - MessagePack support (optional)
• codomyrmex.logging_monitoring for logging
• codomyrmex.exceptions for error handling

Related Modules

• config_management - Configuration files
• documents - Document handling
• cache - Cache serialization

---

Navigation

• Human Documentation: README.md
• Technical Documentation: AGENTS.md
• Functional Specification: SPEC.md
• Parent: codomyrmex