dictify 4.0.3

Documents schema and data validation

Dictify

Lightweight validation for Python mappings and JSON-like documents.

dictify is a lightweight validation library for standalone fields and mapping-shaped models.

It is designed for small schema layers, partial validation, and annotation-first models with explicit dict-like behavior.

• Python 3.12+
• Use Field(...) for defaults, required fields, and extra validators
• Use Python annotations to declare Model field types
• Access model data with either attributes or mapping syntax

Why Dictify?

• Validate a single value with Field(...) without defining a full model
• Define annotation-first Model classes for dict-shaped documents
• Keep mapping access and attribute access together
• Handle unknown keys and public attributes explicitly with strict
• Convert back to plain Python data with dict(model) and model.dict()

Install

pip install dictify

Quick Example

from datetime import UTC, datetime
from typing import Annotated

from dictify import Field, Model


class Note(Model):
    title: str = Field(required=True).verify(
        lambda value: len(value) <= 300,
        "Title must be 300 characters or fewer",
    )
    content: str = Field()
    timestamp: Annotated[datetime, "creation time"] = Field(
        default=lambda: datetime.now(UTC)
    )


note = Note({"title": "Dictify", "content": "dictify is easy"})

note.content = "Updated content"
note["content"] = "Updated again"

# These raise Model.Error.
note.title = 0
note["title"] = 0

Strict Mode

Model is strict by default.

• strict=True rejects undeclared keys and undeclared public attributes
• strict=False stores undeclared keys and attributes as extra model data

note = Note({"title": "Dictify"}, strict=False)

note.category = "docs"
assert note["category"] == "docs"
assert dict(note)["category"] == "docs"

Native Conversion

Use explicit conversion when you need plain Python data.

import json

note_dict = dict(note)        # shallow dict conversion
note_native = note.dict()     # recursive dict/list conversion
note_json = json.dumps(note.dict())

Standalone Fields

Field.instance(...) still works well for standalone validation.

email = Field(required=True).instance(str).match(r".+@.+")
email.value = "[e-mail]"

AI Skill

dictify ships with an installed CLI for the packaged AI skill.

dictify ai-skill-install

The installer prompts for the exact destination folder and defaults to:

./.agents/skills/dictify-usage

If the destination already exists, dictify asks before overwriting it.

Development CLI

Repository-local maintenance commands live under dev/cli.

Run them from the repo root with:

uv run python -m dev.cli --help

Examples:

uv run python -m dev.cli docs build
uv run python -m dev.cli docs dev
uv run python -m dev.cli ai skill-ref
uv run python -m dev.cli build
uv run python -m dev.cli release-check

See dev/README.md for the command summary.

Typing Status

The annotation-first model API is fully supported at runtime.

Static type checker support for declarations like email: str = Field(...) may vary. Treat direct annotation-first declarations as the canonical Dictify style, and only add cast(Any, ...) as a project-specific workaround.

Documentation

• Docs: https://keenlycode.github.io/dictify/
• Usage: https://keenlycode.github.io/dictify/guide/usage/
• AI Skill: https://keenlycode.github.io/dictify/ai-skill/
• Field API: https://keenlycode.github.io/dictify/guide/field-api/
• Validation Recipes: https://keenlycode.github.io/dictify/guide/validation-recipes/
• Changelog: https://github.com/keenlycode/dictify/blob/main/CHANGELOG.md