color_tools.exporters

Palette exporter plugin system.

This module provides a plugin-based architecture for palette exporters. Exporters automatically register themselves on import, and can be discovered via the registry functions.

Architecture:

Each exporter subclasses PaletteExporter (from base.py)
Exporters use @register_exporter decorator to auto-register
Registry tracks all available exporters
CLI and export.py query registry to discover formats

Usage:

>>> from color_tools.exporters import get_exporter, list_export_formats
>>>
>>> # List available formats
>>> formats = list_export_formats('filaments')
>>> print(formats)
{'autoforge': 'AutoForge filament library CSV format', ...}
>>>
>>> # Get an exporter and use it
>>> exporter = get_exporter('json')
>>> from color_tools.palette import Palette
>>> palette = Palette.load_default()
>>> path = exporter.export_colors(palette.colors, 'output.json')

class color_tools.exporters.PaletteExporter[source]

Bases: ABC

Abstract base class for all palette exporters.

All exporters must subclass this and implement: - metadata property: Return ExporterMetadata describing capabilities - _export_colors_impl: Logic for exporting colors (if supports_colors=True) - _export_filaments_impl: Logic for exporting filaments (if supports_filaments=True)

The base class handles: - Capability checking (prevents unsupported operations) - Filename generation with timestamps - Consistent error messages

Example

>>> from color_tools.exporters.base import PaletteExporter, ExporterMetadata
>>>
>>> class TextExporter(PaletteExporter):
...     @property
...     def metadata(self) -> ExporterMetadata:
...         return ExporterMetadata(
...             name="txt",
...             description="Plain text format",
...             file_extension="txt",
...             supports_colors=True,
...             supports_filaments=False,
...         )
...
...     def _export_colors_impl(self, colors, output_path):
...         # Write colors to text file
...         return str(output_path)
...
...     def _export_filaments_impl(self, filaments, output_path):
...         # Not implemented (supports_filaments=False)
...         pass

abstract property metadata: ExporterMetadata

Return metadata describing this exporter’s capabilities.

Returns:: ExporterMetadata instance with name, description, capabilities

export_colors(colors, output_path=None)[source]

Export colors to file.

Parameters:

colors (list[ColorRecord]) – List of ColorRecord objects to export
output_path (Path | str | None) – Output file path (auto-generated if None)

Return type:

str

Returns:

Path to exported file as string

Raises:

NotImplementedError – If this exporter doesn’t support colors

export_filaments(filaments, output_path=None)[source]

Export filaments to file.

Parameters:

filaments (list[FilamentRecord]) – List of FilamentRecord objects to export
output_path (Path | str | None) – Output file path (auto-generated if None)

Return type:

str

Returns:

Path to exported file as string

Raises:

NotImplementedError – If this exporter doesn’t support filaments

generate_filename(data_type)[source]

Generate timestamped filename for export.

Format: {data_type}_{format_name}_{YYYYMMDD}_{HHMMSS}.{ext}

Parameters:: data_type (str) – ‘colors’ or ‘filaments’
Return type:: str
Returns:: Generated filename (not full path, just filename)

Example

>>> exporter.generate_filename('colors')
'colors_json_20251223_143022.json'

class color_tools.exporters.ExporterMetadata(name, description, file_extension, supports_colors, supports_filaments, is_binary=False, is_image=False)[source]

Bases: object

Metadata describing an exporter’s capabilities.

Variables:

name – Machine-readable format name (e.g., “autoforge”, “csv”, “gpl”)
description – Human-readable description for help text
file_extension – File extension without dot (e.g., “csv”, “json”, “ase”)
supports_colors – Whether this exporter can export CSS colors
supports_filaments – Whether this exporter can export 3D printing filaments
is_binary – Whether output is binary (True) or text (False) - default False
is_image – Whether output is an image file (PNG, etc.) - default False

Parameters:

name (str)
description (str)
file_extension (str)
supports_colors (bool)
supports_filaments (bool)
is_binary (bool)
is_image (bool)

Example

>>> meta = ExporterMetadata(
...     name="json",
...     description="JSON format (raw data)",
...     file_extension="json",
...     supports_colors=True,
...     supports_filaments=True,
... )
>>> print(meta.name)
json

name: str

description: str

file_extension: str

supports_colors: bool

supports_filaments: bool

is_binary: bool = False

is_image: bool = False

color_tools.exporters.register_exporter(cls)[source]

Decorator to register an exporter class.

Automatically instantiates the exporter and registers it in the global registry using its metadata.name as the key.

Parameters:: cls (type[PaletteExporter]) – Exporter class to register (must subclass PaletteExporter)
Return type:: type[PaletteExporter]
Returns:: The same class (unchanged), for decorator chaining
Raises:: ValueError – If an exporter with this name is already registered

Example

>>> from color_tools.exporters import register_exporter
>>> from color_tools.exporters.base import PaletteExporter, ExporterMetadata
>>>
>>> @register_exporter
... class MyExporter(PaletteExporter):
...     @property
...     def metadata(self):
...         return ExporterMetadata(...)
...     # ... implementation

color_tools.exporters.get_exporter(format_name)[source]

Get exporter instance by format name.

Parameters:: format_name (str) – Name of the export format (e.g., ‘json’, ‘csv’, ‘autoforge’)
Return type:: PaletteExporter
Returns:: Fresh instance of the requested exporter
Raises:: ValueError – If format_name is not recognized

Example

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

color_tools.exporters.list_export_formats(data_type='both')[source]

List available export formats.

Backward-compatible function that queries the exporter registry.

Parameters:: data_type (str) – Filter by ‘filaments’, ‘colors’, or ‘both’
Return type:: dict[str, str]
Returns:: Dictionary mapping format name to description

Example

>>> formats = list_export_formats('filaments')
>>> print(formats['autoforge'])
AutoForge filament library CSV format