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
Examples and documentation

Install

Python 3.12 or newer is required.

Command	Includes
`python -m pip install "apprc>=0.25.0,<0.26"`	Configuration, Typer commands, prompts, and the Textual editor.
`python -m pip install "apprc-core>=0.25.0,<0.26"`	Configuration and noninteractive management without terminal dependencies.

Both distributions use import apprc. The apprc distribution installs 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. Terminal setup already exists. A Toga GUI and native installer tooling remain planned integrations.

Examples and documentation

Start with Documentation for the learning order and component names.

Document	Purpose
Explanations	Understand the components and their connections.
How-to user guides	Complete one task using an independent example.
References	Look up exact APIs, files, commands, and behavior.
Examples	Choose and run a complete application setup.
Development	Change, verify, build, and release AppRC.

Release files for apprc 0.25.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apprc 0.25.0
File	Size	Uploaded
apprc-0.25.0.tar.gz	5.4 kB	Sep 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for apprc 0.25.0
File	Interpreter	ABI	Platform	Reset
apprc-0.25.0-py3-none-any.whl 5.2 kB Sep 23, 2026	Python 3	none	any	Details

Total release size: 10.7 kB

Release files / apprc-0.25.0.tar.gz

Download URL	apprc-0.25.0.tar.gz
Size	5.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`d04dc115eaff73b18e05952aaf0cbd8edae1ad3a813a2c29f7406645d87a64f0`
BLAKE2b-256 checksum How to use checksums	`12cdd4af9fea5a1c0fd13051c0127e93ccb2ad742936454a4fe3bb7468935149`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / apprc-0.25.0-py3-none-any.whl

Download URL	apprc-0.25.0-py3-none-any.whl
Size	5.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`20a43fd4f763ef9c8fd093c8774024882a4ff578b00c053da8a07fac9f743d7f`
BLAKE2b-256 checksum How to use checksums	`e7c59fb496c63b96f2e04d0970fb1039354e7c8fca6478cf62ee50655dff40dc`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`