JSON-e

Warnings

• gotcha The `json-e` PyPI package exists, but its official usage documentation (json-e.js.org) is primarily JavaScript-centric. Direct, high-level Python API usage examples and import paths for explicit JSON-e templating functions are not easily found in public documentation. Users may find themselves defaulting to Python's built-in `json` module for general JSON handling, which does not provide JSON-e's templating capabilities.
  Fix: Thoroughly consult the `json-e` GitHub repository's source code, specifically its Python implementation directory, for definitive import paths and API usage. Alternatively, consider using `json-e` in a JavaScript context if that aligns with project needs.
• gotcha When working with JSON data in Python, it's a common mistake to confuse `json-e` (a templating system) with Python's built-in `json` module. The `json` module handles serialization and deserialization but does not offer the advanced data-structure parameterization features like `$eval`, `$if`, or `$map` that are central to JSON-e's specification.
  Fix: Be clear about the distinct purposes: use Python's `json` module for basic JSON parsing/serialization, and investigate the specific `json-e` implementation (if available and documented) when data-structure templating is required. If a dedicated Python `json-e` library with a clear API is not found, a custom solution for templating might be needed or consider other templating engines.
• breaking The `json-e` project follows semantic versioning, and breaking changes to the language specification or its implementations (including Python) are possible, though stated to be uncommon and typically result from bug fixes. These changes could arise if a bug fix introduces backward incompatibility, necessitating a major version bump.
  Fix: Always review the `CHANGELOG.rst` in the `json-e` GitHub repository before upgrading major versions. Thoroughly test existing `json-e` templates and their Python processing logic after any upgrade to ensure continued compatibility.

Install

• pip install json-e Install latest version

Imports

• json_e

  import json_e

  While 'json' is Python's built-in JSON handler, 'json-e' is a separate library for data-structure parameterization. The documentation for the Python implementation's specific API is not prominently featured; the main project documentation refers to json-e.js.org for usage. This entry assumes a direct 'json_e' import if a high-level Python API exists as a standalone module within the PyPI package.

Quickstart

This example illustrates the *concept* of data-structure parameterization that JSON-e provides, using Python's standard `json` module for serialization and deserialization. It manually demonstrates a simple substitution process, as a direct, high-level Python API for 'json-e' templating with an explicit `render` function is not readily available in public documentation.

import json

# NOTE: This quickstart demonstrates the *concept* of JSON-e templating
# using Python's built-in 'json' module for data handling. 
# A high-level, standalone Python API for the 'json-e' templating logic
# is not extensively documented in public search results. 
# This example *simulates* a basic substitution operation.

template = {
    "message": "Hello, ${user.name}! Your ID is ${user.id}.",
    "settings": {
        "theme": "${config.theme}",
        "darkMode": "${config.darkMode}"
    }
}

context = {
    "user": {
        "name": "Alice",
        "id": "12345"
    },
    "config": {
        "theme": "dark",
        "darkMode": True
    }
}

def apply_template(template_data, context_data):
    # This is a simplified, manual substitution for demonstration.
    # A true JSON-e implementation would handle more complex operations ($eval, $if, $map, etc.)
    template_str = json.dumps(template_data)
    
    # Basic string interpolation for demonstration
    for key_outer, val_outer in context_data.items():
        if isinstance(val_outer, dict):
            for key_inner, val_inner in val_outer.items():
                placeholder = f"${{{key_outer}.{key_inner}}}"
                template_str = template_str.replace(placeholder, str(val_inner))
        else:
             placeholder = f"${{{key_outer}}}"
             template_str = template_str.replace(placeholder, str(val_outer))
    
    # Attempt to parse the result back to a JSON object
    return json.loads(template_str)


output = apply_template(template, context)
print(json.dumps(output, indent=2))