Fluent API#

CaptureGraph provides a fluent API for chaining operations, making your code more readable and concise.

Method Chaining#

Chain operations directly instead of creating intermediate objects:

# Verbose approach
file_ref = NewFile(parent=session, name="photo")
saved = SaveProcedure(file=file_ref, procedure=CaptureImage())

# Fluent approach (preferred)
saved = session.new_file("photo").save(CaptureImage())

Create nested structures fluently:

target = GetRootDirectory()

# Chain directory creation
photos = target.new_session("daily").new_directory("photos")
photos.new_file("main").save(CaptureImage(label="Main Photo"))

Save vs Cache vs Load#

These three methods control how data is stored and retrieved.

`.save()` — Store and Move On#

Returns PVoid. Use in ProcedureSequence:

ProcedureSequence(
    procedures=[
        session.new_file("photo").save(CaptureImage()),
        session.new_file("notes").save(UserInputString(label="Notes")),
    ]
)

`.cache()` — Store and Keep Using#

Returns the original type. Use when you need the value later:

# Cache returns PBool, usable in conditions
raw_enabled = target.new_file("raw_setting").cache(
    UserInputBool(label="Enable RAW?"),
    skip_if_exists=True  # Don't ask if already set
)

# Use the cached value
photo = CaptureImage(raw_photo=raw_enabled)

`.load()` — Retrieve with Fallback#

Load existing data, or run a fallback if missing:

# Load saved preference, or ask if none exists
setting = target.new_file("preference").load(
    or_else=UserInputString(label="Set your preference")
)

# Load optional reference, or use null
reference = target.new_file("reference").load(
    or_else=NullProcedure(return_type=PImage)
)

The `skip_if_exists` Parameter#

Controls whether to show UI for existing data:

# skip_if_exists=True: Skip the UI entirely if file exists
target.new_file("setting").cache(
    UserInputBool(label="Enable feature?"),
    skip_if_exists=True
)

# skip_if_exists=False (default): Show UI pre-filled with existing data
session.new_file("notes").cache(
    UserInputString(label="Notes"),
    skip_if_exists=False  # User can edit existing notes
)

Optional Operations#

Use .make_optional() for operations that shouldn't block the workflow:

ProcedureSequence(
    procedures=[
        # Core workflow (must succeed)
        session.new_file("measurement").save(
            UserInputNumber(label="Reading")
        ),

        # Optional (can fail without stopping)
        session.new_file("photo").save(
            CaptureImage(label="Optional photo")
        ).make_optional(),
    ]
)

Use .make_optional() for:

Secondary data captures
Background operations (thumbnails)
Network operations that might fail

Bundle Operations#

Use .save_bundle() for sequences of files:

images = CaptureImageSequence(
    label="Take multiple photos",
    raw_photo=True
)

# Saves as: burst/image_0.heic, burst/image_1.heic, ...
session.new_directory("burst").save_bundle(images)

Metadata Shortcuts#

Directories provide shortcuts for common metadata:

# Get metadata file references
session.get_thumbnail_file()      # Thumbnail image
target.get_location_file()        # GPS location
target.get_notification_file()    # Notification settings

# Mark for cleanup after backup
session.mark_for_clear_after_backup()

Session Retrieval#

Access existing sessions:

target.get_first_session("daily")  # Oldest session
target.get_last_session("daily")   # Newest session

# Check if sessions exist
has_data = ProcedureCompleted(procedure=target.get_last_session("daily"))
is_first = ~ProcedureCompleted(procedure=target.get_first_session("daily"))

Reference#

Directory Methods#

Method	Returns	Description
`.new_directory(name)`	`Procedure[PDirectory]`	Create subdirectory
`.new_session(name)`	`Procedure[PDirectory]`	Create timestamped session
`.new_file(name)`	`Procedure[PFile]`	Create file reference
`.get_first_session(name)`	`Procedure[PDirectory]`	Get oldest session
`.get_last_session(name)`	`Procedure[PDirectory]`	Get newest session

File Methods#

Method	Returns	Description
`.save(procedure)`	`Procedure[PVoid]`	Store data
`.cache(procedure, skip_if_exists)`	`Procedure[T]`	Store and return data
`.load(or_else)`	`Procedure[T]`	Load with fallback
`.save_bundle(sequence)`	`Procedure[PVoid]`	Store file sequence

Workflow Methods#

Method	Returns	Description
`.make_optional()`	`Procedure[PVoid]`	Allow failure