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.
| Command | Includes |
|---|---|
python -m pip install "apprc>=0.26.0,<0.27" |
Configuration, Typer commands, prompts, and the Textual editor. |
python -m pip install "apprc-core>=0.26.0,<0.27" |
Configuration and noninteractive management without terminal dependencies. |
python -m pip install "apprc-gui>=0.26.0,<0.27" |
Configuration and a Toga settings view; on Windows, the WinForms backend. |
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.
| 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. |
1 maintainer
Release files for apprc 0.26.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| apprc-0.26.0.tar.gz | 5.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| apprc-0.26.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 11.3 kB
Release files / apprc-0.26.0.tar.gz
| Download URL | apprc-0.26.0.tar.gz |
|---|---|
| Size | 5.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
294d30a63f6290d6f646d893bce1b7b96d7c17374a1f3737214061157ac63cdd
|
|
BLAKE2b-256 checksum How to use checksums |
0d8fdf3ea1021a9ba35eec91add8cf2136f013c54c8ceee29bb5271bc2e77c75
|
| Upload date | |
|
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.26.0-py3-none-any.whl
| Download URL | apprc-0.26.0-py3-none-any.whl |
|---|---|
| Size | 5.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
888599e9a3c3fbff763df1212d73e80830b2ad18d81e33b6646a1cdf30fd8a31
|
|
BLAKE2b-256 checksum How to use checksums |
42b879a072df4e7c009fca95651375155cbbbcc4a5d1a8376ead379955164ec9
|
| Upload date | |
|
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}
|
