AirField

Dataclasses that describe how Pydantic model fields should be presented in any UI context: web forms, CLI prompts, data tables, notebooks, API docs, charts.

• GitHub: https://github.com/feldroy/AirField/
• PyPI package: https://pypi.org/project/AirField/
• Created by: Audrey M. Roy Greenfeld | GitHub https://github.com/feldroy | PyPI https://pypi.org/user/audreyr/
• Free software: MIT License

Features

annotated-types is for validation. AirField is for presentation. Pydantic reads both.

from pydantic import BaseModel
from airfield import AirField, Label, Widget, Autofocus, PrimaryKey

class Article(BaseModel):
    id: int = AirField(primary_key=True)
    title: str = AirField(label="Title", autofocus=True)
    email: str = AirField(type="email", label="Email Address")
    body: str = AirField(widget="textarea", placeholder="Write something...")

Note: AirField works with any Pydantic BaseModel. If you're using Air, use AirModel instead, which extends BaseModel with ORM and form support.

Every parameter produces a typed, frozen dataclass in field_info.metadata. Consumers discover metadata with isinstance checks:

for m in field_info.metadata:
    if isinstance(m, Widget):
        render_input(m.kind)
    elif isinstance(m, Label):
        render_label(m.text)
    elif isinstance(m, PrimaryKey):
        make_read_only()

Two ways to declare, same result:

# Convenience function
email: str = AirField(type="email", label="Email")

# Annotated metadata (composable with annotated-types, etc.)
email: Annotated[str, Widget("email"), Label("Email")]

Presentation types

Documentation

Documentation is built with Zensical and deployed to GitHub Pages.

• Live site: https://feldroy.github.io/AirField/
• Preview locally: just docs-serve (serves at http://localhost:8000)
• Build: just docs-build

API documentation is auto-generated from docstrings using mkdocstrings.

Docs deploy automatically on push to main via GitHub Actions. To enable this, go to your repo's Settings > Pages and set the source to GitHub Actions.

Development

To set up for local development:

# Clone your fork
git clone git@github.com:your_username/AirField.git
cd AirField

# Install in editable mode with live updates
uv tool install --editable .

This installs the CLI globally but with live updates - any changes you make to the source code are immediately available when you run airfield.

Run tests:

uv run pytest

Run quality checks (format, lint, type check, test):

just qa

Author

AirField was created in 2026 by Audrey M. Roy Greenfeld.

Built with Cookiecutter and the audreyfeldroy/cookiecutter-pypackage project template.