{"id":10176,"library":"pyvrl","title":"PyVRL: Python Interface for Vector Remap Language (VRL)","description":"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.","status":"active","version":"0.0.2","language":"en","source_language":"en","source_url":"https://github.com/crowdalert/pyvrl","tags":["vrl","vector-remap-language","data-transformation","data-processing"],"install":[{"cmd":"pip install pyvrl","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"VRLCompiler","correct":"from pyvrl.compiler import VRLCompiler"},{"note":"Value is in the 'value' submodule, not directly under 'pyvrl'.","wrong":"from pyvrl import Value","symbol":"Value","correct":"from pyvrl.value import Value"}],"quickstart":{"code":"from pyvrl.compiler import VRLCompiler\nfrom pyvrl.value import Value\n\n# Initialize the VRL compiler\ncompiler = VRLCompiler()\n\n# Compile a VRL program to uppercase the 'message' field\nvrl_program = '.message = upcase(.message)'\ncompiled_program = compiler.compile(vrl_program)\n\n# Prepare input data as a pyvrl.value.Value object\ninput_data = Value({\"message\": \"hello world\"})\n\n# Run the VRL program\noutput_data = compiled_program.run(input_data)\n\n# Convert the output back to a Python dictionary\nresult = output_data.as_python()\n\nprint(f\"Input: {input_data.as_python()}\")\nprint(f\"Output: {result}\")\n# Expected output: {'message': 'HELLO WORLD'}","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.x"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Wrap your Python data in a `Value` object: `compiled_program.run(Value({'key': 'value'}))`","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.","error":"TypeError: expected pyvrl.value.Value, got dict"},{"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.","cause":"The VRL expression provided to `VRLCompiler().compile()` contains a syntax or semantic error according to VRL rules.","error":"pyvrl.compiler.VRLCompilationError: ... (followed by VRL specific error details)"}]}