modmex
Lightweight Python models built on dataclasses with validation, serialization, and type-safe data mapping.
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_dumpandmodel_dump_json.
- Always excludes this field from
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=Truefor 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 applyexclude_fromrules.include_excluded=Trueto 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_fromdefines where a field should be omitted.profileselects 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".
- Omit this field when serializing with
profile="public"- Apply all field rules tagged for
publicduring serialization.
- Apply all field rules tagged for
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_jsonto produce transport-friendly payloads. - Use
type_serializerswhen 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.