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 desktop settings window
• 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 ConfigView. 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. The Typer guide shows the entire application and command sequence.

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.

Add a desktop settings window

Embed apprc_gui.ConfigView in an application-owned Toga window. Pass it MyRC.manage() so the window 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 native window 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 include this window and its own executable in one MSI installer.

Examples and documentation

Start with Documentation for the learning order and component names.