Configuration¶

The config module provides centralized configuration management for cdl_convert through a type-safe dataclass-based system.

Overview¶

The configuration system consists of three main components:

CDLFormat - An enum defining all supported CDL format types
Config - A dataclass containing all global settings with validation
config - A global configuration instance for centralized access

Global Configuration Instance¶

The module exports a global config instance that provides centralized access to all settings:

from cdl_convert.config import config

# Check error handling mode
if config.halt_on_error:
    # Strict validation mode
    pass

# Check if a format is a collection format
if config.is_collection_format('ccc'):
    # Handle collection format
    pass

CDLFormat Enum¶

The CDLFormat enum provides type-safe format identifiers for all supported CDL formats:

from cdl_convert.config import CDLFormat

# Access format types
format_type = CDLFormat.CCC
print(format_type.value)  # 'ccc'

# Use in comparisons
if my_format == CDLFormat.CC:
    # Handle CC format
    pass

Supported formats:

CDLFormat.ALE - Avid Log Exchange
CDLFormat.CC - XML Color Correction (single)
CDLFormat.CCC - XML Color Correction Collection
CDLFormat.CDL - XML Color Decision List
CDLFormat.EDL - CMX EDL
CDLFormat.FLEX - Film Log EDL Exchange
CDLFormat.FLEX - ASWF’s OpenTimeineIO EDL Exchange
CDLFormat.RCDL - Space-separated CDL (Rhythm & Hues)

class cdl_convert.config.CDLFormat(value)[source]¶

Bases: Enum

Supported CDL format types.

ALE = 'ale'¶

CC = 'cc'¶

CCC = 'ccc'¶

CDL = 'cdl'¶

EDL = 'edl'¶

FLEX = 'flex'¶

NK = 'nk'¶

OTIO = 'otio'¶

RCDL = 'rcdl'¶

Config Class¶

The Config class is a dataclass that contains all global configuration settings with proper type hints and validation.

Attributes¶

halt_on_error : bool: If True, exceptions are raised instead of being handled with default behavior. Used for strict validation mode. Default is False.
collection_formats : FrozenSet[CDLFormat]: Immutable set of formats that represent ColorCollection objects. Includes: ALE, CCC, CDL, EDL, and FLEx.
single_formats : FrozenSet[CDLFormat]: Immutable set of formats that represent single ColorCorrection objects. Includes: CC and RCDL.
sop_tag_name : str: XML element tag name for SOP (Slope/Offset/Power) nodes. Valid values: 'SOPNode' (default), 'ASC_SOP'. Controls the XML tag used when generating SOP elements in output files.
sat_tag_name : str: XML element tag name for Saturation nodes. Valid values: 'SatNode' (default), 'SATNode' (legacy), 'ASC_SAT'. Controls the XML tag used when generating Saturation elements in output files. Default changed from 'SATNode' to 'SatNode' in v1.0 to finally adhere correctly to specification.

Methods¶

The Config class provides helper methods for format type checking and tag name configuration:

from cdl_convert.config import config

# Check if a format string is a collection format
if config.is_collection_format('ccc'):
    print("CCC is a collection format")

# Check if a format string is a single correction format
if config.is_single_format('cc'):
    print("CC is a single correction format")

# Configure XML tag names
config.set_sop_tag_name('ASC_SOP')
config.set_sat_tag_name('ASC_SAT')

class cdl_convert.config.Config(halt_on_error: bool = False, collection_formats: frozenset[CDLFormat] = frozenset({CDLFormat.ALE, CDLFormat.CCC, CDLFormat.CDL, CDLFormat.EDL, CDLFormat.FLEX, CDLFormat.OTIO}), single_formats: frozenset[CDLFormat] = frozenset({CDLFormat.CC, CDLFormat.NK, CDLFormat.RCDL}), sop_tag_name: str = 'SOPNode', sat_tag_name: str = 'SatNode', _input_encoding: str | None = None, _output_encoding: str = 'utf-8')[source]¶

Bases: object

Type-safe configuration for CDL Convert.

This class contains all global configuration settings with proper type hints and validation.

