Skip to content

capturegraph.procedures.nodes.filesystem.directories #

Directory Procedures#

Directory management procedures handle the creation and organization of file system structures within the app's data storage. These provide the foundation for organizing captured data into logical hierarchies of targets and sessions.

Example 
from capturegraph.procedures.nodes.filesystem import GetRootDirectory

def capture_procedure():
    target = GetRootDirectory()  # Get the project root
    session = target.new_session("daily")  # Create timestamped session
    data = session.new_directory("measurements")  # Create subfolder

    return ProcedureSequence(
        label="Daily Capture",
        procedures=[
            data.new_file("reading").save(UserInputNumber(label="Value")),
        ]
    )
Key Concepts
  • Targets: Project-level directories where procedures execute
  • Sessions: Timestamped execution containers within targets
  • Subdirectories: Organizational folders within sessions

GetRootDirectory #

Bases: Procedure[PDirectory]

Gets the target root directory for this procedure execution.

Returns the root directory of the capture target where this procedure is executing. Targets are project-level folders (e.g., "My Research Study", "Daily Photos") that users create to organize related data collection.

Example 
target = GetRootDirectory()
session = target.new_session("daily")  # Create timestamped session
target.new_file("config").cache(...)   # Persistent data
session.new_file("photo").save(...)    # Session-specific data
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
@make_procedure
class GetRootDirectory(Procedure[PDirectory]):
    """
    Gets the target root directory for this procedure execution.

    Returns the root directory of the capture target where this procedure is executing.
    Targets are project-level folders (e.g., "My Research Study", "Daily Photos")
    that users create to organize related data collection.

    Example:
        ```python
        target = GetRootDirectory()
        session = target.new_session("daily")  # Create timestamped session
        target.new_file("config").cache(...)   # Persistent data
        session.new_file("photo").save(...)    # Session-specific data
        ```
    """

NewDirectory #

Bases: Procedure[PDirectory]

Creates a new subdirectory within a parent directory.

Creates a new directory for organizing captured data. The directory will be created if it doesn't exist, or reused if it already exists.

Attributes:

Name Type Description
parent Procedure[PDirectory]

The parent directory to create the subdirectory in
name str

The name of the new directory to create
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
@make_procedure
class NewDirectory(Procedure[PDirectory]):
    """
    Creates a new subdirectory within a parent directory.

    Creates a new directory for organizing captured data. The directory
    will be created if it doesn't exist, or reused if it already exists.

    Attributes:
        parent: The parent directory to create the subdirectory in
        name: The name of the new directory to create
    """

    parent: Procedure[PDirectory]
    name: str

NewSessionDirectory #

Bases: Procedure[PDirectory]

Creates a new timestamped session directory for this execution.

Each time a procedure runs in the companion app, it creates a new session with a unique hex-encoded microsecond timestamp (e.g., "timelapse_capture/00063B40E29D696A"). Sessions enable multiple executions of the same procedure within a target, with each execution's data organized separately and chronologically.

Sessions are essential for procedures that will be executed repeatedly, often triggered by the app's notification system. The app uses session timestamps to provide chronological navigation and automatic backup scheduling.

Attributes:

Name Type Description
parent Procedure[PDirectory]

The parent directory (typically target root) to create the session in
name str

The session type name (e.g., "timelapse_capture", "daily_survey")
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@make_procedure
class NewSessionDirectory(Procedure[PDirectory]):
    """
    Creates a new timestamped session directory for this execution.

    Each time a procedure runs in the companion app, it creates a new session with a
    unique hex-encoded microsecond timestamp (e.g., "timelapse_capture/00063B40E29D696A").
    Sessions enable multiple executions of the same procedure within a target, with each
    execution's data organized separately and chronologically.

    Sessions are essential for procedures that will be executed repeatedly, often
    triggered by the app's notification system. The app uses session timestamps
    to provide chronological navigation and automatic backup scheduling.

    Attributes:
        parent: The parent directory (typically target root) to create the session in
        name: The session type name (e.g., "timelapse_capture", "daily_survey")
    """

    parent: Procedure[PDirectory]
    name: str

GetFirstSessionDirectory #

Bases: Procedure[PDirectory]

Gets the first (oldest) session directory with the given name.

Searches through the target's sessions folder to find the earliest timestamped session of the specified type. Useful for accessing baseline data, initial measurements, or checking if a procedure has ever been executed before.

Commonly used with ProcedureCompleted to determine first-time vs. repeat executions.

Attributes:

Name Type Description
parent Procedure[PDirectory]

The parent directory (typically target root) to search within
name str

The session type name to search for
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@make_procedure
class GetFirstSessionDirectory(Procedure[PDirectory]):
    """
    Gets the first (oldest) session directory with the given name.

    Searches through the target's sessions folder to find the earliest timestamped
    session of the specified type. Useful for accessing baseline data, initial
    measurements, or checking if a procedure has ever been executed before.

    Commonly used with ProcedureCompleted to determine first-time vs. repeat executions.

    Attributes:
        parent: The parent directory (typically target root) to search within
        name: The session type name to search for
    """

    parent: Procedure[PDirectory]
    name: str

GetLastSessionDirectory #

Bases: Procedure[PDirectory]

Gets the last (most recent) session directory with the given name.

Searches through the target's sessions folder to find the most recent timestamped session of the specified type. Useful for comparing to previous data, building on recent measurements, or implementing session-to-session continuity.

Often used in workflows that reference or compare against recent executions.

Attributes:

Name Type Description
parent Procedure[PDirectory]

The parent directory (typically target root) to search within
name str

The session type name to search for
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
@make_procedure
class GetLastSessionDirectory(Procedure[PDirectory]):
    """
    Gets the last (most recent) session directory with the given name.

    Searches through the target's sessions folder to find the most recent timestamped
    session of the specified type. Useful for comparing to previous data, building
    on recent measurements, or implementing session-to-session continuity.

    Often used in workflows that reference or compare against recent executions.

    Attributes:
        parent: The parent directory (typically target root) to search within
        name: The session type name to search for
    """

    parent: Procedure[PDirectory]
    name: str

GetUserDirectory #

Bases: Procedure[PDirectory]

Creates a user-specific subdirectory for per-user configurations.

Useful for collaborative capture scenarios where multiple users share a target but need separate configuration directories. The directory structure is: {parent}/{name}/{user.identifier}/

For example, if name is "config" and user ID is "A1B2C3D4-...", this creates: config/A1B2C3D4-.../

Attributes:

Name Type Description
parent Procedure[PDirectory]

The parent directory to create the user directory in
name str

The base directory name (e.g., "config", "preferences")
user Procedure[PUserID]

The user ID procedure providing the unique identifier
Source code in capturegraph-lib/capturegraph/procedures/nodes/filesystem/directories.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
@make_procedure
class GetUserDirectory(Procedure[PDirectory]):
    """
    Creates a user-specific subdirectory for per-user configurations.

    Useful for collaborative capture scenarios where multiple users share
    a target but need separate configuration directories. The directory
    structure is: {parent}/{name}/{user.identifier}/

    For example, if name is "config" and user ID is "A1B2C3D4-...",
    this creates: config/A1B2C3D4-.../

    Attributes:
        parent: The parent directory to create the user directory in
        name: The base directory name (e.g., "config", "preferences")
        user: The user ID procedure providing the unique identifier
    """

    parent: Procedure[PDirectory]
    name: str
    user: Procedure[PUserID]