all2md.transforms.registry

Transform registry for dynamic transform discovery and management.

This module implements a registry pattern for AST transforms, enabling: - Lazy loading of transform modules - Plugin discovery via entry points - Dependency resolution and ordering - Transform lookup and instantiation

The registry follows the same pattern as ConverterRegistry for consistency.

Examples

Register a transform using the global registry instance (preferred):

>>> from all2md.transforms import transform_registry, TransformMetadata
>>> transform_registry.register(my_transform_metadata)

Get a transform:

>>> from all2md.transforms import transform_registry
>>> transformer = transform_registry.get_transform("remove-images")

List all transforms:

>>> from all2md.transforms import transform_registry
>>> names = transform_registry.list_transforms()
>>> for name in names:
...     metadata = transform_registry.get_metadata(name)
...     print(f"{name}: {metadata.description}")

Notes

The preferred access pattern is to import the global registry instance directly rather than instantiating TransformRegistry. While both patterns work due to the singleton implementation, using the global instance is more explicit and consistent with the library’s design.

class all2md.transforms.registry.TransformRegistry

Bases: object

Registry for managing AST transforms.

This singleton class provides a central registry for all transforms, handling: - Transform registration and discovery - Entry point plugin loading - Dependency resolution - Lazy instantiation

The registry automatically discovers transforms via the all2md.transforms entry point group on first access.

Notes

The preferred way to access the registry is by importing the global registry instance rather than instantiating this class directly. While instantiation works due to the singleton pattern, importing registry is more explicit.

Examples

Use the global registry instance (preferred):

>>> from all2md.transforms import transform_registry
>>> transform_registry.register(metadata)

Get a transform instance:

>>> from all2md.transforms import transform_registry
>>> transformer = transform_registry.get_transform("remove-images")

List all available transforms:

>>> from all2md.transforms import transform_registry
>>> transforms = transform_registry.list_transforms()

Create or return singleton instance.

static __new__(cls) → TransformRegistry: Create or return singleton instance.

register(metadata: TransformMetadata) → None

Register a transform with its metadata.

Parameters:: metadata (TransformMetadata) – Transform metadata to register

Notes

If a transform with the same name is already registered, it will be overwritten and a warning will be logged.

Examples

>>> metadata = TransformMetadata(
...     name="my-transform",
...     description="My custom transform",
...     transformer_class=MyTransform
... )
>>> transform_registry = TransformRegistry()
>>> transform_registry.register(metadata)

unregister(name: str) → bool

Unregister a transform.

Parameters:: name (str) – Transform name to unregister
Returns:: True if transform was unregistered, False if not found
Return type:: bool

get_metadata(name: str) → TransformMetadata

Get metadata for a transform.

Parameters:: name (str) – Transform name
Returns:: Transform metadata
Return type:: TransformMetadata
Raises:: KeyError – If transform is not registered

get_transform(name: str, **kwargs: Any) → NodeTransformer

Get a transform instance by name.

Parameters:

name (str) – Transform name
**kwargs – Parameters to pass to transform constructor

Returns:

Transform instance

Return type:

NodeTransformer

Raises:

KeyError – If transform is not registered
ValueError – If parameters are invalid

Examples

>>> transform_registry = TransformRegistry()
>>> transformer = transform_registry.get_transform("heading-offset", offset=2)

has_transform(name: str) → bool

Check if a transform is registered.

Parameters:: name (str) – Transform name
Returns:: True if transform is registered
Return type:: bool

list_transforms(tags: list[str] | None = None) → list[str]

List all registered transform names.

Parameters:: tags (list[str], optional) – Filter by tags. If provided, only transforms with at least one matching tag are returned
Returns:: List of transform names, sorted alphabetically
Return type:: list[str]

Examples

List all transforms:

>>> names = transform_registry.list_transforms()

List transforms with specific tags:

>>> image_transforms = transform_registry.list_transforms(tags=["images"])

discover_plugins() → int

Discover and register transforms from entry points.

This method scans for plugins using the all2md.transforms entry point group and registers all discovered transforms.

Returns:: Number of transforms discovered and registered
Return type:: int

Examples

>>> transform_registry = TransformRegistry()
>>> count = transform_registry.discover_plugins()
>>> print(f"Discovered {count} transforms")

resolve_dependencies(transform_names: list[str]) → list[str]

Resolve transform dependencies and return execution order.

This method performs topological sorting using Kahn’s algorithm to determine the correct execution order based on dependencies and priorities. Priority is used as a tiebreaker among transforms with no pending dependencies.

Parameters:: transform_names (list[str]) – List of transform names to order
Returns:: Transform names in execution order (dependencies first)
Return type:: list[str]
Raises:: ValueError – If circular dependencies are detected or a dependency is not found

Examples

>>> transform_registry = TransformRegistry()
>>> ordered = transform_registry.resolve_dependencies([
...     "sanitize-links",  # depends on "extract-metadata"
...     "extract-metadata"
... ])
>>> print(ordered)
['extract-metadata', 'sanitize-links']

clear() → None

Clear all registered transforms.

This is primarily useful for testing.