ducpy

https://ducflair.github.io/duc/
Admin
ducpy is a Python library for working with 2D CAD files in the DUC format, providing builders for...
Tokens:65,914
Snippets:563
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create New .duc File with DucSQL

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates creating a new .duc file, inserting elements and their styles, verifying inserts, updating elements using named parameters, and saving the database to a file. Use this when starting a new .duc project.

```python
import os
import tempfile

from ducpy.builders.sql_builder import DucSQL

def demo_create_new():
    print("=== Create new .duc ===")

    with DucSQL.new() as db:
        # Insert two elements
        db.sql(
            "INSERT INTO elements (id, element_type, x, y, width, height, label, opacity) "
            "VALUES (?,?,?,?,?,?,?,?)",
            "r1", "rectangle", 0, 0, 200, 100, "Main Rectangle", 1.0,
        )
        db.sql(
            "INSERT INTO elements (id, element_type, x, y, width, height, label, opacity) "
            "VALUES (?,?,?,?,?,?,?,?)",
            "e1", "ellipse", 250, 0, 120, 80, "Side Ellipse", 0.9,
        )

        # Attach fill colours
        for owner_id, colour in [("r1", "#4ECDC4"), ("e1", "#FF6B6B")]:
            db.sql(
                "INSERT INTO backgrounds (owner_type, owner_id, src, opacity) "
                "VALUES (?,?,?)",
                "element", owner_id, colour, 1.0,
            )

        # Verify inserts
        rows = db.sql("SELECT id, element_type, label FROM elements ORDER BY id")
        for row in rows:
            print(f"  [{row['id']}] {row['element_type']} — {row['label']}")

        # Use named parameters for an update
        db.sql_dict(
            "UPDATE elements SET label = :label WHERE id = :id",
            {"label": "Renamed Rectangle", "id": "r1"},
        )

        updated = db.sql("SELECT label FROM elements WHERE id = ?", "r1")[0]
        print(f"  After rename: '{updated['label']}'")

        # Save to a temporary file
        tmp = tempfile.NamedTemporaryFile(suffix=".duc", delete=False)
        tmp.close()
        db.save(tmp.name)
        print(f"  Saved to: {tmp.name}")

    return tmp.name

```

--------------------------------

### Create Styled Text Element

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates creating a text element with specific positioning, size, and styles. This example also shows how text elements utilize random versioning.

```python
import ducpy as duc
from ducpy.builders.style_builders import (
    create_fill_and_stroke_style,
    create_simple_styles,
    create_solid_content
)

def demo_text_elements():
    """Demo text elements with styles and document formatting."""
    print("\n=== Text Elements Demo ===")
    
    text = (duc.ElementBuilder()
        .at_position(0, 100)
        .with_size(150, 25)
        .with_label("Sample Text")
        .with_styles(create_simple_styles(opacity=0.9))
        .build_text_element()
        .with_text("Hello, DucPy!")
        .build())
    print(f"Text content: '{text.element.text}'")
    print(f"Text uses random versioning: {text.element.base.version > 0}")
```

--------------------------------

### Import Usage Examples

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/index.rst.txt

Demonstrates how to import and use the main functionalities of the ducpy package.

```APIDOC
## Import Usage Examples

### Description
This section shows how to import the ducpy package and access its main components, including classes, parsing functions, serialization functions, and utility modules.

### Code Examples
```python
import ducpy as duc

# Accessing a class
duc.classes.SomeClass

# Using the parse function
duc.parse_duc(source)

# Using the serialize function
duc.serialize_duc(name=..., elements=...)

# Accessing a utility function
duc.utils.some_utility
```
```

--------------------------------

### Install ducpy from PyPI

Source: https://ducflair.github.io/duc/reference/python/_sources/downloads.rst.txt

Use this command to install the latest stable version of ducpy from the Python Package Index.

```bash
pip install ducpy
```

--------------------------------

### Install ducpy from GitHub Pages Index

Source: https://ducflair.github.io/duc/reference/python/_sources/downloads.rst.txt

Install ducpy directly from the package index hosted on GitHub Pages. This is useful for pre-release or platform-specific builds.

```bash
pip install ducpy --extra-index-url https://ducflair.github.io/duc/simple/
```

--------------------------------

### Open, Create, and Load .duc Files with DucSQL

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/sql_builder/index.html

Demonstrates how to open an existing .duc file, create a new one from scratch, and load data from bytes. Use a 'with' statement for automatic resource management.

```python
import ducpy as duc

# Open existing .duc
with duc.DucSQL("drawing.duc") as db:
    rows = db.sql("SELECT id, label FROM elements WHERE element_type = ?", "rectangle")
    db.sql("UPDATE elements SET label = ? WHERE id = ?", "new-label", rows[0]["id"])
```

```python
# Create new .duc from scratch
with duc.DucSQL.new() as db:
    db.sql("INSERT INTO elements (id, element_type, x, y, width, height) VALUES (?,?,?,?,?,?)",
           "r1", "rectangle", 0, 0, 100, 50)
    db.save("output.duc")
```

```python
# From bytes
with duc.DucSQL.from_bytes(raw) as db:
    print(db.sql("SELECT COUNT(*) AS n FROM elements")[0]["n"])
    modified = db.to_bytes()
```

--------------------------------

### Open and Query Existing .duc File

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/sql_builder/index.rst.txt

