mgf-common 0.1.0__tar.gz

mgf_common-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing and coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Packaging
+MANIFEST

mgf_common-0.1.0/.import_linter_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Grimp.
+*

mgf_common-0.1.0/.import_linter_cache/064c9363bb2a6e3bc05545c81c5891a901373aa6.data.json

@@ -0,0 +1 @@
+{"mgf.common._identity":[],"mgf.common":[["mgf.common._identity",24,"from mgf.common._identity import app_name, app_version, configure"]]}

mgf_common-0.1.0/.import_linter_cache/4d7cd651a3735c71269a0e4b8186cb8d7092dd66.data.json

@@ -0,0 +1 @@
+{"mgf.common.observability.excepthook":[["sys",22,"import sys"],["logging",21,"import logging"],["mgf.common._identity",25,"from mgf.common._identity import app_name"],["types",29,"from types import TracebackType"],["typing",23,"from typing import TYPE_CHECKING"],["__future__",19,"from __future__ import annotations"],["mgf.common.observability.crash_reporter",26,"from mgf.common.observability.crash_reporter import report_now"]],"mgf.common.observability.json_formatter":[["__future__",15,"from __future__ import annotations"],["typing",20,"from typing import TYPE_CHECKING, Any"],["mgf.common.observability.redaction",23,"from mgf.common.observability.redaction import Redactor"],["logging",18,"import logging"],["json",17,"import json"],["opentelemetry",158,"from opentelemetry import trace"],["time",19,"import time"]],"mgf.common.observability.redaction":[["__future__",18,"from __future__ import annotations"],["re",20,"import re"],["dataclasses",21,"from dataclasses import dataclass, field"],["typing",22,"from typing import Any"]],"mgf.common.observability.threading_excepthook":[["mgf.common.observability.crash_reporter",18,"from mgf.common.observability.crash_reporter import report_now"],["mgf.common._identity",17,"from mgf.common._identity import app_name"],["__future__",12,"from __future__ import annotations"],["logging",14,"import logging"],["threading",15,"import threading"]],"mgf.common.observability.crash_reporter":[["logging",30,"import logging"],["sys",33,"import sys"],["mgf.common._identity",40,"from mgf.common._identity import app_name, app_version"],["platform",32,"import platform"],["mgf.common.observability.otel_setup",191,"from mgf.common.observability.otel_setup import emit_log_event"],["uuid",35,"import uuid"],["traceback",34,"import traceback"],["pathlib",37,"from pathlib import Path"],["datetime",36,"from datetime import UTC, datetime"],["json",29,"import json"],["sentry_sdk",170,"import sentry_sdk"],["typing",38,"from typing import Any"],["__future__",27,"from __future__ import annotations"],["urllib",208,"import urllib.request"],["os",31,"import os"]],"mgf.common.config._settings":[["pathlib",36,"from pathlib import Path"],["pydantic_settings",47,"from pydantic_settings import PydanticBaseSettingsSource"],["pydantic_settings",40,"from pydantic_settings import ("],["pydantic",39,"from pydantic import field_validator"],["__future__",34,"from __future__ import annotations"],["typing",37,"from typing import TYPE_CHECKING, Any, ClassVar, cast"]],"mgf.common.exceptions._base":[["__future__",24,"from __future__ import annotations"]],"mgf.common.observability.text_formatter":[["mgf.common.observability.redaction",24,"from mgf.common.observability.redaction import Redactor"],["__future__",15,"from __future__ import annotations"],["logging",17,"import logging"],["time",20,"import time"],["os",18,"import os"],["typing",21,"from typing import TYPE_CHECKING, Any"],["sys",19,"import sys"]],"mgf.common.config._loader":[["mgf.common.config._settings",37,"from mgf.common.config._settings import BaseAppSettings"],["os",29,"import os"],["tempfile",30,"import tempfile"],["yaml",34,"import yaml"],["pydantic",35,"from pydantic import ValidationError"],["collections",41,"from collections.abc import Callable"],["__future__",27,"from __future__ import annotations"],["pathlib",31,"from pathlib import Path"],["typing",32,"from typing import TYPE_CHECKING, Any, TypeVar"],["mgf.common.exceptions",38,"from mgf.common.exceptions import AppConfigError"]],"mgf.common.exceptions._well_known":[["mgf.common.exceptions._base",30,"from mgf.common.exceptions._base import AppError"],["__future__",28,"from __future__ import annotations"]],"mgf.common._identity":[["__future__",22,"from __future__ import annotations"]],"mgf.common.config._paths":[["typing",20,"from typing import Literal"],["os",17,"import os"],["mgf.common._identity",81,"from mgf.common._identity import app_name"],["sys",18,"import sys"],["__future__",15,"from __future__ import annotations"],["pathlib",19,"from pathlib import Path"]],"mgf.common.exceptions":[["mgf.common.exceptions._well_known",32,"from mgf.common.exceptions._well_known import ("],["mgf.common.exceptions._base",31,"from mgf.common.exceptions._base import AppError"],["__future__",29,"from __future__ import annotations"]],"mgf.common.observability.otel_setup":[["opentelemetry",137,"from opentelemetry.trace import Status, StatusCode"],["typing",27,"from typing import TYPE_CHECKING, Any"],["opentelemetry",61,"from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter"],["opentelemetry",62,"from opentelemetry.sdk.resources import Resource"],["logging",25,"import logging"],["__future__",22,"from __future__ import annotations"],["mgf.common._identity",29,"from mgf.common._identity import app_name"],["opentelemetry",95,"from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor"],["opentelemetry",136,"from opentelemetry import trace"],["opentelemetry",170,"from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter"],["opentelemetry",60,"from opentelemetry import trace"],["opentelemetry",190,"from opentelemetry._logs import SeverityNumber, get_logger"],["contextlib",24,"import contextlib"],["opentelemetry",171,"from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler"],["opentelemetry",63,"from opentelemetry.sdk.trace import TracerProvider"],["opentelemetry",64,"from opentelemetry.sdk.trace.export import BatchSpanProcessor"],["opentelemetry",172,"from opentelemetry.sdk._logs.export import BatchLogRecordProcessor"],["collections",32,"from collections.abc import Iterator"],["os",26,"import os"]],"mgf.common.observability.logging_setup":[["logging",207,"from logging.handlers import SysLogHandler"],["mgf.common.observability.text_formatter",46,"from mgf.common.observability.text_formatter import TextFormatter"],["urllib",242,"from urllib.parse import urlparse"],["__future__",34,"from __future__ import annotations"],["logging",241,"from logging.handlers import HTTPHandler"],["mgf.common.observability.otel_setup",225,"from mgf.common.observability.otel_setup import build_otlp_log_handler"],["logging",39,"from logging.handlers import RotatingFileHandler"],["mgf.common._identity",43,"from mgf.common._identity import app_name"],["mgf.common.observability.redaction",45,"from mgf.common.observability.redaction import Redactor"],["mgf.common.observability.json_formatter",44,"from mgf.common.observability.json_formatter import JsonFormatter"],["sys",38,"import sys"],["systemd",195,"from systemd.journal import JournalHandler"],["logging",36,"import logging"],["os",37,"import os"],["typing",41,"from typing import Literal"],["pathlib",40,"from pathlib import Path"]],"mgf.common.config":[["mgf.common.config._paths",26,"from mgf.common.config._paths import ("],["__future__",23,"from __future__ import annotations"],["mgf.common.config._settings",32,"from mgf.common.config._settings import BaseAppSettings, make_settings_config"],["mgf.common.config._loader",25,"from mgf.common.config._loader import load_settings, save_settings"]],"mgf.common":[["mgf.common._identity",27,"from mgf.common._identity import app_name, app_version, configure"],["__future__",25,"from __future__ import annotations"]],"mgf.common.observability":[["mgf.common.observability.crash_reporter",28,"from mgf.common.observability.crash_reporter import report_now"],["mgf.common.observability.excepthook",29,"from mgf.common.observability.excepthook import install_excepthook"],["mgf.common.observability.otel_setup",31,"from mgf.common.observability.otel_setup import operation_span, setup_otel"],["mgf.common.observability.redaction",32,"from mgf.common.observability.redaction import Redactor"],["__future__",26,"from __future__ import annotations"],["mgf.common.observability.threading_excepthook",33,"from mgf.common.observability.threading_excepthook import install_threading_excepthook"],["mgf.common.observability.logging_setup",30,"from mgf.common.observability.logging_setup import LogFormat, setup_logging"]]}

