app-resource-resolver

app-resource-resolver resolves application resource locations across platforms: config, data, state, cache, logs, runtime files, locks, bins, credentials, and related app-owned resources.

The package is designed around two layers:

• AppLocations: path and candidate resolution, similar in spirit to platformdirs but strategy-driven.
• AppConfig: config source discovery, parsing, merging, and provenance.

The core package has no runtime dependencies outside the Python standard library.

Current Status

This project is in initial implementation. See:

• docs/DESIGN.md
• docs/TERMINOLOGY.md
• docs/STRATEGIES.md

The examples below show the implemented initial API surface.

Path Resolution Direction

AppLocations is intended to be the platformdirs-like interface. It should return default locations without scanning the filesystem unless the method name makes discovery explicit.

from app_resource_resolver import AppLocations

locations = AppLocations("myapp", strategy="native")

config_dir = locations.user_config_dir()
cache_dir = locations.user_cache_dir()
state_dir = locations.user_state_dir()

Strategies should hide platform-specific details:

from app_resource_resolver import AppLocations

locations = AppLocations(
    "myapp",
    strategy="portable",
    env_prefix="MYAPP",
)

for candidate in locations.config_candidates("config.toml"):
    print(candidate.path, candidate.provider, candidate.scope)

target = locations.config_write_target("config.toml")

Simple target methods answer where a new resource belongs. Discovery methods such as find_*, candidates_*, and resolve_* are the APIs that may inspect whether paths already exist.

Config Management Direction

AppConfig is intended to sit above AppLocations. It should discover config sources, parse supported formats, merge values according to precedence, and preserve provenance.

from app_resource_resolver import AppConfig

config = AppConfig(
    "myapp",
    strategy="portable",
    filenames=("config.toml", "settings.json"),
)

settings = config.load_merged()
sources = config.show_sources()

Common tool presets provide enum-first discovery for real config and data locations without requiring callers to spell out string resource kinds:

from app_resource_resolver import AppConfig, ToolPreset

git_config = AppConfig(preset=ToolPreset.GIT, cwd=project_dir)

for source in git_config.show_sources():
    print(source.candidate.kind, source.candidate.path, source.format_name)

settings = git_config.load_merged()

Some presets include non-config resources so they can be inspected with show_sources(). For example, cargo's ~/.cargo/env and zoxide's data file are discoverable, but load_merged() only loads files with a stdlib-supported suffix or a rule-specified format unless the caller registers another loader.

Presets are small source-rule specs, so applications can provide their own without depending on global state:

from app_resource_resolver import (
    AppConfig,
    ConfigFormat,
    ConfigPreset,
    Provider,
    SourceBase,
    SourceRule,
)

spec = ConfigPreset(
    name="example",
    app_name="example",
    rules=(
        SourceRule(
            SourceBase.XDG_CONFIG_HOME,
            "example/config",
            provider=Provider.XDG_USER,
            format=ConfigFormat.INI,
        ),
    ),
)

config = AppConfig(spec=spec)

The core package will use only standard-library parsers:

• TOML via tomllib;
• JSON via json;
• INI-style files via configparser.

YAML and other formats should be supplied by caller-provided loaders, optional extras, or adapter packages rather than becoming core runtime dependencies.