Demonstrates how to open an existing .duc file and execute SQL queries using positional parameters. The 'with' statement ensures the database connection is properly managed.

```python
import ducpy as duc

# Open existing .duc
with duc.DucSQL("drawing.duc") as db:
    rows = db.sql("SELECT id, label FROM elements WHERE element_type = ?", "rectangle")
    db.sql("UPDATE elements SET label = ? WHERE id = ?", "new-label", rows[0]["id"])
```

--------------------------------

### DucFreeDrawEnds

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/classes/ElementsClass/index.rst.txt

Defines the properties for the start and end caps of a free draw element.

```APIDOC
## Class: DucFreeDrawEnds

### Description
Specifies the properties for the start and end points of a free draw element, such as cap style, taper, and easing.

### Attributes
- **cap** (bool): Indicates if a cap is applied.
- **taper** (float): The taper value for the ends.
- **easing** (str): The easing function applied to the ends.
```

--------------------------------

### DucLine Attributes

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/classes/ElementsClass/index.rst.txt

Attributes for a Ducpy line, defined by start and end references.

```APIDOC
## DucLine

### Description
Represents a line segment defined by two references.

### Attributes
- **start** (DucLineReference): The starting reference of the line.
- **end** (DucLineReference): The ending reference of the line.
```

--------------------------------

### Create DucPy Elements

Source: https://ducflair.github.io/duc/reference/python/_sources/examples.rst.txt

Demonstrates building various geometric and text elements using the fluent builder DSL.

```python
from ducpy import Duc

duc = Duc()

# Rectangles
duc.rect(x=10, y=10, w=50, h=50, fill="red")
duc.rect(x=70, y=10, w=50, h=50, stroke="blue", stroke_width=2)

# Ellipses
duc.ellipse(x=150, y=35, rx=25, ry=15, fill="green")

# Polygons
duc.polygon(points=[(200, 10), (250, 50), (200, 90)], fill="yellow")

# Lines
duc.line(x1=300, y1=10, x2=350, y2=90, stroke="black", stroke_width=3)

# Arrows
duc.arrow(x1=400, y1=10, x2=450, y2=90, stroke="purple", stroke_width=3)

# Text
duc.text(x=10, y=110, text="Hello, DucPy!")
duc.text(x=10, y=140, text="Styled Text", font_size=20, fill="orange", font_family="Arial")

# Frames
duc.frame(x=200, y=110, w=100, h=50)

# Plots (requires matplotlib)
# try:
#     import matplotlib.pyplot as plt
#     fig, ax = plt.subplots()
#     ax.plot([1, 2, 3], [4, 5, 6])
#     duc.plot(fig=fig, x=300, y=110, w=150, h=75)
# except ImportError:
#     print("Matplotlib not installed, skipping plot example.")

# Save the document
duc.save("element_creation.duc")

```

--------------------------------

### Create New .duc File and Insert Data

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/sql_builder/index.rst.txt

Shows how to create a new .duc database from scratch, insert data using SQL, and save it to a file. The 'new()' class method is used for creation, and 'save()' for persistence.

```python
# Create new .duc from scratch
with duc.DucSQL.new() as db:
    db.sql("INSERT INTO elements (id, element_type, x, y, width, height) VALUES (?,?,?,?,?,?)",
           "r1", "rectangle", 0, 0, 100, 50)
    db.save("output.duc")
```

--------------------------------

### Open Existing .duc File with DucSQL

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates opening an existing .duc file using its path, querying the total number of elements, and retrieving element labels along with their associated fill colors. This is useful for accessing previously saved .duc data.

```python
import os

from ducpy.builders.sql_builder import DucSQL

def demo_open_existing(path: str):
    print("\n=== Open existing .duc ===")

    with DucSQL(path) as db:
        count = db.sql("SELECT COUNT(*) AS n FROM elements")[0]["n"]
        print(f"  Total elements: {count}")

        rows = db.sql(
            "SELECT e.id, e.label, b.src AS colour "
            "FROM elements e "
            "LEFT JOIN backgrounds b ON b.owner_type = 'element' AND b.owner_id = e.id "
            "ORDER BY e.id"
        )
        for row in rows:
            print(f"  {row['label']} → fill: {row['colour']}")

    os.unlink(path)

```

--------------------------------

### Main Demo Execution

Source: https://ducflair.github.io/duc/reference/python/examples.html

The main function orchestrates the execution of various element creation demos. It serves as the entry point for the demonstration script.

```python
def main():
    """Run all element creation demos."""
    print("DucPy Element Creation Demo")
    print("=" * 40)
    
    demo_basic_elements()
    demo_linear_elements() 
    demo_text_elements()
    demo_stack_elements()
    demo_custom_stack_base()
    
    print("\n✅ All demos completed successfully!")
    print("The refactored code provides:")
    print("- Reduced code duplication")  
    print("- Consistent random versioning")
    print("- New stack-based element support")
    print("- Improved maintainability")


if __name__ == "__main__":
    main()
```

--------------------------------

### Create Custom Frame with Stack Base

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates creating a frame element with a custom stack base, allowing for specific styling and state management like collapse status. Useful for building complex UI components.

```python
custom_frame = (duc.ElementBuilder()
        .at_position(50, 280)
        .with_size(150, 80)
        .with_label("Custom Container") # Moved label to ElementBuilder
        .build_frame_element()
        .with_stack_base(duc.StateBuilder().build_stack_base()
            .with_is_collapsed(False)
            .with_styles(duc.DucStackLikeStyles(opacity=0.8))
            .build())
        .build())
```

