Metadata-Version: 2.4
Name: mgf-common
Version: 0.44.5
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: mgf-doc-standard<0.2,>=0.1.4
Requires-Dist: pydantic-settings<3,>=2.2
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<8,>=6.0
Provides-Extra: dev
Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mgf-test-supervisor<0.2,>=0.1.9; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.23; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: pytest<10,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml<8,>=6.0; extra == 'dev'
Provides-Extra: observability
Requires-Dist: opentelemetry-api<2,>=1.27; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-httpx<1,>=0.48b0; extra == 'observability'
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == 'observability'
Requires-Dist: sentry-sdk<3,>=2.0; extra == 'observability'
Provides-Extra: vault
Requires-Dist: cryptography<48,>=42; extra == 'vault'
Requires-Dist: keyring<26,>=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 — the pure-Python
infrastructure every Magogi project needs, in one PEP 561 typed
package. Framework adapters (FastAPI, Django, SQLAlchemy, Alembic,
HTTP) ship as separate `mgf-*` sibling packages that depend on
this cornerstone. The engineering standards + the federation
contract live in the [`mgf-doc-standard`](https://codeberg.org/magogi-admin/mgf-doc-standard)
sibling — `mgf-common` depends on it and surfaces the rules via
`mgf-common standards`; see [`FEDERATION.md`](FEDERATION.md).

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

> **If you depend on mgf-common, read [`FEDERATION.md`](FEDERATION.md)
> first.** It is the canonical contract — required docs layout,
> standards-conformance levels, federation-first principle, catch-up
> cadence, and feedback discipline. One page; you'll be aligned with the
> federation by the end of it.

> **Conformance: L3** per the standards in [`mgf-doc-standard`](https://codeberg.org/magogi-admin/mgf-doc-standard) (read any rule with `mgf-common standards <topic>`). As the cornerstone + reference implementation, every MUST **and** SHOULD rule applies here, with run-time enforcement wired up (audit-logs, redaction). The L1/L2/L3 contract is defined in [`FEDERATION.md`](FEDERATION.md) §4.

---

## 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) | Run `mgf-common agents` — the canonical briefing (also in [`STARTHERE.md` §"For the AI agent"](STARTHERE.md)) — then [`docs/audience/ai-agents.md`](docs/audience/ai-agents.md) for the feedback-relay protocol |

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/) (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

- **vm-vmanager-app** — Qt desktop, libvirt VM toolkit (reference consumer; co-designed)
- **inthewords** — Django web app (canonical web consumer)
- **PlasmaMapper** — FastAPI multi-tenant platform (heaviest sibling adopter)
- **iosRecovery** — CLI recovery tool (greenfield canary consumer)

See [`USERS.md`](USERS.md) §2 for the full federation roster, and
[`FEDERATION.md`](FEDERATION.md) for the cornerstone / sibling /
consumer model.

---

## License

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