httpx-qs

Smart, policy-driven query string merging & encoding for httpx powered by qs-codec.

PyPI version PyPI - Status Supported Python versions PyPy support status PyPI - Format Tests CodeQL License Codecov Codacy Quality GitHub Sponsors GitHub Repo stars Contributor Covenant mypy pylint isort Security Status

Overview

httpx-qs provides:

  • A transport wrapper SmartQueryStrings that merges existing URL query parameters with additional ones supplied via request.extensions.

  • A flexible merge_query utility with selectable conflict resolution policies.

  • Consistent, standards-aware encoding via qs-codec (RFC3986 percent-encoding, structured arrays, nested objects, etc.).

Why?

HTTPX already lets you pass params= when making requests, but sometimes you need to:

  • Inject additional query parameters from middleware/transport layers (e.g., auth tags, tracing IDs, feature flags) without losing the caller’s original intent.

  • Combine repeated keys or treat them deterministically (replace / keep / error) rather than always flattening.

  • Support nested data or list semantics consistent across clients and services.

qs-codec supplies the primitives (decoding & encoding with configurable ListFormat). httpx-qs stitches that into HTTPX’s transport pipeline so you can declaratively extend queries at request dispatch time.

Requirements

  • CPython 3.8-3.14 or PyPy 3.8-3.11

  • httpx>=0.28.1,<1.0.0

  • qs-codec>=1.3.1

Installation

pip install httpx-qs

Minimal Example

import httpx
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings

client = httpx.Client(transport=SmartQueryStrings(httpx.HTTPTransport()))

response = client.get(
    "https://www.google.com",
    params={"a": "b", "c": "d"},
    extensions={"extra_query_params": {"c": "D", "tags": ["x", "y"]}},
)

print(str(response.request.url))
# Example (order may vary): https://www.google.com/?a=b&c=d&c=D&tags=x&tags=y

Contents: