Skip to main content

modmex

Lightweight Python models built on dataclasses with validation, serialization, and type-safe data mapping.

CI Coverage PyPI Python Versions License

modmex gives you a small but powerful toolkit for:

  • Typed models with minimal boilerplate.
  • Automatic coercion and validation at initialization time.
  • Recursive serialization to Python primitives and JSON.
  • Per-field and per-model validation hooks.
  • Type-based custom serializers to adapt output for different consumers.

Why modmex

If you want stricter models than plain dataclasses, but without the weight of a large framework, modmex is designed for that middle ground.

It focuses on:

  • Simplicity: small API surface.
  • Predictability: explicit model lifecycle.
  • Flexibility: configurable serialization without changing your model definitions.

Installation

With pip:

pip install modmex

With Poetry:

poetry add modmex

Quick Start

from decimal import Decimal

from modmex import BaseModel, Field


class User(BaseModel):
    id: int
    name: str
    balance: Decimal = Decimal("0")
    password: str = Field("", exclude=True)


user = User(id="1", name=123, balance="10.50")

# Type coercion happens during initialization.
assert user.id == 1
assert user.name == "123"
assert user.balance == Decimal("10.50")

# model_dump returns primitive/serializable values.
assert user.model_dump() == {
    "id": 1,
    "name": "123",
    "balance": 10.5,
}

# model_dump_json returns a JSON string.
assert user.model_dump_json() == '{"id":1,"name":"123","balance":10.5}'

Field Configuration

Use Field(...) to add serialization metadata to a model field.

Main options:

  • exclude=True
    • Always excludes this field from model_dump and model_dump_json.
  • exclude_from={"profile_name"}
    • Excludes this field only for selected serialization profiles.

Example:

from modmex import BaseModel, Field


class Session(BaseModel):
    id: str
    secret: str = Field("", exclude_from={"public"})


class User(BaseModel):
    id: int
    private_note: str = Field("x", exclude=True)
    sessions: list[Session] = Field(default_factory=list)


user = User(id=1, sessions=[Session(id="s1", secret="abc")])

assert user.model_dump(profile="public") == {
    "id": 1,
    "sessions": [{"id": "s1"}],
}

Tip:

  • Use exclude=True for values that should never leave the model.
  • Use exclude_from={...} when omission depends on the output profile.

Everyday Usage

1) Parse and normalize input data

from modmex import BaseModel


class Product(BaseModel):
    id: int
    name: str
    active: bool


product = Product(id="10", name=123, active="true")

assert product.id == 10
assert product.name == "123"
assert product.active is True

2) Work with nested models

from modmex import BaseModel


class Address(BaseModel):
    zipcode: int


class User(BaseModel):
    id: int
    address: Address


user = User(id="1", address={"zipcode": "90210"})
assert user.address.zipcode == 90210

3) Prepare different payloads from the same model

api_payload = account.model_dump(profile="public")
internal_payload = account.model_dump()

4) Build JSON directly

json_payload = account.model_dump_json(profile="public")

Dynamic Models

Use create_model when you need to define a model at runtime.

Field definitions can use one of these forms:

  • (annotation, default)
  • (annotation, Field(...))
  • typing.Annotated[annotation, Field(...)]
from typing import Annotated

from modmex import BaseModel, Field, create_model, field_validator, model_validator


def normalize_name(self, value: str) -> str:
    return value.strip().title()


DynamicUser = create_model(
    "DynamicUser",
    id=(int, ...),
    name=(str, Field(default="anonymous")),
    slug=Annotated[str, Field(default="user", exclude=True)],
    __validators__={"normalize_name": field_validator("name")(normalize_name)},
)


class StaticUser(BaseModel):
    id: int
    name: str = "anonymous"
    slug: str = Field(default="user", exclude=True)

    @field_validator("name")
    def normalize_name(self, value: str) -> str:
        return value.strip().title()


dynamic_user = DynamicUser(id="1", name="  john ")
static_user = StaticUser(id="1", name="  john ")

assert dynamic_user.model_dump() == static_user.model_dump()
assert dynamic_user.name == static_user.name == "Jhon"

Validators

Field validators

Use @field_validator("field_name") to transform or validate a single field.

from modmex import BaseModel, field_validator


class Product(BaseModel):
    name: str

    @field_validator("name")
    def normalize_name(self, value: str) -> str:
        return value.strip().title()

Model validators

Use @model_validator(mode="before" | "after") to work with full model state.

  • before: runs before type coercion.
  • after: runs after field-level validation.
from modmex import BaseModel, model_validator


class Product(BaseModel):
    name: str
    slug: str = ""

    @model_validator(mode="before")
    def build_slug(self, values: dict) -> dict:
        values["slug"] = values["name"].lower().replace(" ", "-")
        return values

Serialization

model_dump(...)

Use model_dump when you need a dictionary payload.

Most common options:

  • exclude={...} to omit fields for a specific call.
  • profile="..." to apply exclude_from rules.
  • include_excluded=True to force metadata-excluded fields into the payload.
  • type_serializers={...} to control how specific Python types are represented.

model_dump_json(...)

Use model_dump_json when you need a JSON string output.

It supports the same practical options as model_dump (exclude, profile, include_excluded, type_serializers).

Omitting Fields During Serialization

Use this feature when the same model must produce different payloads depending on where the data is going.

  • exclude_from defines where a field should be omitted.
  • profile selects which omission rules to apply in a specific dump call.

