Transform Exceptions¶

Exceptions for the bidirectional data transformation engine: chain configuration, primitive execution, patching, and external callable invocation.

Exception hierarchy¶

TransformError (base)
├── TransformConfigError       # Invalid chain or primitive configuration
└── TransformChainError        # Chain execution failed
    ├── PrimitiveError         # A single primitive failed
    │   ├── DecodeError        # base64_decode / bytes_decode
    │   ├── DecompressError    # zlib_decompress (also bomb protection)
    │   ├── ParseError         # json_parse / xml_parse
    │   ├── PatchError         # Patch stage (mapping or callable)
    │   ├── SerializeError     # json_serialize / xml_serialize
    │   ├── CompressError      # zlib_compress
    │   └── EncodeError        # base64_encode / bytes_encode
    ├── CallableImportError    # Callable target cannot be imported
    └── CallableError          # Callable raised at execution

TransformConfigError also inherits from the standard library ValueError, so callers can catch it via either base class.

Common failure modes¶

TransformConfigError is raised when a chain definition is invalid (unknown primitive, wrong type, missing required fields, mutually exclusive options set together, callable module not in the whitelist, server reference unknown). Always raised at config-load time, not at first invocation.
DecompressError covers both standard zlib failures and the bomb protection trip (max ratio or absolute size exceeded).
ParseError is raised for malformed JSON or XML input. The XML parser also rejects DOCTYPE declarations to prevent XXE attacks.
PatchError indicates a problem during the patch stage, typically a mapping miss on a non-string field or a type mismatch.
CallableImportError is raised when the callable target cannot be resolved (module not found, function not in module, or module not in the transforms.security.allowed_callable_modules whitelist).
CallableError wraps any exception raised by an external callable during execution, preserving the original exception via __cause__.

Usage patterns¶

Handling chain configuration errors¶

from kstlib.transform import load_transform_config
from kstlib.transform.exceptions import TransformConfigError

try:
    config = load_transform_config()
except TransformConfigError as e:
    logger.error(f"Invalid transforms config: {e}")
    # Common causes:
    # - Unknown primitive name
    # - zlib skip_bytes without explicit backward
    # - mapping AND callable both set on the same patch
    # - callable module not in allowed_callable_modules whitelist
    # - composed_patch references an unknown chain

Handling decompression bombs¶

from kstlib.transform import transform
from kstlib.transform.exceptions import DecompressError

try:
    result = transform(suspicious_blob, "decode_chain")
except DecompressError as e:
    logger.warning(f"Decompression aborted: {e}")
    # Either the absolute decompressed size or the ratio limit was hit.
    # Default limits: 200 MB absolute, 100x ratio.

Handling external callable failures¶

from kstlib.transform import transform
from kstlib.transform.exceptions import (
    CallableImportError,
    CallableError,
    TransformChainError,
)

try:
    result = transform(blob, "patch_dynamic")
except CallableImportError as e:
    logger.error(f"Callable cannot be imported: {e}")
    # Check that the module path is correct AND that it is whitelisted
    # in transforms.security.allowed_callable_modules.
except CallableError as e:
    logger.error(f"Callable raised: {e}")
    logger.error(f"Original error: {e.__cause__}")
    # The wrapped exception is available via __cause__.

Safe wrapper pattern¶

from kstlib.transform import transform
from kstlib.transform.exceptions import TransformError

def safe_transform(blob: str, chain_name: str, **kwargs) -> str | None:
    """Apply a transform chain with comprehensive error handling."""
    try:
        return transform(blob, chain_name, **kwargs)
    except TransformError as e:
        logger.error(f"Transform '{chain_name}' failed: {e}")
        return None

API reference¶

Specialized exceptions raised by the kstlib.transform module.

Exception hierarchy:

KstlibError
    TransformError (base for all transform errors)
        TransformConfigError (invalid configuration, also ValueError)
        TransformChainError (chain execution failed)
            PrimitiveError (single primitive failed)
                DecodeError (base64_decode / bytes_decode)
                DecompressError (zlib_decompress)
                ParseError (json_parse / xml_parse)
                PatchError (patch stage)
                SerializeError (json_serialize / xml_serialize)
                CompressError (zlib_compress)
                EncodeError (base64_encode / bytes_encode)
            CallableImportError (callable not found)
            CallableError (callable raised)

exception kstlib.transform.exceptions.CallableError(target, reason, *, chain_name=None)[source]

Bases: TransformChainError

Callable raised an exception during execution.

target: The callable target string.

__init__(self, target: 'str', reason: 'str', *, chain_name: 'str | None' = None) → 'None' -> None[source]

Initialize CallableError.

Parameters:

target (str) – The callable target string.
reason (str) – Description of the error.
chain_name (str | None) – Name of the chain that was running.

exception kstlib.transform.exceptions.CallableImportError(target, *, chain_name=None)[source]

Bases: TransformChainError

Callable target could not be imported.

target: The import target string that failed.

__init__(self, target: 'str', *, chain_name: 'str | None' = None) → 'None' -> None[source]

Initialize CallableImportError.

Parameters:

target (str) – The import target string (e.g. “module.path:function”).
chain_name (str | None) – Name of the chain that was running.

exception kstlib.transform.exceptions.CompressError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

Zlib compression failed.

exception kstlib.transform.exceptions.DecodeError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

Base64 or bytes decoding failed.

exception kstlib.transform.exceptions.DecompressError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

Zlib decompression failed.

exception kstlib.transform.exceptions.EncodeError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

Base64 or bytes encoding failed.

exception kstlib.transform.exceptions.ParseError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

JSON or XML parsing failed.

exception kstlib.transform.exceptions.PatchError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

Patch stage failed.

exception kstlib.transform.exceptions.PrimitiveError(message, *, primitive_name=None, chain_name=None)[source]

Bases: TransformChainError

A single transform primitive failed.

primitive_name: Name of the primitive that failed.

__init__(self, message: 'str', *, primitive_name: 'str | None' = None, chain_name: 'str | None' = None) → 'None' -> None[source]

Initialize PrimitiveError.

Parameters:

message (str) – Human-readable error message.
primitive_name (str | None) – Name of the primitive that failed.
chain_name (str | None) – Name of the chain that was running.

exception kstlib.transform.exceptions.SerializeError(message, *, primitive_name=None, chain_name=None)[source]

Bases: PrimitiveError

JSON or XML serialization failed.

exception kstlib.transform.exceptions.TransformChainError(message, *, chain_name=None)[source]

Bases: TransformError

Transform chain execution failed.

chain_name: Name of the chain that failed.

__init__(self, message: 'str', *, chain_name: 'str | None' = None) → 'None' -> None[source]

Initialize TransformChainError.

Parameters:

message (str) – Human-readable error message.
chain_name (str | None) – Name of the chain that failed.

exception kstlib.transform.exceptions.TransformConfigError[source]

Bases: TransformError, ValueError

Transform configuration is invalid.

Raised when the transform chain or primitive configuration contains invalid values, missing required fields, or constraint violations.

exception kstlib.transform.exceptions.TransformError[source]

Bases: KstlibError

Base exception for all transform module errors.