Jsonnet Python Bindings

Warnings

• breaking Between versions 0.21.0 and 0.22.0, bitwise operation arguments are now limited to the 'safe-integer' range (IEEE754 double-precision floating-point integers). Code relying on bitwise operations outside this range will now error. The internal `std.objectRemoveKey` function was also re-implemented to fix several bugs and unexpected behaviors, which might subtly change outcomes for complex object manipulations.
  Fix: Ensure bitwise operation arguments are within the safe-integer range. Review usage of `std.objectRemoveKey` if upgrading from pre-0.22.0 versions.
• breaking Pre-built Python binary wheels (used during `pip install`) now use the Python Limited API (ABI3 compatible) since version 0.22.0. This improves compatibility with newer Python versions, but might require recompilation or specific build environments if you are building from source against an older or non-standard Python setup.
  Fix: For most users installing via `pip`, this should be seamless. If you encounter build issues when installing from source, ensure your Python environment and compiler toolchain are up-to-date and compatible with ABI3.
• gotcha The `_jsonnet` library, being a binding to the C++ implementation, is not hardened for untrusted inputs and poses significant security risks (data exfiltration, denial of service) if used to evaluate arbitrary, untrusted Jsonnet code. The `import`, `importstr`, and `importbin` constructs can read any file accessible to the interpreter process.
  Fix: NEVER evaluate untrusted Jsonnet code without robust sandboxing (e.g., gVisor, Firecracker VM) and/or implementing a custom `import_callback` to restrict file access. For API servers, `exec` the Jsonnet CLI in a `ulimit` child process to bound CPU/RAM.
• gotcha When using `_jsonnet.evaluate_snippet()` for Jsonnet code that contains `import` statements, the interpreter needs to know where to search for imported files. Without specifying `jpathdir` or providing a custom `import_callback`, these imports will fail.
  Fix: Always provide the `jpathdir` argument (a string or list of directory paths) to `evaluate_snippet` if your Jsonnet code uses imports, or implement a custom `import_callback` function for more advanced import logic. Example: `_jsonnet.evaluate_snippet('name', snippet_code, jpathdir=['./my_jsonnet_libs'])`.
• gotcha Jsonnet is a lazy evaluation language. This means expressions are only evaluated when their value is actually needed. This can lead to unexpected behavior regarding errors or performance, as code that appears before an error-inducing line might not be evaluated, or computationally intensive parts might only run when accessed.
  Fix: Be mindful of Jsonnet's lazy evaluation model, especially when debugging errors or optimizing performance. Understand that variable initializers are not evaluated until the variable is used. Explicit assertions can help pinpoint evaluation issues.

Install

• pip install jsonnet Install stable version

Imports

• _jsonnet

  import _jsonnet

  The Python module for Jsonnet is imported as '_jsonnet', not 'jsonnet'.

Quickstart

This quickstart demonstrates how to evaluate a Jsonnet snippet using `_jsonnet.evaluate_snippet` and access external variables. The output is a JSON string, which is then parsed into a Python dictionary.

import _jsonnet
import json

# Example Jsonnet snippet
jsonnet_snippet = '''
local person(name='Alice') = {
  name: name,
  welcome: 'Hello ' + name + '!'
};
{
  person1: person(),
  person2: person('Bob'),
  env_greeting: 'Hello from env ' + std.extVar('GREET_TARGET'),
}
'''

# Evaluate a Jsonnet snippet
# Note: For security, never pass untrusted input to ext_vars without proper sanitization/validation.
output_json_string = _jsonnet.evaluate_snippet(
    'example.jsonnet', # Filename used in error messages
    jsonnet_snippet,
    ext_vars={'GREET_TARGET': 'World'}
)

# Parse the resulting JSON string into a Python object
output_data = json.loads(output_json_string)

print(json.dumps(output_data, indent=2))