color_tools.importers.registry

Palette importer registry.

Importers register themselves through @register_importer. The registry stores importer classes rather than instances so each request receives a fresh, stateless importer.

The registry also provides extension-based candidate lookup and file-content detection. This is necessary because some palette formats share extensions.

For example:

JASC PAL -> .pal RIFF PAL -> .pal

Those importers can both register the pal extension while implementing different can_import() signature checks.

color_tools.importers.registry.register_importer(cls)[source]

Register a palette importer class.

The importer is instantiated once during registration to retrieve its metadata. The class itself is stored and fresh instances are created on demand.

Parameters:

cls (type[PaletteImporter]) – PaletteImporter subclass.

Return type:

type[PaletteImporter]

Returns:

The original class, allowing use as a decorator.

Raises:

ValueError – If another importer already uses the same metadata name.

Example

>>> @register_importer
... class ExampleImporter(PaletteImporter):
...     ...
color_tools.importers.registry.get_importer(format_name)[source]

Create an importer by registered format name.

Parameters:

format_name (str) – Importer metadata name.

Return type:

PaletteImporter

Returns:

Fresh importer instance.

Raises:

ValueError – If the format is not registered.

color_tools.importers.registry.list_import_formats(*, available_only=True)[source]

List registered palette import formats.

Parameters:

available_only (bool) – Exclude importers whose optional dependencies are unavailable.

Return type:

dict[str, str]

Returns:

Mapping of importer name to human-readable description.

color_tools.importers.registry.get_importers_for_extension(extension, *, available_only=True)[source]

Return importers registered for a file extension.

More than one importer may be returned because extensions are not unique.

Parameters:

  • extension (str) – Extension with or without a leading dot.

  • available_only (bool) – Exclude importers with unavailable dependencies.

Return type:

list[PaletteImporter]

Returns:

Fresh importer instances matching the extension.

color_tools.importers.registry.detect_importer(input_path)[source]

Detect the importer for a palette file.

Detection proceeds in two stages:

  1. Select importers registered for the file extension.

  2. Ask each candidate to inspect the file using can_import().

This allows formats that share extensions to distinguish themselves using file signatures or headers.

Parameters:

input_path (Path | str) – Palette file to inspect.

Return type:

PaletteImporter

Returns:

Matching importer.

Raises:

  • FileNotFoundError – If the file does not exist.

  • ValueError – If there are no candidate importers, no candidate recognizes the file, or multiple candidates recognize it.

color_tools.importers.registry.import_palette(input_path, *, format_name=None)[source]

Import a palette using explicit or automatic format selection.

Parameters:

  • input_path (Path | str) – Palette file to import.

  • format_name (str | None) – Optional explicit importer name. If omitted, the registry attempts to detect the format from extension and file contents.

Return type:

PaletteExportData

Returns:

Imported PaletteExportData.

Example

Automatic detection:

>>> palette = import_palette("palette.gpl")

Explicit format:

>>> palette = import_palette(
...     "palette.pal",
...     format_name="jasc_pal",
... )