Metadata-Version: 2.3
Name: app-resource-resolver
Version: 0.1.0
Summary: Resolve application resource locations and configuration sources across platforms.
Keywords: configuration,xdg,appdata,resources,settings
Author: Travis Bender
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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/DESIGN.md)
- [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md)
- [docs/STRATEGIES.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.

```python
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:

```python
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.

```python
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:

```python
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:

```python
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.
