AppRC: Application Runtime Config

AppRC gives Python applications typed settings and tools for configuring them. Define each setting's type, default, and explanation once. Use the same application declaration to load values, show where they came from, and let users edit saved overrides.

Applications can also register named data directories outside their source checkout. Each directory can have its own settings. A config CLI and terminal editor provide setup, inspection, editing, and storage management.

Fig. 1 - Graphical Abstract: AppRC resolves typed settings from layered sources, connects selected storage to its settings and data directory, and shares one declaration across application code and configuration tools.

• Install
• Load settings
• Save user settings
• Add named storage
• Add terminal commands
• Add a Gradio settings page
• Examples and documentation

Install

Python 3.12 or newer is required.

apprc-core and apprc use import apprc; apprc-gui provides from apprc_gui import ConfigEditor. The terminal and GUI distributions each install the exact matching apprc-core version.

Warning

When upgrading from the previous single-distribution package, use a fresh environment or uninstall the old apprc first. Follow the migration instructions for the changed Python API and package ownership.

Load settings

Create one AppRC for the application and register its config sections. This complete example needs no files:

import apprc as rc

MyRC = rc.AppRC(app_id="demo")

@MyRC.config("client", prefix="DEMO_")
class ClientSettings(rc.Config):
    timeout: int = rc.field(
        "DEMO_TIMEOUT",
        default=30,
        title="Request timeout",
        explanation_short="Seconds to wait for an API response.",
    )

resolved = MyRC.resolve(environment={"DEMO_TIMEOUT": "10"})
settings = resolved.build(ClientSettings)
assert settings.timeout == 10
assert settings.provenance_of("timeout").origin == "shell_export_variable"

resolve() reads the chosen inputs and returns a ResolvedConfig. build() converts those inputs into the Python values used by ClientSettings. Pass settings to your application functions. Omit environment to use the actual process environment.

Add dotenv files or packaged defaults when values should come from files. AppRC applies a defined source precedence, and provenance records the source of each field. Reading configuration creates no files and does not change os.environ. An importable client can resolve these layers when constructed, so its caller only imports the client. The complete client example shows the package and its configuration commands.

Save user settings

Add user_dotenv=rc.UserDotenv() to the AppRC declaration when users need saved preferences. The user dotenv is apprc.user.env in the AppRC directory, separate from the installed code. Its default location for app_id="demo" is ~/.local/share/demo; DEMO_APPRC_DIR relocates it.

ConfigManager, obtained from MyRC.manage(), initializes files and applies reviewed edits. The saved-preference guide is a complete runnable program. The user preferences example provides the same operations through a CLI.

Add named storage

Add storage=rc.Storage() when the application writes persistent data. A storage is a registered directory with its own apprc.storage.env. The application obtains the selected root and writes its data there. Users can keep data outside the source checkout, switch between named directories, and move or archive them.

The data-directory guide writes a report to selected storage. The combined example shows how storage settings override user preferences. UserDotenv() and Storage() are independent; enable either or both.

Add terminal commands

The config CLI adds config setup, config doctor, config set, config edit, and storage commands to a Typer application. Set setup_next_step on AppRC to print app-supplied next-step text after successful config setup. The Typer guide shows the entire application and command sequence.

Applications can separately opt in to the application-data CLI with rc.cli.mount_appdata_cli(app, MyRC). It adds appdata paths for the cleanup inventory and appdata clean --dry-run to preview removal of AppRC-managed files and internal storage data. Cleanup is explicit; external storage payloads and unrelated files are retained. Follow the cleanup guide for the mount, runtime-independent policy, and confirmation behavior.

The config editor displays configuration layers together, explains each setting, and edits user or storage overrides. The same config fields also drive the desktop settings view. Set restart_required=True on a field whose saved value takes effect only after the application restarts. The Textual and Gradio editors mark that field and repeat the restart instruction after saving; AppRC never restarts the application automatically.

Add a Gradio settings page

Embed apprc_gui.ConfigEditor in an application-owned Gradio Blocks. Pass it MyRC.manage() so the page can set up declared files, show where effective values came from, and save user or storage overrides. It opens before required settings are complete, which makes it suitable for first-run setup. The Gradio settings guide shows the connection, and the secret companion explanation explains where saved secret=True fields go.

AppRC does not create installers. The Windows installer guide shows how an application can package its own launcher and dependencies in one Setup.exe.

Examples and documentation

Start with Documentation for the learning order and component names.