--------------------------------

### Create Styled Line and Arrow Elements

Source: https://ducflair.github.io/duc/reference/python/examples.html

Shows how to create line and arrow elements with custom stroke styles and points. Requires importing style builder functions.

```python
import ducpy as duc
from ducpy.builders.style_builders import (
    create_fill_and_stroke_style,
    create_simple_styles,
    create_solid_content
)

def demo_linear_elements():
    """Demo linear and arrow elements with styles."""
    print("\n=== Linear Elements Demo ===")
    
    # Create a styled line
    line_points = [(0, 0), (50, 25), (100, 0)]
    line = (duc.ElementBuilder()
        .with_label("Sample Line")
        .with_styles(create_simple_styles(
            strokes=[duc.create_stroke(duc.create_solid_content("#E74C3C"), width=3.0)]
        ))
        .build_linear_element()
        .with_points(line_points)
        .build())
    print(f"Line has {len(line.element.linear_base.points)} points")
    
    # Create a styled arrow
    arrow_points = [(0, 50), (75, 100)]
    arrow = (duc.ElementBuilder()
        .with_label("Sample Arrow")
        .with_styles(create_simple_styles(
            strokes=[duc.create_stroke(duc.create_solid_content("#8E44AD"), width=2.5)]
        ))
        .build_arrow_element()
        .with_points(arrow_points)
        .build())
    print(f"Arrow element type: {type(arrow.element).__name__}")
```

--------------------------------

### Create Basic Shapes with Styles

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates creating rectangles, ellipses, and polygons with custom fill, stroke, and size using the ElementBuilder. Ensure necessary style builder functions are imported.

```python
import ducpy as duc
from ducpy.builders.style_builders import (
    create_fill_and_stroke_style,
    create_simple_styles,
    create_solid_content
)

def demo_basic_elements():
    """Demo basic elements using the builders API."""
    print("=== Basic Elements Demo ===")
    
    # Create basic shapes with styles
    rect = (duc.ElementBuilder()
        .at_position(0, 0)
        .with_size(100, 50)
        .with_label("Sample Rectangle")
        .with_styles(create_fill_and_stroke_style(
            fill_content=create_solid_content("#FF6B6B"),
            stroke_content=create_solid_content("#2C3E50"),
            stroke_width=2.0,
            roundness=5.0
        ))
        .build_rectangle()
        .build())
    
    ellipse = (duc.ElementBuilder()
        .at_position(120, 0)
        .with_size(60, 40)
        .with_label("Sample Ellipse")
        .with_styles(create_fill_and_stroke_style(
            fill_content=create_solid_content("#4ECDC4"),
            stroke_content=create_solid_content("#34495E"),
            stroke_width=1.5
        ))
        .build_ellipse()
        .build())
    
    poly = (duc.ElementBuilder()
        .at_position(200, 0)
        .with_size(50, 50)
        .with_label("Hexagon")
        .with_styles(create_fill_and_stroke_style(
            fill_content=create_solid_content("#45B7D1"),
            stroke_content=create_solid_content("#2C3E50"),
            stroke_width=1.0,
            roundness=0.0
        ))
        .build_polygon()
        .with_sides(6)
        .build())
    
    print(f"Rectangle ID: {rect.element.base.id}")
    print(f"Ellipse ID: {ellipse.element.base.id}")  
    print(f"Polygon sides: {poly.element.sides}")
    
    # Demonstrate mutation with random versioning
    original_version = rect.element.base.version
    duc.mutate_element(rect, x=10, label="Moved Rectangle")
    print(f"Version changed: {original_version} -> {rect.element.base.version}")
```

--------------------------------

### create_background

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates a background wrapper from content.

```APIDOC
## create_background

### Description
Create a background wrapper from content.

### Parameters
(No parameters explicitly documented in the source)

### Request Example
(No request example provided in the source)

### Response
(No response details provided in the source)
```

--------------------------------

### create_background

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates a background wrapper from provided content. Defaults to a solid white background if no content is given.

```APIDOC
## create_background

### Description
Create a background wrapper from content.

### Parameters
- **content** (Optional[ducpy.classes.ElementsClass.ElementContentBase]) - Optional - The content to use for the background. If no content is provided, a solid white background is used.
```

--------------------------------

### CheckpointBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the CheckpointBuilder.

```APIDOC
## CheckpointBuilder

### Description
Provides methods to configure checkpoint properties.

### Methods
- `with_id(id: str)`: Sets the unique identifier for the checkpoint.
- `with_parent_id(parent_id: str)`: Sets the parent ID for the checkpoint.
- `with_is_manual_save(is_manual_save: bool)`: Sets whether this is a manual save.
- `with_data(data: dict)`: Sets the data for the checkpoint.
- `with_description(description: str)`: Sets the description for the checkpoint.
- `build()`: Finalizes the construction of the Checkpoint object.
```

--------------------------------

### LocalStateBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the LocalStateBuilder.

```APIDOC
## LocalStateBuilder

### Description
Provides methods to configure local state properties.

### Methods
- `with_current_item_font_family()`: Sets the font family for the current item.
- `with_current_item_font_size()`: Sets the font size for the current item.
- `with_current_item_text_align()`: Sets the text alignment for the current item.
- `with_current_item_roundness()`: Sets the roundness for the current item.
- `build()`: Finalizes the construction of the LocalState object.
```

