DOCSEARCHbyAlgolia
Submit Docs

jq.py Python Bindings

repository·master·Indexed 19 days ago

https://github.com/mwilliamson/jq.py

Python bindings for the jq JSON processor (version 1.8.2), enabling developers to compile jq programs and filter JSON data directly within Python. It provides a workflow for compiling programs, supplying input via methods like .input_value() or .input_text(), and retrieving results using .first(), .all(), .text(), or .iter(). Convenience functions are also available for one-off operations.

Tokens
1.6K
Snippets
5
Records
6
Agent score
16%

What's inside jq.py

  1. How to use jq.py

    master

    Using jq.py follows a three-step workflow:

    1. Compile: Use jq.compile(program_string) to compile a jq program.
    2. Input: Call an input method on the compiled program to supply data.
    3. Output: Call an output method on the result to retrieve the processed data.

    Using Arguments in Programs You can pass predefined variables into your jq program using the args parameter in jq.compile().

    Accessing the Program String The original program string used for compilation is stored in the program_string attribute of the compiled program object.

    import jq

# Standard workflow
program = jq.compile(".+5")
result = program.input_value(42).first()
assert result == 47

# Using arguments
program = jq.compile("$a + $b + .", args={"a": 100, "b": 20})
assert program.input_value(3).first() == 123

# Accessing program string
assert program.program_string == ".+5"

  2. Install jq.py

    master

    You can install jq using pip. Wheels are available for various Python versions and architectures on Linux, Mac OS X, and Windows.

    If a wheel is not available, the package will build from source (jq 1.8.2), which requires autoreconf, a C compiler toolchain (like gcc and make), libtool, and Python headers.

    Alternatively, you can use system-installed libjq and libonig by setting the JQPY_USE_SYSTEM_LIBS environment variable to 1 during installation.

    pip install jq

  3. Install system dependencies for building jq.py from source

    master

    If you are building from source and wheels are unavailable, install the following dependencies based on your operating system:

    Debian, Ubuntu, or relatives:

    apt-get install autoconf automake build-essential libtool python-dev

    Red Hat, Fedora, CentOS, or relatives:

    yum groupinstall "Development Tools"
yum install autoconf automake libtool python python-devel

    Mac OS X: Requires Xcode and Homebrew. Use Homebrew to install dependencies:

    brew install autoconf automake libtool

  4. Supply input to a jq program

    master

    Once a program is compiled, use one of the following methods to provide input:

    • .input_value(value): Supplies a valid JSON value (e.g., from json.load()).
    • .input_values(list_of_values): Supplies multiple valid JSON values.
    • .input_text(text_string): Supplies unparsed JSON text.
      • Use slurp=True to read the entire input into a single array instead of separate elements.
    • .input(value_or_text, text=None): A legacy method. Pass a JSON value as a positional argument, or unparsed text via the text keyword argument.

    Note on input_text with slurp=True: By default, input_text("1\n2\n3") treats each line as a separate JSON value. With slurp=True, it returns [1, 2, 3].

    import jq

program = jq.compile(".")

# Single JSON value
program.input_value(42)

# Multiple JSON values
program.input_values([1, 2, 3])

# Unparsed JSON text
program.input_text("null")

# Unparsed JSON text with slurp (reads into an array)
program.input_text("1\n2\n3", slurp=True)

# Legacy input method
program.input("hello")
program.input(text='"hello"')

  5. Use jq.py convenience functions

    master

    For simple one-off operations, you can bypass the explicit compile/input/output steps using convenience functions that combine them into a single call:

    • jq.first(program_string, input_value=None, text=None)
    • jq.text(program_string, input_value=None, text=None)
    • jq.all(program_string, input_value=None, text=None)
    • jq.iter(program_string, input_value=None, text=None)

    You can pass either a Python object as the second argument (for input_value) or a JSON string via the text keyword argument.

    import jq

# Using input_value (positional)
assert jq.first(".[] + 1", [1, 2, 3]) == 2
assert jq.all(".[] + 1", [1, 2, 3]) == [2, 3, 4]

# Using text (keyword)
assert jq.first(".[] + 1", text="[1, 2, 3]") == 2
assert jq.text(".[] + 1", [1, 2, 3]) == "2\n3\n4"

# Using iter
assert list(jq.iter(".[] + 1", [1, 2, 3])) == [2, 3, 4]

  6. Retrieve output from a jq program

    master

    After providing input, use these methods to retrieve the results:

    • .first(): Runs the program and returns the first output element.
    • .all(): Returns all output elements as a Python list.
    • .text(): Serializes the output into JSON text. If there are multiple elements, each is represented on a new line.
    • .iter(): Returns an iterator over the output elements.

    Note on .first() vs .all(): If a program produces multiple elements (e.g., .[]), .first() returns only the first one, while .all() returns the entire collection.

    import jq

program = jq.compile(".[]+1")

# Get the first element
assert program.input_value([1, 2, 3]).first() == 2

# Get all elements as a list
assert program.input_value([1, 2, 3]).all() == [2, 3, 4]

# Get output as JSON text (newline separated if multiple)
assert jq.compile(".[]").input_value([1, 2, 3]).text() == "1\n2\n3"

# Get an iterator
iterator = program.input_value([1, 2, 3]).iter()