color_tools.importers.base

Base classes, metadata, dependency handling, and shared color construction for palette importers.

Palette importers convert external palette formats into the library’s existing internal palette representation:

PaletteExportData
├── colors: list[ColorRecord] └── metadata: PaletteMetadata

Importers do not introduce a separate imported-palette model. This allows an imported palette to be passed directly to any palette exporter.

Color-space conversion is delegated to color_tools.conversions so importers use the same conversion logic as the rest of the library.

Example

>>> importer = SomePaletteImporter()
>>> palette = importer.import_palette("palette.gpl")
>>> print(palette.metadata.name)
My Palette
>>> print(palette.colors[0].rgb)
(255, 127, 80)

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