capturegraph.procedures.nodes.filesystem.save

Save and Cache Procedures

Data persistence procedures manage saving and loading of procedure results to the file system. These enable data caching for performance optimization and persistent storage across procedure executions.

Example

from capturegraph.procedures.nodes.action import CaptureImage, UserInputBool
from capturegraph.procedures.nodes.filesystem import GetRootDirectory

def capture_with_settings():
    target = GetRootDirectory()
    session = target.new_session("daily")

    # Cache: save and return the value for later use
    use_raw = target.new_file("raw_setting").cache(
        UserInputBool(label="Use RAW?"),
        skip_if_exists=True
    )

    # Save: just store, returns PVoid
    session.new_file("photo").save(
        CaptureImage(label="Photo", raw_photo=use_raw)
    )

CacheProcedureToFile

Bases: Procedure[T]

Caches the result of a procedure to a file and returns the data.

Executes the given procedure and stores its result to a file. If the file already exists and skip_if_exists is True, returns the cached result instead of re-executing the procedure.

Unlike .save(), this returns the cached data (type T) for use in subsequent procedure logic.

Attributes:

Name	Type	Description
file	Procedure[PFile]	The file to cache the result to.
procedure	Procedure[T]	The procedure whose result should be cached.
skip_if_exists	bool	Whether to skip execution if file already exists.
write_on_save	bool	Whether to write the result to the file.

Example

# Cache a user preference for later use
use_raw = target.new_file("raw_setting").cache(
    UserInputBool(label="Use RAW?"),
    skip_if_exists=True
)

# Use the cached value in another procedure
session.new_file("photo").save(
    CaptureImage(label="Photo", raw_photo=use_raw)
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/save.py

@make_procedure
@forward_types(PSaveable, "procedure")
class CacheProcedureToFile[T: PSaveable](Procedure[T]):
    """
    Caches the result of a procedure to a file and returns the data.

    Executes the given procedure and stores its result to a file. If the file
    already exists and `skip_if_exists` is True, returns the cached result
    instead of re-executing the procedure.

    Unlike `.save()`, this returns the cached data (type `T`) for use in
    subsequent procedure logic.

    Attributes:
        file: The file to cache the result to.
        procedure: The procedure whose result should be cached.
        skip_if_exists: Whether to skip execution if file already exists.
        write_on_save: Whether to write the result to the file.

    Example:
        ```python
        # Cache a user preference for later use
        use_raw = target.new_file("raw_setting").cache(
            UserInputBool(label="Use RAW?"),
            skip_if_exists=True
        )

        # Use the cached value in another procedure
        session.new_file("photo").save(
            CaptureImage(label="Photo", raw_photo=use_raw)
        )
        ```
    """

    file: Procedure[PFile]
    procedure: Procedure[T]
    skip_if_exists: bool = False
    write_on_save: bool = True

CacheProcedureToBundle

Bases: Procedure[T]

Caches the result of a procedure to a directory bundle.

Executes the given procedure and stores its result as a bundle of files in a directory. Used for complex data types like image sequences that require multiple files.

Attributes:

Name	Type	Description
bundle_directory	Procedure[PDirectory]	The directory to store the bundle in.
procedure	Procedure[T]	The procedure whose result should be cached.
skip_if_exists	bool	Whether to skip execution if bundle already exists.
write_on_save	bool	Whether to write the result to the bundle.

Example

# Save multiple images as a bundle
session.new_directory("photos").save_bundle(
    CaptureImageSequence(label="All Photos")
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/save.py

@make_procedure
@forward_types(PSaveableBundle, "procedure")
class CacheProcedureToBundle[T: PSaveableBundle](Procedure[T]):
    """
    Caches the result of a procedure to a directory bundle.

    Executes the given procedure and stores its result as a bundle of files
    in a directory. Used for complex data types like image sequences that
    require multiple files.

    Attributes:
        bundle_directory: The directory to store the bundle in.
        procedure: The procedure whose result should be cached.
        skip_if_exists: Whether to skip execution if bundle already exists.
        write_on_save: Whether to write the result to the bundle.

    Example:
        ```python
        # Save multiple images as a bundle
        session.new_directory("photos").save_bundle(
            CaptureImageSequence(label="All Photos")
        )
        ```
    """

    bundle_directory: Procedure[PDirectory]
    procedure: Procedure[T]
    skip_if_exists: bool = False
    write_on_save: bool = True