Metadata-Version: 2.4
Name: json-interpolator
Version: 1.0.0rc1
Summary: A utility for validating and rendering templates with placeholders in JSON-like strings.
Project-URL: Documentation, https://github.com/mgeborges/json-interpolator#readme
Project-URL: Issues, https://github.com/mgeborges/json-interpolator/issues
Project-URL: Source, https://github.com/mgeborges/json-interpolator
Author-email: Marcelo Borges <borges.marcelo@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: interpolation,json,placeholder,rendering,template
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/markdown

# JSON Interpolator

## Overview
The JSON Interpolator is a Python package for validating and rendering templates with placeholders in JSON-like strings. It ensures placeholders are correctly formatted and substitutes them with provided values.

## Features
- **Validation**: Ensures placeholders meet naming conventions.
- **Rendering**: Dynamically replaces placeholders with values from a dictionary.
- **Object-Oriented Design**: Encapsulated within the `JSONInterpolator` class for easy reuse and extension.

## Placeholder Format
Placeholders should follow the syntax:
```
<<placeholder_name>>
```
Where:
- `placeholder_name` cannot start with a digit.
- `placeholder_name` must include at least one word character (letters, digits, or underscores).

## Installation

Install from PyPI:
```bash
pip install json-interpolator
```

Or clone the repository for local development:
```bash
git clone https://github.com/mgeborges/json-interpolator.git
cd json-interpolator
pip install -e .
```


## Usage
### Example

```python
from json_interpolator import JSONInterpolator

template = """
    {
        "name": <<name>>,
        "age": <<age>>,
        "roles": <<roles>>,
        "contact_info": <<contact_info>>,
        "is_active": <<is_active>>
    }
"""
params = {
    "name": "Alice",
    "age": 30,
    "roles": ["admin", "support"],
    "contact_info": {"email": "alice@company.com", "phone": "(555) 555-5555"},
    "is_active": True
}

result = JSONInterpolator.render_template(params, template)
print(result)
# Outputs:
# {
#     "name": "Alice",
#     "age": 30,
#     "roles": ["admin", "support"],
#     "contact_info": {"email": "alice@company.com", "phone": "(555) 555-5555"},
#     "is_active": true
# }
```
Please note that there is no need to wrap string placeholders with quotes inside templates. Doing so will lead to an invalid JSON.

## Error Handling
Raises:
- `ValueError` if
    - invalid placeholders are found. Placeholder names are expected to follow the Python variables naming standards.
    - an invalid JSON is generated because of bad template formatting.
- `TypeError` if the template is not a string or if the parameters are not provided in a dictionary.

## Testing
The package includes a test suite in the `tests/` directory. To run tests:

### Using `unittest`
Run tests from the root directory:
```bash
python -m unittest discover -s tests
```

### Using `pytest`
If you prefer `pytest`:
```bash
pip install pytest
pytest
```

## Dependencies
This project does not require external dependencies beyond the standard library.

## License
MIT License

