adaptix

An extremely flexible and configurable data model conversion library.

[!IMPORTANT] Adaptix is ready for production! The beta version only means there may be some backward incompatible changes, so you need to pin a specific version.

📚 Documentation

TL;DR

Install

pip install adaptix==3.0.0b11

Use for model loading and dumping.

from dataclasses import dataclass

from adaptix import Retort


@dataclass
class Book:
    title: str
    price: int


data = {
    "title": "Fahrenheit 451",
    "price": 100,
}

# Retort is meant to be global constant or just one-time created
retort = Retort()

book = retort.load(data, Book)
assert book == Book(title="Fahrenheit 451", price=100)
assert retort.dump(book) == data

Use for converting one model to another.

from dataclasses import dataclass

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

from adaptix.conversion import get_converter


class Base(DeclarativeBase):
    pass


class Book(Base):
    __tablename__ = 'books'

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    price: Mapped[int]


@dataclass
class BookDTO:
    id: int
    title: str
    price: int


convert_book_to_dto = get_converter(Book, BookDTO)

assert (
    convert_book_to_dto(Book(id=183, title="Fahrenheit 451", price=100))
    ==
    BookDTO(id=183, title="Fahrenheit 451", price=100)
)

Use cases

• Validation and transformation of received data for your API.
• Conversion between data models and DTOs.
• Config loading/dumping via codec that produces/takes dict.
• Storing JSON in a database and representing it as a model inside the application code.
• Creating API clients that convert a model to JSON sending to the server.
• Persisting entities at cache storage.
• Implementing fast and primitive ORM.

Advantages

• Sane defaults for JSON processing, no configuration is needed for simple cases.
• Separated model definition and rules of conversion that allow preserving SRP and have different representations for one model.
• Speed. It is one of the fastest data parsing and serialization libraries.
• There is no forced model representation, adaptix can adjust to your needs.
• Support dozens of types, including different model kinds: @dataclass, TypedDict, NamedTuple, attrs, sqlalchemy, pydantic and msgspec.
• Working with self-referenced data types (such as linked lists or trees).
• Saving path where an exception is raised (including unexpected errors).
• Machine-readable errors that could be dumped.
• Support for user-defined generic models.
• Automatic name style conversion (e.g. snake_case to camelCase).
• Predicate system that allows to concisely and precisely override some behavior.
• Disabling additional checks to speed up data loading from trusted sources.
• No auto casting by default. The loader does not try to guess value from plenty of input formats.