Standard

A modular Python utility library with predictable behavior and agent-first guidance.

The project and PyPI distribution are named standard; the Python import package and command are named std. Install core by itself or add FastAPI, AWS, HTTP, Redis cache, or relational database support through an extra. All six distributions share one release version; see the publishing guide for the current release. Standard is an alpha library; the documentation site has the guides, API contracts, examples, and release instructions.

Documentation map

• Get started — installation and first configuration examples.
• API reference — supported modules, classes, and CLI behavior.
• Architecture decisions — module boundaries, configuration lifecycle, and deferred design questions.
• Configuration contract — merge, interpolation, source priority, and error behavior.
• Logging guide — environment defaults, console/JSON formats, and custom options.
• HTTP client guide — async requests, authentication, retries, and response models.
• Redis cache guide — cache helpers, decorators, and distributed locks.
• Relational database guide — async SQLAlchemy sessions for SQLite, PostgreSQL, and MySQL.
• Testing and benchmarks — local checks, Testcontainers, parity, and measurement limits.
• Changelog — user-visible changes by release.
• FastAPI app template — a copyable, feature-first layout with co-located module code, YAML settings, startup injection, and lifecycle wiring.
• FastAPI consumer sample — an independently assembled app installed from the published package, with a fresh-agent evaluation report.
• Contributing · Support · Security policy · MIT license.

Install from PyPI

python -m pip install standard
python -m pip install 'standard[fastapi]'
python -m pip install 'standard[aws]'
python -m pip install 'standard[http]'
python -m pip install 'standard[cache]'
python -m pip install 'standard[rdbms]'
python -m pip install 'standard[fastapi,aws,http,cache,rdbms]'

The core provides YAML/TOML configuration, Pydantic Settings sources, immutable snapshots, recursive mapping helpers, atomic text writes, environment-aware logging, async service lifecycle management, and the std CLI. FastAPI, AWS, HTTP, cache, and RDBMS are separately installable distributions. The standard[fastapi], standard[aws], standard[http], standard[cache], and standard[rdbms] extras select those providers. All six distributions share the same release version; see the publishing guide for the current status and tag workflow.

Install from this checkout

Run these commands from the repository root. The integration source projects are installed alongside core in editable mode.

The editable installs above are for developing this checkout. For an application, install the released package and only the integration extras it uses; core does not import or install optional providers by default.

First use

Create config/settings.yaml:

database:
  host: localhost

Then load a value from it:

from std.config import ConfigManager

config = ConfigManager.from_file("config/settings.yaml")
host = config.snapshot.get_path("database.host", "localhost")

For Pydantic Settings, create config/app.yaml:

host: localhost
port: 8080

Define a Pydantic Settings model in core/settings.py:

from std.config import YamlSettings


class Settings(YamlSettings):
    std_config_file = "config/app.yaml"
    host: str
    port: int = 8080

In main.py, construct the model once and use it to build the application:

from app.core.settings import Settings


def main() -> None:
    settings = Settings()
    # Build the application and inject its validated settings here.


if __name__ == "__main__":
    main()

Call Settings() only from the application entry point. By default, Pydantic Settings resolves values in this order: constructor values, Standard config files, process environment, dotenv, and file secrets. Callers can change the order through Pydantic's settings_customise_sources hook.

Agent guidance

std guide
std guide --format json
std skill show
std skill install

std guide summarizes the supported library surface for coding agents. std guide --format json emits schema-versioned install, module, command, and documentation data. std skill show prints the packaged idiomatic-Python skill. std skill install writes it to .agents/skills/standard-idiomatic-python/SKILL.md and refuses to overwrite an existing file unless you pass --force.

The source repository contains the development checks, end-to-end tests, and full documentation site. The published distribution is intended to contain only the working library, its CLI, and the required package metadata, README, and license.

For usage questions, bug reports, and feature requests, see Support. Report security issues privately using the process in SECURITY.md.