Metadata-Version: 2.4
Name: mgf-common
Version: 0.1.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-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'
Description-Content-Type: text/markdown

# mgf-common

Shared infrastructure for MGF projects: typed exceptions, central
configuration (`pydantic-settings`), and a structured-logging +
OpenTelemetry-tracing stack. One implementation, lifted out of
[VManager](https://codeberg.org/magogi-admin/VManager) so other
projects can consume it directly instead of copy-pasting.

## Status

**Phase 2 complete** (bootstrapped 2026-04-22). The three core
subpackages — `exceptions`, `observability`, `config` — are lifted
and tested in place; VManager cutover (Phase 3) is next. See
[`COMMON.md`](COMMON.md) (lands in Phase 5) or
[`../VManager/docs/COMMON.md`](../VManager/docs/COMMON.md) for the
extraction plan.

## Install

Once published:

```bash
pip install mgf-common
# Optional Tier C observability (OpenTelemetry SDK + Sentry):
pip install 'mgf-common[observability]'
```

For local development (the Phase 5 default until PyPI publish):

```bash
# In a consumer project's pyproject.toml:
dependencies = ["mgf-common"]

[tool.uv.sources]
mgf-common = { path = "../mgf_common", editable = true }
```

## Use

```python
import mgf.common

# Once at startup — establishes app identity for logging, crash
# reports, OTel resource attributes.
mgf.common.configure(app_name="myapp", app_version="1.0.0")

from mgf.common.observability import setup_logging, setup_otel
setup_logging(level="INFO")            # console + rotating file + opt-in journald/OTLP
setup_otel()                           # no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set

from mgf.common.exceptions import AppError
class MyAppError(AppError):
    pass

from mgf.common.config import BaseAppSettings, load_settings, make_settings_config
class Settings(BaseAppSettings):
    model_config = make_settings_config(env_prefix="MYAPP_")
    backend_uri: str = "..."
    # ... your fields
```

## Standards

The cross-project engineering standards are at [`docs/standards/`](docs/standards/)
(land in Phase 4). They cover error handling, logging, configuration,
and design principles — what every MGF-family project commits to.

## Development

```bash
uv venv
uv sync --extra dev --extra observability

# Tests + lint + types + layering
pytest --tb=short -q
ruff check src tests
mypy src
lint-imports
```

## Layout

```
mgf_common/
├── pyproject.toml
├── COMMON.md                      extraction plan + path to PyPI
├── docs/
│   └── standards/                 cross-project engineering standards
├── src/
│   └── mgf/                       PEP 420 namespace package (no __init__.py)
│       └── common/
│           ├── exceptions/
│           ├── config/
│           └── observability/
└── tests/
```

## License

MIT — see [`LICENSE`](LICENSE).
