Examples

The 26 programs in examples are complete and runnable from a checkout with the project installed in .venv. Ten user-preference scenarios and nine fundamental recipes use memory or automatically cleaned temporary directories. The seven persistent examples below use distinct per-user configuration locations; migration reads an existing historical file and creates a separate v2 file.

Run an example on Windows with:

.\.venv\Scripts\python.exe examples\basic_store.py

User preference scenarios

Start with User preference scenarios for everyday application behavior. All ten scenarios use temporary files, and only the first two require terminal input.

Script	User scenario
first_run_preferences.py	Initial setup and reuse on the next startup.
apply_preferences.py	Edit a draft, then confirm, discard, or cancel.
reset_preferences.py	Remove one override, a section, or the whole configuration.
recent_files.py	Keep a bounded history of recently opened documents.
window_preferences.py	Restore visible window geometry after changing displays.
account_preferences.py	Keep separate preferences for accounts within one OS user.
session_overrides.py	Override preferences through CLI options with opt-in persistence.
import_export_preferences.py	Transfer validated portable preferences without local history.
backup_restore.py	Restore a previous preference snapshot.
migration_preview.py	Preview legacy conversion and preserve ambiguous raw data.

Progressive recipes

These examples are explained with full source in Practical recipes. Use the same command above with the desired filename. On Linux or macOS, use ./.venv/bin/python examples/portable_store.py.

Level	Script	Input and file effects
Simple	portable_store.py	No input; temporary store with defaults and updates.
Simple	boolean_collection.py	Terminal; boolean and optional text, no file.
Intermediate	edit_settings.py	Terminal; retain values or edit JSON, no file.
Intermediate	gui_collection.py	GUI extra required; formatted prefill, no file.
Intermediate	handle_errors.py	No input; malformed YAML in a temporary directory.
Advanced	nested_collection.py	Terminal; edit a subsection and save a temporary file.
Advanced	custom_interface.py	Scripted answers with retries, no file.
Advanced	typed_settings.py	No input; dataclass validation and a temporary store.
Advanced	schema_upgrade.py	No input; idempotent transformation of a temporary file.

The remaining examples below progress from simple storage to project setup, environment profiles, and migration. Persistent examples print their paths.

Basic storage

This example saves a mapping, loads a fresh copy, and prints the exact path. Running it again replaces the same example configuration.

"""Save and reload a small per-user configuration."""

from upref import ConfigStore

store = ConfigStore("upref-basic-example")

store.save(
    {
        "theme": "dark",
        "notifications": True,
    }
)

config = store.load()
print(config)
print(f"Configuration saved to: {store.path}")

Defaults, update, and delete

Defaults are merged recursively in memory. The resolved mapping is then saved, selected changes are merged and persisted, and the example removes its file.

"""Combine defaults, persist selected changes, then clean up the example."""

from upref import Config, ConfigStore

store = ConfigStore("upref-update-example")

defaults: Config = {
    "network": {
        "host": "localhost",
        "port": 8080,
    },
    "notifications": True,
}

config = store.load(defaults=defaults)
print("With defaults:", config)

# Loading defaults does not write them. Save the resolved configuration when
# the application wants those values to become persistent.
store.save(config)

updated = store.update(
    {
        "network": {"port": 9000},
        "notifications": False,
    }
)
print("Saved changes:", updated)

print("Configuration removed:", store.delete())

Required project variables

This terminal-based setup asks only for project variables that have not been saved yet: directories, the expected Python version, and whether tests should run before a build. Boolean input accepts common forms such as yes, no, on, and off.

"""Collect and persist the variables required to work on one project."""

from upref import ConfigStore, ConfigValue, Field, PromptCancelled, collect, parse_bool


def is_non_empty_string(value: ConfigValue) -> bool:
    """Return whether a parsed configuration value is a non-empty string."""
    return isinstance(value, str) and bool(value.strip())


store = ConfigStore("upref-project-example", filename="variables.yaml")
schema = {
    "project_name": Field(
        "Project name",
        description="A human-readable name, for example customer-portal",
        validator=is_non_empty_string,
    ),
    "source_directory": Field(
        "Source directory",
        description="Path relative to the project root, for example src",
        validator=is_non_empty_string,
    ),
    "build_directory": Field(
        "Build directory",
        description="Path relative to the project root, for example dist",
        validator=is_non_empty_string,
    ),
    "python_version": Field(
        "Python version",
        description="Version expected by the project, for example 3.12",
        validator=is_non_empty_string,
    ),
    "run_tests_before_build": Field(
        "Run tests before building",
        parser=parse_bool,
    ),
}

try:
    variables = collect(
        schema,
        initial=store.load(),
        interface="tty",
        mode="missing",
    )
except PromptCancelled:
    print("Setup cancelled; the existing project variables were not changed.")
else:
    store.save(variables)
    print("Project variables:")
    for variable_name in schema:
        print(f"  {variable_name}: {variables[variable_name]}")
    print(f"Saved to: {store.path}")

Environment profiles and runtime overrides

This example stores development, testing, and production profiles. The UPREF_PROFILE, UPREF_SERVICE_URL, and UPREF_TIMEOUT environment variables can temporarily override the selected values without modifying the saved YAML file.

For example, in PowerShell:

$env:UPREF_PROFILE = "production"
$env:UPREF_TIMEOUT = "45"
.\.venv\Scripts\python.exe examples\environment_profiles.py

"""Select a saved environment profile and apply temporary runtime overrides."""

import os

from upref import Config, ConfigStore, ConfigValue


def require_mapping(value: ConfigValue, *, name: str) -> Config:
    """Return a configuration mapping or report an invalid saved shape."""
    if not isinstance(value, dict):
        raise TypeError(f"{name} must be a mapping")
    return value


def require_string(value: ConfigValue, *, name: str) -> str:
    """Return a string setting or report an invalid saved type."""
    if not isinstance(value, str):
        raise TypeError(f"{name} must be a string")
    return value


def require_integer(value: ConfigValue, *, name: str) -> int:
    """Return an integer setting while rejecting booleans."""
    if isinstance(value, bool) or not isinstance(value, int):
        raise TypeError(f"{name} must be an integer")
    return value


def require_boolean(value: ConfigValue, *, name: str) -> bool:
    """Return a boolean setting or report an invalid saved type."""
    if not isinstance(value, bool):
        raise TypeError(f"{name} must be a boolean")
    return value


DEFAULTS: Config = {
    "active_profile": "development",
    "profiles": {
        "development": {
            "service_url": "http://localhost:8000",
            "timeout": 10,
            "debug": True,
        },
        "testing": {
            "service_url": "http://localhost:8001",
            "timeout": 5,
            "debug": False,
        },
        "production": {
            "service_url": "https://api.example.org",
            "timeout": 30,
            "debug": False,
        },
    },
}

store = ConfigStore("upref-profiles-example")
settings = store.load(defaults=DEFAULTS)
if not store.exists():
    store.save(settings)

profiles = require_mapping(settings["profiles"], name="profiles")
saved_profile = require_string(settings["active_profile"], name="active_profile")
profile_name = os.environ.get("UPREF_PROFILE", saved_profile)
if profile_name not in profiles:
    choices = ", ".join(sorted(profiles))
    raise ValueError(f"Unknown profile {profile_name!r}; choose one of: {choices}")

profile = require_mapping(profiles[profile_name], name=f"profiles.{profile_name}")
saved_service_url = require_string(profile["service_url"], name="service_url")
service_url = os.environ.get("UPREF_SERVICE_URL", saved_service_url)

saved_timeout = require_integer(profile["timeout"], name="timeout")
timeout_text = os.environ.get("UPREF_TIMEOUT")
timeout = saved_timeout if timeout_text is None else int(timeout_text)
if timeout <= 0:
    raise ValueError("UPREF_TIMEOUT must be greater than zero")
debug = require_boolean(profile["debug"], name="debug")

print(f"Profile: {profile_name}")
print(f"Service URL: {service_url}")
print(f"Timeout: {timeout} seconds")
print(f"Debug logging: {debug}")
print(f"Persistent configuration: {store.path}")
print("Environment-variable overrides were not persisted.")

Multiple projects

Related projects can share one application configuration directory while using a distinct YAML filename for each project. This is useful for a workspace containing a frontend, backend, worker, or other independently configured component.

"""Keep independent per-user settings for several related projects."""

from upref import Config, ConfigStore

PROJECT_DEFAULTS: dict[str, Config] = {
    "frontend": {
        "working_directory": "apps/frontend",
        "test_command": "npm test",
        "build_command": "npm run build",
        "enabled": True,
    },
    "backend": {
        "working_directory": "apps/backend",
        "test_command": "python -m pytest",
        "build_command": "python -m build",
        "enabled": True,
    },
}

for project_name, defaults in PROJECT_DEFAULTS.items():
    # Each project receives a separate file below the same application-specific
    # per-user configuration directory.
    store = ConfigStore(
        "upref-workspace-example",
        filename=f"{project_name}.yaml",
    )
    settings = store.load(defaults=defaults)
    if not store.exists():
        store.save(settings)

    print(f"{project_name}: {settings}")
    print(f"  file: {store.path}")

Terminal collection

On the first run, missing values are requested in the terminal. Later runs reuse saved values. Cancelling before save leaves the existing file unchanged.

"""Ask only for missing values in a terminal, then save them explicitly."""

from upref import ConfigStore, Field, PromptCancelled, collect

store = ConfigStore("upref-tty-example")
schema = {
    "service_url": Field(
        "Service URL",
        description="For example: https://api.example.org",
    ),
    "timeout": Field(
        "Timeout in seconds",
        parser=int,
        validator=lambda value: isinstance(value, int) and value > 0,
    ),
}

try:
    values = collect(
        schema,
        initial=store.load(),
        interface="tty",
        mode="missing",
    )
except PromptCancelled:
    print("Input cancelled; the configuration was not changed.")
else:
    store.save(values)
    print(f"Configuration saved to: {store.path}")

Migrating from v1

This program imports an existing historical file. Change LEGACY_NAME to the old configuration name. Migration leaves its source untouched and checks for an existing v2 target before saving. Concurrent migrations require an external lock.

"""Import values from an existing Upref v1 configuration."""

from upref import ConfigStore, UprefError

LEGACY_NAME = "my_personnal_data"
store = ConfigStore("upref-migration-example")

try:
    preview = store.import_legacy(LEGACY_NAME, source_format="auto", dry_run=True)
    print("Proposed keys:", ", ".join(sorted(preview)))
    # Use source_format="raw" when keys such as "value" are application data.
    # The import below reads the source again and repeats the target checks.
    migrated = store.import_legacy(LEGACY_NAME)
except UprefError as error:
    print(f"Migration was not performed: {error}")
else:
    print("Migrated keys:", ", ".join(sorted(migrated)))
    print(f"New configuration: {store.path}")

Warning

Upref configuration files contain plain YAML. Masked interactive input is not encrypted storage; use a system keyring or secrets manager for passwords and tokens.