collection_formats: frozenset[CDLFormat] = frozenset({CDLFormat.ALE, CDLFormat.CCC, CDLFormat.CDL, CDLFormat.EDL, CDLFormat.FLEX, CDLFormat.OTIO})¶: Set of formats that represent ColorCollection objects.

halt_on_error: bool = False¶: If True, exceptions are raised instead of being handled with default behavior. Used for strict validation mode.

property input_encoding: str | None¶

Character encoding used when reading input files.

None (default): Auto-detect encoding for XML formats (cc, ccc, cdl) from XML declaration, use UTF-8 for non-XML formats (ale, flex, nk, rcdl).
Specified value: Override auto-detection and use this encoding for all input files.

Common encodings: ‘utf-8’, ‘latin-1’, ‘iso-8859-1’, ‘cp1252’

property output_encoding: str¶

utf-8.

Common encodings: ‘utf-8’, ‘latin-1’, ‘iso-8859-1’, ‘cp1252’

Type:: Character encoding used when writing output files. Default

property output_encoding_xml: str¶

Get output encoding in XML standard (IANA) format for declarations.

Returns:: XML standard encoding name (e.g., ‘UTF-8’, ‘ISO-8859-1’)

sat_tag_name: str = 'SatNode'¶

‘SatNode’, ‘SATNode’, ‘ASC_SAT’. Default is ‘SatNode’ (changed from ‘SATNode’ in v1.0 for consistency). Use ‘SATNode’ for legacy behavior.

Type:: XML element tag name for Saturation nodes. Valid values

single_formats: frozenset[CDLFormat] = frozenset({CDLFormat.CC, CDLFormat.NK, CDLFormat.RCDL})¶: Set of formats that represent single ColorCorrection objects.

sop_tag_name: str = 'SOPNode'¶

‘SOPNode’, ‘ASC_SOP’. Default is ‘SOPNode’ for standard format.

Type:: XML element tag name for SOP nodes. Valid values

static normalize_encoding_name(encoding: str) → str[source]¶

Normalize Python encoding names to IANA standard names for XML.

Uses Python’s codecs module to get the canonical encoding name, then maps it to the IANA-registered name suitable for XML declarations. Python’s codecs.lookup() normalizes encoding aliases (e.g., ‘latin-1’, ‘latin1’, ‘iso-8859-1’) to their canonical Python names, which we then convert to IANA standard names.

Parameters:: encoding – Python encoding name (e.g., ‘latin-1’, ‘utf-8’)
Returns:: IANA standard encoding name for XML (e.g., ‘ISO-8859-1’, ‘UTF-8’)
Raises:: LookupError – If the encoding is not recognized by Python

Example

>>> Config.normalize_encoding_name('latin-1')
'ISO-8859-1'
>>> Config.normalize_encoding_name('utf-8')
'UTF-8'

__init__(halt_on_error: bool = False, collection_formats: frozenset[CDLFormat] = frozenset({CDLFormat.ALE, CDLFormat.CCC, CDLFormat.CDL, CDLFormat.EDL, CDLFormat.FLEX, CDLFormat.OTIO}), single_formats: frozenset[CDLFormat] = frozenset({CDLFormat.CC, CDLFormat.NK, CDLFormat.RCDL}), sop_tag_name: str = 'SOPNode', sat_tag_name: str = 'SatNode', _input_encoding: str | None = None, _output_encoding: str = 'utf-8') → None¶

is_collection_format(format_type: str) → bool[source]¶

Check if a format string represents a collection format.

Parameters:: format_type – Format string to check (e.g., ‘ccc’, ‘cdl’)
Returns:: True if the format is a collection format, False otherwise.

is_single_format(format_type: str) → bool[source]¶

Check if a format string represents a single correction format.

Parameters:: format_type – Format string to check (e.g., ‘cc’, ‘rcdl’)
Returns:: True if the format is a single format, False otherwise.

set_sat_tag_name(tag_name: str) → None[source]¶

Set Saturation tag name with validation.

