capturegraph.procedures.toolkits.metadata.notification_manager

Notification Management Toolkit

This module provides utilities for configuring and managing notification schedules for capture targets. Notifications remind users when it's time to capture data and help maintain consistent data collection workflows.

The toolkit supports two notification modes:

• Time-of-day notifications: Trigger at specific times each day

• Interval notifications: Trigger at fixed intervals after each capture

You can also just use the configure_notifications() function to ask the user for their preferences and set up notifications accordingly.

All notification settings are persisted and can be configured once per capture target.

set_next_notification_time(notification_time)

Saves the next scheduled notification time to persistent storage.

This function stores the calculated next notification time so the app can schedule appropriate alerts and reminders for the user.

Parameters:

Name	Type	Description	Default
notification_time	Procedure[PTime]	The calculated time when the next notification should occur	required

Returns:

Type	Description
Procedure[PVoid]	A procedure that saves the notification time to the target's notification file

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/notification_manager.py

def set_next_notification_time(
    notification_time: Procedure[PTime],
) -> Procedure[PVoid]:
    """
    Saves the next scheduled notification time to persistent storage.

    This function stores the calculated next notification time so the app
    can schedule appropriate alerts and reminders for the user.

    Args:
        notification_time: The calculated time when the next notification should occur

    Returns:
        A procedure that saves the notification time to the target's notification file
    """
    return (
        GetRootDirectory()
        .get_notification_file()
        .save(procedure=notification_time, skip_if_exists=False)
        .set_label("Set Next Notification Time")
    )

configure_time_of_day_notification()

Configures notifications to fire at specific times of day.

Sets up notifications that trigger at a fixed time each day (e.g., 9:00 AM daily). Users specify the interval between notifications in days and the preferred time of day. Ideal for daily data collection routines.

Returns:

Type	Description
Procedure[PVoid]	A procedure that configures time-of-day based notifications

Example

User might configure notifications to fire every 2 days at 9:00 AM.

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/notification_manager.py

def configure_time_of_day_notification() -> Procedure[PVoid]:
    """
    Configures notifications to fire at specific times of day.

    Sets up notifications that trigger at a fixed time each day (e.g., 9:00 AM daily).
    Users specify the interval between notifications in days and the preferred time
    of day. Ideal for daily data collection routines.

    Returns:
        A procedure that configures time-of-day based notifications

    Example:
        User might configure notifications to fire every 2 days at 9:00 AM.
    """
    settings_dir = _notification_settings_dir.new_directory(".time_of_day_settings")

    # Ask how many days between alerts
    days_interval = (
        settings_dir.new_file(".interval")
        .cache(
            procedure=UserInputTimeInterval(
                label="How long until the next notification?", round_to_days=True
            ),
            skip_if_exists=True,
        )
        .set_label("Cache Days Interval")
    )

    # Ask what time of day to fire
    time_of_day = (
        settings_dir.new_file(".time_of_day")
        .cache(
            procedure=UserInputTimeOfDay(label="What time should notifications fire?"),
            skip_if_exists=True,
        )
        .set_label("Cache Time of Day")
    )

    # Compute: next = beginning_of_day(current + days_interval) + time_of_day
    next_time = AddTimeInterval(
        time=GetBeginningOfDay(
            time=AddTimeInterval(time=CaptureTime(), seconds=days_interval).set_label(
                "Next Notification Day"
            )
        ).set_label("Beginning of Day for Next Notification"),
        seconds=time_of_day,
    ).set_label("Calculate Next Notification Time")

    return set_next_notification_time(next_time)

configure_interval_notifications()

Configures notifications to fire at fixed intervals after each capture.

Sets up notifications that trigger a specified amount of time after each data capture event (e.g., 4 hours after each capture). Users specify the interval duration. Ideal for event-driven or irregular data collection.

Returns:

Type	Description
Procedure[PVoid]	A procedure that configures interval-based notifications

Example

User might configure notifications to fire 6 hours after each capture.

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/notification_manager.py

def configure_interval_notifications() -> Procedure[PVoid]:
    """
    Configures notifications to fire at fixed intervals after each capture.

    Sets up notifications that trigger a specified amount of time after each
    data capture event (e.g., 4 hours after each capture). Users specify the
    interval duration. Ideal for event-driven or irregular data collection.

    Returns:
        A procedure that configures interval-based notifications

    Example:
        User might configure notifications to fire 6 hours after each capture.
    """
    settings_dir = _notification_settings_dir.new_directory(".interval_settings")

    # Ask how long between notifications
    interval = (
        settings_dir.new_file(".interval")
        .cache(
            procedure=UserInputTimeInterval(
                label="How long until the next notification?", round_to_days=False
            ),
            skip_if_exists=True,
        )
        .set_label("Cache Interval Duration")
    )

    # Compute: next = last_capture + interval
    next_time = AddTimeInterval(time=CaptureTime(), seconds=interval).set_label(
        "Calculate Next Notification Time"
    )

    return set_next_notification_time(next_time)

configure_notifications()

Main entry point for configuring all notification settings.

Presents users with options to enable/disable notifications and choose between time-of-day or interval-based scheduling. This is typically called once per capture target to set up the notification preferences.

Returns:

Type	Description
Procedure[PVoid]	A procedure that configures notifications based on user choices

Example

# Add to the beginning of your procedure
configure_notifications(),

Source code in capturegraph-lib/capturegraph/procedures/toolkits/metadata/notification_manager.py

def configure_notifications() -> Procedure[PVoid]:
    """
    Main entry point for configuring all notification settings.

    Presents users with options to enable/disable notifications and choose
    between time-of-day or interval-based scheduling. This is typically called
    once per capture target to set up the notification preferences.

    Returns:
        A procedure that configures notifications based on user choices

    Example:
        ```python
        # Add to the beginning of your procedure
        configure_notifications(),
        ```
    """

    # Branch on user’s choice
    return cached_user_select_procedure(
        label="Enable notifications?",
        options={
            "No": DoNothing().set_label("Skip Notifications"),
            "Yes, use time-of-day scheduling": configure_time_of_day_notification().set_label(
                "Configure Time-of-Day Notifications"
            ),
            "Yes, use fixed interval scheduling": configure_interval_notifications().set_label(
                "Configure Interval Notifications"
            ),
        },
        file=_notification_settings_dir.new_file(".enabled"),
        skip_if_exists=True,
    )