Metadata-Version: 2.4
Name: oaknut-exception
Version: 12.5.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/tree/master/packages/oaknut-exception
Project-URL: Documentation, https://rob-smallshire.github.io/oaknut/disc/api/patterns/errors.html
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.
