magogi/prod/: mgf-common-0.46.11 metadata and description

Shared infrastructure (typed exceptions, central config, structured logging + tracing) for MGF projects

author	Bassam Alsanie, mgf-common contributors
classifiers	Development Status :: 3 - Alpha Intended Audience :: Developers License :: OSI Approved :: MIT License Operating System :: MacOS Operating System :: Microsoft :: Windows Operating System :: POSIX :: Linux Programming Language :: Python :: 3 Programming Language :: Python :: 3.11 Programming Language :: Python :: 3.12 Programming Language :: Python :: 3.13 Topic :: Software Development :: Libraries Topic :: System :: Logging Typing :: Typed
description_content_type	text/markdown
keywords	configuration, exceptions, logging, observability, opentelemetry, pydantic-settings
license	MIT
license_file	LICENSE
metadata_version	2.4
project_urls	Homepage, https://codeberg.org/magogi-admin/mgf-common Issues, https://codeberg.org/magogi-admin/mgf-common/issues
requires_dist	pydantic-settings<3,>=2.2 pydantic<3,>=2.6 pyyaml<8,>=6.0 hypothesis<7,>=6.100; extra == 'dev' import-linter<3,>=2.0; extra == 'dev' mgf-standard<0.2,>=0.1.6; extra == 'dev' mgf-test-supervisor<0.2,>=0.1.9; extra == 'dev' mypy<2,>=1.10; extra == 'dev' pytest-asyncio<2,>=0.23; extra == 'dev' pytest-cov<8,>=5.0; extra == 'dev' pytest-timeout<3,>=2.3; extra == 'dev' pytest<10,>=8.0; extra == 'dev' ruff<0.16,>=0.4; extra == 'dev' types-pyyaml<8,>=6.0; extra == 'dev' opentelemetry-api<2,>=1.27; extra == 'observability' opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == 'observability' opentelemetry-instrumentation-httpx<1,>=0.48b0; extra == 'observability' opentelemetry-sdk<2,>=1.27; extra == 'observability' sentry-sdk<3,>=2.0; extra == 'observability' mgf-standard<0.2,>=0.1.6; extra == 'standards' cryptography<48,>=42; extra == 'vault' keyring<26,>=24; extra == 'vault'
requires_python	>=3.11

Because this project isn't in the mirror_whitelist, no releases from root/pypi are included.

File	Tox results	History
mgf_common-0.46.11-py3-none-any.whl Size 380 KB Type Python Wheel Python 3		Uploaded to magogi/prod by magogi 2026-06-19 06:23:31

mgf-common

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-standard sibling — mgf-common depends on it and surfaces the rules via mgf-common standards; see FEDERATION.md.

Status: pre-1.0 (current 0.46.5). API stable enough that four real consumers (vm-vmanager-app Qt desktop, inthewords Django, TelePlasma 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 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-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 §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`
Building with it (already adopted)	`docs/audience/users.md`
Contributing or designing alongside	`docs/audience/developers.md`
A test/QA engineer	`docs/audience/qa.md`
Cutting releases / running CI	`docs/audience/release.md`
Doing a security review	`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") — then `docs/audience/ai-agents.md` for the feedback-relay protocol

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

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

At a glance

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.

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/ (cookbook patterns) and PUBLIC_API.md (full surface).

Top-level files

File	Purpose
`STARTHERE.md`	Two-flow navigation hub (new project vs catching up an existing one)
`FEEDBACK.md`	Living queue of consumer-filed feedback (the relay process driver)
`CHANGELOG.md`	Per-release short-form (Keep-a-Changelog format)
`PUBLIC_API.md`	Full public surface, table-form
`PUBLIC_API.json`	Auto-generated machine-readable surface
`SECURITY.md`	Vulnerability reporting policy (per SC-12)
`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 §2 for the full federation roster, and FEDERATION.md for the cornerstone / sibling / consumer model.

License

MIT. See LICENSE.

devpi