httpx-qs 0.1.0__py3-none-any.whl

httpx_qs/__init__.py

@@ -0,0 +1,14 @@
+"""httpx-qs: A library for smart query string handling with httpx."""
+
+__version__ = "0.1.0"
+
+from .enums.merge_policy import MergePolicy
+from .transporters import smart_query_strings
+from .utils.merge_query import merge_query
+
+
+__all__ = [
+    "smart_query_strings",
+    "MergePolicy",
+    "merge_query",
+]

httpx_qs/enums/merge_policy.py

@@ -0,0 +1,19 @@
+"""Policy that determines how to handle keys that already exist in the query string."""
+
+from enum import Enum
+
+
+class MergePolicy(str, Enum):
+    """Policy that determines how to handle keys that already exist in the query string.
+
+    Values:
+        COMBINE: (default) Combine existing and new values into a list (preserving order: existing then new).
+        REPLACE: Replace existing value with the new one (last-wins).
+        KEEP: Keep the existing value, ignore the new one (first-wins).
+        ERROR: Raise a ValueError if a key collision occurs.
+    """
+
+    COMBINE = "combine"
+    REPLACE = "replace"
+    KEEP = "keep"
+    ERROR = "error"

httpx_qs/transporters/smart_query_strings.py

@@ -0,0 +1,36 @@
+"""A transport that merges extra query params supplied via request.extensions."""
+
+import typing as t
+
+import httpx
+from qs_codec import EncodeOptions, ListFormat
+
+from httpx_qs.utils.merge_query import MergePolicy, merge_query
+
+
+class SmartQueryStrings(httpx.BaseTransport):
+    """A transport that merges extra query params supplied via request.extensions."""
+
+    def __init__(self, next_transport: httpx.BaseTransport) -> None:
+        """Initialize with the next transport in the chain."""
+        self.next_transport = next_transport
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        """Handle the request, merging extra query params if provided."""
+        extra_params: t.Dict[t.Any, t.Any] = request.extensions.get("extra_query_params", {})
+        extra_params_options: t.Optional[EncodeOptions] = request.extensions.get("extra_query_params_options", None)
+        merge_policy: t.Optional[t.Union[MergePolicy, str]] = request.extensions.get("extra_query_params_policy")
+        if extra_params:
+            request.url = httpx.URL(
+                merge_query(
+                    str(request.url),
+                    extra_params,
+                    (
+                        extra_params_options
+                        if extra_params_options is not None
+                        else EncodeOptions(list_format=ListFormat.REPEAT)
+                    ),
+                    policy=merge_policy if merge_policy is not None else MergePolicy.COMBINE,
+                )
+            )
+        return self.next_transport.handle_request(request)

httpx_qs/utils/merge_query.py

