color_tools.exporters.base

Base classes and metadata for palette exporters.

This module provides the abstract base class and metadata dataclass that all palette exporters must implement. This allows for a plugin-style architecture where new exporters can be added without modifying existing code.

Design Pattern:

• PaletteExporter: Abstract base class defining the exporter interface

• ExporterMetadata: Dataclass describing exporter capabilities

• Exporters register themselves via decorator in __init__.py

• CLI and export.py use the registry to discover available formats

Example

>>> from color_tools.exporters.base import PaletteExporter, ExporterMetadata
>>>
>>> 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,
...         )
...
...     def _export_colors_impl(self, colors, output_path):
...         # Implementation here
...         pass

class color_tools.exporters.base.ExporterMetadata(name, description, file_extension, supports_colors, supports_filaments, is_binary=False, is_image=False)

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

class color_tools.exporters.base.PaletteExporter

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)

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)

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)

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'