Metadata-Version: 2.4
Name: ga-dictparser
Version: 0.1.1
Summary: Read a dictionary or JSON/YAML file with dynamic parameters
Author-email: Andrea Gemma <andrea.gemma@gmail.com>
License-Expression: MIT
Project-URL: Documentation, https://github.com/andreagemma/dictparser#readme
Project-URL: Issues, https://github.com/andreagemma/dictparser/issues
Project-URL: Source, https://github.com/andreagemma/dictparser
Keywords: configuration,dictionary,json,parser,dynamic,parameters
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.3
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

## DictParser

DictParser is a typed utility to read configuration values from dictionaries, JSON files, and YAML files with support for dynamic placeholders.

### Features

- Dot-path access for nested dictionaries and lists
- Runtime placeholder resolution with `{key}` syntax
- Recursive resolution for nested containers (`dict`, `list`, `tuple`, `set`)
- Optional shallow copy for mutable return values
- Full resolved export with `get_all()`
- JSON/YAML serialization helpers: `to_json()` and `to_yaml()`
- File export helper with format inference: `save()`

### Installation

Install from source:

```bash
pip install -e .
```

### Quick Example

```python
from dictparser import DictParser

data = {
    "aa": "and",
    "c": [0, 1, "{a.c.d}"],
    "a": {"b": 1, "c": {"d": "{aa}", "e": "{a.b}"}},
}

parser = DictParser(data)

assert parser.get("a.b") == 1
assert parser.get("a.c.d") == "and"
assert parser.get("a.c.e") == "1"
assert parser.get("c.1") == 1
assert parser.get("c.2") == "and"
```

### Notes on Resolution Dispatch

The resolver internally dispatches by container type while navigating paths:

- dictionary key lookup for mappings
- integer index lookup for lists and tuples
- recursive placeholder expansion for nested containers

This behavior is now documented directly in source comments in `src/dictparser/dictparser.py`.

### API Additions

The class exposes additional helpers for full output and persistence:

```python
resolved = parser.get_all()
json_text = parser.to_json()
yaml_text = parser.to_yaml()

# Infer format from output suffix (.json/.yaml/.yml), fallback json.
parser.save("output.json")
parser.save("output.yaml")

# Force format regardless of output suffix.
parser.save("output.txt", format="json")
parser.save("output.txt", format="yaml")
```

### CLI Usage

The package exposes a CLI entry point:

```bash
dictparser INPUT_FILE [-k KEY] [-o OUTPUT_FILE] [-f {json,yaml}]
```

- Without `-k/--key`, the CLI resolves and returns the entire dictionary (`get_all`).
- With `-k/--key`, the CLI resolves and returns only the selected key (`get`).
- With `-o/--output`, the CLI saves the result to file.
- With `-f/--format`, the output format is forced.
- Without `-f/--format`, format is inferred from output filename and defaults to json.

### Third-Party Licenses

Third-party licenses are archived in:

- `licenses/third_party/packages/`

Dependency summary and source links are listed in:

- `licenses/third_party/summary.tsv`
- `THIRD_PARTY_NOTICES.md`