--------------------------------

### create_simple_styles

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates base element styles from backgrounds and strokes.

```APIDOC
## create_simple_styles

### Description
Create base element styles from backgrounds and strokes.

### Parameters
(No parameters explicitly documented in the source)

### Request Example
(No request example provided in the source)

### Response
(No response details provided in the source)
```

--------------------------------

### create_text_style

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates a text style instance.

```APIDOC
## create_text_style

### Description
Create a text style instance.

### Parameters
(No parameters explicitly documented in the source)

### Request Example
(No request example provided in the source)

### Response
(No response details provided in the source)
```

--------------------------------

### Bulk Insert and Schema Introspection with DucSQL

Source: https://ducflair.github.io/duc/reference/python/examples.html

Demonstrates how to perform a bulk insert of records into a database table and then query the schema to retrieve table names. Requires an active database connection object `db`.

```python
records = [
            (f"el{i}", "rectangle", i * 110, 0, 100, 60, f"Box {i}", 1.0)
            for i in range(5)
        ]
        db.conn.executemany(
            "INSERT INTO elements (id, element_type, x, y, width, height, label, opacity) "
            "VALUES (?,?,?,?,?,?,?,?)",
            records,
        )

        total = db.sql("SELECT COUNT(*) AS n FROM elements")[0]["n"]
        print(f"  Bulk-inserted {total} elements")

        tables = [
            row["name"]
            for row in db.sql(
                "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
            )
        ]
        print(f"  Schema tables: {', '.join(tables[:6])} …")
```

--------------------------------

### Direct CDN Access for Wheels

Source: https://ducflair.github.io/duc/reference/python/_sources/downloads.rst.txt

Fetch wheels directly from GitHub Pages via CDN. This method is particularly useful for Pyodide and other browser-based Python runtimes.

```text
https://cdn.jsdelivr.net/gh/ducflair/duc@gh-pages/simple/ducpy/<wheel-filename>
```

--------------------------------

### RegionBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the RegionBuilder.

```APIDOC
## RegionBuilder

### Description
Provides methods to configure region properties.

### Methods
- `with_label(label: str)`: Sets the label for the region.
- `with_boolean_operation(operation: str)`: Sets the boolean operation for the region.
- `with_is_collapsed(is_collapsed: bool)`: Sets whether the region is collapsed.
- `with_is_plot(is_plot: bool)`: Sets whether the region is a plot.
- `with_is_visible(is_visible: bool)`: Sets whether the region is visible.
- `with_locked(locked: bool)`: Sets whether the region is locked.
- `with_opacity(opacity: float)`: Sets the opacity of the region.
- `with_id(id: str)`: Sets the unique identifier for the region.
- `build()`: Finalizes the construction of the Region object.
```

--------------------------------

### Open .duc from Bytes and Export

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/sql_builder/index.rst.txt

Illustrates opening a .duc database directly from raw bytes and then exporting it back to bytes. This is useful for in-memory database operations or data transfer.

```python
# From bytes
with duc.DucSQL.from_bytes(raw) as db:
    print(db.sql("SELECT COUNT(*) AS n FROM elements")[0]["n"])
    modified = db.to_bytes()
```

--------------------------------

### Import ducpy and Access Components

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/index.rst.txt

Demonstrates how to import the ducpy package and access its various components like classes, parsing functions, serialization functions, and utility functions.

```python
import ducpy as duc

duc.classes.SomeClass
duc.parse_duc(source)
duc.serialize_duc(name=..., elements=...)
duc.utils.some_utility
```

--------------------------------

### create_solid_content

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates content with a solid color. You can specify the color, opacity, and visibility.

```APIDOC
## create_solid_content

### Description
Create solid color content.

### Parameters
- **color** (str) - Required - Hex color string (for example, "#FF0000").
- **opacity** (float) - Optional - Content opacity from 0.0 to 1.0. Defaults to 1.0.
- **visible** (bool) - Optional - Whether content should be visible. Defaults to True.
```

--------------------------------

### create_simple_styles

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates base element styles from backgrounds and strokes. Provides defaults for background and stroke if not specified.

```APIDOC
## create_simple_styles

### Description
Create base element styles from backgrounds and strokes.

### Parameters
- **roundness** (float) - Optional - The roundness of the element corners. Defaults to 0.0.
- **opacity** (float) - Optional - The opacity of the styles. Defaults to 1.0.
- **backgrounds** (Optional[List[ducpy.classes.ElementsClass.ElementBackground]]) - Optional - A list of background elements.
- **strokes** (Optional[List[ducpy.classes.ElementsClass.ElementStroke]]) - Optional - A list of stroke elements.
- **blending** (Optional[ducpy.enums.BLENDING]) - Optional - The blending mode for the styles.
```

--------------------------------

### StackBaseBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the StackBaseBuilder.

```APIDOC
## StackBaseBuilder

### Description
Provides methods to configure stack base properties.

### Methods
- `with_label(label: str)`: Sets the label for the stack base.
- `with_is_collapsed(is_collapsed: bool)`: Sets whether the stack base is collapsed.
- `with_is_plot(is_plot: bool)`: Sets whether the stack base is a plot.
- `with_is_visible(is_visible: bool)`: Sets whether the stack base is visible.
- `with_locked(locked: bool)`: Sets whether the stack base is locked.
- `with_styles(styles: dict)`: Sets the styles for the stack base.
- `build()`: Finalizes the construction of the StackBase object.
```

