color_tools.exporters.registry

Exporter registry and discovery utilities.

This module owns the global exporter registry used by the palette exporter plugin system.

Concrete exporters register themselves with the @register_exporter decorator. The registry stores exporter classes rather than instances and creates fresh instances on demand.

Keeping registry behavior in this module avoids circular imports between color_tools.exporters and individual exporter modules.

color_tools.exporters.registry.register_exporter(cls)

Register an exporter class.

The exporter is instantiated once during registration so its metadata can be inspected. The class itself is stored in the registry and fresh exporter instances are created when requested with get_exporter().

Parameters:

cls (type[PaletteExporter]) – Exporter class to register.

Return type:

type[PaletteExporter]

Returns:

The same exporter class, unchanged, allowing this function to be used as a class decorator.

Raises:

ValueError – If another exporter is already registered with the same metadata name.

Example

>>> from color_tools.exporters.base import (
...     ExporterMetadata,
...     PaletteExporter,
... )
>>> from color_tools.exporters.registry import register_exporter
>>>
>>> @register_exporter
... class MyExporter(PaletteExporter):
...     @property
...     def metadata(self) -> ExporterMetadata:
...         return ExporterMetadata(
...             name="myformat",
...             description="My custom format",
...             file_extension="txt",
...             supports_colors=True,
...             supports_filaments=False,
...         )

color_tools.exporters.registry.get_exporter(format_name)

Create an exporter instance by format name.

Parameters:

format_name (str) – Exporter identifier from ExporterMetadata.name.

Return type:

PaletteExporter

Returns:

A fresh instance of the requested exporter.

Raises:

ValueError – If the requested format is not registered.

Example

>>> exporter = get_exporter("json")
>>> print(exporter.metadata.description)
JSON format (raw data, backup/restore)

color_tools.exporters.registry.list_export_formats(data_type='both', *, available_only=True)

List registered export formats.

Formats may be filtered by the type of data they support and, optionally, by whether all of their required dependencies are currently installed.

Parameters:

• data_type (str) –

  Data type to filter by:

  • "colors"

  • "filaments"

  • "both"

  "both" means exporters supporting either type, preserving the behavior of the previous exporter registry.

• available_only (bool) – When True, omit exporters whose optional dependencies are missing. When False, include all registered exporters that match data_type.

Return type:

dict[str, str]

Returns:

Dictionary mapping exporter name to human-readable description.

Raises:

ValueError – If data_type is not one of the supported values.

color_tools.exporters.registry.get_export_formats_dict()

Return export format metadata in the legacy EXPORT_FORMATS structure.

This preserves compatibility with code that previously consumed the dictionary maintained by export.py.

Returns:

• description

• file_extension

• applies_to

• available

Return type:

Dictionary mapping exporter name to metadata containing

Example

>>> formats = get_export_formats_dict()
>>> formats["json"]["applies_to"]
'both'