mgf_common-0.1.0/.import_linter_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by Grimp.
+# For information about cache directory tags see https://bford.info/cachedir/

mgf_common-0.1.0/.import_linter_cache/mgf.common.meta.json

@@ -0,0 +1 @@
+{"mgf.common.observability.crash_reporter": 1776847582.9769654, "mgf.common": 1776852806.7539823, "mgf.common.observability.threading_excepthook": 1776847614.9621625, "mgf.common.observability.excepthook": 1776847601.8450816, "mgf.common.observability": 1776847665.0852346, "mgf.common.config._paths": 1776848268.334705, "mgf.common.config._settings": 1776849070.3382397, "mgf.common.exceptions._base": 1776847106.1362891, "mgf.common.exceptions": 1776848235.215801, "mgf.common.observability.json_formatter": 1776847468.170272, "mgf.common.observability.redaction": 1776847318.282407, "mgf.common.observability.otel_setup": 1776848268.334705, "mgf.common.config": 1776848845.0275648, "mgf.common._identity": 1776846821.1630905, "mgf.common.observability.logging_setup": 1776848268.334705, "mgf.common.config._loader": 1776849009.6930761, "mgf.common.observability.text_formatter": 1776847490.1654031, "mgf.common.exceptions._well_known": 1776847208.45681}