--------------------------------

### instantiate_block

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/block_utils/index.rst.txt

Creates an instance of a block at a specific position, cloning its associated elements and updating their positions and instance IDs.

```APIDOC
## instantiate_block

### Description
Creates an instance of a block at a specific position. This function handles the creation of metadata, finding and cloning associated elements, updating their positions relative to the new insertion point, setting their instance IDs, and adding them to the state.

### Parameters
- **state** (ducpy.classes.DataStateClass.ExportedDataState) - The ExportedDataState object to modify.
- **block_id** (str) - The ID of the block to instantiate.
- **position_x** (float) - The X coordinate for the instance insertion point.
- **position_y** (float) - The Y coordinate for the instance insertion point.
- **instance_id** (Optional[str]) - Optional custom ID for the instance. If None, one is generated.

### Returns
- **ducpy.classes.DataStateClass.DucBlockInstance** - The created DucBlockInstance object.
```

--------------------------------

### DocElementBuilder

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/element_builders/index.rst.txt

Builder for creating document elements with text, style, and grid configuration.

```APIDOC
## DocElementBuilder

### Description
Builder for creating document elements with text, style, and grid configuration.

### Methods
- `with_text(text: str)`
- `with_doc_style(style: Optional[ducpy.classes.ElementsClass.DucDocStyle])`
- `with_file_id(file_id: str)`
- `with_grid_config(grid_config: ducpy.classes.ElementsClass.DocumentGridConfig)`
- `build() -> ducpy.classes.ElementsClass.ElementWrapper`
```

--------------------------------

### DeltaBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the DeltaBuilder.

```APIDOC
## DeltaBuilder

### Description
Provides methods to configure delta properties.

### Methods
- `with_id(id: str)`: Sets the unique identifier for the delta.
- `with_payload(payload: dict)`: Sets the payload for the delta.
- `with_parent_id(parent_id: str)`: Sets the parent ID for the delta.
- `with_is_manual_save(is_manual_save: bool)`: Sets whether this is a manual save.
- `with_description(description: str)`: Sets the description for the delta.
- `build()`: Finalizes the construction of the Delta object.
```

--------------------------------

### VersionGraphBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the VersionGraphBuilder.

```APIDOC
## VersionGraphBuilder

### Description
Provides methods to configure version graph properties.

### Methods
- `with_checkpoints(checkpoints: list)`: Sets the checkpoints for the version graph.
- `with_deltas(deltas: list)`: Sets the deltas for the version graph.
- `with_user_checkpoint_version_id(version_id: str)`: Sets the user checkpoint version ID.
- `with_latest_version_id(version_id: str)`: Sets the latest version ID.
- `build()`: Finalizes the construction of the VersionGraph object.
```

--------------------------------

### create_block

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Creates a block element.

```APIDOC
## create_block

### Description
Creates a block element with a given ID, label, optional elements, and description.

### Parameters
- `_id` (str): The unique identifier for the block.
- `_label` (str): The label for the block.
- `_elements` (List[ducpy.classes.ElementsClass.ElementWrapper] | None, optional): A list of elements to include in the block. Defaults to None.
- `_description` (str | None, optional): A description for the block. Defaults to None.

### Returns
- `ducpy.classes.ElementsClass.DucBlock`: The created block object.
```

--------------------------------

### LayerBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the LayerBuilder.

```APIDOC
## LayerBuilder

### Description
Provides methods to configure layer properties.

### Methods
- `with_label(label: str)`: Sets the label for the layer.
- `with_readonly(readonly: bool)`: Sets whether the layer is read-only.
- `with_is_collapsed(is_collapsed: bool)`: Sets whether the layer is collapsed.
- `with_is_plot(is_plot: bool)`: Sets whether the layer is a plot.
- `with_is_visible(is_visible: bool)`: Sets whether the layer is visible.
- `with_locked(locked: bool)`: Sets whether the layer is locked.
- `with_opacity(opacity: float)`: Sets the opacity of the layer.
- `with_stroke_color(color: str)`: Sets the stroke color of the layer.
- `with_background_color(color: str)`: Sets the background color of the layer.
- `with_id(id: str)`: Sets the unique identifier for the layer.
- `build()`: Finalizes the construction of the Layer object.
```

--------------------------------

### CheckpointBuilder

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

Builder for creating and configuring Checkpoint objects.

```APIDOC
## CheckpointBuilder

### Description
Builder for creating and configuring Checkpoint objects.

### Methods
- `with_id(id: str)`: Sets the unique identifier for the checkpoint.
- `with_parent_id(parent_id: str)`: Sets the parent ID of the checkpoint.
- `with_is_manual_save(is_manual: bool)`: Sets whether the checkpoint was a manual save.
- `with_data(data: bytes)`: Sets the data for the checkpoint.
- `with_description(description: str)`: Sets the description for the checkpoint.
- `build() -> ducpy.classes.DataStateClass.Checkpoint`: Constructs and returns the Checkpoint object.
```

--------------------------------

### create_doc_style

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates a DucDocStyle instance.

```APIDOC
## create_doc_style

### Description
DucDocStyle is empty in the current schema.

### Parameters
(No parameters explicitly documented in the source)

### Request Example
(No request example provided in the source)

### Response
(No response details provided in the source)
```

--------------------------------

### ExternalFileBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the ExternalFileBuilder.

