oaknut-exception 11.0.0__tar.gz

oaknut_exception-11.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+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.

oaknut_exception-11.0.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: oaknut-exception
+Version: 11.0.0
+Summary: Categorised exceptions and CLI error-reporting boundary for the oaknut package family.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: exit-codes>=1.3
+Dynamic: license-file
+
+# oaknut-exception
+
+Categorised exceptions and a CLI error-reporting boundary for the
+`oaknut-*` family of packages.
+
+The package defines a small exception hierarchy that every other
+`oaknut-*` package's domain errors slot into:
+
+- `OaknutException` — root of the hierarchy. Carries an `exit_code`
+  property derived from the BSD `sysexits.h` set (via the `exit-codes`
+  package).
+- `DataError` — the operation failed because of the *data* it was given
+  (a user-supplied path, a corrupted on-disc structure, an unsupported
+  filetype). No traceback at the CLI boundary.
+- `ConfigurationError` — the operation failed because of a runtime
+  environment / configuration issue. No traceback at the CLI boundary.
+- `InternalError` — the operation failed because something went wrong
+  inside the library. **Traceback retained** at the CLI boundary so
+  the report-an-issue path is obvious.
+
+Plus a single error-handling boundary helper:
+
+- `handled_errors` — a context manager (also usable as a decorator)
+  that catches `DataError` and `ConfigurationError`, prints them via a
+  caller-supplied printer, and exits with the most appropriate
+  `ExitCode`. `InternalError` and unexpected exceptions propagate so
+  their tracebacks reach the user. `KeyboardInterrupt` exits with the
+  conventional `128 + SIGINT` status.
+
+This package is what every `oaknut-disc`-like CLI uses to map library
+errors onto stable exit codes without dropping into try/except in every
+command.
+
+See the [oaknut documentation](https://rob-smallshire.github.io/oaknut/)
+for the full API reference.

oaknut_exception-11.0.0/README.md

@@ -0,0 +1,35 @@
+# oaknut-exception
+
+Categorised exceptions and a CLI error-reporting boundary for the
+`oaknut-*` family of packages.
+
+The package defines a small exception hierarchy that every other
+`oaknut-*` package's domain errors slot into:
+
+- `OaknutException` — root of the hierarchy. Carries an `exit_code`
+  property derived from the BSD `sysexits.h` set (via the `exit-codes`
+  package).
+- `DataError` — the operation failed because of the *data* it was given
+  (a user-supplied path, a corrupted on-disc structure, an unsupported
+  filetype). No traceback at the CLI boundary.
+- `ConfigurationError` — the operation failed because of a runtime
+  environment / configuration issue. No traceback at the CLI boundary.
+- `InternalError` — the operation failed because something went wrong
+  inside the library. **Traceback retained** at the CLI boundary so
+  the report-an-issue path is obvious.
+
+Plus a single error-handling boundary helper:
+
+- `handled_errors` — a context manager (also usable as a decorator)
+  that catches `DataError` and `ConfigurationError`, prints them via a
+  caller-supplied printer, and exits with the most appropriate
+  `ExitCode`. `InternalError` and unexpected exceptions propagate so
+  their tracebacks reach the user. `KeyboardInterrupt` exits with the
+  conventional `128 + SIGINT` status.
+
+This package is what every `oaknut-disc`-like CLI uses to map library
+errors onto stable exit codes without dropping into try/except in every
+command.
+
+See the [oaknut documentation](https://rob-smallshire.github.io/oaknut/)
+for the full API reference.

oaknut_exception-11.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-exception"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Categorised exceptions and CLI error-reporting boundary for the oaknut package family."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "exit-codes>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.exception.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_exception-11.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_exception-11.0.0/src/oaknut/exception/__init__.py

@@ -0,0 +1,281 @@
+"""Categorised exceptions and CLI error-reporting boundary for oaknut.
+
+This module supplies three things every ``oaknut-*`` library and CLI
+shares:
+
+1. A small exception hierarchy — :class:`OaknutException` root and the
+   :class:`DataError`/:class:`ConfigurationError`/:class:`InternalError`
+   category subclasses. Each carries a stable :class:`ExitCode` so the
+   library decides how an error classifies; the CLI just observes.
+
+2. A :func:`handled_errors` context manager (also usable as a
+   decorator, via :class:`contextlib.ContextDecorator`) that catches
+   :class:`DataError` and :class:`ConfigurationError`, prints them via
+   a caller-supplied printer, and exits with the most appropriate
+   :class:`ExitCode`. :class:`InternalError` and other exceptions
+   propagate so their tracebacks reach the user. ``KeyboardInterrupt``
+   exits with the conventional ``128 + SIGINT`` status.
+
+3. A :func:`render_error` helper that walks an exception's ``__cause__``
+   chain and any ``__notes__`` so the boundary printer can format the
+   full story rather than just the leaf message.
+
+The design is intentionally close to ``demonstrable-exception`` — we
+have permission to borrow the shape — with a few opinionated
+refinements: per-instance exit-code override, deterministic
+first-wins selection across exception groups, an explicit
+:func:`render_error` separation, and a printer protocol that is easy
+to wrap with format-aware adapters at the CLI layer.
+"""
+
+from __future__ import annotations
+
+import signal
+import sys
+from collections.abc import Callable, Iterable
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+from exit_codes import ExitCode
+
+__version__ = "11.0.0"
+
+__all__ = [
+    "OaknutException",
+    "DataError",
+    "ConfigurationError",
+    "InternalError",
+    "Printer",
+    "handled_errors",
+    "render_error",
+    "exit_code_for",
+]
+
+
+# ---------------------------------------------------------------------------
+# Exception hierarchy
+# ---------------------------------------------------------------------------
+
+
+class OaknutException(Exception):
+    """Base class for every domain exception in the oaknut family.
+
+    Do not raise this directly — raise one of the category subclasses
+    (:class:`DataError`, :class:`ConfigurationError`,
+    :class:`InternalError`) or a domain-specific class that derives
+    from one of them.
+
+    Every instance has an :attr:`exit_code` of type :class:`ExitCode`.
+    The class attribute :attr:`_exit_code` provides the default for a
+    given category or subclass; a constructor argument overrides it for
+    a single instance::
+
+        raise DataError("path not found: $.HELLO", exit_code=ExitCode.OS_FILE)
+
+    The override is what lets a library raise the right BSD code for a
+    specific case (path-not-found vs. permission-denied vs. file-full)
+    without needing a private exception class for every variant.
+    """
+
+    #: The default :class:`ExitCode` for this class. Subclasses override.
+    _exit_code: ExitCode = ExitCode.SOFTWARE
+
+    def __init__(self, *args: object, exit_code: Optional[ExitCode] = None) -> None:
+        super().__init__(*args)
+        self._instance_exit_code: Optional[ExitCode] = exit_code
+
+    @property
+    def exit_code(self) -> ExitCode:
+        """The :class:`ExitCode` that should accompany this error.
+
+        The per-instance override, if one was passed to the
+        constructor; otherwise the class default.
+        """
+        if self._instance_exit_code is not None:
+            return self._instance_exit_code
+        return self._exit_code
+
+
+class DataError(OaknutException):
+    """An error caused by the *data* the operation was asked to act on.
+
+    Covers both user input (a path that doesn't exist, an invalid name,
+    a file the user pointed at) and on-disc data (a corrupted catalogue,
+    an inconsistent free-space map). The CLI boundary prints these
+    without a stack trace — they are not bugs, they are problems with
+    the input.
+    """
+
+    _exit_code = ExitCode.DATA_ERR
+
+
+class ConfigurationError(OaknutException):
+    """An error caused by a runtime-environment configuration issue.
+
+    Things like "configured cache directory is not writable", "required
+    extension binary not on PATH", or "config file references a missing
+    profile". The CLI boundary prints these without a stack trace —
+    they are problems with the *setup*, not the *data* or the code.
+    """
+
+    _exit_code = ExitCode.CONFIG
+
+
+class InternalError(OaknutException):
+    """An error caused by something going unexpectedly wrong inside the library.
+
+    The CLI boundary lets these propagate with a stack trace because
+    that is the report-an-issue signal: there is no clean way to
+    explain it to a user — the maintainers need the traceback to fix
+    the root cause.
+    """
+
+    _exit_code = ExitCode.SOFTWARE
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+#: A printer callable. Takes the rendered error message string and a
+#: hint about whether the rendering came from the leaf exception
+#: (``False``) or a chained cause / note (``True``). CLIs typically
+#: render leaves in red and continuations in a muted colour.
+Printer = Callable[[str, bool], None]
+
+
+def exit_code_for(exc: BaseException) -> ExitCode:
+    """Return the :class:`ExitCode` for *exc*.
+
+    For :class:`OaknutException` instances, returns the instance's
+    :attr:`~OaknutException.exit_code`. For everything else, returns
+    :data:`ExitCode.SOFTWARE` so an unexpected exception still maps to
+    a sensible non-zero code if a caller chooses to swallow it.
+    """
+    if isinstance(exc, OaknutException):
+        return exc.exit_code
+    return ExitCode.SOFTWARE
+
+
+def render_error(exc: BaseException) -> Iterator[tuple[str, bool]]:
+    """Yield ``(line, is_continuation)`` pairs for *exc* and its causes.
+
+    The leaf exception's ``str()`` is yielded first with
+    ``is_continuation=False``. Any ``__notes__`` (PEP 678, Python 3.11+)
+    follow with ``is_continuation=True``. If the exception was raised
+    with ``raise X from Y``, the cause chain is walked and rendered
+    recursively, each line prefixed with ``"caused by: "``.
+
+    Callers feed each ``(line, is_continuation)`` pair to a
+    :data:`Printer` and the printer decides the styling — the splitting
+    is the same regardless of whether the printer is colour-aware,
+    pipe-friendly, or JSON.
+    """
+    yield str(exc) or type(exc).__name__, False
+    for note in getattr(exc, "__notes__", ()):
+        yield str(note), True
+
+    cause = exc.__cause__
+    while cause is not None:
+        yield f"caused by: {cause or type(cause).__name__}", True
+        for note in getattr(cause, "__notes__", ()):
+            yield str(note), True
+        cause = cause.__cause__
+
+
+# ---------------------------------------------------------------------------
+# handled_errors — the CLI boundary helper
+# ---------------------------------------------------------------------------
+
+
+DEFAULT_EXIT_CODE = ExitCode.SOFTWARE
+
+
+def _default_printer(line: str, _is_continuation: bool) -> None:
+    print(line, file=sys.stderr)
+
+
+@contextmanager
+def handled_errors(
+    printer: Optional[Printer] = None,
+    *,
+    exit_func: Callable[[int], None] = sys.exit,
+    debug: bool = False,
+) -> Iterator[None]:
+    """Catch :class:`DataError`/:class:`ConfigurationError`, print, exit.
+
+    Use at the CLI boundary, either as a context manager wrapping a
+    body of work::
+
+        with handled_errors(print_error):
+            do_the_work()
+
+    or — because :func:`contextlib.contextmanager` produces a
+    :class:`contextlib.ContextDecorator` — as a decorator on a Click
+    command callback::
+
+        @handled_errors(print_error)
+        def cmd(...): ...
+
+    Behaviour:
+
+    - :class:`DataError` / :class:`ConfigurationError` and any
+      :class:`ExceptionGroup` containing them are caught, each leaf
+      rendered via :func:`render_error`, and the process is exited
+      with the **first** leaf's exit code (deterministic; matches the
+      order errors were raised).
+    - :class:`InternalError` and any other exception propagate.
+    - ``KeyboardInterrupt`` exits with ``128 + SIGINT`` after printing
+      itself.
+    - When *debug* is ``True``, :class:`DataError` and
+      :class:`ConfigurationError` are *re-raised* after being printed
+      so the caller still sees the full Python traceback — useful
+      during development; off by default for users.
+
+    *printer* defaults to a plain stderr writer. *exit_func* defaults
+    to :func:`sys.exit`; tests inject a custom function to capture the
+    code without terminating the test runner.
+    """
+    if printer is None:
+        printer = _default_printer
+
+    pending_exit: Optional[int] = None
+    pending_reraise: Optional[BaseException] = None
+
+    try:
+        yield
+    except* (DataError, ConfigurationError) as group:
+        leaves = list(_iter_leaves(group))
+        for leaf in leaves:
+            for line, is_continuation in render_error(leaf):
+                printer(line, is_continuation)
+        if debug and leaves:
+            pending_reraise = leaves[0]
+        else:
+            # First-wins: the first leaf's code, falling back to the
+            # category default if somehow none classify.
+            first_code = next(
+                (exit_code_for(leaf) for leaf in leaves if isinstance(leaf, OaknutException)),
+                DEFAULT_EXIT_CODE,
+            )
+            pending_exit = int(first_code)
+    except* KeyboardInterrupt as group:
+        for leaf in _iter_leaves(group):
+            for line, is_continuation in render_error(leaf):
+                printer(line, is_continuation)
+        pending_exit = 128 + signal.SIGINT
+
+    if pending_reraise is not None:
+        raise pending_reraise
+    if pending_exit is not None:
+        exit_func(pending_exit)
+
+
+def _iter_leaves(group: BaseExceptionGroup) -> Iterable[BaseException]:
+    """Yield leaf exceptions from a (possibly nested) exception group."""
+    for exc in group.exceptions:
+        if isinstance(exc, BaseExceptionGroup):
+            yield from _iter_leaves(exc)
+        else:
+            yield exc

oaknut_exception-11.0.0/src/oaknut_exception.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: oaknut-exception
+Version: 11.0.0
+Summary: Categorised exceptions and CLI error-reporting boundary for the oaknut package family.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: exit-codes>=1.3
+Dynamic: license-file
+
+# oaknut-exception
+
+Categorised exceptions and a CLI error-reporting boundary for the
+`oaknut-*` family of packages.
+
+The package defines a small exception hierarchy that every other
+`oaknut-*` package's domain errors slot into:
+
+- `OaknutException` — root of the hierarchy. Carries an `exit_code`
+  property derived from the BSD `sysexits.h` set (via the `exit-codes`
+  package).
+- `DataError` — the operation failed because of the *data* it was given
+  (a user-supplied path, a corrupted on-disc structure, an unsupported
+  filetype). No traceback at the CLI boundary.
+- `ConfigurationError` — the operation failed because of a runtime
+  environment / configuration issue. No traceback at the CLI boundary.
+- `InternalError` — the operation failed because something went wrong
+  inside the library. **Traceback retained** at the CLI boundary so
+  the report-an-issue path is obvious.
+
+Plus a single error-handling boundary helper:
+
+- `handled_errors` — a context manager (also usable as a decorator)
+  that catches `DataError` and `ConfigurationError`, prints them via a
+  caller-supplied printer, and exits with the most appropriate
+  `ExitCode`. `InternalError` and unexpected exceptions propagate so
+  their tracebacks reach the user. `KeyboardInterrupt` exits with the
+  conventional `128 + SIGINT` status.
+
+This package is what every `oaknut-disc`-like CLI uses to map library
+errors onto stable exit codes without dropping into try/except in every
+command.
+
+See the [oaknut documentation](https://rob-smallshire.github.io/oaknut/)
+for the full API reference.

oaknut_exception-11.0.0/src/oaknut_exception.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/exception/__init__.py
+src/oaknut_exception.egg-info/PKG-INFO
+src/oaknut_exception.egg-info/SOURCES.txt
+src/oaknut_exception.egg-info/dependency_links.txt
+src/oaknut_exception.egg-info/requires.txt
+src/oaknut_exception.egg-info/top_level.txt
+tests/test_exception_hierarchy.py
+tests/test_handled_errors.py
+tests/test_render_error.py

oaknut_exception-11.0.0/src/oaknut_exception.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_exception-11.0.0/src/oaknut_exception.egg-info/requires.txt

@@ -0,0 +1 @@
+exit-codes>=1.3

oaknut_exception-11.0.0/src/oaknut_exception.egg-info/top_level.txt

@@ -0,0 +1 @@
+oaknut

oaknut_exception-11.0.0/tests/test_exception_hierarchy.py

@@ -0,0 +1,95 @@
+"""Tests for the OaknutException hierarchy and exit-code resolution."""
+
+from __future__ import annotations
+
+import pytest
+from exit_codes import ExitCode
+from oaknut.exception import (
+    ConfigurationError,
+    DataError,
+    InternalError,
+    OaknutException,
+    exit_code_for,
+)
+
+
+class TestCategoryDefaults:
+    """Each category exposes its sysexits.h default through `.exit_code`."""
+
+    def test_data_error_default(self) -> None:
+        assert DataError("nope").exit_code is ExitCode.DATA_ERR
+
+    def test_configuration_error_default(self) -> None:
+        assert ConfigurationError("bad cfg").exit_code is ExitCode.CONFIG
+
+    def test_internal_error_default(self) -> None:
+        assert InternalError("bug").exit_code is ExitCode.SOFTWARE
+
+    def test_root_default(self) -> None:
+        # The root is meant to be subclassed, but if anyone instantiates
+        # it directly the fallback should be SOFTWARE so the resulting
+        # exit code is at least non-zero and not misleadingly DATA_ERR.
+        assert OaknutException("raw").exit_code is ExitCode.SOFTWARE
+
+
+class TestInstanceOverride:
+    """A constructor `exit_code=` overrides the class default for one
+    instance, without needing a private subclass per variant."""
+
+    def test_override_takes_precedence(self) -> None:
+        exc = DataError("missing", exit_code=ExitCode.OS_FILE)
+        assert exc.exit_code is ExitCode.OS_FILE
+
+    def test_override_is_per_instance(self) -> None:
+        overridden = DataError("missing", exit_code=ExitCode.OS_FILE)
+        default = DataError("missing")
+        assert overridden.exit_code is ExitCode.OS_FILE
+        assert default.exit_code is ExitCode.DATA_ERR
+
+
+class TestSubclassDefault:
+    """A subclass can override `_exit_code` to pin a more specific code
+    for every instance of that class. This is the canonical pattern
+    used by oaknut-file's FSError tree."""
+
+    class _PathNotFound(DataError):
+        _exit_code = ExitCode.OS_FILE
+
+    def test_subclass_uses_its_own_default(self) -> None:
+        assert self._PathNotFound("hi").exit_code is ExitCode.OS_FILE
+
+    def test_subclass_default_still_overridable(self) -> None:
+        exc = self._PathNotFound("hi", exit_code=ExitCode.NO_PERM)
+        assert exc.exit_code is ExitCode.NO_PERM
+
+
+class TestExitCodeFor:
+    """The free function form is what CLI boundary code uses when it
+    only has an exception object, not a known type."""
+
+    def test_oaknut_exception_returns_its_code(self) -> None:
+        exc = DataError("x", exit_code=ExitCode.OS_FILE)
+        assert exit_code_for(exc) is ExitCode.OS_FILE
+
+    def test_non_oaknut_exception_falls_back_to_software(self) -> None:
+        # A library that raises a stdlib exception by accident still
+        # gets a non-zero code if the boundary catches it explicitly.
+        assert exit_code_for(ValueError("not ours")) is ExitCode.SOFTWARE
+
+
+class TestInheritance:
+    """Sanity: the category structure is what callers expect."""
+
+    def test_categories_share_root(self) -> None:
+        assert issubclass(DataError, OaknutException)
+        assert issubclass(ConfigurationError, OaknutException)
+        assert issubclass(InternalError, OaknutException)
+
+    def test_categories_are_distinct(self) -> None:
+        assert not issubclass(DataError, ConfigurationError)
+        assert not issubclass(ConfigurationError, InternalError)
+        assert not issubclass(DataError, InternalError)
+
+    def test_caught_as_OaknutException(self) -> None:
+        with pytest.raises(OaknutException):
+            raise DataError("test")

oaknut_exception-11.0.0/tests/test_handled_errors.py

@@ -0,0 +1,174 @@
+"""Tests for the handled_errors boundary helper."""
+
+from __future__ import annotations
+
+import signal
+
+import pytest
+from exit_codes import ExitCode
+from oaknut.exception import (
+    ConfigurationError,
+    DataError,
+    InternalError,
+    handled_errors,
+)
+
+
+def _capture_exit():
+    """Return (captured_codes, exit_func) so tests can intercept sys.exit."""
+    captured: list[int] = []
+    return captured, captured.append
+
+
+def _capture_printer():
+    """Return (lines, printer) capturing (text, is_continuation) pairs."""
+    lines: list[tuple[str, bool]] = []
+
+    def printer(text: str, is_continuation: bool) -> None:
+        lines.append((text, is_continuation))
+
+    return lines, printer
+
+
+class TestNormalCompletion:
+    def test_no_error_does_not_exit(self) -> None:
+        codes, exit_func = _capture_exit()
+        with handled_errors(exit_func=exit_func):
+            pass
+        assert codes == []
+
+
+class TestDataError:
+    def test_caught_and_exits_with_data_code(self) -> None:
+        codes, exit_func = _capture_exit()
+        lines, printer = _capture_printer()
+        with handled_errors(printer, exit_func=exit_func):
+            raise DataError("bad input")
+        assert codes == [int(ExitCode.DATA_ERR)]
+        assert lines == [("bad input", False)]
+
+    def test_per_instance_override_is_honoured(self) -> None:
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+        with handled_errors(printer, exit_func=exit_func):
+            raise DataError("missing", exit_code=ExitCode.OS_FILE)
+        assert codes == [int(ExitCode.OS_FILE)]
+
+
+class TestConfigurationError:
+    def test_caught_and_exits_with_config_code(self) -> None:
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+        with handled_errors(printer, exit_func=exit_func):
+            raise ConfigurationError("bad config")
+        assert codes == [int(ExitCode.CONFIG)]
+
+
+class TestInternalError:
+    """InternalError propagates — the traceback is the report-an-issue signal."""
+
+    def test_propagates_unchanged(self) -> None:
+        codes, exit_func = _capture_exit()
+        with pytest.raises(InternalError, match="oops"):
+            with handled_errors(exit_func=exit_func):
+                raise InternalError("oops")
+        # No call to exit_func because the error propagated.
+        assert codes == []
+
+
+class TestOtherExceptions:
+    """Anything outside the OaknutException tree is left alone."""
+
+    def test_value_error_propagates(self) -> None:
+        codes, exit_func = _capture_exit()
+        with pytest.raises(ValueError):
+            with handled_errors(exit_func=exit_func):
+                raise ValueError("not ours")
+        assert codes == []
+
+
+class TestKeyboardInterrupt:
+    def test_caught_and_exits_with_128_plus_sigint(self) -> None:
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+        with handled_errors(printer, exit_func=exit_func):
+            raise KeyboardInterrupt
+        assert codes == [128 + signal.SIGINT]
+
+
+class TestExceptionGroup:
+    """The except* branches in handled_errors mean an ExceptionGroup
+    of categorised errors is also handled correctly."""
+
+    def test_group_of_data_errors_uses_first_code(self) -> None:
+        codes, exit_func = _capture_exit()
+        lines, printer = _capture_printer()
+        with handled_errors(printer, exit_func=exit_func):
+            raise ExceptionGroup(
+                "two errors",
+                [
+                    DataError("first", exit_code=ExitCode.OS_FILE),
+                    DataError("second", exit_code=ExitCode.NO_PERM),
+                ],
+            )
+        # First-wins: deterministic, matches reading order.
+        assert codes == [int(ExitCode.OS_FILE)]
+        # Both errors were rendered.
+        assert ("first", False) in lines
+        assert ("second", False) in lines
+
+    def test_mixed_group_with_internal_error_propagates_partial(self) -> None:
+        # Python's except* automatically splits the group: the
+        # DataError half is consumed by our handler, the InternalError
+        # half propagates as its own group.
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+        with pytest.raises(ExceptionGroup) as exc_info:
+            with handled_errors(printer, exit_func=exit_func):
+                raise ExceptionGroup(
+                    "mixed",
+                    [DataError("data"), InternalError("internal")],
+                )
+        # The propagated group should contain only the internal half.
+        leaves = [type(leaf).__name__ for leaf in exc_info.value.exceptions]
+        assert leaves == ["InternalError"]
+
+
+class TestDebugMode:
+    """In debug mode, even DataError gets re-raised after being printed
+    so developers see the full traceback."""
+
+    def test_data_error_reraised_after_printing(self) -> None:
+        codes, exit_func = _capture_exit()
+        lines, printer = _capture_printer()
+        with pytest.raises(DataError, match="for the dev"):
+            with handled_errors(printer, exit_func=exit_func, debug=True):
+                raise DataError("for the dev")
+        # Printed once before re-raising.
+        assert lines == [("for the dev", False)]
+        # No exit call because we re-raised.
+        assert codes == []
+
+    def test_internal_error_unaffected_by_debug(self) -> None:
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+        with pytest.raises(InternalError):
+            with handled_errors(printer, exit_func=exit_func, debug=True):
+                raise InternalError("propagates either way")
+        assert codes == []
+
+
+class TestDecoratorUsage:
+    """contextmanager from contextlib produces ContextDecorator, so the
+    helper is usable as @handled_errors() too."""
+
+    def test_decorates_a_function(self) -> None:
+        codes, exit_func = _capture_exit()
+        _, printer = _capture_printer()
+
+        @handled_errors(printer, exit_func=exit_func)
+        def boom():
+            raise DataError("decorated")
+
+        boom()
+        assert codes == [int(ExitCode.DATA_ERR)]

oaknut_exception-11.0.0/tests/test_render_error.py

@@ -0,0 +1,66 @@
+"""Tests for render_error — the cause-chain + notes walker."""
+
+from __future__ import annotations
+
+from oaknut.exception import DataError, InternalError, render_error
+
+
+def _lines(exc):
+    return list(render_error(exc))
+
+
+class TestLeaf:
+    def test_message_is_first_pair(self) -> None:
+        line, is_continuation = _lines(DataError("hello"))[0]
+        assert line == "hello"
+        assert is_continuation is False
+
+    def test_empty_message_uses_class_name(self) -> None:
+        # str(exc) is empty when no args are passed; the renderer
+        # falls back to the class name so the user sees *something*.
+        line, _ = _lines(InternalError())[0]
+        assert line == "InternalError"
+
+
+class TestNotes:
+    def test_notes_render_as_continuations(self) -> None:
+        exc = DataError("primary")
+        exc.add_note("first note")
+        exc.add_note("second note")
+        lines = _lines(exc)
+        assert lines == [
+            ("primary", False),
+            ("first note", True),
+            ("second note", True),
+        ]
+
+
+class TestCauseChain:
+    def test_walks_the_cause_chain(self) -> None:
+        # Build a chained exception manually so we don't need an
+        # actual `raise X from Y` in the test body.
+        original = ValueError("root cause")
+        intermediate = DataError("intermediate")
+        intermediate.__cause__ = original
+        leaf = DataError("leaf")
+        leaf.__cause__ = intermediate
+
+        lines = _lines(leaf)
+        assert lines == [
+            ("leaf", False),
+            ("caused by: intermediate", True),
+            ("caused by: root cause", True),
+        ]
+
+    def test_notes_on_cause_chain(self) -> None:
+        original = ValueError("root cause")
+        original.add_note("a note on the root")
+        leaf = DataError("leaf")
+        leaf.__cause__ = original
+
+        lines = _lines(leaf)
+        assert lines == [
+            ("leaf", False),
+            ("caused by: root cause", True),
+            ("a note on the root", True),
+        ]