PyVRL: Python Interface for Vector Remap Language (VRL)

0.0.2 · active · verified Fri Apr 17

PyVRL is a Python library that allows you to execute Vector Remap Language (VRL) transformations directly within your Python applications. It provides bindings to the VRL compiler and runtime, enabling data manipulation, filtering, and routing with VRL expressions. The current version is 0.0.2, indicating it's in very early development with an irregular release cadence.

Common errors

```
TypeError: expected pyvrl.value.Value, got dict
```
cause You are passing a standard Python dictionary or list directly to a `pyvrl` function (e.g., `compiled_program.run()`) that expects a `pyvrl.value.Value` object.

fix Wrap your Python data in a `Value` object: `compiled_program.run(Value({'key': 'value'}))`
```
pyvrl.compiler.VRLCompilationError: ... (followed by VRL specific error details)
```
cause The VRL expression provided to `VRLCompiler().compile()` contains a syntax or semantic error according to VRL rules.

fix Carefully review your VRL expression for correctness. Common errors include missing dots for field access (`.field`), incorrect function names, or mismatched parentheses. Consult VRL documentation.

Warnings

breaking As a library in early development (version 0.0.x), the API is subject to frequent and potentially breaking changes. Stability is not guaranteed between minor or even patch versions.
Fix: Always consult the latest GitHub README and any release notes for API changes before upgrading. Pin your dependency to a specific patch version if stability is critical.
gotcha VRL expressions in `pyvrl` operate on `pyvrl.value.Value` objects, not standard Python dictionaries or lists directly. Passing raw Python types where a `Value` is expected will result in type errors.
Fix: Ensure all input data for VRL processing is wrapped using `pyvrl.value.Value(your_python_data)`. To retrieve Python-native types from `pyvrl` output, use the `.as_python()` method on the resulting `Value` object.
gotcha VRL syntax errors are caught by the `VRLCompiler` during the `compile()` step, not by Python's interpreter. Invalid VRL expressions will lead to `pyvrl.compiler.VRLCompilationError` at runtime.
Fix: Thoroughly test VRL expressions for correctness before embedding them in your Python code. You may use external VRL validators or the `Vector` CLI to pre-validate complex VRL logic.

Install

pip install pyvrl Install stable version

Imports

VRLCompiler
```
from pyvrl.compiler import VRLCompiler
```
Value
wrong:
```
from pyvrl import Value
```
correct:
```
from pyvrl.value import Value
```
Value is in the 'value' submodule, not directly under 'pyvrl'.

Quickstart

This quickstart demonstrates how to compile a VRL expression and execute it on a Python dictionary, ensuring data is correctly converted to and from `pyvrl.value.Value` objects.

from pyvrl.compiler import VRLCompiler
from pyvrl.value import Value

# Initialize the VRL compiler
compiler = VRLCompiler()

# Compile a VRL program to uppercase the 'message' field
vrl_program = '.message = upcase(.message)'
compiled_program = compiler.compile(vrl_program)

# Prepare input data as a pyvrl.value.Value object
input_data = Value({"message": "hello world"})

# Run the VRL program
output_data = compiled_program.run(input_data)

# Convert the output back to a Python dictionary
result = output_data.as_python()

print(f"Input: {input_data.as_python()}")
print(f"Output: {result}")
# Expected output: {'message': 'HELLO WORLD'}

view raw JSON →