Skip to main content

Settings

The Settings API provides a powerful mechanism to store and retrieve configuration data, user preferences, and persistent information for your Anchorpoint actions. There are two types of settings available: local user settings and shared workspace/project settings.

Usage​

Settings are accessed through the apsync module:

import apsync

# Create a local user settings instance
settings = apsync.Settings()

# Create a named settings instance
named_settings = apsync.Settings("Blender Action Settings")

# Create workspace-wide shared settings
project = apsync.get_project(path)
if project:
    shared_settings = apsync.SharedSettings(project.workspace_id, "Team Settings")

Settings Class​

The Settings class stores data locally on the user's machine. These settings are private and not synchronized across users or devices.

Constructor​

  • apsync.Settings(name=None, identifier=None, location=None, user=True) Creates a new Settings instance with optional scoping and naming parameters.

    Arguments

    • name (str, optional): A name to identify the settings, allowing retrieval of the same settings across different actions
    • identifier (str, optional): An identifier to scope the settings (e.g., project ID to make settings unique per project)
    • location (str, optional): Custom location where settings are stored on disk
    • user (bool): Set to True to make settings available for all users (default: True)

Methods​

  • set(key, value) Stores a value identified by a key name.

    Arguments

    • key (str): The name of the settings value
    • value (object): The value to be stored (can be string, number, boolean, etc.)

  • get(key, default='') Retrieves a stored value by key name, returning a default value if the key doesn't exist.

    Arguments

    • key (str): The name of the settings value
    • default (object): The default value to return if key is not found (default: empty string)

    Returns (object): The stored value or the provided default

  • contains(key) Checks if a key exists in the settings.

    Arguments

    • key (str): The name of the settings value

    Returns (bool): True if the key exists, False otherwise

  • remove(key) Removes a value from the settings by key name.

    Arguments

    • key (str): The name of the settings value to remove

  • clear() Removes all stored values from the settings - essentially a factory reset.

  • store() Persists all changes made to the settings. This method must be called after any modifications to ensure changes are saved to disk.

SharedSettings Class​

The SharedSettings class stores data in the cloud that is shared across all users in a workspace or project. These settings are synchronized and accessible to all team members with appropriate access.

Note: Currently, SharedSettings are not encrypted.

Constructor​

  • SharedSettings(workspace_id, identifier) Creates workspace-wide shared settings accessible to all workspace members.

    Arguments

    • workspace_id (str): The ID of the workspace where the settings will be stored
    • identifier (str): A unique identifier for this set of shared settings within the workspace

  • SharedSettings(project_id, workspace_id, identifier) Creates project-scoped shared settings accessible only to users with access to the specific project.

    Arguments

    • project_id (str): The ID of the project where the settings will be stored
    • workspace_id (str): The ID of the workspace containing the project
    • identifier (str): A unique identifier for this set of shared settings within the project

Methods​

The SharedSettings class provides the same methods as the Settings class:

  • set(key, value) Stores a shared value identified by a key name.

    Arguments

    • key (str): The name of the settings value
    • value (object): The value to be stored (can be string, number, boolean, etc.)

  • get(key, default='') Retrieves a stored shared value by key name, returning a default value if the key doesn't exist.

    Arguments

    • key (str): The name of the settings value
    • default (object): The default value to return if key is not found (default: empty string)

    Returns (object): The stored value or the provided default

  • contains(key) Checks if a key exists in the shared settings.

    Arguments

    • key (str): The name of the settings value

    Returns (bool): True if the key exists, False otherwise

  • remove(key) Removes a value from the shared settings by key name.

    Arguments

    • key (str): The name of the settings value to remove

  • clear() Removes all stored values from the shared settings - essentially a factory reset.

  • store() Persists all changes made to the shared settings. This method must be called after any modifications to ensure changes are saved to the cloud.

Examples​

Basic Settings Operations​

import apsync

# Create a settings instance
settings = apsync.Settings()

# Store various types of data
settings.set("lottery numbers", 4815162342)
settings.set("user_name", "John Doe")
settings.set("auto_save", True)
settings.store()  # Don't forget to persist changes

# Retrieve stored values
jackpot = settings.get("lottery numbers", 4815162342)
username = settings.get("user_name", "Anonymous")
auto_save = settings.get("auto_save", False)

# Check if settings exist
if settings.contains("lottery numbers"):
    print("Lucky numbers are saved!")

# Remove individual settings
settings.remove("lottery numbers")
settings.store()  # Persist the removal

# Clear all settings (factory reset)
settings.clear()
settings.store()  # Make the clearing permanent

SharedSettings - Workspace Level​

import apsync

# Create workspace-wide shared settings
project = apsync.get_project(path)
if project:
    shared_settings = apsync.SharedSettings(project.workspace_id, "Blender Action Settings")
    
    # Store team preferences
    shared_settings.set("render_quality", "high")
    shared_settings.set("auto_backup", True)
    shared_settings.store()
    
    # Later, any team member can access these settings
    quality = shared_settings.get("render_quality", "medium")
    backup_enabled = shared_settings.get("auto_backup", False)

SharedSettings - Project Level​

import apsync

# Create project-scoped shared settings
project = apsync.get_project(path)
if project:
    project_shared_settings = apsync.SharedSettings(
        project.project_id, 
        project.workspace_id, 
        "Team Render Settings"
    )
    
    # Store project-specific team settings
    project_shared_settings.set("output_path", "/shared/renders")
    project_shared_settings.set("file_format", "exr")
    project_shared_settings.store()

User Preferences Storage​

import apsync

# Store user preferences that persist across action executions
preferences = apsync.Settings("UserPreferences")

# Set user preferences
preferences.set("theme", "dark")
preferences.set("auto_save_interval", 300)  # 5 minutes
preferences.set("show_notifications", True)
preferences.store()

# Retrieve preferences in another action
def load_user_preferences():
    prefs = apsync.Settings("UserPreferences")
    theme = prefs.get("theme", "light")
    auto_save = prefs.get("auto_save_interval", 600)
    notifications = prefs.get("show_notifications", True)
    return theme, auto_save, notifications

Project-Specific Configuration​

import apsync

# Store project-specific settings
project = apsync.get_project("/path/to/project")
if project:
    config = apsync.Settings("ProjectConfig", project.project_id)
    config.set("render_engine", "cycles")
    config.set("output_format", "png")
    config.set("resolution", [1920, 1080])
    config.store()