color_tools.export

Export system for filaments and colors.

Provides export functionality to various formats (CSV, JSON, GPL, etc.) for integration with external tools like AutoForge, HueForge, GIMP, and other color management systems.

ARCHITECTURE NOTE (v6.0.0): This module now serves as a backward-compatibility facade over the new plugin-based exporter system located in color_tools/exporters/. All export logic has been moved to individual exporter classes in the exporters/ folder.

The functions in this file (export_filaments_csv, export_colors_json, etc.) are now STUBS that delegate to the new exporter implementations. This preserves backward compatibility while allowing new exporters to be added as plugins without modifying this file.

New exporters can be added by:

Creating a new file in exporters/ (e.g., exporters/ase_exporter.py)
Subclassing PaletteExporter from exporters/base.py
Using @register_exporter decorator
The exporter automatically appears in list_export_formats()

For the new plugin architecture, see color_tools/exporters/ For adding new exporters, see color_tools/exporters/base.py

color_tools.export.export_palette(palette, format_name, output_path=None, *, metadata=None, options=None)[source]

Export a searchable palette or export-data wrapper to a chosen format.

Supply metadata with a Palette, or embed it in PaletteExportData, not both. Formats without metadata support export colors only. Exporter-specific options, dependency checks, and file errors are handled by the exporter. Returns the output path as a string; an omitted path is exporter-generated. Unknown or non-color formats and conflicting metadata raise ValueError.

Example

>>> palette = Palette.from_hex(["#f00", "#00f"])
>>> path = export_palette(palette, "gpl", "custom.gpl")

Return type:

str

Parameters:

palette (Palette | PaletteExportData)
format_name (str)
output_path (Path | str | None)
metadata (PaletteMetadata | None)
options (ExportOptionsBase | None)

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

List available export formats.

DELEGATION NOTE: This function delegates to 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

color_tools.export.generate_filename(data_type, format_name)[source]

Generate timestamped filename for export.

DELEGATION NOTE: This function delegates to the exporter’s generate_filename method.

Parameters:

data_type (str) – ‘filaments’ or ‘colors’
format_name (str) – Export format name (e.g., ‘autoforge’, ‘csv’, ‘json’)

Returns:

{type}_{format}_{YYYYMMDD}_{HHMMSS}.{ext}

Return type:

str

Example

>>> generate_filename('filaments', 'autoforge')
'filaments_autoforge_20251223_143022.csv'

color_tools.export.export_filaments_autoforge(filaments, output_path=None)[source]

Export filaments to AutoForge CSV format.

DELEGATION NOTE: This function is a stub that delegates to AutoForgeExporter in exporters/csv_exporter.py. Kept for backward compatibility.

Format:: Brand,Name,TD,Color,Owned Bambu Lab PLA Basic,Jet Black,0.1,#000000,TRUE

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 the exported file

Example

>>> from color_tools.filament_palette import FilamentPalette
>>> palette = FilamentPalette.load_default()
>>> bambu = [f for f in palette.filaments if f.maker == 'Bambu Lab']
>>> path = export_filaments_autoforge(bambu)
>>> print(f"Exported {len(bambu)} filaments to {path}")

color_tools.export.export_filaments_csv(filaments, output_path=None)[source]

Export filaments to generic CSV format with all fields.

DELEGATION NOTE: This function is a stub that delegates to CSVExporter in exporters/csv_exporter.py. Kept for backward compatibility.

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 the exported file

Example

>>> from color_tools.filament_palette import FilamentPalette
>>> palette = FilamentPalette.load_default()
>>> path = export_filaments_csv(palette.filaments)

color_tools.export.export_filaments_json(filaments, output_path=None)[source]

Export filaments to JSON format.

DELEGATION NOTE: This function is a stub that delegates to JSONExporter in exporters/json_exporter.py. Kept for backward compatibility.

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 the exported file

Example

>>> from color_tools.filament_palette import FilamentPalette
>>> palette = FilamentPalette.load_default()
>>> path = export_filaments_json(palette.filaments, 'backup.json')

color_tools.export.export_colors_csv(colors, output_path=None)[source]

Export colors to generic CSV format with all fields.

DELEGATION NOTE: This function is a stub that delegates to CSVExporter in exporters/csv_exporter.py. Kept for backward compatibility.

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 the exported file

Example

>>> from color_tools.palette import Palette
>>> palette = Palette.load_default()
>>> path = export_colors_csv(palette.colors)

color_tools.export.export_colors_json(colors, output_path=None)[source]

Export colors to JSON format.

DELEGATION NOTE: This function is a stub that delegates to JSONExporter in exporters/json_exporter.py. Kept for backward compatibility.

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 the exported file

Example

>>> from color_tools.palette import Palette
>>> palette = Palette.load_default()
>>> path = export_colors_json(palette.colors, 'my_colors.json')

color_tools.export.export_filaments(filaments, format_name, output_path=None, *, options=None)[source]

Export filaments to specified format.

DELEGATION NOTE: This function delegates to the exporter registry. Now supports any format registered in the exporters/ folder.

Parameters:

filaments (list[FilamentRecord]) – List of FilamentRecord objects to export
format_name (str) – Export format (‘autoforge’, ‘csv’, ‘json’, etc.)
output_path (Path | str | None) – Output file path (auto-generated if None)
options (ExportOptionsBase | None) – Optional exporter-specific configuration

Return type:

str

Returns:

Path to the exported file

Raises:

ValueError – If format is not supported for filaments

Example

>>> from color_tools.filament_palette import FilamentPalette
>>> palette = FilamentPalette.load_default()
>>> bambu = [f for f in palette.filaments if f.maker == 'Bambu Lab']
>>> path = export_filaments(bambu, 'autoforge')

color_tools.export.export_filament_data(data, format_name, output_path=None, *, options=None)[source]

Export metadata-bearing filament transfer data.

Formats that do not preserve collection metadata automatically export the ordered filament records through their existing filament implementation.

Parameters:

data (FilamentExportData) – Filament records and collection-level metadata.
format_name (str) – Registered filament export format.
output_path (Path | str | None) – Optional destination path.
options (ExportOptionsBase | None) – Optional exporter-specific configuration.

Return type:

str

Returns:

Path to the exported file as a string.

color_tools.export.export_colors(colors, format_name, output_path=None, *, options=None)[source]

Export colors to specified format.

DELEGATION NOTE: This function delegates to the exporter registry. Now supports any format registered in the exporters/ folder.

Parameters:

colors (list[ColorRecord]) – List of ColorRecord objects to export
format_name (str) – Export format (‘csv’, ‘json’, ‘gpl’, etc.)
output_path (Path | str | None) – Output file path (auto-generated if None)
options (ExportOptionsBase | None) – Optional exporter-specific configuration

Return type:

str

Returns:

Path to the exported file

Raises:

ValueError – If format is not supported for colors

Example

>>> from color_tools.palette import Palette
>>> palette = Palette.load_default()
>>> blues = [c for c in palette.colors if 'blue' in c.name.lower()]
>>> path = export_colors(blues, 'json', 'blue_colors.json')