oaknut.extension

The entry-point plug-in framework shared by every extensible axis of the oaknut family. An axis is one extension point — a family of interchangeable plug-ins that all answer the same question. The primary axis is oaknut.filesystem (each plug-in detects and operates on one disc format); oaknut.command (CLI subcommands) is another.

A concrete extension subclasses Extension, declares a kind (a short identifier such as "filesystem"), and is registered under the oaknut.<kind> entry-point namespace in its package’s pyproject.toml:

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

Consumers discover and load extensions with the functions below, which wrap stevedore. Discovery is by installed entry point, so a plug-in shipped by any package appears automatically — there is no central registry to edit.

This module is deliberately domain-agnostic: it knows nothing about discs, files, or formats. Per-axis packages build a thin convenience layer on top.

Every name documented here is importable directly from oaknut.extension.

The extension base class

class oaknut.extension.Extension(name, **kwargs)

Base class for every oaknut plug-in extension.

A concrete extension overrides _kind() to name its axis and is instantiated with the entry-point name it was registered under. The class docstring doubles as its human-readable description (see describe()).

Parameters:

name (str)

classmethod kind()

The kind of extension — the axis this plug-in belongs to.

Return type:

str

property name: str

The entry-point name this extension was loaded under.

classmethod dirpath()

The directory path to the package providing this extension.

Return type:

Path

classmethod version()

The extension version. Override to report something meaningful.

Return type:

str

classmethod describe(*, single_line=False)

A human-readable description of the extension.

By default this is the extension class’s docstring. Override it if you want something different.

Parameters:

single_line (bool) – If True, return only the first non-empty line of the description. Defaults to False for the full text.

Returns:

The description. If single_line is True, only the first non-empty line; otherwise the complete (de-indented) docstring.

Return type:

str

classmethod entry_point_name()

The entry-point name (key) this extension class is registered under.

Performs a reverse lookup from class to entry-point name by searching the axis’s namespace. Cached indefinitely since entry-point names are immutable for the life of the process.

Raises:

ExtensionError – If this class is not a registered extension.

Return type:

str

exception oaknut.extension.ExtensionError(*args, exit_code=None)

Raised when an extension cannot be discovered or loaded.

A plug-in that is missing, mis-registered, or fails at import time is an environment/setup problem rather than bad input or a library bug — hence a ConfigurationError.

Parameters:

  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None

Namespaces

oaknut.extension.namespace_for(kind)

Return the entry-point namespace for an extension kind.

The convention is "oaknut.<kind>" — e.g. namespace_for("filesystem") is "oaknut.filesystem".

Parameters:

kind (str)

Return type:

str

Discovery and loading

oaknut.extension.list_extensions(namespace)

List the names of the extensions registered in namespace.

Parameters:

namespace (str)

Return type:

list[str]

oaknut.extension.create_extension(kind, namespace, name, exception_type=None, **kwargs)

Instantiate an extension by name.

Parameters:

  • kind (str) – The kind of extension (for error messages).

  • namespace (str) – The entry-point namespace to search.

  • name (str) – The name of the extension to load.

  • exception_type (type[BaseException] | None) – Exception raised if the extension cannot be loaded. Defaults to ExtensionError.

  • **kwargs – Forwarded to the extension constructor.

Returns:

An Extension instance.

Return type:

Extension

oaknut.extension.extension(kind, namespace, name, exception_type=None)

Get an extension class (without instantiating it).

Parameters:

  • kind (str) – The kind of extension (for error messages).

  • namespace (str) – The entry-point namespace to search.

  • name (str) – The name of the extension to load.

  • exception_type (type[BaseException] | None) – Exception raised if the extension cannot be loaded. Defaults to ExtensionError.

Returns:

The extension class.

Return type:

Type[Extension]

oaknut.extension.describe_extension(kind, namespace, name, exception_type=None, *, single_line=False)

Return the description of an extension by name.

Parameters:

  • kind (str) – The kind of extension (for error messages).

  • namespace (str) – The entry-point namespace to search.

  • name (str) – The name of the extension.

  • exception_type (type[BaseException] | None) – Exception raised if the extension cannot be loaded.

  • single_line (bool) – If True, return only the first non-empty line.

Returns:

The extension’s description string.

Return type:

str

oaknut.extension.extension_name_from_class(namespace, extension_class)

Reverse-lookup the entry-point name for an extension class.

Iterates the extensions in namespace until one whose plug-in is extension_class is found.

Raises:

ExtensionError – If the class is not registered in namespace.

Parameters:
Return type:

str

oaknut.extension.list_dirpaths(namespace)

Map each extension name in namespace to its package directory path.

Parameters:

namespace (str)

Return type:

dict[str, Path]

oaknut.extension.load_failure_callback(manager, entrypoint, exception)

Turn a stevedore load failure into an ExtensionError.