Metadata-Version: 2.4
Name: config-get
Version: 1.0.0
Summary: Cross-platform configuration file locator and reader supporting .env, .ini, .toml, .json, .yml
Home-page: https://github.com/cumulus13/config-get
Author: Hadi Cahyadi
Author-email: Hadi Cahyadi <cumulus13@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/cumulus13/config-get
Project-URL: Repository, https://github.com/cumulus13/config-get
Project-URL: Bug Tracker, https://github.com/cumulus13/config-get/issues
Keywords: config,configuration,env,ini,toml,json,yaml,envdot,cross-platform
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: envdot
Requires-Dist: envdot>=1.0.29; extra == "envdot"
Provides-Extra: toml
Requires-Dist: toml>=0.10.2; extra == "toml"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: all
Requires-Dist: envdot>=1.0.29; extra == "all"
Requires-Dist: toml>=0.10.2; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: envdot>=1.0.29; extra == "dev"
Requires-Dist: toml>=0.10.2; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# config-get

> Cross-platform configuration file locator and reader for Python.

[![PyPI version](https://badge.fury.io/py/config-get.svg)](https://pypi.org/project/config-get/)
[![Python Versions](https://img.shields.io/pypi/pyversions/config-get.svg)](https://pypi.org/project/config-get/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**config-get** automatically discovers and reads configuration files from standard OS-specific locations. Supports `.env`, `.ini`, `.toml`, `.json`, `.yml`, and `.yaml` formats — no manual path wrangling required.

---

## Features

- 🔍 **Auto-discovery** — searches platform-standard directories (`%APPDATA%`, `~/.config`, etc.)
- 📄 **Multi-format** — `.env`, `.ini`, `.toml`, `.json`, `.yml`/`.yaml`
- 🪟 **Cross-platform** — Windows, Linux, macOS
- 🔗 **Zero required deps** — optional extras for TOML, YAML, dotenv
- 🐍 **Pythonic API** — dict-like access, context manager, class methods
- 🔄 **Reload support** — re-read config from disk at any time

---

## Installation

```bash
pip install config-get
```

With optional format support:

```bash
pip install "config-get[all]"     # all formats
pip install "config-get[envdot]"  # envdot
pip install "config-get[toml]"    # toml (Python < 3.11)
pip install "config-get[yaml]"    # pyyaml
```

---

## Quick Start

```python
from config_get import ConfigGet

# Auto-discover a config file for "myapp" in ~/.config/myapp/
cfg = ConfigGet("myapp", config_dir="myapp")

# Access values
db_host = cfg.get("DB_HOST", fallback="localhost")
api_key = cfg["API_KEY"]

# Section-aware access (for .ini / .toml / nested JSON/YAML)
port = cfg.get("server", "port", fallback="8080")

# Dict-like
for key, value in cfg.items():
    print(f"{key} = {value}")
```

---

## Search Order

### Windows

| Priority | Path |
|----------|------|
| 1 | `%APPDATA%\<config_dir>\` |
| 2 | `%USERPROFILE%\<config_dir>\` |
| 3 | `%APPDATA%\` |
| 4 | `%USERPROFILE%\` |
| 5 | Current working directory |

### Linux / macOS

| Priority | Path |
|----------|------|
| 1 | `~/<config_dir>/` |
| 2 | `~/.config/<config_dir>/` |
| 3 | `~/.config/` |
| 4 | `~/` |
| 5 | Current working directory |

For each directory, the following filenames are checked (in order):
`.env` → `<stem>.ini` → `<stem>.toml` → `<stem>.json` → `<stem>.yml` → `<stem>.yaml`

Or you can specify your configuration name

---

## API Reference

### `ConfigGet(config_file, config_dir, *, auto_load, create)`

```python
cfg = ConfigGet(
    config_file="myapp",   # base filename (stem)
    config_dir="myapp",    # app sub-directory
    auto_load=True,        # load on init (default True)
    create=False,          # create empty .env if not found
)
```

#### Class methods

```python
ConfigGet.from_file("path/to/config.toml")   # explicit path
ConfigGet.from_env(config_dir="myapp")        # .env shortcut
ConfigGet.from_ini("myapp", config_dir="myapp")
ConfigGet.from_toml("myapp", config_dir="myapp")
ConfigGet.from_json("myapp", config_dir="myapp")
ConfigGet.from_yaml("myapp", config_dir="myapp")
ConfigGet.search_paths("myapp", "myapp")      # inspect candidate paths
```

#### Instance methods

| Method | Description |
|--------|-------------|
| `cfg.get(key, fallback=None)` | Flat key lookup |
| `cfg.get(section, key, fallback=None)` | Section + key lookup |
| `cfg.get_section(section)` | Return entire section dict |
| `cfg.all()` | Return copy of all data |
| `cfg.reload()` | Re-read from disk |
| `cfg.find()` | Find path without loading |
| `cfg.load(path=None)` | (Re)load from path or auto-discover |

#### Dict-like interface

```python
cfg["KEY"]          # raises KeyError if missing
"KEY" in cfg        # membership test
len(cfg)            # number of top-level keys
list(cfg)           # iterate keys
cfg.keys()
cfg.values()
cfg.items()
```

---

### `get_config_file(config_file, config_dir, *, create)`

Module-level helper — returns the path of the first matching config file, or `None`.

```python
from config_get import get_config_file

path = get_config_file("myapp", config_dir="myapp")
if path:
    print(f"Found: {path}")
```

---

## Examples

### .env file

```
DB_HOST=localhost
DB_PORT=5432
SECRET_KEY="my-secret"
```

```python
cfg = ConfigGet.from_file(".env")
print(cfg["DB_HOST"])   # localhost
```

### .ini file

```ini
[database]
host = localhost
port = 5432

[server]
debug = true
```

```python
cfg = ConfigGet.from_file("app.ini")
print(cfg.get("database", "host"))   # localhost
print(cfg.get_section("server"))     # {'debug': 'true'}
```

### .toml file

```toml
[database]
host = "localhost"
port = 5432
```

```python
cfg = ConfigGet.from_file("config.toml")
print(cfg.get("database", "host"))   # localhost
```

### Context manager

```python
with ConfigGet("myapp", config_dir="myapp") as cfg:
    token = cfg.get("API_TOKEN", fallback="")
```

### Debug search paths

```python
paths = ConfigGet.search_paths("myapp", "myapp")
for p in paths:
    print(p)
```

---

## Logging

`config-get` uses Python's standard `logging` module under the `config_get` logger:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

---

## License

MIT © [Hadi Cahyadi](https://github.com/cumulus13)

## 👤 Author
        
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
    

[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)

[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
 
[Support me on Patreon](https://www.patreon.com/cumulus13)