What each option does

  • exclude_from={"public"}
    • Omit this field when serializing with profile="public".
  • profile="public"
    • Apply all field rules tagged for public during serialization.

Common pattern

You may want one shape for API responses and another for internal flows (logs, queues, exports, persistence payloads, etc.).

  • API payload (profile="public"): hide internal fields.
  • Internal payload (no profile, or another profile): keep those fields.

Example

from modmex import BaseModel, Field


class Account(BaseModel):
    id: int
    email: str = Field("", exclude_from={"public"})
    internal_note: str = Field("", exclude=True)


account = Account(id=1, email="a@x.com", internal_note="secret")

# No profile: only always-excluded fields are removed.
assert account.model_dump() == {
    "id": 1,
    "email": "a@x.com",
}

# public profile: profile-based exclusions are applied.
assert account.model_dump(profile="public") == {
    "id": 1,
}

# include_excluded=True: ignore Field exclusion metadata.
assert account.model_dump(profile="public", include_excluded=True) == {
    "id": 1,
    "email": "a@x.com",
    "internal_note": "secret",
}

# Dynamic omission for one call (without metadata changes).
assert account.model_dump(exclude={"email"}) == {
    "id": 1,
}

Type-Based Custom Serializers

You can override serialization behavior by type with type_serializers.

Shape:

type_serializers = {
    SomeType: serializer_function,
}

Keep Decimal values as Decimal in model_dump

from decimal import Decimal

dumped = model.model_dump(
    type_serializers={
        Decimal: lambda value: value,
    }
)

Convert float to Decimal for a specific output contract

from decimal import Decimal

from modmex import BaseModel


class Price(BaseModel):
    amount: float


p = Price(amount=10.25)
dumped = p.model_dump(
    type_serializers={
        float: lambda value: Decimal(str(value)),
    }
)

assert dumped["amount"] == Decimal("10.25")

Emit Decimal as string in JSON

from decimal import Decimal

dumped_json = model.model_dump_json(
    type_serializers={
        Decimal: lambda value: str(value),
    }
)

Note: some client libraries expect Decimal instead of float values (for example, common boto3 workflows). Type serializers let you adapt output contracts cleanly, without hard-coding backend-specific behavior into your models.

Error Handling

Validation issues raise ValidationError.

Each error includes:

  • loc: location path (supports nested structures).
  • msg: human-readable message.
  • type: error category.

Example locations:

  • ["address", "zipcode"]
  • ["tags", 1]

Practical Usage Pattern

Use this rule of thumb:

  • Keep rich Python types in the in-memory model instance.
  • Use model_dump / model_dump_json to produce transport-friendly payloads.
  • Use type_serializers when a specific consumer requires a different type format.

Compatibility

  • Python 3.10+

Metadata

Release files for modmex 1.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for modmex 1.2.3
File Size Uploaded Provenance Actions
modmex-1.2.3.tar.gz 32.0 kB With provenance Details for modmex-1.2.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for modmex 1.2.3
File Interpreter ABI Platform Actions
modmex-1.2.3-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for modmex-1.2.3-cp310-abi3-win_amd64.whl
modmex-1.2.3-cp310-abi3-manylinux_2_34_x86_64.whl CPython 3.10 abi3 Linux glibc 2.34+ x86-64 Details for modmex-1.2.3-cp310-abi3-manylinux_2_34_x86_64.whl
modmex-1.2.3-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for modmex-1.2.3-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 737.9 kB

Release files / modmex-1.2.3.tar.gz

Download URL modmex-1.2.3.tar.gz
Size 32.0 kB
Tags Source
SHA-256 checksum
How to use checksums
52f949677410933b35c063f6025ee74e0e9b5d5bf73921ee1ab0bd48f63ae407
BLAKE2b-256 checksum
How to use checksums
189edd9d0e05125f127be0471e926672bd3825c3ae40d6b39f1132f72ebbf061
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / modmex-1.2.3-cp310-abi3-win_amd64.whl

Download URL modmex-1.2.3-cp310-abi3-win_amd64.whl
Size 183.1 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
7b6ff74fbf059167af65b190499ad9e197fdba725355d4bd64f7123092a4ad38
BLAKE2b-256 checksum
How to use checksums
16692e645d945a2845bdc43e356338ea8655fa1686b2b53473624d694bf16033
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / modmex-1.2.3-cp310-abi3-manylinux_2_34_x86_64.whl

Download URL modmex-1.2.3-cp310-abi3-manylinux_2_34_x86_64.whl
Size 272.2 kB
Tags CPython 3.10 Linux glibc 2.34+ x86-64 abi3
SHA-256 checksum
How to use checksums
b232f8ebd45c6890cb2e06d175c1caa0fdb5072122e6b6f80c89c89bdff482d2
BLAKE2b-256 checksum
How to use checksums
ff2c62ee7443fd38d99ee3d1b232ae6602ae49a4038bbe2cbecbed53db28371a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / modmex-1.2.3-cp310-abi3-macosx_11_0_arm64.whl

Download URL modmex-1.2.3-cp310-abi3-macosx_11_0_arm64.whl
Size 250.6 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b79dc5b2b76cc7d17c38e05adccf5f459c9f71dad564870ceb87e3c31442aedc
BLAKE2b-256 checksum
How to use checksums
d97f0f0d8295701fa6e0a9f35ad03ce492785414ca678d75ca45481db04660d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for modmex 1.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for modmex-1.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page