qc.serializers

ITypeSerializer

Bases: Protocol

Protocol defining the interface for type-specific serializers.

This protocol ensures that all serializer implementations provide both byte-based (for embedding) and file-based (for external storage) serialization.

can_serialize

can_serialize(obj: Any) -> bool

Check if this serializer can handle the given object type.

Parameters:

Name	Type	Description	Default
obj	Any	Object to check.	required

Returns:

Name	Type	Description
bool	bool	True if this serializer can handle the object.

Source code in src/contraqctor/qc/serializers.py

def can_serialize(self, obj: t.Any) -> bool:
    """Check if this serializer can handle the given object type.

    Args:
        obj: Object to check.

    Returns:
        bool: True if this serializer can handle the object.
    """
    ...

serialize_as_bytes

serialize_as_bytes(obj: Any) -> Dict[str, Any]

Serialize the object to a dictionary with base64-encoded bytes.

Used for embedding data directly in reports (e.g., HTML).

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize.	required

Returns:

Type	Description
Dict[str, Any]	Dict containing the serialized representation with base64-encoded data.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_bytes(self, obj: t.Any) -> t.Dict[str, t.Any]:
    """Serialize the object to a dictionary with base64-encoded bytes.

    Used for embedding data directly in reports (e.g., HTML).

    Args:
        obj: Object to serialize.

    Returns:
        Dict containing the serialized representation with base64-encoded data.
    """
    ...

serialize_as_file

serialize_as_file(
    obj: Any, output_dir: Path, filename: str
) -> Dict[str, Any]

Serialize the object to a file and return metadata.

Used for saving data to external files (e.g., for CLI reports).

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize.	required
output_dir	Path	Directory where the file should be saved.	required
filename	str	Name for the output file (without extension).	required

Returns:

Type	Description
Dict[str, Any]	Dict containing metadata including 'type', 'path', and other relevant info.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_file(self, obj: t.Any, output_dir: Path, filename: str) -> t.Dict[str, t.Any]:
    """Serialize the object to a file and return metadata.

    Used for saving data to external files (e.g., for CLI reports).

    Args:
        obj: Object to serialize.
        output_dir: Directory where the file should be saved.
        filename: Name for the output file (without extension).

    Returns:
        Dict containing metadata including 'type', 'path', and other relevant info.
    """
    ...

TypeSerializer

Bases: ABC

Base class for type-specific serializers.

Implements the ITypeSerializer protocol with abstract methods that must be overridden by subclasses.

can_serialize abstractmethod

can_serialize(obj: Any) -> bool

Check if this serializer can handle the given object type.

Parameters:

Name	Type	Description	Default
obj	Any	Object to check.	required

Returns:

Name	Type	Description
bool	bool	True if this serializer can handle the object.

Source code in src/contraqctor/qc/serializers.py

@abstractmethod
def can_serialize(self, obj: t.Any) -> bool:
    """Check if this serializer can handle the given object type.

    Args:
        obj: Object to check.

    Returns:
        bool: True if this serializer can handle the object.
    """
    pass

serialize_as_bytes abstractmethod

serialize_as_bytes(obj: Any) -> Dict[str, Any]

Serialize the object to a dictionary with base64-encoded bytes.

Used for embedding data directly in reports (e.g., HTML).

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize.	required

Returns:

Type	Description
Dict[str, Any]	Dict containing the serialized representation with base64-encoded data.

Source code in src/contraqctor/qc/serializers.py

@abstractmethod
def serialize_as_bytes(self, obj: t.Any) -> t.Dict[str, t.Any]:
    """Serialize the object to a dictionary with base64-encoded bytes.

    Used for embedding data directly in reports (e.g., HTML).

    Args:
        obj: Object to serialize.

    Returns:
        Dict containing the serialized representation with base64-encoded data.
    """
    pass

serialize_as_file abstractmethod

serialize_as_file(
    obj: Any, output_dir: Path, filename: str
) -> Dict[str, Any]

Serialize the object to a file and return metadata.

Used for saving data to external files (e.g., for CLI reports).

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize.	required
output_dir	Path	Directory where the file should be saved.	required
filename	str	Name for the output file (without extension).	required

Returns:

Type	Description
Dict[str, Any]	Dict containing metadata including 'type', 'path', and other relevant info.

Source code in src/contraqctor/qc/serializers.py