```APIDOC
## ExternalFileBuilder

### Description
Provides methods to configure external file properties.

### Methods
- `with_key(key: str)`: Sets the key for the external file.
- `with_mime_type(mime_type: str)`: Sets the MIME type of the file.
- `with_data(data: bytes)`: Sets the data content of the file.
- `with_last_retrieved(timestamp: int)`: Sets the timestamp of the last retrieval.
- `build()`: Finalizes the construction of the ExternalFile object.
```

--------------------------------

### create_solid_style

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

A convenience helper that returns solid content for style composition. Used for creating solid color styles.

```APIDOC
## create_solid_style

### Description
Convenience helper that returns solid content for style composition.

### Signature
```python
create_solid_style(color: str, opacity: float = 1.0)
```

### Parameters
* **color** (str) - The color of the solid style.
* **opacity** (float, optional) - The opacity of the solid style. Defaults to 1.0.
```

--------------------------------

### create_hatch_content

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates hatch pattern content. Specify the pattern, opacity, and visibility.

```APIDOC
## create_hatch_content

### Description
Create hatch pattern content.

### Parameters
- **pattern** (str) - Required - Hatch pattern source/identifier.
- **opacity** (float) - Optional - Content opacity from 0.0 to 1.0. Defaults to 1.0.
- **visible** (bool) - Optional - Whether content should be visible. Defaults to True.
```

--------------------------------

### Helper Functions for Creating States

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

This section lists helper functions that provide a convenient way to create specific DUC state objects from a base configuration.

```APIDOC
## Helper Functions

### Description
These functions simplify the creation of various DUC state objects by abstracting the builder pattern.

### Functions

- `create_global_state_from_base(base: BaseStateParams, extra: dict)`: Creates a GlobalState from base parameters and extra configuration.
- `create_local_state_from_base(base: BaseStateParams, extra: dict)`: Creates a LocalState from base parameters and extra configuration.
- `create_group_from_base(base: BaseStateParams, extra: dict)`: Creates a Group from base parameters and extra configuration.
- `create_layer_from_base(base: BaseStateParams, extra: dict)`: Creates a Layer from base parameters and extra configuration.
- `create_region_from_base(base: BaseStateParams, extra: dict)`: Creates a Region from base parameters and extra configuration.
- `create_version_graph_from_base(base: BaseStateParams, extra: dict)`: Creates a VersionGraph from base parameters and extra configuration.
- `create_checkpoint_from_base(base: BaseStateParams, extra: dict)`: Creates a Checkpoint from base parameters and extra configuration.
- `create_delta_from_base(base: BaseStateParams, extra: dict)`: Creates a Delta from base parameters and extra configuration.
- `create_external_file_from_base(base: BaseStateParams, extra: dict)`: Creates an ExternalFile from base parameters and extra configuration.
- `create_stack_base_from_base(base: BaseStateParams, extra: dict)`: Creates a StackBase from base parameters and extra configuration.
- `create_block()`: Creates a block.
- `create_string_value_entry()`: Creates a string value entry.
```

--------------------------------

### TilingProperties Properties

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/classes/ElementsClass/index.rst.txt

Properties for configuring tiling behavior.

```APIDOC
## TilingProperties

### Description
Properties for configuring tiling behavior.

### Attributes
- **size_in_percent** (float): The size of the tiling in percentage.
- **angle** (float): The angle of the tiling.
- **spacing** (Optional[float]): The spacing between tiles. Defaults to None.
- **offset_x** (Optional[float]): The X offset for tiling. Defaults to None.
- **offset_y** (Optional[float]): The Y offset for tiling. Defaults to None.
```

--------------------------------

### CheckpointBuilder

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Builder for constructing Checkpoint objects.

```APIDOC
## Class ducpy.builders.state_builders.CheckpointBuilder

### Description
Builder for constructing Checkpoint objects, inheriting from StateSpecificBuilder.

### Methods
- **with_id(_id: str_)**: Sets the ID for the checkpoint.
- **with_parent_id(_parent_id: str_)**: Sets the parent ID for the checkpoint.
- **with_is_manual_save(_is_manual: bool_)**: Sets whether the checkpoint is a manual save.
- **with_data(_data: bytes_)**: Sets the data for the checkpoint.
- **with_description(_description: str_)**: Sets the description for the checkpoint.
- **build() -> ducpy.classes.DataStateClass.Checkpoint**: Builds and returns the Checkpoint object.
```

--------------------------------

### StackBaseBuilder

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Builder for creating stack base elements.

```APIDOC
## StackBaseBuilder

### Description
Builder for creating stack base elements.

### Methods
- `with_label(label: str)`: Sets the label for the stack.
- `with_is_collapsed(is_collapsed: bool)`: Sets whether the stack is collapsed.
- `with_is_plot(is_plot: bool)`: Sets whether the stack is a plot.
- `with_is_visible(is_visible: bool)`: Sets whether the stack is visible.
- `with_locked(locked: bool)`: Sets whether the stack is locked.
- `with_styles(styles: ducpy.classes.ElementsClass.DucStackLikeStyles_)`: Sets the styles for the stack.
- `build() -> ducpy.classes.ElementsClass.DucStackBase`: Builds and returns the stack base object.
```

--------------------------------

### create_text_style

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates a text style instance with safe defaults for alignment and line spacing.

