httpx_qs.utils.merge_query module

Utility to merge query parameters into a URL’s query string.

Provides different merge policies controlling how conflicting keys are handled.

httpx_qs.utils.merge_query.merge_query(url: str, extra: ~typing.Mapping[str, ~typing.Any], options: ~qs_codec.models.encode_options.EncodeOptions = EncodeOptions(allow_dots=False, add_query_prefix=False, allow_empty_lists=False, indices=None, list_format=<ListFormat.REPEAT: list_format_name='REPEAT', generator=<function ListFormatGenerator.repeat>>, charset=<Charset.UTF8: encoding='utf-8'>, charset_sentinel=False, delimiter='&', encode=True, encode_dot_in_keys=False, encode_values_only=False, format=<Format.RFC3986: format_name='RFC3986', formatter=<function Formatter.rfc3986>>, filter=None, skip_nulls=False, serialize_date=<function EncodeUtils.serialize_date>, encoder=<function EncodeOptions.encoder.<locals>.<lambda>>, strict_null_handling=False, comma_round_trip=None, comma_compact_nulls=False, sort=None), policy: ~httpx_qs.enums.merge_policy.MergePolicy | str = MergePolicy.COMBINE) → str[source]

Merge extra query parameters into a URL’s existing query string.

Parameters:

  • url – The original URL which may contain an existing query string.

  • extra – Mapping of additional query parameters to merge into the URL.

  • options – Optional 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.