Metadata-Version: 2.4
Name: oaknut-extension
Version: 12.5.0
Summary: Entry-point plug-in framework shared by every extensible axis of 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-extension
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: oaknut-exception>=10.0
Requires-Dist: stevedore>=5.0
Dynamic: license-file

# oaknut-extension

The entry-point plug-in framework shared by every extensible *axis* of the
`oaknut` package family.

An **axis** is one extension point — a family of interchangeable plug-ins that
all answer the same question. The primary axis is *filesystems* (each plug-in
detects and operates on one disc format, in `oaknut-filesystem`);
`oaknut.command` (CLI subcommands contributed by filesystem packages) is
another.

Each axis declares a `kind` (a short identifier such as `"filesystem"`).
Concrete extensions for that axis subclass `Extension`, override `_kind()`,
and register themselves under the `oaknut.<kind>` entry-point namespace in
their package's `pyproject.toml`:

```toml
[project.entry-points."oaknut.filesystem"]
acorn-dfs = "oaknut.dfs.filesystem:AcornDFS"
```

Consumers discover and load them through `list_extensions()`,
`create_extension()`, and friends, which wrap [stevedore](https://docs.openstack.org/stevedore/).
Because discovery is by installed entry point, a plug-in shipped by any package
appears automatically — no central registry to edit.

This package is deliberately domain-agnostic: it knows nothing about discs,
files, or formats. It depends only on `oaknut-exception` (for the shared error
hierarchy) and `stevedore`.
