resourcemap 0.0.1

Python package that allows you to use application resources without worrying about where they are stored.

resourcemap

resourcemap is a Python package that allows you to use application resources without worrying about where they are stored.
It provides convenient APIs to load, locate, and manage resource files across different operating systems.

---

✨ Features

• Load JSON, YAML, or other files with automatic encoding detection (charset-normalizer)
• Define relocatable resource paths per application and author
• Automatically resolve resource locations based on user OS conventions
• Reuse a single ResourceMap object throughout your application

---

🚀 Installation

pip install resourcemap

---

📖 Usage

1. Basic Example

Load a file directly:

import resourcemap as resmap

# Direct load
file = resmap.load_json('path/to/file')

# Using a custom loader
file = resmap.load('path/to/file', loader=your_loader)

Note
If encoding is not specified in load_json() or load_yaml(),
charset-normalizer will be used to automatically guess the encoding.

---

2. Automatic Resource Mapping

from pathlib import Path
import resourcemap as resmap

# Define your application info
APP = 'app_name'
AUTHOR = 'author_name'

# Save the default dictionary
resmap.ResourceMap.create(APP, AUTHOR) \
    .set('config.json', 'path/to/config.json') \
    .set('query.sql', 'path/to/query.sql') \
    .set('data.csv', 'path/to/data.csv') \
    .save(exist_ok=True)

# Automatic resource selection
config = resmap.load_json('config', APP, AUTHOR)
query = resmap.load_json('query', APP, AUTHOR, default=Path('default/path/to/query'))

# Get only the path without loading
data_path = resmap.locate('data', APP, AUTHOR)

resourcemap saves the dictionary of resource paths in an OS-appropriate location.

For example, on Windows:

%LocalAppData%\AUTHOR\resmap\APP.json

This file specifies where relocatable resources should be placed.
By default, create it using ResourceMap.create(), .set(), and .save().

---

3. Application-wide Usage

In most cases, a single ResourceMap instance is sufficient.
Load it once and reuse it across the entire app.

# app/path/to/resmap.py
import resourcemap as resmap

# Load the RESMAP used throughout the application
RESMAP = resmap.ResourceMap.load(APP, AUTHOR)

# app/path/to/your_code.py
from pathlib import Path
import resourcemap as resmap
from app.path.to.resmap import RESMAP

config = resmap.load_json('config', RESMAP)
query = resmap.load_json('query', RESMAP, default=Path('default/path/to/query'))
data_path = resmap.locate('data', RESMAP)

---

📦 Dependencies

• appdirs
• pydantic
• charset-normalizer

---

📝 License

Apache License 2.0