Metadata-Version: 2.5
Name: standard
Version: 0.2.4
Summary: A predictable Python utility library with an agent-first interface
Project-URL: Documentation, https://appunni-m.github.io/python-standard/
Project-URL: Repository, https://github.com/appunni-m/python-standard
Project-URL: Changelog, https://appunni-m.github.io/python-standard/changelog/
Author: Standard contributors
License-Expression: MIT
License-File: LICENSE
Keywords: configuration,logging,pydantic,structured-logging,toml,utilities,yaml
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic-settings<3,>=2.6
Requires-Dist: pyyaml<7,>=6
Provides-Extra: aws
Requires-Dist: standard-aws==0.2.4; extra == 'aws'
Provides-Extra: cache
Requires-Dist: standard-cache==0.2.4; extra == 'cache'
Provides-Extra: fastapi
Requires-Dist: standard-fastapi==0.2.4; extra == 'fastapi'
Provides-Extra: http
Requires-Dist: standard-http==0.2.4; extra == 'http'
Provides-Extra: rdbms
Requires-Dist: standard-rdbms==0.2.4; extra == 'rdbms'
Description-Content-Type: text/markdown

# 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](docs/publishing.md) for the current release. Standard is an alpha library; the [documentation site](https://appunni-m.github.io/python-standard/) has the guides, API contracts, examples, and release instructions.

## Documentation map

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

## Install from PyPI

```bash
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](docs/publishing.md) 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.

| Need | Command | Import path |
| --- | --- | --- |
| Core only | `python -m pip install -e .` | `std` |
| FastAPI | `python -m pip install -e . -e packages/standard-fastapi` | `std.fastapi` |
| AWS | `python -m pip install -e . -e packages/standard-aws` | `std.aws` |
| HTTP | `python -m pip install -e . -e packages/standard-http` | `std.http` |
| Redis cache | `python -m pip install -e . -e packages/standard-cache` | `std.cache` |
| Relational databases | `python -m pip install -e . -e packages/standard-rdbms` | `std.rdbms` |
| All providers | `python -m pip install -e . -e packages/standard-fastapi -e packages/standard-aws -e packages/standard-http -e packages/standard-cache -e packages/standard-rdbms` | All provider modules |

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`:

```yaml
database:
  host: localhost
```

Then load a value from it:

```python
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`:

```yaml
host: localhost
port: 8080
```

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

```python
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:

```python
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

```bash
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](SUPPORT.md).
Report security issues privately using the process in [SECURITY.md](SECURITY.md).