```APIDOC
## create_text_style

### Description
Create a text style instance. This helper provides safe defaults for alignment and line spacing.

### Signature
`create_text_style(_font_family: str = 'Arial', _font_size: float = 12, _is_ltr: bool = True, _text_align: ducpy.enums.TEXT_ALIGN | None = None, _vertical_align: ducpy.enums.VERTICAL_ALIGN | None = None, _line_height: float = 1.0, _line_spacing_value: float = 1.0, _line_spacing_type: ducpy.enums.LINE_SPACING_TYPE | None = None, _oblique_angle: float = 0.0, _width_factor: float = 1.0, _is_upside_down: bool = False, _is_backwards: bool = False_) -> ducpy.classes.ElementsClass.DucTextStyle`
```

--------------------------------

### create_block

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

Creates a DucBlock object, which can contain elements and a description.

```APIDOC
## create_block

### Description
Creates a DucBlock object.

### Signature
`create_block(id: str, label: str, elements: Optional[List[ducpy.classes.ElementsClass.ElementWrapper]] = None, description: Optional[str] = None) -> ducpy.classes.ElementsClass.DucBlock`

### Parameters
* **id** (str) - Required - The unique identifier for the block.
* **label** (str) - Required - The display label for the block.
* **elements** (Optional[List[ducpy.classes.ElementsClass.ElementWrapper]]) - Optional - A list of elements to include in the block.
* **description** (Optional[str]) - Optional - A description for the block.
```

--------------------------------

### create_image_content

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates image content. Supports various image sources and allows setting opacity, visibility, and fit mode.

```APIDOC
## create_image_content

### Description
Create image content.

### Parameters
- **image_src** (str) - Required - Image source (file id, URL, or supported element reference).
- **opacity** (float) - Optional - Content opacity from 0.0 to 1.0. Defaults to 1.0.
- **visible** (bool) - Optional - Whether content should be visible. Defaults to True.
- **fit_mode** (Optional[str]) - Optional - Reserved for fit mode behavior.
```

--------------------------------

### GroupBuilder Methods

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/state_builders/index.html

Methods for configuring the GroupBuilder.

```APIDOC
## GroupBuilder

### Description
Provides methods to configure group properties.

### Methods
- `with_label(label: str)`: Sets the label for the group.
- `with_is_collapsed(is_collapsed: bool)`: Sets whether the group is collapsed.
- `with_is_plot(is_plot: bool)`: Sets whether the group is a plot.
- `with_is_visible(is_visible: bool)`: Sets whether the group is visible.
- `with_locked(locked: bool)`: Sets whether the group is locked.
- `with_opacity(opacity: float)`: Sets the opacity of the group.
- `with_id(id: str)`: Sets the unique identifier for the group.
- `build()`: Finalizes the construction of the Group object.
```

--------------------------------

### VersionChain Class

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/classes/DataStateClass/index.rst.txt

Represents a chain of versions, potentially including schema migrations.

```APIDOC
## Class: VersionChain

### Description
Represents a chain of versions.

### Attributes
- **id** (str) - The unique identifier for the version chain.
- **schema_version** (int) - The schema version of the chain.
- **start_version** (int) - The starting version number.
- **end_version** (Optional[int]) - The ending version number, if applicable. Defaults to None.
- **migration** (Optional[SchemaMigration]) - The schema migration associated with this chain. Defaults to None.
```

--------------------------------

### create_image_content

Source: https://ducflair.github.io/duc/reference/python/autoapi/ducpy/builders/style_builders/index.html

Creates image content for styling elements.

```APIDOC
## create_image_content

### Description
Create image content.

### Parameters
(No parameters explicitly documented in the source)

### Request Example
(No request example provided in the source)

### Response
(No response details provided in the source)
```

--------------------------------

### StackBaseBuilder

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

Builder for creating and configuring DucStackBase objects.

```APIDOC
## StackBaseBuilder

### Description
Builder for creating and configuring DucStackBase objects.

### Methods
- `with_label(label: str)`: Sets the label for the stack base.
- `with_is_collapsed(is_collapsed: bool)`: Sets the collapsed state of the stack base.
- `with_is_plot(is_plot: bool)`: Sets whether the stack base is a plot.
- `with_is_visible(is_visible: bool)`: Sets the visibility of the stack base.
- `with_locked(locked: bool)`: Sets the locked state of the stack base.
- `with_styles(styles: ducpy.classes.ElementsClass.DucStackLikeStyles)`: Sets the styles for the stack base.
- `build() -> ducpy.classes.ElementsClass.DucStackBase`: Constructs and returns the DucStackBase object.
```

--------------------------------

### create_text_style

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates a text style instance with safe defaults for alignment and line spacing. Allows customization of font properties, alignment, and spacing.

