PyByntic

PyByntic extends Pydantic with binary-typed fields and automatic byte-level serialization. Define models using familiar Pydantic syntax and turn them into compact binary payloads with full control over layout and numeric precision.

Features

• Binary Serialization: Convert Pydantic models to compact binary format
• Type Safety: Full type annotations with custom binary types
• Nested Models: Support for nested models and lists
• Custom Encoders: Support for compression and custom encoding
• Size Efficiency: Significantly smaller than JSON serialization

Installation

pip install pybyntic

Benchmark

For comparison is based on 2 million user records. Users contain various types such as UInt16, UInt32, Int32, Int64, Bool, Float32, String, and DateTime32. Each user also includes nested objects — roles and permissions, and in some cases, there can be hundreds of permissions. PyByntic gives the smallest memory usage of all tested solutions.

Development

# Install dev dependencies
poetry install --with dev

# Run tests
poe test

# Format code
poe autoformat

Usage

from pybyntic import AnnotatedBaseModel
from pybyntic.types import UInt32, String, Bool, Date
from typing import Annotated
import datetime


class User(AnnotatedBaseModel):
	user_id: Annotated[int, UInt32]
	username: Annotated[str, String]
	is_active: Annotated[bool, Bool]
	join_date: Annotated[datetime.date, Date]


# Create and serialize
user = User(
	user_id=123,
	username='admin',
	is_active=True,
	join_date=datetime.date.today()
)

# Serialize to bytes
serialized = user.serialize()

# Deserialize from bytes
deserialized = User.deserialize(serialized)

Examples

See the examples/ directory for more comprehensive examples including:

• Basic serialization
• List handling
• Nested models
• Compression
• Benchmarking

Types

Implementing Custom Types

Example of a type implementation:

from pybyntic.buffer import Buffer


class Bool:
	@classmethod
	def read(cls, buf: Buffer):
		return bool(buf.read_formated("b"))

	@classmethod
	def write(cls, buf: Buffer, value):
		buf.write_formated("b", 1 if value else 0)

Type classes must implement read and write class methods to handle serialization and deserialization. Read methods receive a Buffer instance for byte operations, and write methods receive a Buffer and the value to serialize.

Testing

The project includes comprehensive tests covering:

• Basic serialization/deserialization
• List handling
• Nested models and lists
• Dictionary serialization with JSON
• Compression functionality
• Individual type testing

Run tests with:

poetry run pytest