@@ -0,0 +1,84 @@
+"""Utility to merge query parameters into a URL's query string.
+
+Provides different merge policies controlling how conflicting keys are handled.
+"""
+
+import typing as t
+from urllib.parse import SplitResult, urlsplit, urlunsplit
+
+from qs_codec import EncodeOptions, ListFormat, decode, encode
+
+from httpx_qs.enums.merge_policy import MergePolicy
+
+
+def _combine(existing_value: t.Any, new_value: t.Any) -> t.List[t.Any]:
+    """Return a combined list ensuring list semantics for multiple values.
+
+    Always returns a list (copy) even if both inputs are scalar values.
+    """
+    left_list: t.List[t.Any]
+    if isinstance(existing_value, list):
+        # slice copy then cast to satisfy type checker
+        left_list = t.cast(t.List[t.Any], existing_value[:])
+    else:
+        left_list = [existing_value]
+
+    right_list: t.List[t.Any]
+    if isinstance(new_value, list):
+        right_list = t.cast(t.List[t.Any], new_value[:])
+    else:
+        right_list = [new_value]
+    # Return a new list (avoid mutating originals if lists)
+    return list(left_list) + list(right_list)
+
+
+def merge_query(
+    url: str,
+    extra: t.Mapping[str, t.Any],
+    options: EncodeOptions = EncodeOptions(list_format=ListFormat.REPEAT),
+    policy: t.Union[MergePolicy, str] = MergePolicy.COMBINE,
+) -> str:
+    """Merge extra query parameters into a URL's existing query string.
+
+    Args:
+        url: The original URL which may contain an existing query string.
+        extra: Mapping of additional query parameters to merge into the URL.
+        options: Optional :class:`qs_codec.EncodeOptions` to customize encoding behavior.
+        policy: Merge policy to apply when a key already exists (``combine`` | ``replace`` | ``keep`` | ``error``).
+    Returns:
+        The URL with the merged query string.
+    Raises:
+        ValueError: If ``policy == 'error'`` and a duplicate key is encountered.
+    """
+    policy_enum: MergePolicy = MergePolicy(policy) if not isinstance(policy, MergePolicy) else policy
+
+    parts: SplitResult = urlsplit(url)
+    existing: t.Dict[str, t.Any] = decode(parts.query) if parts.query else {}
+
+    for k, v in extra.items():
+        if k not in existing:
+            existing[k] = v
+            continue
+
+        # k exists already
+        if policy_enum is MergePolicy.COMBINE:
+            existing[k] = _combine(existing[k], v)
+        elif policy_enum is MergePolicy.REPLACE:
+            existing[k] = v
+        elif policy_enum is MergePolicy.KEEP:
+            # Leave existing value untouched
+            continue
+        elif policy_enum is MergePolicy.ERROR:
+            raise ValueError(f"Duplicate query parameter '{k}' encountered while policy=error")
+        else:  # pragma: no cover - defensive (should not happen due to Enum validation)
+            existing[k] = _combine(existing[k], v)
+
+    return urlunsplit(
+        (
+            parts.scheme,
+            parts.netloc,
+            parts.path,
+            encode(existing, options),
+            parts.fragment,
+        )
+    )

