Metadata-Version: 2.4
Name: config-forge
Version: 0.1.0
Summary: Utilities for generating dictionary based parameter sets
License-Expression: MIT
Project-URL: Homepage, https://github.com/5hun/config-forge
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# config-forge

Utilities for generating dictionary based configuration sets. A configuration set is iterable and yields `(name, config_dict)` pairs. You can patch existing sets and combine them while the library manages name composition.

## Installation

```bash
pip install config-forge
```

## Quick example

```python
import config_forge as cforge

# optionally change the separator used for generated names
cforge.set_name_separator("__")  # or use `name_separator("__")` as a context manager

base = cforge.Single("foo", {"a": 10, "b": {"c": 20, "d": 30}, "c": "qux"})

cfgs = (
    base.patch(**{f"b_c_{i}": {"b": {"c": i}} for i in range(0, 10)}).patch(
        **{f"c_{s}": {"c": s} for s in ["x", "y", "z"]}
    )
    | base.patch(**{f"c_{s}": {"c": s} for s in ["bar", "baz"]})
    | base.patch(aaa={"b": cforge.Replace({"x": 30})})
)


for name, cfg in cfgs:
    print(name, cfg)
```

The above script prints names composed from each patch along with the resulting dictionaries. The output begins like this:

```
foo__b_c_0__c_x {'a': 10, 'b': {'c': 0, 'd': 30}, 'c': 'x'}
foo__b_c_0__c_y {'a': 10, 'b': {'c': 0, 'd': 30}, 'c': 'y'}
foo__b_c_0__c_z {'a': 10, 'b': {'c': 0, 'd': 30}, 'c': 'z'}
foo__b_c_1__c_x {'a': 10, 'b': {'c': 1, 'd': 30}, 'c': 'x'}
foo__b_c_1__c_y {'a': 10, 'b': {'c': 1, 'd': 30}, 'c': 'y'}
...
foo__c_baz {'a': 10, 'b': {'c': 20, 'd': 30}, 'c': 'baz'}
foo__aaa {'a': 10, 'b': {'x': 30}, 'c': 'qux'}
```

See `examples/example.py` for a full demonstration.

## Concepts

### Building configuration sets

- **Single** – wrap a single base configuration.
- **Patch** – apply dictionary patches to each configuration in a set.
- **Union** – combine multiple configuration sets into one.

### Merge helpers

- **Replace** – fully replace a sub-dictionary when merging.
- **Remove** – remove a key entirely during merging.

### Transformations

- **map** – transform each `(name, config)` pair in a set.
- **filter** – drop pairs that don't satisfy a predicate.

## License

This project is licensed under the MIT License.
