color_tools.config

Immutable execution-context configuration for color processing.

class color_tools.config.ColorConfig(multi_color_mode='first', gamut_tolerance=0.01, gamut_max_iterations=20)[source]

Bases: object

Validated settings captured by operations and filament construction.

first selects the first component, last the final component, and srgb_mean averages encoded sRGB channels with equal weights. Future modes (not accepted yet): representative, lightest, darkest, most_chromatic, least_chromatic, linear_rgb_mean, and lab_mean.

Tolerance is measured in 0-255 RGB channel units. Iterations limit the gamut search; numerical convergence may stop it earlier.

Parameters:

multi_color_mode (Literal['first', 'last', 'srgb_mean'])
gamut_tolerance (float)
gamut_max_iterations (int)

multi_color_mode: Literal['first', 'last', 'srgb_mean']

gamut_tolerance: float

gamut_max_iterations: int

color_tools.config.get_config()[source]

Return the current frozen settings instance, without copying it.

Return type:: ColorConfig

color_tools.config.set_config(*, multi_color_mode=None, gamut_tolerance=None, gamut_max_iterations=None)[source]

Update current-context settings atomically; None leaves a value unchanged.

New async tasks inherit their creation context. Independent threads do not automatically inherit these overrides; callers can explicitly propagate context with contextvars.copy_context. Existing records are unchanged. Invalid types raise TypeError; invalid values raise ValueError.

Return type:

None

Parameters:

multi_color_mode (Literal['first', 'last', 'srgb_mean'] | None)
gamut_tolerance (float | None)
gamut_max_iterations (int | None)

color_tools.config.reset_config()[source]

Restore built-in defaults in the current execution context only.

Return type:: None

color_tools.config.config_context(*, multi_color_mode=None, gamut_tolerance=None, gamut_max_iterations=None)[source]

Temporarily override settings, restoring the exact instance on exit.

Nested overrides, set_config, and reset_config inside the block are all undone on exit, including when an exception is raised.

Return type:

Generator[None, None, None]

Parameters:

multi_color_mode (Literal['first', 'last', 'srgb_mean'] | None)
gamut_tolerance (float | None)
gamut_max_iterations (int | None)