xtr-logging-contracts 1.0.0__tar.gz

xtr_logging_contracts-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xterr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xtr_logging_contracts-1.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: xtr-logging-contracts
+Version: 1.0.0
+Summary: The logging contract: one interface, eight severities, and a logger that discards everything.
+Keywords: logging,contracts,interface,protocol,structured-logging
+Author: Razvan Ceana
+Author-email: Razvan Ceana <razvan@ceana.ro>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.4
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xtr-logging-contracts
+
+**The logging contract, and nothing else — so a library that logs installs nothing else.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="core dependencies: 1" src="https://img.shields.io/badge/core%20deps-1-3FB950">
+<img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
+<img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
+
+</div>
+
+---
+
+## Why?
+
+A library that logs should not decide where records go. It takes a `LoggerInterface`, defaults to
+a `NullLogger`, and leaves handlers, formatters and configuration to the application that wires
+it.
+
+Which means a library needs the *contract*, not an implementation — and should not pay for one.
+Depending on [xtr-logging](https://github.com/xterr/python-xtr-logging) to annotate one parameter
+drags in a JSON codec, a clock and seventeen handlers the library never touches. This package is
+that dependency, reduced to what the seam is actually made of:
+
+- 🧩 **`LoggerInterface`** — eight severities plus `log()`, with a context mapping.
+- 🕳️ **`NullLogger`** — what makes logging optional for your callers.
+- 🪜 **`Level`** — the eight RFC 5424 severities, comparable as integers.
+- 🗂️ **`Context`** — the mapping every method takes, and the key an exception goes under.
+- 🪶 **One dependency** — `typing-extensions`, for `@override` on 3.11.
+
+```python
+from xtr_logging_contracts import LoggerInterface, NullLogger
+
+
+class Checkout:
+    def __init__(self, logger: LoggerInterface | None = None) -> None:
+        self._logger = logger or NullLogger()
+
+    def pay(self, order: Order) -> None:
+        self._logger.error("payment {order} failed", {"order": order.id})
+```
+
+## Install
+
+```sh
+uv add xtr-logging-contracts
+```
+
+Requires Python 3.11+.
+
+## Who installs what
+
+|  | Depends on |
+| --- | --- |
+| **A library that logs** | `xtr-logging-contracts` at runtime, `xtr-logging` as a dev dependency — its tests build real loggers and assert on a `TestHandler`. |
+| **An application** | `xtr-logging`, which implements this contract and wires channels, handlers and processors from configuration. |
+
+`xtr-logging` **re-exports** every symbol here rather than redefining it, so
+`xtr_logging.LoggerInterface is xtr_logging_contracts.LoggerInterface`. That identity is what lets
+a container register a logger under the interface and a library, which never imported
+`xtr-logging`, receive it.
+
+## The interface
+
+```python
+class LoggerInterface(Protocol):
+    def emergency(self, message: str, /, context: Context | None = None) -> None: ...
+    def alert(self, message: str, /, context: Context | None = None) -> None: ...
+    def critical(self, message: str, /, context: Context | None = None) -> None: ...
+    def error(self, message: str, /, context: Context | None = None) -> None: ...
+    def warning(self, message: str, /, context: Context | None = None) -> None: ...
+    def notice(self, message: str, /, context: Context | None = None) -> None: ...
+    def info(self, message: str, /, context: Context | None = None) -> None: ...
+    def debug(self, message: str, /, context: Context | None = None) -> None: ...
+    def log(self, level: LevelLike, message: str, /, context: Context | None = None) -> None: ...
+```
+
+The rules:
+
+- `context` is a mapping of anything. Formatters describe what they cannot serialise; a value
+  never makes logging fail.
+- An exception to report goes under `context["exception"]`.
+- `{key}` placeholders in the message are filled from context downstream, not by the logger, so a
+  handler can still see the template and the values apart.
+
+`AbstractLogger` implements the eight severity methods on top of `log()`, so an implementation
+writes one method. `LoggerAware` gives a class a `logger` that is a `NullLogger` until
+`set_logger()` is called.
+
+> ruff's `PLE1205` assumes every `logger.info(...)` is the standard library's and flags the
+> context mapping as a stray format argument. Ignore it in projects using this interface.
+
+### Levels
+
+| Level | Value | RFC 5424 | | Level | Value | RFC 5424 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `DEBUG` | 100 | 7 | | `ERROR` | 400 | 3 |
+| `INFO` | 200 | 6 | | `CRITICAL` | 500 | 2 |
+| `NOTICE` | 250 | 5 | | `ALERT` | 550 | 1 |
+| `WARNING` | 300 | 4 | | `EMERGENCY` | 600 | 0 |
+
+Anywhere a level is accepted, `Level.parse` reads it: a `Level`, its value, an RFC 5424 severity,
+or a name in any case (`"error"`). Anything else raises `InvalidLevelError`.
+
+### Context
+
+`Context` is `Mapping[str, object]` — the second argument to every method above. Values are
+`object` because a caller may log anything; whatever writes the record normalises what it cannot
+serialise rather than refusing it. An exception to report goes under `EXCEPTION_KEY`:
+
+```python
+from xtr_logging_contracts import EXCEPTION_KEY
+
+logger.error("payment failed", {"order": order.id, EXCEPTION_KEY: error})
+```
+
+## What is not here
+
+Everything that *acts* on what was logged: `LogRecord`, `Logger`, `LoggerFactory`,
+`LoggingConfig`, the seventeen handlers, the processors, the formatters, ambient
+`bound_context()`, and the standard-library bridge. All of that is
+[xtr-logging](https://github.com/xterr/python-xtr-logging).
+
+`LogRecord` in particular belongs there, not here: it appears in no signature above. A library
+that logs never builds one or sees one — it is made inside the logger and consumed by handlers
+and processors, which are implementation.
+
+`HandlerInterface`, `ProcessorInterface` and `FormatterInterface` are deliberately absent for the
+same reason, plus one more: nothing outside `xtr-logging` implements them yet, and a contract
+package earns its stability by staying small. They move here when a third-party handler needs
+them — and `LogRecord` would move with them.
+
+## Errors
+
+| Error | Raised when |
+| --- | --- |
+| `LoggingError` | Never directly — the base every logging error derives from, `xtr-logging`'s included |
+| `InvalidLevelError` | A value names no level (also a `ValueError`) |
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-logging-contracts`; run the commands below from there. The `python-xtr-logging-contracts` repository is a
+read-only copy, so send issues and pull requests to the monorepo.
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run basedpyright
+uv run ty check
+uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_logging_contracts-1.0.0/README.md

@@ -0,0 +1,158 @@
+<div align="center">
+
+# xtr-logging-contracts
+
+**The logging contract, and nothing else — so a library that logs installs nothing else.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="core dependencies: 1" src="https://img.shields.io/badge/core%20deps-1-3FB950">
+<img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
+<img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
+
+</div>
+
+---
+
+## Why?
+
+A library that logs should not decide where records go. It takes a `LoggerInterface`, defaults to
+a `NullLogger`, and leaves handlers, formatters and configuration to the application that wires
+it.
+
+Which means a library needs the *contract*, not an implementation — and should not pay for one.
+Depending on [xtr-logging](https://github.com/xterr/python-xtr-logging) to annotate one parameter
+drags in a JSON codec, a clock and seventeen handlers the library never touches. This package is
+that dependency, reduced to what the seam is actually made of:
+
+- 🧩 **`LoggerInterface`** — eight severities plus `log()`, with a context mapping.
+- 🕳️ **`NullLogger`** — what makes logging optional for your callers.
+- 🪜 **`Level`** — the eight RFC 5424 severities, comparable as integers.
+- 🗂️ **`Context`** — the mapping every method takes, and the key an exception goes under.
+- 🪶 **One dependency** — `typing-extensions`, for `@override` on 3.11.
+
+```python
+from xtr_logging_contracts import LoggerInterface, NullLogger
+
+
+class Checkout:
+    def __init__(self, logger: LoggerInterface | None = None) -> None:
+        self._logger = logger or NullLogger()
+
+    def pay(self, order: Order) -> None:
+        self._logger.error("payment {order} failed", {"order": order.id})
+```
+
+## Install
+
+```sh
+uv add xtr-logging-contracts
+```
+
+Requires Python 3.11+.
+
+## Who installs what
+
+|  | Depends on |
+| --- | --- |
+| **A library that logs** | `xtr-logging-contracts` at runtime, `xtr-logging` as a dev dependency — its tests build real loggers and assert on a `TestHandler`. |
+| **An application** | `xtr-logging`, which implements this contract and wires channels, handlers and processors from configuration. |
+
+`xtr-logging` **re-exports** every symbol here rather than redefining it, so
+`xtr_logging.LoggerInterface is xtr_logging_contracts.LoggerInterface`. That identity is what lets
+a container register a logger under the interface and a library, which never imported
+`xtr-logging`, receive it.
+
+## The interface
+
+```python
+class LoggerInterface(Protocol):
+    def emergency(self, message: str, /, context: Context | None = None) -> None: ...
+    def alert(self, message: str, /, context: Context | None = None) -> None: ...
+    def critical(self, message: str, /, context: Context | None = None) -> None: ...
+    def error(self, message: str, /, context: Context | None = None) -> None: ...
+    def warning(self, message: str, /, context: Context | None = None) -> None: ...
+    def notice(self, message: str, /, context: Context | None = None) -> None: ...
+    def info(self, message: str, /, context: Context | None = None) -> None: ...
+    def debug(self, message: str, /, context: Context | None = None) -> None: ...
+    def log(self, level: LevelLike, message: str, /, context: Context | None = None) -> None: ...
+```
+
+The rules:
+
+- `context` is a mapping of anything. Formatters describe what they cannot serialise; a value
+  never makes logging fail.
+- An exception to report goes under `context["exception"]`.
+- `{key}` placeholders in the message are filled from context downstream, not by the logger, so a
+  handler can still see the template and the values apart.
+
+`AbstractLogger` implements the eight severity methods on top of `log()`, so an implementation
+writes one method. `LoggerAware` gives a class a `logger` that is a `NullLogger` until
+`set_logger()` is called.
+
+> ruff's `PLE1205` assumes every `logger.info(...)` is the standard library's and flags the
+> context mapping as a stray format argument. Ignore it in projects using this interface.
+
+### Levels
+
+| Level | Value | RFC 5424 | | Level | Value | RFC 5424 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `DEBUG` | 100 | 7 | | `ERROR` | 400 | 3 |
+| `INFO` | 200 | 6 | | `CRITICAL` | 500 | 2 |
+| `NOTICE` | 250 | 5 | | `ALERT` | 550 | 1 |
+| `WARNING` | 300 | 4 | | `EMERGENCY` | 600 | 0 |
+
+Anywhere a level is accepted, `Level.parse` reads it: a `Level`, its value, an RFC 5424 severity,
+or a name in any case (`"error"`). Anything else raises `InvalidLevelError`.
+
+### Context
+
+`Context` is `Mapping[str, object]` — the second argument to every method above. Values are
+`object` because a caller may log anything; whatever writes the record normalises what it cannot
+serialise rather than refusing it. An exception to report goes under `EXCEPTION_KEY`:
+
+```python
+from xtr_logging_contracts import EXCEPTION_KEY
+
+logger.error("payment failed", {"order": order.id, EXCEPTION_KEY: error})
+```
+
+## What is not here
+
+Everything that *acts* on what was logged: `LogRecord`, `Logger`, `LoggerFactory`,
+`LoggingConfig`, the seventeen handlers, the processors, the formatters, ambient
+`bound_context()`, and the standard-library bridge. All of that is
+[xtr-logging](https://github.com/xterr/python-xtr-logging).
+
+`LogRecord` in particular belongs there, not here: it appears in no signature above. A library
+that logs never builds one or sees one — it is made inside the logger and consumed by handlers
+and processors, which are implementation.
+
+`HandlerInterface`, `ProcessorInterface` and `FormatterInterface` are deliberately absent for the
+same reason, plus one more: nothing outside `xtr-logging` implements them yet, and a contract
+package earns its stability by staying small. They move here when a third-party handler needs
+them — and `LogRecord` would move with them.
+
+## Errors
+
+| Error | Raised when |
+| --- | --- |
+| `LoggingError` | Never directly — the base every logging error derives from, `xtr-logging`'s included |
+| `InvalidLevelError` | A value names no level (also a `ValueError`) |
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-logging-contracts`; run the commands below from there. The `python-xtr-logging-contracts` repository is a
+read-only copy, so send issues and pull requests to the monorepo.
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run basedpyright
+uv run ty check
+uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_logging_contracts-1.0.0/pyproject.toml

@@ -0,0 +1,140 @@
+[project]
+name = "xtr-logging-contracts"
+version = "1.0.0"
+description = "The logging contract: one interface, eight severities, and a logger that discards everything."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "logging",
+    "contracts",
+    "interface",
+    "protocol",
+    "structured-logging",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+dependencies = ["typing-extensions>=4.4"]
+
+[[project.authors]]
+name = "Razvan Ceana"
+email = "razvan@ceana.ro"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ty>=0.0.83",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = [
+    "src",
+    "tests",
+]
+exclude = [
+    "**/__pycache__",
+    "**/.venv",
+    "**/build",
+    "**/dist",
+    ".tmp",
+]
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    "TRY003",
+    "EM101",
+    "EM102",
+    "PLE1205",
+    "PLE1206",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+    "ARG",
+    "PLR2004",
+    "SLF001",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-config",
+    "--strict-markers",
+]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    '^\s*\.\.\.$',
+]