mgf_common-0.1.0/.importlinter

@@ -0,0 +1,52 @@
+# Layering contracts for mgf.common — enforces the dependency
+# direction documented in docs/standards/DESIGN_PRINCIPLES.md
+# (rule DP-01) and the lift-readiness rule (LIFT-1) from
+# docs/STANDARD_GAP.md.
+#
+# Run locally:      lint-imports
+# Run in CI:        see .woodpecker.yml lint step
+#
+# Adding contracts? Each contract is phrased as a hard MUST NOT —
+# import-linter fails the CI build on any violation. When adding a
+# new rule, add a ``reason = ...`` comment so a future engineer
+# (or AI) knows why it exists before deciding to relax it.
+
+[importlinter]
+root_packages =
+    mgf.common
+# Required because the contracts below name external packages
+# (vmanager, mgf.cli, mgf.gui) as forbidden — without this flag,
+# import-linter refuses to start.
+include_external_packages = True
+
+# ---------------------------------------------------------------------------
+# Contract 1 — mgf.common is a leaf (the lift-readiness invariant).
+#
+# Reason: mgf.common is the SHARED library that every consumer
+# project depends on. The dependency direction MUST be one-way:
+# consumers (vmanager, future projects) depend on mgf.common, never
+# the reverse. Without this contract, a casual ``import vmanager.X``
+# inside mgf.common would create a cycle that breaks every other
+# consumer. Better to fail loudly in CI here than at integration
+# time in some downstream project.
+#
+# The "forbidden_modules" list is deliberately broad — anything not
+# in mgf.common's own deps (pydantic, pydantic-settings, pyyaml,
+# stdlib, opentelemetry, sentry_sdk) is by definition off-limits.
+# The contract relies on import-linter's behaviour: only top-level
+# packages we control or explicitly forbid are checked; third-party
+# deps not listed here are fine.
+# ---------------------------------------------------------------------------
+
+[importlinter:contract:mgf-common-is-a-leaf]
+name = mgf.common does not import any consumer project
+type = forbidden
+source_modules =
+    mgf.common
+forbidden_modules =
+    vmanager
+# NOTE: future ``mgf.cli`` / ``mgf.gui`` siblings would also be
+# forbidden in principle, but import-linter rejects "subpackages of
+# external packages" in the forbidden_modules list. Consumers in the
+# ``mgf.<sibling>`` namespace will be added as separate top-level
+# entries here when they exist.

mgf_common-0.1.0/.woodpecker.yml