Parameters:: tag_name – Tag name to use. Must be ‘SatNode’, ‘SATNode’, or ‘ASC_SAT’.
Raises:: ValidationError – If tag_name is not a valid option.

Example

>>> config.set_sat_tag_name("ASC_SAT")
>>> config.set_sat_tag_name("SATNode")  # Legacy behavior
>>> config.set_sat_tag_name("InvalidTag")  # Raises ValidationError

set_sop_tag_name(tag_name: str) → None[source]¶

Set SOP tag name with validation.

Parameters:: tag_name – Tag name to use. Must be ‘SOPNode’ or ‘ASC_SOP’.
Raises:: ValidationError – If tag_name is not a valid option.

Example

>>> config.set_sop_tag_name("ASC_SOP")
>>> config.set_sop_tag_name("InvalidTag")  # Raises ValidationError

Usage Examples¶

Strict Validation Mode¶

Enable strict validation to raise exceptions instead of using default behavior:

from cdl_convert.config import config

# Enable strict mode
config.halt_on_error = True

# Now parsing errors will raise exceptions
try:
    cc = parse_cc('invalid.cc')
except ValidationError as e:
    print(f"Validation failed: {e}")

Format Type Checking¶

Use the configuration to determine how to handle different format types:

from cdl_convert.config import config

def process_file(filepath, format_type):
    if config.is_collection_format(format_type):
        # Parse as collection
        collection = parse_collection(filepath)
        return collection
    elif config.is_single_format(format_type):
        # Parse as single correction
        correction = parse_correction(filepath)
        return correction
    else:
        raise ValueError(f"Unknown format: {format_type}")

Working with Format Enums¶

Use the CDLFormat enum for type-safe format handling:

from cdl_convert.config import CDLFormat, config

def get_parser(format_type: CDLFormat):
    """Get the appropriate parser for a format type."""
    if format_type in config.collection_formats:
        return parse_collection
    elif format_type in config.single_formats:
        return parse_correction
    else:
        raise ValueError(f"Unsupported format: {format_type}")

# Use with enum
parser = get_parser(CDLFormat.CCC)

Configurable XML Tag Names¶

Configure the XML element tag names used for SOP and Saturation nodes to improve compatibility with different color correction systems:

from cdl_convert.config import config
from cdl_convert import write_cc, ColorCorrection

# Use ASC CDL specification-compliant tag names
config.set_sop_tag_name('ASC_SOP')
config.set_sat_tag_name('ASC_SAT')

# Create and write a color correction
cc = ColorCorrection('shot_001')
cc.slope = [1.2, 1.1, 1.0]
cc.sat = 0.9
write_cc(cc)  # Will use ASC_SOP and ASC_SAT tags

# Use legacy SATNode tag for backward compatibility
config.set_sat_tag_name('SATNode')
write_cc(cc)  # Will use SOPNode and SATNode tags

Available SOP Tag Names:

'SOPNode' (default) - Standard format
'ASC_SOP' - ASC CDL specification format

Available Saturation Tag Names:

'SatNode' (default) - Standard format (new in v1.0)
'SATNode' - Legacy format (pre-v1.0)
'ASC_SAT' - ASC CDL specification format

Note

The default Saturation tag changed from 'SATNode' to 'SatNode' in v1.0 to adhere to the CDL specification. Use config.set_sat_tag_name('SATNode') to maintain legacy behavior.

Migration from Legacy Configuration¶

Prior to version 1.0, cdl_convert used a simple module-level HALT_ON_ERROR boolean. The new configuration system provides:

Type safety through dataclasses and enums
Validation of configuration values
Extensibility for future configuration options
Better IDE support with type hints

Legacy code:

# Old way (pre-1.0)
from cdl_convert import config
config.HALT_ON_ERROR = True

Modern code:

# New way (1.0+)
from cdl_convert.config import config
config.halt_on_error = True

Note

The global config instance is mutable, allowing you to change settings at runtime. However, be aware that changes affect all subsequent operations in your application.

Warning

The collection_formats and single_formats attributes are frozen sets and cannot be modified. This ensures consistency in format type classification throughout the library.