xtr_logging_contracts-1.0.0/pyproject.toml.orig

@@ -0,0 +1,139 @@
+[project]
+name = "xtr-logging-contracts"
+version = "1.0.0"
+description = "The logging contract: one interface, eight severities, and a logger that discards everything."
+readme = "README.md"
+authors = [
+    { name = "Razvan Ceana", email = "razvan@ceana.ro" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["logging", "contracts", "interface", "protocol", "structured-logging"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+# One dependency, for `@override` on 3.11, where typing has none. A library
+# that only logs should install nothing else.
+dependencies = [
+    "typing-extensions>=4.4",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ty>=0.0.83",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+# ─────────────────────────────────────────────────────────────────
+# basedpyright — typeCheckingMode = "all" sets every report flag to error
+# ─────────────────────────────────────────────────────────────────
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.venv", "**/build", "**/dist", ".tmp"]
+
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+
+# ─────────────────────────────────────────────────────────────────
+# ruff — select = ["ALL"], minimal justified ignores
+# ─────────────────────────────────────────────────────────────────
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Formatter conflicts (ruff documents these)
+    "COM812",
+    "ISC001",
+    # Mutually-exclusive docstring conventions; keep the modern one
+    "D203",
+    "D213",
+    # Project-specific noise
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    # Exceptions compose their own messages from typed fields; the string at a
+    # raise site is a data field. See xtr_logging_contracts/exception/.
+    "TRY003",
+    "EM101",
+    "EM102",
+    # A context mapping after the message is this interface's signature, not a stray
+    # %-format argument: these rules assume every `logger.info` is stdlib's.
+    "PLE1205",
+    "PLE1206",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",    # assert is the point of pytest
+    "ARG",     # fixtures look unused
+    "PLR2004", # magic numbers in test data
+    "SLF001",  # tests reach into privates
+    "D",       # test names are the docs
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+# ─────────────────────────────────────────────────────────────────
+# ty — a second opinion on the source
+# ─────────────────────────────────────────────────────────────────
+[tool.ty.src]
+include = ["src", "tests"]
+
+# ─────────────────────────────────────────────────────────────────
+# pytest
+# ─────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    # A Protocol body states a contract; there is nothing there to run.
+    "^\\s*\\.\\.\\.$",
+]

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/__init__.py

@@ -0,0 +1,55 @@
+"""The logging contract: what code that logs depends on, and nothing more.
+
+A library that logs should not decide where records go. It takes a
+:class:`LoggerInterface`, defaults to a :class:`NullLogger`, and leaves
+handlers, formatters and configuration to the application that wires it — so
+depending on this package costs a library nothing but the contract.
+
+What is here is only what appears in that contract: the interface itself, the
+:class:`Context` and :class:`Level` its methods accept, and the two ways of
+satisfying it — :class:`AbstractLogger` to implement it in one method, and
+:class:`NullLogger` to implement it in none. Everything that *acts* on what was
+logged — records, handlers, processors, formatters, configuration — is
+``xtr-logging``, which implements this contract and re-exports it, so the two
+are never two different objects.
+
+    from xtr_logging_contracts import LoggerInterface, NullLogger
+
+
+    class Checkout:
+        def __init__(self, logger: LoggerInterface | None = None) -> None:
+            self._logger = logger or NullLogger()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .abstract_logger import AbstractLogger
+from .context import EXCEPTION_KEY, Context
+from .exception import InvalidLevelError, LoggingError
+from .level import Level, LevelLike
+from .logger_aware import LoggerAware
+from .logger_aware_interface import LoggerAwareInterface
+from .logger_interface import LoggerInterface
+from .null_logger import NullLogger
+
+try:
+    __version__ = version("xtr-logging-contracts")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree or a vendored copy, with no installed
+    # metadata to read. Having no version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "EXCEPTION_KEY",
+    "AbstractLogger",
+    "Context",
+    "InvalidLevelError",
+    "Level",
+    "LevelLike",
+    "LoggerAware",
+    "LoggerAwareInterface",
+    "LoggerInterface",
+    "LoggingError",
+    "NullLogger",
+    "__version__",
+]

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/abstract_logger.py

@@ -0,0 +1,69 @@
+"""A logger whose eight severity methods all funnel into ``log``."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from .level import Level
+from .logger_interface import LoggerInterface
+
+if TYPE_CHECKING:
+    from .context import Context
+    from .level import LevelLike
+
+__all__ = ["AbstractLogger"]
+
+
+class AbstractLogger(LoggerInterface, ABC):
+    """Implements every severity method in terms of :meth:`log`.
+
+    Subclass it and write ``log`` alone.
+    """
+
+    @abstractmethod
+    @override
+    def log(self, level: LevelLike, message: str, /, context: Context | None = None) -> None:
+        """Log ``message`` at ``level``."""
+
+    @override
+    def emergency(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.EMERGENCY`."""
+        self.log(Level.EMERGENCY, message, context)
+
+    @override
+    def alert(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.ALERT`."""
+        self.log(Level.ALERT, message, context)
+
+    @override
+    def critical(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.CRITICAL`."""
+        self.log(Level.CRITICAL, message, context)
+
+    @override
+    def error(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.ERROR`."""
+        self.log(Level.ERROR, message, context)
+
+    @override
+    def warning(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.WARNING`."""
+        self.log(Level.WARNING, message, context)
+
+    @override
+    def notice(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.NOTICE`."""
+        self.log(Level.NOTICE, message, context)
+
+    @override
+    def info(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.INFO`."""
+        self.log(Level.INFO, message, context)
+
+    @override
+    def debug(self, message: str, /, context: Context | None = None) -> None:
+        """Log at :attr:`Level.DEBUG`."""
+        self.log(Level.DEBUG, message, context)

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/context.py

@@ -0,0 +1,23 @@
+"""The structured data a caller attaches to what it logs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final, TypeAlias
+
+__all__ = ["EXCEPTION_KEY", "Context"]
+
+Context: TypeAlias = Mapping[str, object]
+"""Structured data attached to what is logged.
+
+Values are ``object`` because a caller may log anything; an implementation
+normalises what it cannot serialise rather than refusing it.
+"""
+
+EXCEPTION_KEY: Final = "exception"
+"""The context key reserved for an exception to report.
+
+Part of the contract rather than of any implementation: a library puts the
+exception it is reporting here, and whatever writes the record knows to look
+for it.
+"""

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/exception/__init__.py

@@ -0,0 +1,17 @@
+"""The errors the contract itself can raise.
+
+Only two live here, because only two can be raised by the contract rather than
+by an implementation: :class:`LoggingError`, the root every logging error
+derives from — including every one ``xtr-logging`` adds — and
+:class:`InvalidLevelError`, which :meth:`Level.parse` raises. Catching
+:class:`LoggingError` therefore catches anything logging can go wrong with,
+whichever package raised it.
+"""
+
+from .invalid_level_error import InvalidLevelError
+from .logging_error import LoggingError
+
+__all__ = [
+    "InvalidLevelError",
+    "LoggingError",
+]

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/exception/invalid_level_error.py

@@ -0,0 +1,26 @@
+"""A value names no log level."""
+
+from __future__ import annotations
+
+from .logging_error import LoggingError
+
+__all__ = ["InvalidLevelError"]
+
+_ACCEPTED = "a Level, a level name, a value from 100 to 600, or an RFC 5424 severity from 0 to 7"
+
+
+class InvalidLevelError(LoggingError, ValueError):
+    """A value names no log level.
+
+    Also a :class:`ValueError`, which is what lets a configuration parser
+    report the field that held it.
+    """
+
+    value: int | str
+
+    def __init__(self, value: int | str) -> None:
+        """Record the value that could not be read as a level."""
+        self.value = value
+        super().__init__(
+            f"{value!r} is not a log level; expected {_ACCEPTED}",
+        )

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/exception/logging_error.py

@@ -0,0 +1,14 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["LoggingError"]
+
+
+class LoggingError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything logging can go wrong with; catch a subclass
+    to handle one cause. Every subclass carries the data a caller needs as
+    typed attributes and composes its own message from them.
+    """

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/level.py

@@ -0,0 +1,108 @@
+"""The eight RFC 5424 severities, valued 100 to 600.
+
+The values leave room between them, so a level added later still sorts where
+it belongs, and they compare as integers: ``Level.ERROR > Level.WARNING``.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import TYPE_CHECKING, Final, TypeAlias
+
+from .exception.invalid_level_error import InvalidLevelError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["Level", "LevelLike"]
+
+_LOWEST_RFC5424: Final = 0
+_HIGHEST_RFC5424: Final = 7
+
+
+class Level(IntEnum):
+    """A log level, ordered from least to most severe."""
+
+    DEBUG = 100
+    INFO = 200
+    NOTICE = 250
+    WARNING = 300
+    ERROR = 400
+    CRITICAL = 500
+    ALERT = 550
+    EMERGENCY = 600
+
+    @classmethod
+    def parse(cls, value: LevelLike) -> Level:
+        """Read any accepted spelling of a level.
+
+        Accepts a :class:`Level`, its value (``400``), an RFC 5424 severity
+        (``3``), or a name in any case (``"error"``, ``"ERROR"``).
+
+        Raises:
+            InvalidLevelError: If ``value`` names no level.
+        """
+        match value:
+            case Level():
+                return value
+            case bool():
+                raise InvalidLevelError(value)
+            case int():
+                if _LOWEST_RFC5424 <= value <= _HIGHEST_RFC5424:
+                    return _BY_RFC5424[value]
+                if value in _BY_VALUE:
+                    return _BY_VALUE[value]
+                raise InvalidLevelError(value)
+            case str():
+                return cls.from_name(value)
+
+    @classmethod
+    def from_name(cls, name: str) -> Level:
+        """Return the level called ``name``, in any case.
+
+        Raises:
+            InvalidLevelError: If no level has that name.
+        """
+        found = cls.__members__.get(name.upper())
+        if found is None:
+            raise InvalidLevelError(name)
+        return found
+
+    @property
+    def lower_name(self) -> str:
+        """The name of this level in lower case, as configuration writes it."""
+        return self.name.lower()
+
+    @property
+    def rfc5424(self) -> int:
+        """The RFC 5424 severity: 0 for EMERGENCY through 7 for DEBUG."""
+        return _TO_RFC5424[self]
+
+    def includes(self, other: Level) -> bool:
+        """Whether a threshold of this level lets ``other`` through."""
+        return self <= other
+
+    def is_higher_than(self, other: Level) -> bool:
+        """Whether this level is strictly more severe than ``other``."""
+        return self > other
+
+    def is_lower_than(self, other: Level) -> bool:
+        """Whether this level is strictly less severe than ``other``."""
+        return self < other
+
+
+LevelLike: TypeAlias = Level | int | str
+"""Anything :meth:`Level.parse` accepts."""
+
+_TO_RFC5424: Final[Mapping[Level, int]] = {
+    Level.EMERGENCY: 0,
+    Level.ALERT: 1,
+    Level.CRITICAL: 2,
+    Level.ERROR: 3,
+    Level.WARNING: 4,
+    Level.NOTICE: 5,
+    Level.INFO: 6,
+    Level.DEBUG: 7,
+}
+_BY_RFC5424: Final[Mapping[int, Level]] = {rfc: level for level, rfc in _TO_RFC5424.items()}
+_BY_VALUE: Final[Mapping[int, Level]] = {level.value: level for level in Level}

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/logger_aware.py

@@ -0,0 +1,36 @@
+"""A mixin giving a class a logger that is never missing."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from typing_extensions import override
+
+from .logger_aware_interface import LoggerAwareInterface
+from .null_logger import NullLogger
+
+if TYPE_CHECKING:
+    from .logger_interface import LoggerInterface
+
+__all__ = ["LoggerAware"]
+
+
+class LoggerAware(LoggerAwareInterface):
+    """Holds a logger, defaulting to a :class:`NullLogger`.
+
+    Code in the class logs through :attr:`logger` without checking whether one
+    was ever set.
+    """
+
+    _default: ClassVar[LoggerInterface] = NullLogger()
+    _logger: LoggerInterface | None = None
+
+    @property
+    def logger(self) -> LoggerInterface:
+        """The logger set last, or one that discards everything."""
+        return self._logger if self._logger is not None else self._default
+
+    @override
+    def set_logger(self, logger: LoggerInterface, /) -> None:
+        """Log through ``logger`` from now on."""
+        self._logger = logger

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/logger_aware_interface.py

@@ -0,0 +1,23 @@
+"""Something that can be handed a logger after it is built."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .logger_interface import LoggerInterface
+
+__all__ = ["LoggerAwareInterface"]
+
+
+@runtime_checkable
+class LoggerAwareInterface(Protocol):
+    """Accepts a logger through a setter.
+
+    Prefer a constructor argument. This exists for objects a framework builds
+    for you, where the constructor is not yours to extend.
+    """
+
+    def set_logger(self, logger: LoggerInterface, /) -> None:
+        """Log through ``logger`` from now on."""
+        ...

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/logger_interface.py

@@ -0,0 +1,75 @@
+"""The logging surface code writes through."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .context import Context
+    from .level import LevelLike
+
+__all__ = ["LoggerInterface"]
+
+
+@runtime_checkable
+class LoggerInterface(Protocol):
+    """Writes messages at one of eight severities, with structured context.
+
+    The only type code that logs should depend on. Whatever implements it —
+    a channel of ``xtr-logging``'s ``Logger``, a
+    :class:`~xtr_logging_contracts.null_logger.NullLogger`, an adapter over a
+    standard library logger — can be swapped without touching a call site.
+
+    The rules:
+
+    - ``message`` may hold ``{key}`` placeholders naming entries of
+      ``context``. The logger does not substitute them; something later in the
+      pipeline does — ``xtr-logging``'s ``PlaceholderProcessor`` — so a handler
+      may still see the template and the values apart.
+    - An exception to report goes under ``context["exception"]``.
+    - Context is data, never code: an implementation must not fail because of
+      what it holds.
+
+    ``message`` is positional-only, so an implementation may name it freely;
+    ``context`` may also be passed by keyword.
+    """
+
+    def emergency(self, message: str, /, context: Context | None = None) -> None:
+        """The system is unusable."""
+        ...
+
+    def alert(self, message: str, /, context: Context | None = None) -> None:
+        """Action must be taken immediately — the whole site is down, say."""
+        ...
+
+    def critical(self, message: str, /, context: Context | None = None) -> None:
+        """A critical condition, such as an unavailable component."""
+        ...
+
+    def error(self, message: str, /, context: Context | None = None) -> None:
+        """A runtime error that needs no immediate action but must be seen."""
+        ...
+
+    def warning(self, message: str, /, context: Context | None = None) -> None:
+        """Something exceptional that is not an error, like a deprecated call."""
+        ...
+
+    def notice(self, message: str, /, context: Context | None = None) -> None:
+        """A normal but significant event."""
+        ...
+
+    def info(self, message: str, /, context: Context | None = None) -> None:
+        """An interesting event, such as a user logging in."""
+        ...
+
+    def debug(self, message: str, /, context: Context | None = None) -> None:
+        """Detailed information for debugging."""
+        ...
+
+    def log(self, level: LevelLike, message: str, /, context: Context | None = None) -> None:
+        """Log at ``level``, given in any form :meth:`Level.parse` accepts.
+
+        Raises:
+            InvalidLevelError: If ``level`` names no level.
+        """
+        ...

xtr_logging_contracts-1.0.0/src/xtr_logging_contracts/null_logger.py

@@ -0,0 +1,32 @@
+"""A logger that discards everything."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .abstract_logger import AbstractLogger
+
+if TYPE_CHECKING:
+    from .context import Context
+    from .level import LevelLike
+
+__all__ = ["NullLogger"]
+
+
+@final
+class NullLogger(AbstractLogger):
+    """Discards everything it is given.
+
+    The default for a library that accepts a logger: logging stays optional
+    for its callers, and the library's code never has to ask whether it has
+    one.
+    """
+
+    __slots__ = ()
+
+    @override
+    def log(self, level: LevelLike, message: str, /, context: Context | None = None) -> None:
+        """Do nothing — not even check ``level``, which costs a call site nothing."""
+        del level, message, context