# ducpy

> # ducpy
> 
> <p align="center">
>   <br/>
>   <a href="https://duc.ducflair.com" target="_blank"><img width="256px" src="https://cdn.jsdelivr.net/gh/ducflair/assets@main/src/duc/duc-extended.png" /></a>
>   <p align="center">SQLite-backed project-state format for physical-engineering work before execution</p>
>   <p align="center" style="align: center;">
>     <a href="https://pypi.org/project/ducpy/"><img src="https://shields.io/badge/Pip-blue?logo=Pypi&logoColor=white&style=round-square" alt="Pip" /></a>
>     <a href="https://github.com/ducflair/duc/releases"><img src="https://img.shields.io/pypi/v/ducpy?style=round-square&label=latest%20stable" alt="PyPI ducpy@latest release" /></a>
>     <a href="https://pypi.org/project/ducpy/"><img src="https://img.shields.io/pypi/dm/ducpy?style=round-square&color=salmon" alt="Downloads" /></a>
>     <img src="https://shields.io/badge/Python-ffde57?logo=Python&logoColor=646464&style=round-square" alt="Python" />
>   </p>
> </p>
> 
> The `ducpy` package is the official Python implementation of the `.duc` project-state format. It is built on top of the [`duc`](../ducrs) Rust crate, exposed as the `ducpy_native` extension. A `.duc` file is a gzip-compressed SQLite database — `ducpy` gives you both a high-level builder DSL and direct low-level access to that schema, plus parsing, serialization, and search helpers.
> 
> ## Installation
> 
> ```bash
> pip install ducpy
> ```
> 
> or with [`uv`](https://docs.astral.sh/uv/):
> 
> ```bash
> uv add ducpy
> ```
> 
> ## Quick start
> 
> ```python
> import ducpy as duc
> ```
> 
> ## API overview
> 
> `ducpy` is organised around four conceptual entry points, matching the structure of the full [API reference](https://duc.ducflair.com):
> 
> ### Builders API (High-level)
> 
> The easy way to build and manage `.duc` files. Construct elements, apply styles, manage layers, build blocks, and handle document state through the `duc.builders` module.
> 
> See the worked examples:
> 
> - [Element creation](src/examples/element_creation_demo.py) — building rectangles, ellipses, polygons, lines, arrows, text, frames and plots with the fluent builder DSL.
> - [Mutating elements](src/examples/mutation_demo.py) — updating element properties in place and observing version changes.
> - [Document elements](src/examples/document_element_demo.py) and [model elements](src/examples/model_element_demo.py) — for the higher-level container / model element types.
> 
> ### SQL Builder (Low-level)
> 
> A `.duc` file is a gzip-compressed SQLite database. Use `duc.builders.sql_builder` (`DucSQL`) for direct schema access, bulk queries, and low-level manipulation.
> 
> See the worked example: [SQL Builder](src/examples/sql_builder_demo.py) — `DucSQL.new()` to create a `.duc` from scratch, `DucSQL(path)` to query an existing one.
> 
> ### Search
> 
> Query and search elements and files programmatically through the `duc.search` API.
> 
> ### File I/O
> 
> Read and write `.duc` files using the `duc.parse` and `duc.serialize` modules.
> 
> See the worked examples:
> 
> - [Parsing](src/examples/parsing_demo.py) — `parse_duc` / `list_external_files` / streaming revision helpers.
> - [Serialization](src/examples/serialization_demo.py) — `serialize_duc` from builder-created elements.
> - [External files](src/examples/external_files_demo.py) — attaching binary blobs (images, PDFs) to a `.duc` document.
> 
> ## Documentation
> 
> For detailed documentation, including the full API reference, schema specification, and end-to-end examples, see:
> 
> - API reference & guides: [duc.ducflair.com](https://duc.ducflair.com)
> - Source-level reference: [docs/](docs/index.rst)
> - Full example index: [docs/examples.rst](docs/examples.rst)
> 
> ## Tools
> 
> - [Playground](https://scopture.com): Experiment with the `duc` format in a live environment.
> 
> ## Contributing
> 
> Feel free to open an issue or contact us at [Ducflair Support](https://www.ducflair.com/support).
> 
> ## License
> 
> This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more details.


2026, Ducflair

## Pages

- [ducpy](index.html.md): &#42;&#42;Builders API (High-level)&#42;&#42;
- [API Reference](autoapi/index.html.md): This page contains auto-generated API reference documentation &lt;sup&gt;1&lt;/sup&gt;.
- [ducpy](autoapi/ducpy/index.html.md): Python library for the .duc project-state format for physical-engineering work before execution.
- [ducpy.builders](autoapi/ducpy/builders/index.html.md): User-friendly helper functions for creating DUC elements without verbose dataclass construction.
- [ducpy.builders.block_instance_builder](autoapi/ducpy/builders/block_instance_builder/index.html.md): | &#96;BlockInstanceBuilder&#96;   |    |
- [ducpy.builders.block_utils](autoapi/ducpy/builders/block_utils/index.html.md): | &#96;&#95;get_base&#96;(element)     |                                                        |
- [ducpy.builders.element_builders](autoapi/ducpy/builders/element_builders/index.html.md): Helper functions for creating DUC elements with a user-friendly API.
- [ducpy.builders.mutate_builder](autoapi/ducpy/builders/mutate_builder/index.html.md): | &#96;mutate_element&#96;(el, &#92;&#42;&#92;&#42;kwargs)               | Mutate any property of an element (ElementWrapper...
- [ducpy.builders.sql_builder](autoapi/ducpy/builders/sql_builder/index.html.md): Thin wrapper to open .duc files as SQLite databases and run raw SQL.
- [ducpy.builders.state_builders](autoapi/ducpy/builders/state_builders/index.html.md): Helper functions for creating DUC state-related objects with a user-friendly API.
- [ducpy.builders.style_builders](autoapi/ducpy/builders/style_builders/index.html.md): Helper functions for creating element styles with a user-friendly API.
- [ducpy.classes](autoapi/ducpy/classes/index.html.md): &#42; ducpy.classes.DataStateClass
- [ducpy.classes.DataStateClass](autoapi/ducpy/classes/DataStateClass/index.html.md): | &#96;DucIssueAnchor&#96;   |    |
- [ducpy.classes.ElementsClass](autoapi/ducpy/classes/ElementsClass/index.html.md): | &#96;DucElement&#96;   |    |
- [ducpy.classes.locator](autoapi/ducpy/classes/locator/index.html.md): | &#96;ExternalFileResolutionStatus&#96;   | str(object='') -&gt; str   |
- [ducpy.enums](autoapi/ducpy/enums/index.html.md): Native enum definitions for DUC types.
- [ducpy.model_output](autoapi/ducpy/model_output/index.html.md): Typed model artifacts shared by desktop and cloud Python workers.
- [ducpy.parse](autoapi/ducpy/parse/index.html.md): Parse .duc files using the Rust native extension (ducpy_native).
- [ducpy.search](autoapi/ducpy/search/index.html.md): Search helpers for DUC SQLite databases.
- [ducpy.search.&#95;model_files](autoapi/ducpy/search/_model_files/index.html.md): Internal helpers for reading model-linked external files from DUC data.
- [ducpy.search.image_ocr](autoapi/ducpy/search/image_ocr/index.html.md): Server-side image OCR helpers for DUC search.
- [ducpy.search.search_build123d](autoapi/ducpy/search/search_build123d/index.html.md): Semantic text extraction for build123d model elements.
- [ducpy.search.search_charter_issues](autoapi/ducpy/search/search_charter_issues/index.html.md): Search user-authored project Charter and Issue content in DUC files.
- [ducpy.search.search_elements](autoapi/ducpy/search/search_elements/index.html.md): Element search helpers for &#96;.duc&#96; SQLite databases.
- [ducpy.search.search_external_files](autoapi/ducpy/search/search_external_files/index.html.md): Scoped external-file search helpers.
- [ducpy.search.search_ezdxf](autoapi/ducpy/search/search_ezdxf/index.html.md): DXF text extraction for model-element search (the &#96;ezdxf&#96; engine).
- [ducpy.search.search_ifc](autoapi/ducpy/search/search_ifc/index.html.md): IFC text extraction for model-element search (the IfcOpenShell engine).
- [ducpy.search.search_models](autoapi/ducpy/search/search_models/index.html.md): Scoped model-element search helpers.
- [ducpy.search.search_pdf](autoapi/ducpy/search/search_pdf/index.html.md): PDF text extraction for search.
- [ducpy.serialize](autoapi/ducpy/serialize/index.html.md): Serialize DUC data using the Rust native extension (ducpy_native).
- [ducpy.tessellate](autoapi/ducpy/tessellate/index.html.md): CAD and BIM model tessellation subpackage for ducpy.
- [ducpy.tessellate.&#95;&#92;&#95;main&#95;&#92;&#95;](autoapi/ducpy/tessellate/__main__/index.html.md): Module entry point for python -m ducpy.tessellate.
- [ducpy.tessellate.cli](autoapi/ducpy/tessellate/cli/index.html.md): CLI entry point for ducpy CAD and BIM tessellation sidecar.
- [ducpy.tessellate.runner](autoapi/ducpy/tessellate/runner/index.html.md): CAD and BIM model tessellation execution engine for ducpy.
- [ducpy.tessellate.shims](autoapi/ducpy/tessellate/shims/index.html.md): CAD and BIM tessellation and capture shims for ducpy.
- [ducpy.utils](autoapi/ducpy/utils/index.html.md): &#42; ducpy.utils.constants
- [ducpy.utils.constants](autoapi/ducpy/utils/constants/index.html.md): Utility constants for DucPy package.
- [ducpy.utils.convert](autoapi/ducpy/utils/convert/index.html.md): Utilities for converting between Python snake_case and Rust/JSON camelCase naming,
- [ducpy.utils.io](autoapi/ducpy/utils/io/index.html.md): This module provides high-level functions for reading and writing DUC files.
- [ducpy.utils.mutate_utils](autoapi/ducpy/utils/mutate_utils/index.html.md): Utility function for recursively mutating dataclass objects.
- [ducpy.utils.rand_utils](autoapi/ducpy/utils/rand_utils/index.html.md): | &#96;generate_random_id&#96;(&#91;length&#93;)   | Generate a random string ID.                        |
- [Examples](examples.html.md): The source for all examples lives in &#96;packages/ducpy/src/examples/&#96;.
- [Downloads &amp; Installation](downloads.html.md): The recommended way to install ducpy:
