Examples

The programs below are complete and runnable from a checkout with the project installed in .venv. Except for migration, they write to a distinct platform-specific per-user configuration directory, not to the source tree.

Run an example on Windows with:

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

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


def parse_boolean(raw: str) -> bool:
    """Parse a human-friendly boolean entered in the terminal."""
    normalized = raw.strip().lower()
    if normalized in {"1", "true", "yes", "y", "on"}:
        return True
    if normalized in {"0", "false", "no", "n", "off"}:
        return False
    raise ValueError("Enter yes/no, true/false, on/off, or 1/0")


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_boolean,
    ),
}

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:
    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.