color_tools.importers

Palette importer system.

Importers convert external palette formats into the shared color_tools palette representation:

PaletteExportData
├── list[ColorRecord] └── PaletteMetadata

Importer classes register automatically when this package is imported.

Basic usage:

>>> from color_tools.importers import import_palette
>>>
>>> palette = import_palette("palette.gpl")
>>> print(palette.metadata.name)

Explicit importer selection is also available:

>>> from color_tools.importers import get_importer
>>>
>>> importer = get_importer("gpl")
>>> palette = importer.import_palette("palette.gpl")

Automatic detection becomes especially useful for extensions shared by multiple formats. For example, future JASC PAL and RIFF PAL importers can both register the .pal extension and distinguish themselves by inspecting file contents.

class color_tools.importers.ImporterDependency(package, import_name, extra=None)[source]

Bases: object

Optional third-party dependency required by an importer.

Variables:

package – Distribution/package name used when installing the dependency.
import_name – Python module name used to test whether the dependency is installed.
extra – Optional color-tools dependency extra that installs the package.

Parameters:

package (str)
import_name (str)
extra (str | None)

package: str

import_name: str

extra: str | None

class color_tools.importers.ImporterMetadata(name, description, file_extensions, is_binary=False, dependencies=())[source]

Bases: object

Metadata describing a palette importer’s capabilities.

Variables:

name – Machine-readable importer identifier such as "gpl" or "jasc_pal".
description – Human-readable description of the palette format.
file_extensions –
File extensions recognized by the importer, without leading dots.

Importers use a tuple because a single format may legitimately be associated with more than one extension.
is_binary – Whether the input format is binary.
dependencies – Optional third-party dependencies required by the importer.

Parameters:

name (str)
description (str)
file_extensions (tuple[str, ...])
is_binary (bool)
dependencies (tuple[ImporterDependency, ...])

name: str

description: str

file_extensions: tuple[str, ...]

is_binary: bool

dependencies: tuple[ImporterDependency, ...]

__post_init__()[source]

Validate importer metadata.

Return type:: None

exception color_tools.importers.MissingImporterDependencyError(importer_name, dependencies)[source]

Bases: RuntimeError

Raised when an importer requires an unavailable optional dependency.

Variables:

importer_name – Machine-readable importer name.
dependencies – Missing dependencies required by the importer.

Parameters:

importer_name (str)
dependencies (tuple[ImporterDependency, ...])

Return type:

None

class color_tools.importers.PaletteImporter[source]

Bases: ABC

Base class for all palette importers.

Concrete importers provide format metadata and implement _import_palette_impl().

The base class handles:

Input-path validation.

Optional dependency checking.

Extension matching.

Format-detection dispatch.

Shared ColorRecord construction.

Color-space conversions are performed through color_tools.conversions so imported colors use the same calculations as colors created elsewhere in the library.

A format with an ambiguous extension should override _can_import_impl() to inspect the file signature or contents.

For example, both JASC PAL and RIFF PAL use .pal, so those importers should distinguish themselves by examining their respective headers.

abstract property metadata: ImporterMetadata

Return metadata describing this importer.

Returns:: Importer metadata.

property missing_dependencies: tuple[ImporterDependency, ...]

Return optional dependencies that are not currently installed.

Returns:: Tuple containing unavailable dependencies.

property is_available: bool

Return whether the importer can run in the current environment.

Returns:: True if all required dependencies are installed.

import_palette(input_path)[source]

Import a palette file.

Parameters:

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

Return type:

PaletteExportData

Returns:

PaletteExportData containing imported colors and metadata.

Raises:

FileNotFoundError – If the supplied file does not exist.
IsADirectoryError – If input_path refers to a directory.
MissingImporterDependencyError – If a required optional dependency is unavailable.

can_import(input_path)[source]

Return whether this importer recognizes a palette file.

Extension matching is performed first. The concrete importer may then inspect the file to distinguish formats that share an extension.

Parameters:: input_path (Path | str) – Candidate palette file.
Return type:: bool
Returns:: True if this importer recognizes the file.

color_tools.importers.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.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.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.detect_importer(input_path)[source]

Detect the importer for a palette file.

Detection proceeds in two stages:

Select importers registered for the file extension.

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.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",
... )

color_tools.importers.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.

class color_tools.importers.GPLImporter[source]

Bases: PaletteImporter

Import GIMP Palette (.gpl) files.

Standard GPL metadata is preserved where possible. color_tools-specific Author, Description, and Tags comments are also recovered when present.

property metadata: ImporterMetadata: Return metadata describing the GPL importer.

class color_tools.importers.HexImporter[source]

Bases: PaletteImporter

Import plain-text hexadecimal RGB palette files.

The format is intentionally minimal:

One RGB color per line.

Six hexadecimal digits.

Leading # is accepted but not required.

Blank lines are ignored.

Comment lines beginning with # `` or ``; are ignored.

No palette-level metadata is available in the format.

property metadata: ImporterMetadata: Return metadata describing the HEX importer.

class color_tools.importers.JascPalImporter[source]

Bases: PaletteImporter

Import JASC-PAL (.pal) palette files.

JASC PAL is a simple text format consisting of:

JASC-PAL signature

0100 version

Declared color count

One R G B entry per color

The .pal extension is shared with RIFF PAL, so this importer detects its format by checking the JASC-PAL header.

property metadata: ImporterMetadata: Return metadata describing the JASC PAL importer.

class color_tools.importers.RiffPalImporter[source]

Bases: PaletteImporter

Import RIFF PAL (.pal) palette files.

RIFF PAL is a binary RIFF container whose form type is PAL `` and whose palette data is stored in a ``data chunk.

The .pal extension is shared with JASC PAL, so this importer detects its format by checking the RIFF and PAL signatures.

property metadata: ImporterMetadata: Return metadata describing the RIFF PAL importer.