drupal-jsonapi-params-python

Python port of drupal-jsonapi-params — a query string builder for Drupal's JSON:API. Pure Python, no dependencies, Python 3.9+.

Scope: query string generation only. No HTTP, no auth, no response parsing.

Installation

pip install drupal-jsonapi-params

Or for development:

git clone https://github.com/VincenzoGambino/drupal-jsonapi-params-python.git
cd drupal-jsonapi-params-python
pip install -e ".[dev]"

Quick start

from drupal_jsonapi_params import DrupalJsonApiParams, FilterOperator

api = DrupalJsonApiParams()
(
    api
    .add_group("publish_status", "OR", "parent_group")
    .add_group("parent_group", "AND")
    .add_filter("status", "1")
    .add_filter("status", "2", "<>", "publish_status")
    .add_page_limit(5)
    .add_page_offset(20)
    .add_fields("node--article", ["field_a.id", "field_b.uid"])
    .add_include(["field_a.id", "field_b.uid"])
    .add_sort("id", "DESC")
    .add_sort("uid")
)

# URL-encoded (default)
print(api.get_query_string())

# Unencoded (useful for debugging / reading)
print(api.get_query_string(encode=False))

JS → Python API reference

Side-by-side examples

Simple equality filter

JavaScript

const api = new DrupalJsonApiParams();
api.addFilter('status', '1');
api.getQueryString({ encode: false });
// → filter[status]=1

Python

api = DrupalJsonApiParams()
api.add_filter("status", "1")
api.get_query_string(encode=False)
# → filter[status]=1

IN filter

JavaScript

api.addFilter('uid.name', ['admin', 'john'], 'IN');

Python

api.add_filter("uid.name", ["admin", "john"], "IN")
# or with enum:
api.add_filter("uid.name", ["admin", "john"], FilterOperator.IN)

BETWEEN filter

JavaScript

api.addFilter('changed', ['0', '123456789'], 'BETWEEN');

Python

api.add_filter("changed", ["0", "123456789"], "BETWEEN")

IS NULL filter

JavaScript

api.addFilter('status', null, 'IS NULL');

Python

api.add_filter("status", None, "IS NULL")

Grouped filters

JavaScript

api
  .addGroup('and-group', 'AND')
  .addFilter('uid.name', 'admin', '=', 'and-group')
  .addFilter('status', '1', '=', 'and-group');

Python

(
    api
    .add_group("and-group", "AND")
    .add_filter("uid.name", "admin", "=", "and-group")
    .add_filter("status", "1", "=", "and-group")
)

Round-trip

JavaScript

const qs = api.getQueryString();
api.clear();
api.initializeWithQueryString(qs);

Python

qs = api.get_query_string()
api.clear()
api.initialize_with_query_string(qs)

Custom parameters

JavaScript

api.addCustomParam({ foo: 'bar' })
   .addCustomParam({ foo: { bar: 'baz' } });

Python

api.add_custom_param({"foo": "bar"}).add_custom_param({"foo": {"bar": "baz"}})

Output options (qs compatibility)

The JS library delegates serialization to the qs library and exposes its full options via getQueryString() / setQsOption().

This Python port supports only the two options that are relevant for Drupal JSON:API usage:

Other qs options (e.g. arrayFormat, delimiter, sort, charset) are not supported. The bracket-notation format used by Drupal's JSON:API is always applied.

You can also persist options across calls:

api.set_output_options(encode=False, add_query_prefix=True)
api.get_query_string()  # uses stored options

FilterOperator enum

from drupal_jsonapi_params import FilterOperator

FilterOperator.EQUAL          # "="
FilterOperator.NOT_EQUAL      # "<>"
FilterOperator.GREATER_THAN   # ">"
FilterOperator.LESS_THAN      # "<"
FilterOperator.IN             # "IN"
FilterOperator.NOT_IN         # "NOT IN"
FilterOperator.BETWEEN        # "BETWEEN"
FilterOperator.NOT_BETWEEN    # "NOT BETWEEN"
FilterOperator.IS_NULL        # "IS NULL"
FilterOperator.IS_NOT_NULL    # "IS NOT NULL"
FilterOperator.CONTAINS       # "CONTAINS"
FilterOperator.STARTS_WITH    # "STARTS_WITH"
FilterOperator.ENDS_WITH      # "ENDS_WITH"

Because FilterOperator extends str, you can pass either the enum member or its string value interchangeably:

api.add_filter("title", "Foo", FilterOperator.CONTAINS)
api.add_filter("title", "Foo", "CONTAINS")  # equivalent

Note: FilterOperator.NOT_EQUAL uses "<>", Drupal's canonical not-equal operator. The JS library's test suite uses "!=", but Drupal's JSON:API may reject it — you can pass either string directly if needed.