Metadata-Version: 2.4
Name: mgf-common
Version: 0.31.0
Summary: Shared infrastructure (typed exceptions, central config, structured logging + tracing) for MGF projects
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf_common
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf_common/issues
Author: Bassam Alsanie, mgf-common contributors
License: MIT
License-File: LICENSE
Keywords: configuration,exceptions,logging,observability,opentelemetry,pydantic-settings
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.27; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'observability'
Requires-Dist: sentry-sdk>=2.0; extra == 'observability'
Provides-Extra: vault
Requires-Dist: cryptography>=42; extra == 'vault'
Requires-Dist: keyring>=24; extra == 'vault'
Description-Content-Type: text/markdown

# mgf-common

[![PyPI version](https://img.shields.io/pypi/v/mgf-common.svg)](https://pypi.org/project/mgf-common/)
[![Python versions](https://img.shields.io/pypi/pyversions/mgf-common.svg)](https://pypi.org/project/mgf-common/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Typed: PEP 561](https://img.shields.io/badge/typed-PEP%20561-brightgreen.svg)](https://peps.python.org/pep-0561/)

The cornerstone library for the **Magogi** ecosystem. Typed
exceptions + layered configuration + structured logging + OTel +
crash reporting + vault + process management + FastAPI/Django/
alembic adapters — bundled into one PEP 561 typed package so
every Magogi project (and any compatible consumer) inherits the
same shape.

> **Status:** pre-1.0 (current `0.24.0`). API stable enough that
> three real consumers (VManager Qt desktop, inthewords Django,
> PlasmaMapper FastAPI) ship with it. Public names are
> `experimental` per AP-11; promoted to `stable` after one full
> MINOR cycle without a 🔴 Blocker filed against them.

---

## Pick your starting point

The docs are organised by **audience**. Pick one:

| If you are… | Read |
|---|---|
| **Evaluating** mgf-common (right library for me?) | [`docs/audience/shoppers.md`](docs/audience/shoppers.md) |
| **Building** with it (already adopted) | [`docs/audience/users.md`](docs/audience/users.md) |
| **Contributing** or designing alongside | [`docs/audience/developers.md`](docs/audience/developers.md) |
| A **test/QA** engineer | [`docs/audience/qa.md`](docs/audience/qa.md) |
| Cutting **releases** / running CI | [`docs/audience/release.md`](docs/audience/release.md) |
| Doing a **security** review | [`docs/audience/security.md`](docs/audience/security.md) |
| An **AI agent** (Claude or other) | [`docs/audience/ai-agents.md`](docs/audience/ai-agents.md) |

If you don't fit any of these neatly: [`docs/audience/README.md`](docs/audience/README.md)
is the meta-routing index.

If you just want to **try it**: see
[`docs/tutorial.md`](docs/tutorial.md) (zero → working app in
~30 minutes).

---

## At a glance

```python
import mgf.common as mc

with mc.bootstrap(app_name="myapp", app_version="1.0") as ctx:
    # identity + logging + OTel + excepthooks all wired transactionally
    do_work()
# Clean shutdown on context-exit; LIFO rollback on any startup failure.
```

```python
from mgf.common.process import Service, AllOf, PortReady, LogLineReady

with Service(
    ["postgres", "-D", str(db_dir), "-p", str(port)],
    ready=AllOf([
        PortReady("127.0.0.1", port),
        LogLineReady(r"database system is ready"),
    ]),
    timeout_s=20.0,
) as svc:
    run_my_integration_tests(port=port)
# Service stopped + process group cascaded on context-exit.
```

More: [`docs/recipes/`](docs/recipes/) (17 cookbook patterns)
and [`PUBLIC_API.md`](PUBLIC_API.md) (full surface).

---

## Top-level files

| File | Purpose |
|---|---|
| [`STARTHERE.md`](STARTHERE.md) | Two-flow navigation hub (new project vs catching up an existing one) |
| [`FEEDBACK.md`](FEEDBACK.md) | Living queue of consumer-filed feedback (the relay process driver) |
| [`CHANGELOG.md`](CHANGELOG.md) | Per-release short-form (Keep-a-Changelog format) |
| [`PUBLIC_API.md`](PUBLIC_API.md) | Full public surface, table-form |
| [`PUBLIC_API.json`](PUBLIC_API.json) | Auto-generated machine-readable surface |
| [`SECURITY.md`](SECURITY.md) | Vulnerability reporting policy (per SC-12) |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Dev setup + the four green gates + PR process |

---

## Consumers using it today

- **VManager** — Qt desktop, libvirt VM toolkit (reference consumer; co-designed)
- **inthewords** — Django web app (canonical web consumer)
- **PlasmaMapper** — FastAPI scientific platform ("small consumer" scope discipline)

---

## License

MIT. See [`LICENSE`](LICENSE).