httpx_qs-0.1.0.dist-info/METADATA

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: httpx-qs
+Version: 0.1.0
+Summary: HTTPX transport leveraging qs-codec for advanced query string encoding and decoding.
+Project-URL: Homepage, https://techouse.github.io/httpx_qs/
+Project-URL: Repository, https://github.com/techouse/httpx_qs.git
+Project-URL: Issues, https://github.com/techouse/httpx_qs/issues
+Project-URL: Changelog, https://github.com/techouse/httpx_qs/blob/master/CHANGELOG.md
+Project-URL: Sponsor, https://github.com/sponsors/techouse
+Project-URL: PayPal, https://paypal.me/ktusar
+Author-email: Klemen Tusar <techouse@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: arrays,brackets,codec,form-urlencoded,httpx,nested,percent-encoding,qs,query,query-string,querystring,rfc3986,url,urldecode,urlencode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: qs-codec>=1.2.3
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: toml>=0.10.2; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Description-Content-Type: text/x-rst
+
+httpx-qs
+========
+
+Smart, policy-driven query string merging & encoding for `httpx <https://www.python-httpx.org>`_ powered by
+`qs-codec <https://techouse.github.io/qs_codec/>`_.
+
+.. image:: https://img.shields.io/pypi/v/httpx-qs
+   :target: https://pypi.org/project/httpx-qs/
+   :alt: PyPI version
+
+.. image:: https://img.shields.io/pypi/status/httpx-qs
+   :target: https://pypi.org/project/httpx-qs/
+   :alt: PyPI - Status
+
+.. image:: https://img.shields.io/pypi/pyversions/httpx-qs
+   :target: https://pypi.org/project/httpx-qs/
+   :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/format/httpx-qs
+   :target: https://pypi.org/project/httpx-qs/
+   :alt: PyPI - Format
+
+.. image:: https://github.com/techouse/httpx_qs/actions/workflows/test.yml/badge.svg
+   :target: https://github.com/techouse/httpx_qs/actions/workflows/test.yml
+   :alt: Tests
+
+.. image:: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql/badge.svg
+   :target: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql
+   :alt: CodeQL
+
+.. image:: https://img.shields.io/github/license/techouse/httpx_qs
+   :target: https://github.com/techouse/httpx_qs/blob/master/LICENSE
+   :alt: License
+
+.. image:: https://codecov.io/gh/techouse/httpx_qs/graph/badge.svg?token=JMt8akIZFh
+   :target: https://codecov.io/gh/techouse/httpx_qs
+   :alt: Codecov
+
+.. image:: https://app.codacy.com/project/badge/Grade/420bf66ab90d4b3798573b6ff86d02af
+   :target: https://app.codacy.com/gh/techouse/httpx_qs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
+   :alt: Codacy Quality
+
+.. image:: https://img.shields.io/github/sponsors/techouse
+   :target: https://github.com/sponsors/techouse
+   :alt: GitHub Sponsors
+
+.. image:: https://img.shields.io/github/stars/techouse/qs_codec
+   :target: https://github.com/techouse/qs_codec/stargazers
+   :alt: GitHub Repo stars
+
+.. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
+   :target: CODE-OF-CONDUCT.md
+   :alt: Contributor Covenant
+
+.. |flake8| image:: https://img.shields.io/badge/flake8-checked-blueviolet.svg
+   :target: https://flake8.pycqa.org/en/latest/
+
+.. image:: https://img.shields.io/badge/mypy-checked-blue.svg
+   :target: https://mypy.readthedocs.io/en/stable/
+   :alt: mypy
+
+.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen.svg
+   :target: https://github.com/pylint-dev/pylint
+   :alt: pylint
+
+.. image:: https://img.shields.io/badge/imports-isort-blue.svg
+   :target: https://pycqa.github.io/isort/
+   :alt: isort
+
+.. image:: https://img.shields.io/badge/security-bandit-blue.svg
+   :target: https://github.com/PyCQA/bandit
+   :alt: 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.
+
+Installation
+------------
+
+.. code-block:: bash
+
+	pip install httpx-qs
+
+Minimal Example
+---------------
+
+.. code-block:: python
+
+	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
+
+Using Merge Policies
+--------------------
+
+Conflict resolution when a key already exists is controlled by ``MergePolicy``.
+
+Available policies:
+
+* ``combine`` (default): concatenate values → existing first, new afterward (``a=1&a=2``)
+* ``replace``: last-wins, existing value is overwritten (``a=2``)
+* ``keep``: first-wins, ignore the new value (``a=1``)
+* ``error``: raise ``ValueError`` on duplicate key
+
+Specify per request:
+
+.. code-block:: python
+
+	from httpx_qs import MergePolicy
+
+	r = client.get(
+		"https://api.example.com/resources",
+		params={"dup": "original"},
+		extensions={
+			"extra_query_params": {"dup": "override"},
+			"extra_query_params_policy": MergePolicy.REPLACE,
+		},
+	)
+	# Query contains only dup=override
+
+Async Usage
+-----------
+
+``SmartQueryStrings`` works equally for ``AsyncClient``:
+
+.. code-block:: python
+
+	import httpx
+	from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
+
+	async def main() -> None:
+		async with httpx.AsyncClient(transport=SmartQueryStrings(httpx.AsyncHTTPTransport())) as client:
+			r = await client.get(
+				"https://example.com/items",
+				params={"filters": "active"},
+				extensions={"extra_query_params": {"page": 2}},
+			)
+			print(r.request.url)
+
+	# Run with: asyncio.run(main())
+
+``merge_query`` Utility
+-----------------------
+
+You can use the underlying function directly:
+
+.. code-block:: python
+
+	from httpx_qs import merge_query, MergePolicy
+	from qs_codec import EncodeOptions, ListFormat
+
+	new_url = merge_query(
+		"https://example.com?a=1",
+		{"a": 2, "tags": ["x", "y"]},
+		options=EncodeOptions(list_format=ListFormat.REPEAT),
+		policy=MergePolicy.COMBINE,
+	)
+	# → https://example.com/?a=1&a=2&tags=x&tags=y
+
+Why ``ListFormat.REPEAT`` by Default?
+-------------------------------------
+
+``qs-codec`` exposes several list formatting strategies (e.g. repeat, brackets, indices). ``httpx-qs`` defaults to
+``ListFormat.REPEAT`` because:
+
+* It matches common server expectations (``key=value&key=value``) without requiring bracket parsing logic.
+* It preserves original ordering while remaining unambiguous and simple for log inspection.
+* Many API gateways / proxies / caches reliably forward repeated keys whereas bracket syntaxes can be normalized away.
+
+If your API prefers another convention (e.g. ``tags[]=x&tags[]=y`` or ``tags[0]=x``) just pass a custom ``EncodeOptions`` via
+``extensions['extra_query_params_options']`` or parameter ``options`` when calling ``merge_query`` directly.
+
+Advanced Per-Request Customization
+----------------------------------
+
+.. code-block:: python
+
+	from qs_codec import EncodeOptions, ListFormat
+
+	r = client.get(
+		"https://service.local/search",
+		params={"q": "test"},
+		extensions={
+			"extra_query_params": {"debug": True, "tags": ["alpha", "beta"]},
+			"extra_query_params_policy": "combine",  # also accepts string values
+			"extra_query_params_options": EncodeOptions(list_format=ListFormat.BRACKETS),
+		},
+	)
+	# Example: ?q=test&debug=true&tags[]=alpha&tags[]=beta
+
+Error Policy Example
+--------------------
+
+.. code-block:: python
+
+	try:
+		client.get(
+			"https://example.com",
+			params={"token": "abc"},
+			extensions={
+				"extra_query_params": {"token": "xyz"},
+				"extra_query_params_policy": "error",
+			},
+		)
+	except ValueError as exc:
+		print("Duplicate detected:", exc)
+
+Testing Strategy
+----------------
+
+The project includes unit tests covering policy behaviors, error handling, and transport-level integration. Run them with:
+
+.. code-block:: bash
+
+	pytest
+
+Further Reading
+---------------
+
+* HTTPX documentation: https://www.python-httpx.org
+* qs-codec documentation: https://techouse.github.io/qs_codec/
+
+License
+-------
+
+BSD-3-Clause. See ``LICENSE`` for details.
+
+Contributing
+------------
+
+Issues & PRs welcome. Please add tests for new behavior and keep doc examples in sync.

httpx_qs-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+httpx_qs/__init__.py,sha256=L_QNDEcprD6zfOnzSu2ZRRPRtKE07NzFPR83fr2LdSA,308
+httpx_qs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+httpx_qs/enums/merge_policy.py,sha256=CULesKR01GjBqIuPN7WD_EasvogpIpQy4oTNlbEG9Mg,653
+httpx_qs/transporters/smart_query_strings.py,sha256=d3XKTb2X1Rey3vk1uiWjk4JTKZ5bstbd4NHUw-lXuig,1584
+httpx_qs/utils/merge_query.py,sha256=usOLroZzR0tTFixV2Bh2TzxUz8poqJC_4qBaS9yPhOs,3016
+httpx_qs-0.1.0.dist-info/METADATA,sha256=6mzStJzL6DTnxX78GOTIN_Ewn5qMMKObFiJX9BEqXBo,10237
+httpx_qs-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+httpx_qs-0.1.0.dist-info/licenses/LICENSE,sha256=BGym7TZirVdWajaAWJVsuIt57rdDM8_mmVAzXDerIlY,1498
+httpx_qs-0.1.0.dist-info/RECORD,,

httpx_qs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

httpx_qs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Klemen Tusar
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.