ducpy.serialize¶

Serialize DUC data using the Rust native extension (ducpy_native).

Attributes¶

`logger`
`DUC_SCHEMA_VERSION`
`_ELEMENT_CLASS_TO_TYPE`
`_FLATTEN_KEYS`

Functions¶

`_find_schema_file`(→ pathlib.Path \| None)
`_decode_user_version_to_semver`(→ str)	Decode sqlite-style schema user_version to semver.
`_read_schema_version_fallback`(→ str)	Resolve schema version directly from repository schema/duc.sql.
`_flatten_dict`(→ dict)	Recursively flatten nested dicts whose key is in `_FLATTEN_KEYS`.
`_element_to_camel`(→ dict)	Convert an element (or ElementWrapper) to the camelCase dict Rust expects.
`_convert_external_files`(→ Tuple[Optional[Dict[str, ...)	Convert DucExternalFile dict (or legacy list) to camelCase dicts for serialization.
`_convert_dict_entries`(→ Optional[Dict[str, str]])	Convert a list of DictionaryEntry to a `{key: value}` dict.
`_convert_list`(→ Optional[list])	Convert a list of dataclass instances to camelCase dicts.
`serialize_duc`(→ bytes)	Serialize elements and document state to raw `.duc` binary format.

Module Contents¶

ducpy.serialize.logger¶

ducpy.serialize._find_schema_file() → pathlib.Path | None¶

ducpy.serialize._decode_user_version_to_semver(user_version: int) → str¶

Decode sqlite-style schema user_version to semver.

Encoding convention:: major * 1_000_000 + minor * 1_000 + patch

ducpy.serialize._read_schema_version_fallback() → str¶

Resolve schema version directly from repository schema/duc.sql.

This is used when ducpy._version isn’t available (for example, in clean CI environments before setup-time generation has run).

ducpy.serialize.DUC_SCHEMA_VERSION = '0.0.0'¶

ducpy.serialize._ELEMENT_CLASS_TO_TYPE: Dict[str, str]¶

ducpy.serialize._FLATTEN_KEYS¶

ducpy.serialize._flatten_dict(d: dict) → dict¶: Recursively flatten nested dicts whose key is in _FLATTEN_KEYS.

ducpy.serialize._element_to_camel(wrapper_or_element: Any) → dict¶: Convert an element (or ElementWrapper) to the camelCase dict Rust expects.

ducpy.serialize._convert_external_files(entries: Any | None) → Tuple[Dict[str, Any] | None, Dict[str, bytes] | None]¶

Convert DucExternalFile dict (or legacy list) to camelCase dicts for serialization.

Returns (files_meta, files_data) where files_meta contains revision metadata (no blobs) and files_data maps revision-id → raw bytes for the separate filesData key expected by the Rust serializer.

ducpy.serialize._convert_dict_entries(entries: list | None) → Dict[str, str] | None¶: Convert a list of DictionaryEntry to a {key: value} dict.

ducpy.serialize._convert_list(items: list | None) → list | None¶: Convert a list of dataclass instances to camelCase dicts.

ducpy.serialize.serialize_duc(name: str, thumbnail: bytes | None = None, dictionary: list | None = None, elements: list | None = None, duc_local_state: Any = None, duc_global_state: Any = None, version_graph: Any = None, blocks: list | None = None, block_instances: list | None = None, block_collections: list | None = None, groups: list | None = None, regions: list | None = None, layers: list | None = None, external_files: list | None = None) → bytes¶

Serialize elements and document state to raw .duc binary format.

This function accepts lists of elements created via the ducpy.builders API (e.g., ElementBuilder) and serializes them into the compressed format expected by .duc files. Element instances and state dataclasses are automatically converted to the camelCase dicts expected by the Rust native module.

Parameters¶

namestr: The document name or identifier (used to populate the source field).
thumbnailOptional[bytes], default=None: Raw PNG bytes representing a thumbnail of the document.
dictionaryOptional[list], default=None: List of Key-Value string pairs for dictionary entries.
elementsOptional[list], default=None: A list of elements (e.g., created via ElementBuilder) to include.
duc_local_stateAny, default=None: A DucLocalState object representing viewport state (pan, zoom, etc).
duc_global_stateAny, default=None: A DucGlobalState object representing document-wide settings.
version_graphAny, default=None: Version history metadata of the document.
blocksOptional[list], default=None: List of block definitions.
block_instancesOptional[list], default=None: List of block instances.
block_collectionsOptional[list], default=None: List of block collections (libraries).
groupsOptional[list], default=None: List of element groups.
regionsOptional[list], default=None: List of boolean regions.
layersOptional[list], default=None: List of document layers.
external_filesOptional[list], default=None: List of external files (e.g., embedded images or PDFs).

Returns¶

bytes: The raw .duc binary data, ready to be written to a file.