capturegraph.procedures.nodes.automatic.control

Control Flow Procedures

Control flow procedures manage conditional logic, assertions, and program flow within workflows. These enable dynamic behavior, validation, and decision-making based on data conditions, user input, and runtime state.

Example

from capturegraph.procedures.nodes.automatic import IfThenElse, DoNothing

# Conditional workflow based on user selection
is_advanced = user_mode == ConstantString(value="advanced")

result = IfThenElse(
    condition=is_advanced,
    true_branch=advanced_workflow(),
    false_branch=simple_workflow()
)

AssertBool

Bases: Procedure[PVoid]

Asserts that a boolean condition is true, failing with a message if false.

Used to validate conditions and assumptions during procedure execution. If the condition evaluates to false, the procedure will fail with the provided error message.

Attributes:

Name	Type	Description
condition	Procedure[PBool]	The boolean condition that must be true.
message	str	Error message to display if the condition is false.

Source code in capturegraph-lib/capturegraph/procedures/nodes/automatic/control.py

@make_procedure
class AssertBool(Procedure[PVoid]):
    """
    Asserts that a boolean condition is true, failing with a message if false.

    Used to validate conditions and assumptions during procedure execution.
    If the condition evaluates to false, the procedure will fail with the
    provided error message.

    Attributes:
        condition: The boolean condition that must be true.
        message: Error message to display if the condition is false.
    """

    condition: Procedure[PBool]
    message: str

IfThenElse

Bases: Procedure[T]

Conditional execution based on a boolean condition.

Executes one of two branches based on whether a condition is true or false. Both branches must return the same type T. This enables dynamic workflows that adapt based on user input, data conditions, or environmental factors.

Attributes:

Name	Type	Description
condition	Procedure[PBool]	Boolean procedure to evaluate.
true_branch	Procedure[T]	Procedure to execute if condition is true.
false_branch	Procedure[T]	Procedure to execute if condition is false.

Example

# Show tutorial on first run
is_first = ~ProcedureCompleted(
    procedure=target.get_first_session("daily")
)

return IfThenElse(
    condition=is_first,
    true_branch=tutorial_workflow(session),
    false_branch=normal_workflow(session)
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/automatic/control.py

@make_procedure
@forward_types(PType, "true_branch", "false_branch")
class IfThenElse[T: PType](Procedure[T]):
    """
    Conditional execution based on a boolean condition.

    Executes one of two branches based on whether a condition is true or false.
    Both branches must return the same type `T`. This enables dynamic workflows
    that adapt based on user input, data conditions, or environmental factors.

    Attributes:
        condition: Boolean procedure to evaluate.
        true_branch: Procedure to execute if condition is true.
        false_branch: Procedure to execute if condition is false.

    Example:
        ```python
        # Show tutorial on first run
        is_first = ~ProcedureCompleted(
            procedure=target.get_first_session("daily")
        )

        return IfThenElse(
            condition=is_first,
            true_branch=tutorial_workflow(session),
            false_branch=normal_workflow(session)
        )
        ```
    """

    condition: Procedure[PBool]

    true_branch: Procedure[T]
    false_branch: Procedure[T]

DoNothing

Bases: Procedure[PVoid]

A no-op procedure that does nothing and returns immediately.

Useful as a placeholder or default branch in conditional logic where one path should perform no action.

Example

# Conditionally update location or do nothing
IfThenElse(
    condition=should_update,
    true_branch=set_location(current_location),
    false_branch=DoNothing()
)

Source code in capturegraph-lib/capturegraph/procedures/nodes/automatic/control.py

@make_procedure
class DoNothing(Procedure[PVoid]):
    """
    A no-op procedure that does nothing and returns immediately.

    Useful as a placeholder or default branch in conditional logic
    where one path should perform no action.

    Example:
        ```python
        # Conditionally update location or do nothing
        IfThenElse(
            condition=should_update,
            true_branch=set_location(current_location),
            false_branch=DoNothing()
        )
        ```
    """

NullProcedure

Bases: Procedure[T]

A procedure that returns a null/empty value of type T.

Used as a placeholder that produces no actual data but maintains type compatibility. Useful for optional branches or default values.

Attributes:

Name	Type	Description
return_type	type[T]	The type T that this procedure should return.

Example

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

Source code in capturegraph-lib/capturegraph/procedures/nodes/automatic/control.py

@make_procedure
class NullProcedure[T: PType](Procedure[T]):
    """
    A procedure that returns a null/empty value of type T.

    Used as a placeholder that produces no actual data but maintains
    type compatibility. Useful for optional branches or default values.

    Attributes:
        return_type: The type `T` that this procedure should return.

    Example:
        ```python
        # Load optional reference, or use null if none exists
        reference = target.new_file("reference").load(
            or_else=NullProcedure(return_type=PImage)
        )
        ```
    """

    return_type: type[T]

    def __post_init__(self) -> None:
        object.__setattr__(self, "_return_type", self.return_type)
        object.__setattr__(self, "return_type", None)
        super().__post_init__()