`tlc.export.exporter_registry`¶

Registry for pluggable exporters.

Exporters can be registered through three paths, all funneling into a single registry:

Entry points (preferred for third-party plugins) — group tlc.exporters
Config-based (for admin/deployment control) — exporters key in config
Direct / decorator (for built-ins and in-process use) — @register_exporter

Module Contents¶

Classes¶

Class	Description
`ExporterInfo`	Structured metadata for a registered exporter.
`ExporterRegistry`	Maintains registered exporters and provides lookup and discovery.

Functions¶

Function	Description
`list_exporter_formats`	List the format strings of all registered exporters.
`list_exporters`	List all registered exporters with structured metadata.
`register_exporter`	Class decorator that registers an `Exporter` subclass.

Data¶

Data	Description
`ExporterSource`

API¶

class ExporterInfo¶

Bases: typing_extensions.TypedDict

Structured metadata for a registered exporter.

Initialize self. See help(type(self)) for accurate signature.

exporter_class: str = None¶

format: str = None¶

module: str = None¶

source: 'builtin' | 'entrypoint' | 'config' | 'runtime' = None¶

class ExporterRegistry¶

Maintains registered exporters and provides lookup and discovery.

This is a static registry class — all methods are @staticmethod and state is stored in class variables. The registry maps format strings to exporter instances.

Registration follows a well-defined order:

Built-in exporters (@register_exporter at import time)
Entry point plugins (discover_entrypoint_exporters(), lazy)
Config-based (load_exporters_from_config(), at service startup)
Runtime direct calls (any time)

A later phase can replace an earlier one via force=True.

static discover_entrypoint_exporters() → list[Exporter]¶

Discover and register exporters from installed entry points.

Scans for entry points in the tlc.exporters group. Each entry point should reference an Exporter subclass that can be instantiated with no arguments.

By default, exporters whose format is already registered are skipped (built-ins take priority). Set force = True on the exporter class to replace already-registered formats.

Returns:: List of successfully loaded exporter instances.

static get_exporter_for_format( fmt: str, ) → Exporter | None¶

Get the exporter registered for the given format.

If the format is not found and entry point discovery has not yet run, triggers discovery before giving up.

Parameters:: fmt – The format string (e.g., "csv", "coco").
Returns:: The exporter instance, or None if no exporter is registered for the format.

static get_registered_exporters() → dict[str, Exporter]¶

Get a copy of all registered exporters.

Returns:: Dictionary mapping format strings to their exporter instances.

static get_registered_formats() → list[str]¶

Get all registered format strings.

Returns:: List of registered format strings.

static infer_format( table: Table, output_url: Url, ) → str¶

Infer the most suitable export format given a table and an output URL.

Iterates all registered exporters, calls can_export() on each, and returns the format with the highest priority. Raises ValueError if no compatible exporter is found or if there is an ambiguous tie.

Parameters:

table – The table to export.
output_url – The URL to export to.

Returns:

The inferred format string.

Raises:

ValueError – If no compatible exporter is found, the output URL has no extension, or multiple exporters tie at the highest priority.

static list_exporter_formats() → list[str]¶

List the format strings of all registered exporters.

Triggers entry point discovery if it has not yet run.

Returns:: Sorted list of registered format strings.

static list_exporters() → list[ExporterInfo]¶

Get structured metadata for all registered exporters.

Triggers entry point discovery if it has not yet run.

Returns:: One ExporterInfo per registered format.

static load_exporter_from_module( module_name: str, class_name: str, kwargs: dict[str, Any] | None = None, *, force: bool = False, ) → Exporter | None¶

Load and register an exporter from a module.

Dynamically imports a module and instantiates an exporter class.

Parameters:

module_name – The fully qualified module name (e.g., "mypackage.exporters").
class_name – The exporter class name (e.g., "MyCustomExporter").
kwargs – Optional keyword arguments to pass to the exporter constructor.
force – If True, allow overriding already-registered formats.

Returns:

The exporter instance if successful, None otherwise.

static load_exporters_from_config( config: list[dict[str, Any]], *, force: bool = False, ) → list[Exporter]¶

Load exporters from a configuration list.

Each entry in the config list should be a dictionary with:

module: The fully qualified module name
class: The exporter class name
kwargs (optional): Dictionary of constructor arguments
force (optional): If True, allow this exporter to override already-registered formats. Overrides the method-level force parameter for this entry.

Parameters:

config – List of exporter configuration dictionaries.
force – Default value for whether to allow overriding already-registered formats. Individual entries can override this with their own force key.

Returns:

List of successfully loaded exporters.

static register_exporter( exporter: Exporter, *, force: bool = False, source: 'builtin' | 'entrypoint' | 'config' | 'runtime' = 'runtime', ) → None¶

Parameters:

exporter – The exporter instance to register. Must have a supported_format attribute.
force – If True, allow overriding an already-registered format. If False (default), raises ValueError when attempting to register a format that already has an exporter.
source – Where this registration originates from. One of "builtin", "entrypoint", "config", or "runtime".

Raises:

ValueError – If the format is already registered and force is False.

static reset() → None¶

Reset the registry to its initial state.

This removes all registered exporters. Primarily intended for testing.

static unregister_exporter( exporter: Exporter, ) → bool¶

Unregister an exporter by instance.

Parameters:: exporter – The exporter instance to unregister.
Returns:: True if the exporter was found and removed, False otherwise.

static unregister_format( fmt: str, ) → bool¶

Unregister the exporter for a specific format.

Parameters:: fmt – The format to unregister.
Returns:: True if the format was found and removed, False otherwise.

ExporterSource = None¶

list_exporter_formats() → list[str]¶

List the format strings of all registered exporters.

Module-level wrapper that delegates to ExporterRegistry.list_exporter_formats(). Use :func:list_exporters for full structured metadata.

Returns:: Sorted list of registered format strings.

list_exporters() → list[ExporterInfo]¶

List all registered exporters with structured metadata.

Module-level wrapper that delegates to ExporterRegistry.list_exporters(). Triggers entry point discovery if it has not yet run, so plugins installed via pip are reflected in the output without any extra setup.

Returns:: One ExporterInfo per registered format.

register_exporter( cls: type[Exporter], ) → type[Exporter]¶

Class decorator that registers an Exporter subclass.

Instantiates the class with no arguments and registers it for the format specified by supported_format. If instantiation or registration fails, the error is logged and the class is returned unregistered.

Built-in exporters (those with supported_format in _BUILTIN_FORMATS) are recorded with source="builtin"; all others get source="runtime".

Parameters:: cls – The Exporter subclass to register.
Returns:: The class, unchanged.

tlc.export.exporter_registry¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`tlc.export.exporter_registry`¶