Metadata-Version: 2.4
Name: resourcemap
Version: 0.0.1
Summary: Python package that allows you to use application resources without worrying about where they are stored.
Author-email: quote-meta <nullpo.loveletter.vbs@gmail.com>
License-Expression: Apache-2.0
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: appdirs
Requires-Dist: pydantic
Requires-Dist: charset-normalizer
Provides-Extra: ipykernel
Requires-Dist: ipykernel; extra == "ipykernel"
Provides-Extra: yaml
Requires-Dist: PyYAML; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# 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

```bash
pip install resourcemap
```

---

## 📖 Usage

### 1. Basic Example
Load a file directly:

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

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

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

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

```python
# 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](https://pypi.org/project/appdirs/)  
- [pydantic](https://pypi.org/project/pydantic/)  
- [charset-normalizer](https://pypi.org/project/charset-normalizer/)  

---

## 📝 License
Apache License 2.0