@@ -0,0 +1,105 @@
+# Codeberg / Woodpecker CI for mgf-common.
+#
+# Four steps on every push / PR / tag:
+#
+#   1. lint        — ruff check on src + tests + import-linter contracts
+#   2. typecheck   — mypy --strict on src
+#   3. test        — pytest matrix (Python 3.11 / 3.12 / 3.13);
+#                    coverage gate enforced on 3.12 only
+#   4. build       — sdist + wheel via `python -m build`; runs on every
+#                    push so a packaging regression fails fast
+#
+# **No PyPI publish step.** PyPI's trusted-publisher OIDC does not
+# (yet) support Codeberg / Forgejo as an issuer — the supported list
+# is GitHub, GitLab, Google, ActiveState. Until that changes, the
+# release workflow is manual `twine upload` from a developer machine
+# (see COMMON.md §8.2). The `build` step here exists to catch
+# packaging regressions on every push, NOT to gate the release.
+#
+# All steps run in fresh python:X-slim containers; the workspace dir
+# is mounted across all steps but each container does its own pip
+# install so the failure surface is per-step in the Woodpecker UI.
+#
+# No real-libvirt smoke (mgf.common doesn't touch libvirt). No
+# install-script step. No GUI test (mgf.common doesn't ship a GUI
+# today — the GUI worker / log viewer / Qt excepthook stay in
+# vmanager per COMMON.md §12.2).
+#
+# The Python version matrix: mgf-common declares Python 3.11+ but
+# is developed against 3.12 day-to-day. The matrix verifies every
+# supported version so a 3.11-incompat construct (or a 3.13-only
+# stdlib feature) fails CI loudly.
+
+when:
+  - event: push
+  - event: pull_request
+  - event: tag
+  - event: manual
+
+steps:
+  - name: lint
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev]"
+      - ruff check src tests
+      # Layering enforcement (rule DP-01) — see ``.importlinter``.
+      # Catches any new code that breaks "mgf.common is a leaf".
+      - lint-imports
+
+  - name: typecheck
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,observability]"
+      - mypy src
+
+  # ---------------------------------------------------------------------
+  # Test matrix — runs unit tests on every supported Python version.
+  # Coverage is reported on the 3.12 job only (it is identical across
+  # versions and re-collecting it three times wastes CI minutes).
+  #
+  # The 80% floor — versus VManager's 85% — reflects that mgf.common
+  # has a higher proportion of conditional sink code (Sentry, OTLP,
+  # syslog, journald, HTTP webhook) that can only be meaningfully
+  # exercised against real backends. The lazy-import design that
+  # makes the [observability] extra optional is precisely what
+  # depresses the line-coverage number; raising the gate would force
+  # us to mock SDKs we already trust. Today we sit at ~85%; the 80%
+  # floor catches a real regression without forcing test churn.
+  # ---------------------------------------------------------------------
+  - name: test
+    image: python:${PYTHON_VERSION}-slim
+    matrix:
+      PYTHON_VERSION:
+        - "3.11"
+        - "3.12"
+        - "3.13"
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet -e ".[dev,observability]"
+      - |
+        if [ "${PYTHON_VERSION}" = "3.12" ]; then
+          pytest --tb=short -q --cov --cov-report=term-missing --cov-fail-under=80
+        else
+          pytest --tb=short -q
+        fi
+
+  # ---------------------------------------------------------------------
+  # Build — verifies pyproject.toml, the hatchling wheel target, and
+  # the py.typed PEP 561 marker still produce a valid sdist + wheel.
+  # Runs on every push so a packaging regression fails fast. `twine
+  # check` validates the metadata PyPI will reject if malformed.
+  # ---------------------------------------------------------------------
+  - name: build
+    image: python:3.12-slim
+    commands:
+      - pip install --quiet --upgrade pip
+      - pip install --quiet build twine
+      - python -m build
+      - twine check dist/*
+      # Inspection: confirm the wheel ships py.typed (we shipped the
+      # marker in commit 2bd2fe4 to make `mypy --strict` happy on
+      # consumers; if hatchling ever stops bundling it, this catches
+      # the regression).
+      - unzip -l dist/mgf_common-*.whl | grep py.typed

mgf_common-0.1.0/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to `mgf-common` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+For the version-bump workflow + scope policy (what counts as a major
+vs minor change in the 0.x series), see
+[`COMMON.md`](COMMON.md) §8.3 + §8.4.
+
+## [Unreleased]
+
+(Nothing yet.)
+
+## [0.1.0] — 2026-04-22
+
+First public release. Extracted from
+[VManager](https://codeberg.org/magogi-admin/VManager) per the Round 5
+plan in [`COMMON.md`](COMMON.md). VManager is the reference consumer
+and the only consumer to date; the API is "lifted-from-VManager-shaped"
+and may need adjustment when a second project arrives — the 0.x major
+zero exists to make that future churn possible.
+
+### Added
+
+- **`mgf.common.exceptions`** — typed exception hierarchy.
+  `AppError` base + 7 well-known category bases (`ConfigError`,
+  `ProviderError`, `OperationError`, `GuestError`, `EnvironmentError`
+  [deliberately shadows the builtin alias], `VaultError`,
+  `SchedulerError`) + 6 generic concretes that carry machine-readable
+  fields (`SchemaValidationError.errors`, `AppConfigError`,
+  `CommandError.argv/.returncode/.stderr`, `ResourceNotFoundError.name`,
+  `ResourceAlreadyExistsError.name`, `GuestUnreachableError`,
+  `GuestCommandError`). Consumer projects subclass per their domain.
+
+- **`mgf.common.config`** — reusable typed configuration.
+  `BaseAppSettings` (pydantic-settings base with the layered source
+  order `kwargs > env > .env > YAML > defaults`, YAML override hook,
+  version-check validator, `to_yaml_dict` helper),
+  `make_settings_config(env_prefix=...)` (helper that builds a
+  `SettingsConfigDict` with the recommended baseline plus consumer
+  overrides — the canonical way to set `env_prefix` on a subclass;
+  the `**BaseAppSettings.model_config` spread does NOT work),
+  `load_settings` / `save_settings` (typed loader with optional
+  migration callback + atomic temp-file writer at mode `0o600`),
+  `platform_dir(kind)` + `default_config_path(app)` (cross-OS XDG /
+  macOS Application Support / Windows AppData resolution),
+  `expand_path` (validator helper for `~` and `$VARS` expansion).
+
+- **`mgf.common.observability`** — full observability stack.
+  `setup_logging` (single-point logging with console + rotating file
+  + opt-in journald / syslog / OTLP / HTTP webhook sinks),
+  `JsonFormatter` (one JSON object per line, OTel-aware, redacted),
+  `TextFormatter` (TTY-friendly with ANSI colour, honours `NO_COLOR`),
+  `Redactor` (sensitive-field redaction policy covering `password`,
+  `token`, `api_key`, `Bearer ...`, JWTs, PEM blocks; configurable
+  extras), `setup_otel` + `operation_span` (lazy OpenTelemetry — no-op
+  without the `[observability]` extra; `operation_span` records
+  exceptions and skips `None` attributes), `report_now` (local crash
+  report under `<state>/crashes/` + opt-in remote ship via
+  `<APP>_CRASH_SINK=sentry|otlp|https://...`),
+  `install_excepthook` + `install_threading_excepthook` (idempotent
+  process-wide hooks).
+
+- **`mgf.common.configure(app_name, app_version)`** — process-wide
+  identity cache. Every observability function reads `app_name()` to
+  derive log paths, env-var prefixes, OTel service name, and the
+  crash report `app` field. Call once per entry point, before any
+  other `mgf.common.*` function that emits diagnostics.
+
+- **`docs/standards/`** — cross-project engineering standards
+  (DESIGN_PRINCIPLES, ERROR_HANDLING, LOGGING, CONFIGURATION,
+  COMMON_COMPONENTS, plus the master README with conformance
+  keywords + L0 / L1 / L2 levels). Lifted from VManager in Phase 4.
+
+- **PEP 561 `py.typed` marker** so downstream `mypy --strict`
+  consumers see fully-typed inline annotations instead of
+  `module is installed, but missing library stubs or py.typed marker`
+  warnings (and the cascade of "cannot subclass" errors that follows).
+
+- **`[observability]` extra** — pulls in `opentelemetry-api`,
+  `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`,
+  `opentelemetry-instrumentation-httpx`, and `sentry-sdk`. Default
+  install stays slim; consumers opt in when they want L2 conformance.
+
+- **Quality gates wired:** `mypy --strict` clean on 18 source files,
+  157 tests pass, `ruff` clean, `import-linter` enforces the single
+  contract `mgf-common-is-a-leaf` (forbids any import of a consumer
+  project from inside `mgf.common`).
+
+[Unreleased]: https://codeberg.org/magogi-admin/mgf_common/compare/v0.1.0...HEAD
+[0.1.0]: https://codeberg.org/magogi-admin/mgf_common/releases/tag/v0.1.0