Query Plan Executor

Apply layered modifications to a query string while preserving insertion order and multi-valued keys. Start from the provided base query, optionally replace it entirely, append additional parameters without losing existing ones, and drop selected keys before encoding the result.

Operations occur in this order: replace the whole query when a reset is provided, append new parameters while expanding list-like inputs into repeated keys, remove specified keys (or everything when asked), then encode using the requested delimiter. Return both the encoded query string and convenient access to a specific key's first and all values.

Capabilities

Append without replacement

• Starting from tag=alpha&tag=beta&sort=asc, applying an append plan of [('tag', 'gamma'), ('filter', 'new'), ('tag', 'delta')] returns tag=alpha&tag=beta&sort=asc&tag=gamma&filter=new&tag=delta when encoded with the default delimiter. It reports the first value for tag as alpha and all values for tag as ['alpha', 'beta', 'gamma', 'delta']. @test

Full reset then append

• Starting from page=2&page=3&lang=en, applying a reset plan of {'lang': 'fr', 'page': ['10', '11']} followed by appending {'extra': 'yes'} returns lang=fr&page=10&page=11&extra=yes. The first value for page becomes 10, and all values for page are ['10', '11']. @test

Drop keys and custom delimiter

• Starting from mode=full&mode=lite&keep=true, appending {'keep': 'false', 'mode': 'debug'} and dropping ['mode'] returns keep=true;keep=false when encoded with the ; delimiter. The first value for mode is None and the list of values for mode is empty. @test

Implementation

@generates

API

from typing import Any, Mapping

Plan = Mapping[str, Any]

def apply_query_plan(base_query: str,
                     plan: Plan,
                     target_key: str,
                     delimiter: str = "&") -> tuple[str, str | None, list[str]]:
    """
    Apply a sequence of operations to a query string.

    The plan supports:
    - 'reset': optional query-like input that replaces the entire query before other steps.
    - 'append': optional query-like input that adds parameters without replacing existing values.
    - 'drop': optional list of keys to remove, or True to clear everything.

    Returns the encoded query string using the requested delimiter, the first value for target_key (or None),
    and the list of all values for target_key in insertion order.
    """

Dependencies { .dependencies }

furl { .dependency }

Provides URL and query manipulation utilities.