API Reference

Complete reference for all public functions, classes, and constants in the crous Python module.

Core Functions

crous.dumps(obj, default=None)

Serialize a Python object to FLUX binary bytes.

Returns: bytes — FLUX binary data

Raises: CrousEncodeError — if serialization fails

crous.loads(data, object_hook=None)

Deserialize FLUX/CROUS binary bytes to a Python object.

Returns: Any — Deserialized Python object

Raises: CrousDecodeError — if deserialization fails

crous.dump(obj, file, default=None)

Serialize and write to a file path or file object.

Returns: None

Raises: CrousEncodeError, IOError

crous.load(file, object_hook=None)

Read and deserialize from a file path or file object.

Returns: Any — Deserialized Python object

Raises: CrousDecodeError, FileNotFoundError

Stream Functions

crous.dump_to_stream(obj, stream, default=None)

Serialize and write to a writable stream.

crous.load_from_stream(stream, object_hook=None)

Read and deserialize from a readable stream.

CROUT Functions

crous.to_crout(obj)

Serialize a Python object to CROUT text format.

Returns: str — CROUT text representation

crous.from_crout(text)

Deserialize CROUT text to a Python object.

Returns: Any — Deserialized Python object

crous.crout_to_flux(text)

Convert CROUT text directly to FLUX binary (no Python intermediary).

Returns: bytes — FLUX binary data

crous.flux_to_crout(data)

Convert FLUX binary directly to CROUT text (no Python intermediary).

Returns: str — CROUT text representation

Custom Serializer Registry

crous.register_serializer(type, serializer, tag=None)

Register a custom serializer for a Python type.

crous.unregister_serializer(type)

Remove a previously registered serializer.

crous.register_decoder(tag, decoder)

Register a custom decoder for a tagged value.

crous.unregister_decoder(tag)

Remove a previously registered decoder.

Classes

crous.CrousEncoder

Reusable encoder with persistent options.

class CrousEncoder:
    def __init__(self, default=None, allow_custom=True):
        """
        Args:
            default: Fallback handler for unsupported types
            allow_custom: Whether to use registered custom serializers
        """

    def encode(self, obj) -> bytes:
        """Serialize obj to FLUX binary bytes."""

crous.CrousDecoder

Reusable decoder with persistent options.

class CrousDecoder:
    def __init__(self, object_hook=None):
        """
        Args:
            object_hook: Transform function for decoded dictionaries
        """

    def decode(self, data: bytes) -> Any:
        """Deserialize FLUX binary bytes to Python object."""

Exceptions

crous.CrousError

Base exception for all Crous errors. Inherits from Exception.

crous.CrousEncodeError

Raised during serialization. Inherits from CrousError.

crous.CrousDecodeError

Raised during deserialization. Inherits from CrousError.

Module Attributes

crous.version Module

The crous.version submodule provides detailed version and compatibility utilities.

Constants

Feature Flags (IntFlag)

SemanticVersion

from crous.version import SemanticVersion

# Create from string
v = SemanticVersion.parse("2.0.0")

# Get current library version
v = SemanticVersion.current()

# Comparison operators
v1 = SemanticVersion.parse("1.0.0")
v2 = SemanticVersion.parse("2.0.0")
assert v1 < v2

# Constraint checking (supports >=, >, <=, <, ==, !=, ^, ~)
assert v2.satisfies(">=1.0.0")
assert v2.satisfies("^2.0.0")
assert v2.satisfies("~2.0")

# Bump versions
v3 = v2.bump_minor()   # 2.1.0
v4 = v2.bump_major()   # 3.0.0

Header

from crous.version import Header

header = Header.parse(binary_data)
header.magic         # b'FLUX'
header.wire_version  # 1
header.flags         # 0
header.is_valid      # True if magic == b'FLUX'

check_compatibility(data)

from crous.version import check_compatibility

result = check_compatibility(binary_data)
result.status         # Compatibility enum value
result.is_compatible  # True/False
result.is_warning     # True if warnings
result.is_error       # True if incompatible
result.message        # Human-readable description

Serializable Types

# Type alias for all natively serializable types
CrousSerializable = Union[
    None,
    bool,
    int,
    float,
    str,
    bytes,
    List['CrousSerializable'],
    Tuple['CrousSerializable', ...],
    Dict[str, 'CrousSerializable'],
    Set['CrousSerializable'],
    FrozenSet['CrousSerializable'],
]