```APIDOC
## create_text_style

### Description
Create a text style instance.

This helper provides safe defaults for alignment and line spacing.

### Signature
```python
create_text_style(font_family: str = 'Arial', font_size: float = 12, is_ltr: bool = True, text_align: Optional[ducpy.enums.TEXT_ALIGN] = None, vertical_align: Optional[ducpy.enums.VERTICAL_ALIGN] = None, line_height: float = 1.0, line_spacing_value: float = 1.0, line_spacing_type: Optional[ducpy.enums.LINE_SPACING_TYPE] = None, oblique_angle: float = 0.0, width_factor: float = 1.0, is_upside_down: bool = False, is_backwards: bool = False)
```

### Parameters
* **font_family** (str, optional) - The font family to use. Defaults to 'Arial'.
* **font_size** (float, optional) - The font size. Defaults to 12.
* **is_ltr** (bool, optional) - Whether the text is left-to-right. Defaults to True.
* **text_align** (Optional[ducpy.enums.TEXT_ALIGN], optional) - The horizontal alignment of the text.
* **vertical_align** (Optional[ducpy.enums.VERTICAL_ALIGN], optional) - The vertical alignment of the text.
* **line_height** (float, optional) - The height of the line. Defaults to 1.0.
* **line_spacing_value** (float, optional) - The value for line spacing. Defaults to 1.0.
* **line_spacing_type** (Optional[ducpy.enums.LINE_SPACING_TYPE], optional) - The type of line spacing.
* **oblique_angle** (float, optional) - The oblique angle for the text. Defaults to 0.0.
* **width_factor** (float, optional) - The width factor for the text. Defaults to 1.0.
* **is_upside_down** (bool, optional) - Whether the text is upside down. Defaults to False.
* **is_backwards** (bool, optional) - Whether the text is backwards. Defaults to False.
```

--------------------------------

### create_fill_and_stroke_style

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates styles configured with both fill and stroke properties. Allows customization of roundness, opacity, and stroke placement.

```APIDOC
## create_fill_and_stroke_style

### Description
Create styles configured with both fill and stroke.

### Signature
```python
create_fill_and_stroke_style(fill_content: ducpy.classes.ElementsClass.ElementContentBase, stroke_content: ducpy.classes.ElementsClass.ElementContentBase, stroke_width: float = 1.0, roundness: float = 0.0, opacity: float = 1.0, placement: ducpy.enums.STROKE_PLACEMENT = STROKE_PLACEMENT.INSIDE)
```

### Parameters
* **fill_content** (ducpy.classes.ElementsClass.ElementContentBase) - The content for the fill.
* **stroke_content** (ducpy.classes.ElementsClass.ElementContentBase) - The content for the stroke.
* **stroke_width** (float, optional) - The width of the stroke. Defaults to 1.0.
* **roundness** (float, optional) - The roundness of the corners. Defaults to 0.0.
* **opacity** (float, optional) - The opacity of the style. Defaults to 1.0.
* **placement** (ducpy.enums.STROKE_PLACEMENT, optional) - The placement of the stroke. Defaults to STROKE_PLACEMENT.INSIDE.
```

--------------------------------

### create_checkpoint_from_base

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

Creates a checkpoint object from a base state and additional keyword arguments.

```APIDOC
## create_checkpoint_from_base

### Description
Creates a checkpoint object from a base state and additional keyword arguments.

### Parameters
- `base` (BaseStateParams): The base state parameters.
- `**kwargs`: Additional keyword arguments.

### Returns
- `ducpy.classes.DataStateClass.Checkpoint`: The created checkpoint object.
```

--------------------------------

### create_solid_style

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates styles for solid elements, combining fill and stroke properties.

```APIDOC
## create_solid_style

### Description
Create styles configured with solid fill and stroke.

### Parameters
- **color** (str) - Required - Hex color string for the solid fill.
- **roundness** (float) - Optional - The roundness of the element corners. Defaults to 0.0.
- **opacity** (float) - Optional - The opacity of the styles. Defaults to 1.0.
- **stroke_width** (float) - Optional - The width of the stroke. Defaults to 1.0.
- **stroke_placement** (ducpy.enums.STROKE_PLACEMENT) - Optional - The placement of the stroke. Defaults to STROKE_PLACEMENT.INSIDE.
```

--------------------------------

### Round-trip .duc Data via Bytes with DucSQL

Source: https://ducflair.github.io/duc/reference/python/examples.html

Shows how to serialize a .duc database to bytes in memory and then restore it from those bytes. This is useful for transferring or storing .duc data without direct disk I/O.

```python
from ducpy.builders.sql_builder import DucSQL

def demo_bytes_roundtrip():
    print("\n=== Bytes round-trip ===")

    # Build in memory
    with DucSQL.new() as db:
        db.sql(
            "INSERT INTO elements (id, element_type, x, y, width, height, label) "
            "VALUES (?,?,?,?,?,?,?)",
            "t1", "text", 10, 10, 300, 40, "Hello, DUC!",
        )
        raw = db.to_bytes()

    print(f"  Serialised to {len(raw):,} bytes")

    # Restore from bytes and query
    with DucSQL.from_bytes(raw) as db:
        row = db.sql("SELECT label FROM elements WHERE id = 't1'")[0]
        print(f"  Restored label: '{row['label']}'")

```

--------------------------------

### create_external_file_from_base

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/state_builders/index.rst.txt

Creates an external file object from a base state and additional keyword arguments.

```APIDOC
## create_external_file_from_base

### Description
Creates an external file object from a base state and additional keyword arguments.

### Parameters
- `base` (BaseStateParams): The base state parameters.
- `**kwargs`: Additional keyword arguments.

### Returns
- `ducpy.classes.DataStateClass.DucExternalFile`: The created external file object.
```

--------------------------------

### create_table_style

Source: https://ducflair.github.io/duc/reference/python/_sources/autoapi/ducpy/builders/style_builders/index.rst.txt

Creates an empty DucTableStyle instance. Note that DucTableStyle is empty in the current schema.

```APIDOC
## create_table_style

### Description
DucTableStyle is empty in the current schema.

### Signature
```python
create_table_style()
```
```
Tokens:
Raw