@abstractmethod
def serialize_as_file(self, obj: t.Any, output_dir: Path, filename: str) -> t.Dict[str, t.Any]:
    """Serialize the object to a file and return metadata.

    Used for saving data to external files (e.g., for CLI reports).

    Args:
        obj: Object to serialize.
        output_dir: Directory where the file should be saved.
        filename: Name for the output file (without extension).

    Returns:
        Dict containing metadata including 'type', 'path', and other relevant info.
    """
    pass

MatplotlibFigureSerializer

Bases: TypeSerializer

Serializer for matplotlib Figure objects.

can_serialize

can_serialize(obj: Any) -> bool

Check if object is a matplotlib Figure.

Source code in src/contraqctor/qc/serializers.py

def can_serialize(self, obj: t.Any) -> bool:
    """Check if object is a matplotlib Figure."""
    try:
        import matplotlib.figure

        return isinstance(obj, matplotlib.figure.Figure)
    except ImportError:
        return False

serialize_as_bytes

serialize_as_bytes(obj: Any) -> Dict[str, Any]

Serialize matplotlib Figure to base64-encoded PNG.

Parameters:

Name	Type	Description	Default
obj	Any	Matplotlib Figure object.	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'data' keys containing base64-encoded PNG.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_bytes(self, obj: t.Any) -> t.Dict[str, t.Any]:
    """Serialize matplotlib Figure to base64-encoded PNG.

    Args:
        obj: Matplotlib Figure object.

    Returns:
        Dict with 'type' and 'data' keys containing base64-encoded PNG.
    """
    buf = io.BytesIO()
    obj.savefig(buf, format="png", bbox_inches="tight")
    buf.seek(0)
    img_base64 = base64.b64encode(buf.read()).decode("utf-8")
    buf.close()

    return {"type": "image", "data": f"data:image/png;base64,{img_base64}"}

serialize_as_file

serialize_as_file(
    obj: Any, output_dir: Path, filename: str
) -> Dict[str, Any]

Serialize matplotlib Figure to a PNG file.

Parameters:

Name	Type	Description	Default
obj	Any	Matplotlib Figure object.	required
output_dir	Path	Directory where the file should be saved.	required
filename	str	Name for the output file (without extension).	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'path' keys.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_file(self, obj: t.Any, output_dir: Path, filename: str) -> t.Dict[str, t.Any]:
    """Serialize matplotlib Figure to a PNG file.

    Args:
        obj: Matplotlib Figure object.
        output_dir: Directory where the file should be saved.
        filename: Name for the output file (without extension).

    Returns:
        Dict with 'type' and 'path' keys.
    """
    output_dir.mkdir(parents=True, exist_ok=True)
    output_path = output_dir / f"{filename}.png"
    obj.savefig(output_path, format="png", bbox_inches="tight")

    return {"type": "image", "path": str(output_path)}

PILImageSerializer

Bases: TypeSerializer

Serializer for PIL Image objects.

can_serialize

can_serialize(obj: Any) -> bool

Check if object is a PIL Image.

Source code in src/contraqctor/qc/serializers.py

def can_serialize(self, obj: t.Any) -> bool:
    """Check if object is a PIL Image."""
    try:
        from PIL import Image

        return isinstance(obj, Image.Image)
    except ImportError:
        return False

serialize_as_bytes

serialize_as_bytes(obj: Any) -> Dict[str, Any]

Serialize PIL Image to base64-encoded PNG.

Parameters:

Name	Type	Description	Default
obj	Any	PIL Image object.	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'data' keys containing base64-encoded PNG.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_bytes(self, obj: t.Any) -> t.Dict[str, t.Any]:
    """Serialize PIL Image to base64-encoded PNG.

    Args:
        obj: PIL Image object.

    Returns:
        Dict with 'type' and 'data' keys containing base64-encoded PNG.
    """
    buf = io.BytesIO()
    obj.save(buf, format="PNG")
    buf.seek(0)
    img_base64 = base64.b64encode(buf.read()).decode("utf-8")
    buf.close()

    return {"type": "image", "data": f"data:image/png;base64,{img_base64}"}

serialize_as_file

serialize_as_file(
    obj: Any, output_dir: Path, filename: str
) -> Dict[str, Any]

Serialize PIL Image to a PNG file.

Parameters:

Name	Type	Description	Default
obj	Any	PIL Image object.	required
output_dir	Path	Directory where the file should be saved.	required
filename	str	Name for the output file (without extension).	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'path' keys.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_file(self, obj: t.Any, output_dir: Path, filename: str) -> t.Dict[str, t.Any]:
    """Serialize PIL Image to a PNG file.

    Args:
        obj: PIL Image object.
        output_dir: Directory where the file should be saved.
        filename: Name for the output file (without extension).

    Returns:
        Dict with 'type' and 'path' keys.
    """
    output_dir.mkdir(parents=True, exist_ok=True)
    output_path = output_dir / f"{filename}.png"
    obj.save(output_path, format="PNG")

    return {"type": "image", "path": str(output_path)}

NumpyArrayImageSerializer

Bases: TypeSerializer

Serializer for numpy arrays representing images.

can_serialize

can_serialize(obj: Any) -> bool

Check if object is a numpy array that could be an image.

Valid image arrays are 2D (grayscale) or 3D with 3 or 4 channels (RGB/RGBA).

Source code in src/contraqctor/qc/serializers.py

def can_serialize(self, obj: t.Any) -> bool:
    """Check if object is a numpy array that could be an image.

    Valid image arrays are 2D (grayscale) or 3D with 3 or 4 channels (RGB/RGBA).
    """
    try:
        import numpy as np

        if not isinstance(obj, np.ndarray):
            return False

        if obj.ndim == 2:
            return True
        elif obj.ndim == 3 and obj.shape[2] in (3, 4):
            return True

        return False
    except ImportError:
        return False

serialize_as_bytes

serialize_as_bytes(obj: Any) -> Dict[str, Any]

Serialize numpy array to base64-encoded PNG using PIL.

Parameters:

Name	Type	Description	Default
obj	Any	Numpy array representing an image.	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'data' keys containing base64-encoded PNG.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_bytes(self, obj: t.Any) -> t.Dict[str, t.Any]:
    """Serialize numpy array to base64-encoded PNG using PIL.

    Args:
        obj: Numpy array representing an image.

    Returns:
        Dict with 'type' and 'data' keys containing base64-encoded PNG.
    """
    img = self._array_to_pil(obj)

    buf = io.BytesIO()
    img.save(buf, format="PNG")
    buf.seek(0)
    img_base64 = base64.b64encode(buf.read()).decode("utf-8")
    buf.close()

    return {"type": "image", "data": f"data:image/png;base64,{img_base64}"}

serialize_as_file

serialize_as_file(
    obj: Any, output_dir: Path, filename: str
) -> Dict[str, Any]

Serialize numpy array to a PNG file.

Parameters:

Name	Type	Description	Default
obj	Any	Numpy array representing an image.	required
output_dir	Path	Directory where the file should be saved.	required
filename	str	Name for the output file (without extension).	required

Returns:

Type	Description
Dict[str, Any]	Dict with 'type' and 'path' keys.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_file(self, obj: t.Any, output_dir: Path, filename: str) -> t.Dict[str, t.Any]:
    """Serialize numpy array to a PNG file.

    Args:
        obj: Numpy array representing an image.
        output_dir: Directory where the file should be saved.
        filename: Name for the output file (without extension).

    Returns:
        Dict with 'type' and 'path' keys.
    """
    img = self._array_to_pil(obj)

    output_dir.mkdir(parents=True, exist_ok=True)
    output_path = output_dir / f"{filename}.png"
    img.save(output_path, format="PNG")

    return {"type": "image", "path": str(output_path)}

ContextExportableObjSerializer

ContextExportableObjSerializer(
    serializers: Optional[List[ITypeSerializer]] = None,
)

Serializer for ContextExportableObj instances.

This class recursively searches through dictionaries and serializes ContextExportableObj instances based on their wrapped object types.

Attributes:

Name	Type	Description
serializers	List[ITypeSerializer]	List of ITypeSerializer instances to use for serialization.

Initialize the serializer with optional custom type serializers.

Parameters:

Name	Type	Description	Default
serializers	Optional[List[ITypeSerializer]]	List of ITypeSerializer instances. If None, uses default serializers for matplotlib figures and PIL/numpy images.	None

Source code in src/contraqctor/qc/serializers.py

def __init__(self, serializers: t.Optional[t.List[ITypeSerializer]] = None):
    """Initialize the serializer with optional custom type serializers.

    Args:
        serializers: List of ITypeSerializer instances. If None, uses default
            serializers for matplotlib figures and PIL/numpy images.
    """
    if serializers is None:
        self.serializers: t.List[ITypeSerializer] = t.cast(t.List[ITypeSerializer], KNOWN_SERIALIZERS.copy())
    else:
        self.serializers = serializers

add_serializer

add_serializer(serializer: ITypeSerializer) -> None

Add a custom type serializer.

Parameters:

Name	Type	Description	Default
serializer	ITypeSerializer	ITypeSerializer instance to add.	required

Source code in src/contraqctor/qc/serializers.py

def add_serializer(self, serializer: ITypeSerializer) -> None:
    """Add a custom type serializer.

    Args:
        serializer: ITypeSerializer instance to add.
    """
    self.serializers.append(serializer)

serialize_as_bytes

serialize_as_bytes(context: Any) -> Any

Recursively serialize ContextExportableObj instances to base64-encoded bytes.

This method walks through the context structure and serializes any ContextExportableObj instances it finds to base64-encoded data.

Parameters:

Name	Type	Description	Default
context	Any	Context data to serialize (can be dict, list, or any value).	required

Returns:

Type	Description
Any	Serialized context with ContextExportableObj instances replaced by
Any	their base64-encoded representations.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_bytes(self, context: t.Any) -> t.Any:
    """Recursively serialize ContextExportableObj instances to base64-encoded bytes.

    This method walks through the context structure and serializes any
    ContextExportableObj instances it finds to base64-encoded data.

    Args:
        context: Context data to serialize (can be dict, list, or any value).

    Returns:
        Serialized context with ContextExportableObj instances replaced by
        their base64-encoded representations.
    """
    if isinstance(context, dict):
        result = {}
        for key, value in context.items():
            if isinstance(value, ContextExportableObj):
                result[key] = self._serialize_exportable_obj_as_bytes(value)
            else:
                result[key] = self.serialize_as_bytes(value)
        return result
    elif isinstance(context, (list, tuple)):
        return type(context)(self.serialize_as_bytes(item) for item in context)
    elif isinstance(context, ContextExportableObj):
        return self._serialize_exportable_obj_as_bytes(context)
    else:
        return context

serialize_as_file

serialize_as_file(
    context: Any,
    output_dir: Path,
    base_filename: str = "asset",
    counter: Optional[dict] = None,
) -> Any

Recursively serialize ContextExportableObj instances to files.

This method walks through the context structure and serializes any ContextExportableObj instances it finds to external files.

Parameters:

Name	Type	Description	Default
context	Any	Context data to serialize (can be dict, list, or any value).	required
output_dir	Path	Directory where files should be saved.	required
base_filename	str	Base name for output files.	'asset'
counter	Optional[dict]	Optional counter dict to track file numbers (for internal use).	None

Returns:

Type	Description
Any	Serialized context with ContextExportableObj instances replaced by
Any	their file path representations.

Source code in src/contraqctor/qc/serializers.py

def serialize_as_file(
    self, context: t.Any, output_dir: Path, base_filename: str = "asset", counter: t.Optional[dict] = None
) -> t.Any:
    """Recursively serialize ContextExportableObj instances to files.

    This method walks through the context structure and serializes any
    ContextExportableObj instances it finds to external files.

    Args:
        context: Context data to serialize (can be dict, list, or any value).
        output_dir: Directory where files should be saved.
        base_filename: Base name for output files.
        counter: Optional counter dict to track file numbers (for internal use).

    Returns:
        Serialized context with ContextExportableObj instances replaced by
        their file path representations.
    """
    if counter is None:
        counter = {"count": 0}

    if isinstance(context, dict):
        result = {}
        for key, value in context.items():
            if isinstance(value, ContextExportableObj):
                result[key] = self._serialize_exportable_obj_as_file(value, output_dir, base_filename, counter)
            else:
                result[key] = self.serialize_as_file(value, output_dir, base_filename, counter)
        return result
    elif isinstance(context, (list, tuple)):
        return type(context)(self.serialize_as_file(item, output_dir, base_filename, counter) for item in context)
    elif isinstance(context, ContextExportableObj):
        return self._serialize_exportable_obj_as_file(context, output_dir, base_filename, counter)
    else:
        return context