httpx-qs 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of httpx-qs might be problematic. Click here for more details.
- httpx_qs-0.1.0/.gitignore +119 -0
- httpx_qs-0.1.0/CHANGELOG.md +3 -0
- httpx_qs-0.1.0/CODE-OF-CONDUCT.md +132 -0
- httpx_qs-0.1.0/LICENSE +28 -0
- httpx_qs-0.1.0/PKG-INFO +302 -0
- httpx_qs-0.1.0/README.rst +258 -0
- httpx_qs-0.1.0/pyproject.toml +133 -0
- httpx_qs-0.1.0/requirements_dev.txt +9 -0
- httpx_qs-0.1.0/src/httpx_qs/__init__.py +14 -0
- httpx_qs-0.1.0/src/httpx_qs/enums/merge_policy.py +19 -0
- httpx_qs-0.1.0/src/httpx_qs/py.typed +0 -0
- httpx_qs-0.1.0/src/httpx_qs/transporters/smart_query_strings.py +36 -0
- httpx_qs-0.1.0/src/httpx_qs/utils/merge_query.py +84 -0
- httpx_qs-0.1.0/tests/unit/test_merge_query.py +40 -0
- httpx_qs-0.1.0/tests/unit/test_transport.py +81 -0
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.installed.cfg
|
|
25
|
+
*.egg
|
|
26
|
+
MANIFEST
|
|
27
|
+
|
|
28
|
+
# PyInstaller
|
|
29
|
+
# Usually these files are written by a python script from a template
|
|
30
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
31
|
+
*.manifest
|
|
32
|
+
*.spec
|
|
33
|
+
|
|
34
|
+
# Installer logs
|
|
35
|
+
pip-log.txt
|
|
36
|
+
pip-delete-this-directory.txt
|
|
37
|
+
|
|
38
|
+
# Unit test / coverage reports
|
|
39
|
+
htmlcov/
|
|
40
|
+
coverage/
|
|
41
|
+
.tox/
|
|
42
|
+
.coverage
|
|
43
|
+
.coverage.*
|
|
44
|
+
.cache
|
|
45
|
+
nosetests.xml
|
|
46
|
+
coverage.xml
|
|
47
|
+
coverage.lcov
|
|
48
|
+
*.cover
|
|
49
|
+
.hypothesis/
|
|
50
|
+
.pytest_cache/
|
|
51
|
+
|
|
52
|
+
# Translations
|
|
53
|
+
*.mo
|
|
54
|
+
*.pot
|
|
55
|
+
|
|
56
|
+
# Django stuff:
|
|
57
|
+
*.log
|
|
58
|
+
local_settings.py
|
|
59
|
+
db.sqlite3
|
|
60
|
+
|
|
61
|
+
# Flask stuff:
|
|
62
|
+
instance/
|
|
63
|
+
.webassets-cache
|
|
64
|
+
|
|
65
|
+
# Scrapy stuff:
|
|
66
|
+
.scrapy
|
|
67
|
+
|
|
68
|
+
# Sphinx documentation
|
|
69
|
+
docs/_build/
|
|
70
|
+
|
|
71
|
+
# PyBuilder
|
|
72
|
+
target/
|
|
73
|
+
|
|
74
|
+
# Jupyter Notebook
|
|
75
|
+
.ipynb_checkpoints
|
|
76
|
+
|
|
77
|
+
# pyenv
|
|
78
|
+
.python-version
|
|
79
|
+
|
|
80
|
+
# celery beat schedule file
|
|
81
|
+
celerybeat-schedule
|
|
82
|
+
|
|
83
|
+
# SageMath parsed files
|
|
84
|
+
*.sage.py
|
|
85
|
+
|
|
86
|
+
# Environments
|
|
87
|
+
.env
|
|
88
|
+
.venv
|
|
89
|
+
env/
|
|
90
|
+
venv/
|
|
91
|
+
ENV/
|
|
92
|
+
env.bak/
|
|
93
|
+
venv.bak/
|
|
94
|
+
|
|
95
|
+
# Spyder project settings
|
|
96
|
+
.spyderproject
|
|
97
|
+
.spyproject
|
|
98
|
+
|
|
99
|
+
# Rope project settings
|
|
100
|
+
.ropeproject
|
|
101
|
+
|
|
102
|
+
# mkdocs documentation
|
|
103
|
+
/site
|
|
104
|
+
|
|
105
|
+
# mypy
|
|
106
|
+
.mypy_cache/
|
|
107
|
+
|
|
108
|
+
# PyCharm specific files
|
|
109
|
+
.idea
|
|
110
|
+
|
|
111
|
+
# macOS specific
|
|
112
|
+
.DS_Store
|
|
113
|
+
|
|
114
|
+
# AI related
|
|
115
|
+
.junie
|
|
116
|
+
AGENTS.md
|
|
117
|
+
|
|
118
|
+
# History files
|
|
119
|
+
.history
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Contributor Covenant Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Our Pledge
|
|
4
|
+
|
|
5
|
+
We as members, contributors, and leaders pledge to make participation in our
|
|
6
|
+
community a harassment-free experience for everyone, regardless of age, body
|
|
7
|
+
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
|
8
|
+
identity and expression, level of experience, education, socio-economic status,
|
|
9
|
+
nationality, personal appearance, race, caste, color, religion, or sexual identity
|
|
10
|
+
and orientation.
|
|
11
|
+
|
|
12
|
+
We pledge to act and interact in ways that contribute to an open, welcoming,
|
|
13
|
+
diverse, inclusive, and healthy community.
|
|
14
|
+
|
|
15
|
+
## Our Standards
|
|
16
|
+
|
|
17
|
+
Examples of behavior that contributes to a positive environment for our
|
|
18
|
+
community include:
|
|
19
|
+
|
|
20
|
+
* Demonstrating empathy and kindness toward other people
|
|
21
|
+
* Being respectful of differing opinions, viewpoints, and experiences
|
|
22
|
+
* Giving and gracefully accepting constructive feedback
|
|
23
|
+
* Accepting responsibility and apologizing to those affected by our mistakes,
|
|
24
|
+
and learning from the experience
|
|
25
|
+
* Focusing on what is best not just for us as individuals, but for the
|
|
26
|
+
overall community
|
|
27
|
+
|
|
28
|
+
Examples of unacceptable behavior include:
|
|
29
|
+
|
|
30
|
+
* The use of sexualized language or imagery, and sexual attention or
|
|
31
|
+
advances of any kind
|
|
32
|
+
* Trolling, insulting or derogatory comments, and personal or political attacks
|
|
33
|
+
* Public or private harassment
|
|
34
|
+
* Publishing others' private information, such as a physical or email
|
|
35
|
+
address, without their explicit permission
|
|
36
|
+
* Other conduct which could reasonably be considered inappropriate in a
|
|
37
|
+
professional setting
|
|
38
|
+
|
|
39
|
+
## Enforcement Responsibilities
|
|
40
|
+
|
|
41
|
+
Community leaders are responsible for clarifying and enforcing our standards of
|
|
42
|
+
acceptable behavior and will take appropriate and fair corrective action in
|
|
43
|
+
response to any behavior that they deem inappropriate, threatening, offensive,
|
|
44
|
+
or harmful.
|
|
45
|
+
|
|
46
|
+
Community leaders have the right and responsibility to remove, edit, or reject
|
|
47
|
+
comments, commits, code, wiki edits, issues, and other contributions that are
|
|
48
|
+
not aligned to this Code of Conduct, and will communicate reasons for moderation
|
|
49
|
+
decisions when appropriate.
|
|
50
|
+
|
|
51
|
+
## Scope
|
|
52
|
+
|
|
53
|
+
This Code of Conduct applies within all community spaces, and also applies when
|
|
54
|
+
an individual is officially representing the community in public spaces.
|
|
55
|
+
Examples of representing our community include using an official e-mail address,
|
|
56
|
+
posting via an official social media account, or acting as an appointed
|
|
57
|
+
representative at an online or offline event.
|
|
58
|
+
|
|
59
|
+
## Enforcement
|
|
60
|
+
|
|
61
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
62
|
+
reported to the community leaders responsible for enforcement at
|
|
63
|
+
[techouse@gmail.com](mailto:techouse@gmail.com).
|
|
64
|
+
All complaints will be reviewed and investigated promptly and fairly.
|
|
65
|
+
|
|
66
|
+
All community leaders are obligated to respect the privacy and security of the
|
|
67
|
+
reporter of any incident.
|
|
68
|
+
|
|
69
|
+
## Enforcement Guidelines
|
|
70
|
+
|
|
71
|
+
Community leaders will follow these Community Impact Guidelines in determining
|
|
72
|
+
the consequences for any action they deem in violation of this Code of Conduct:
|
|
73
|
+
|
|
74
|
+
### 1. Correction
|
|
75
|
+
|
|
76
|
+
**Community Impact**: Use of inappropriate language or other behavior deemed
|
|
77
|
+
unprofessional or unwelcome in the community.
|
|
78
|
+
|
|
79
|
+
**Consequence**: A private, written warning from community leaders, providing
|
|
80
|
+
clarity around the nature of the violation and an explanation of why the
|
|
81
|
+
behavior was inappropriate. A public apology may be requested.
|
|
82
|
+
|
|
83
|
+
### 2. Warning
|
|
84
|
+
|
|
85
|
+
**Community Impact**: A violation through a single incident or series
|
|
86
|
+
of actions.
|
|
87
|
+
|
|
88
|
+
**Consequence**: A warning with consequences for continued behavior. No
|
|
89
|
+
interaction with the people involved, including unsolicited interaction with
|
|
90
|
+
those enforcing the Code of Conduct, for a specified period of time. This
|
|
91
|
+
includes avoiding interactions in community spaces as well as external channels
|
|
92
|
+
like social media. Violating these terms may lead to a temporary or
|
|
93
|
+
permanent ban.
|
|
94
|
+
|
|
95
|
+
### 3. Temporary Ban
|
|
96
|
+
|
|
97
|
+
**Community Impact**: A serious violation of community standards, including
|
|
98
|
+
sustained inappropriate behavior.
|
|
99
|
+
|
|
100
|
+
**Consequence**: A temporary ban from any sort of interaction or public
|
|
101
|
+
communication with the community for a specified period of time. No public or
|
|
102
|
+
private interaction with the people involved, including unsolicited interaction
|
|
103
|
+
with those enforcing the Code of Conduct, is allowed during this period.
|
|
104
|
+
Violating these terms may lead to a permanent ban.
|
|
105
|
+
|
|
106
|
+
### 4. Permanent Ban
|
|
107
|
+
|
|
108
|
+
**Community Impact**: Demonstrating a pattern of violation of community
|
|
109
|
+
standards, including sustained inappropriate behavior, harassment of an
|
|
110
|
+
individual, or aggression toward or disparagement of classes of individuals.
|
|
111
|
+
|
|
112
|
+
**Consequence**: A permanent ban from any sort of public interaction within
|
|
113
|
+
the community.
|
|
114
|
+
|
|
115
|
+
## Attribution
|
|
116
|
+
|
|
117
|
+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
|
118
|
+
version 2.1, available at
|
|
119
|
+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
|
|
120
|
+
|
|
121
|
+
Community Impact Guidelines were inspired by
|
|
122
|
+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
|
|
123
|
+
|
|
124
|
+
For answers to common questions about this code of conduct, see the FAQ at
|
|
125
|
+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
|
|
126
|
+
at [https://www.contributor-covenant.org/translations][translations].
|
|
127
|
+
|
|
128
|
+
[homepage]: https://www.contributor-covenant.org
|
|
129
|
+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
|
|
130
|
+
[Mozilla CoC]: https://github.com/mozilla/diversity
|
|
131
|
+
[FAQ]: https://www.contributor-covenant.org/faq
|
|
132
|
+
[translations]: https://www.contributor-covenant.org/translations
|
httpx_qs-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025, Klemen Tusar
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
16
|
+
contributors may be used to endorse or promote products derived from
|
|
17
|
+
this software without specific prior written permission.
|
|
18
|
+
|
|
19
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
20
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
21
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
22
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
23
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
24
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
25
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
26
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
27
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
28
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
httpx_qs-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: httpx-qs
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: HTTPX transport leveraging qs-codec for advanced query string encoding and decoding.
|
|
5
|
+
Project-URL: Homepage, https://techouse.github.io/httpx_qs/
|
|
6
|
+
Project-URL: Repository, https://github.com/techouse/httpx_qs.git
|
|
7
|
+
Project-URL: Issues, https://github.com/techouse/httpx_qs/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/techouse/httpx_qs/blob/master/CHANGELOG.md
|
|
9
|
+
Project-URL: Sponsor, https://github.com/sponsors/techouse
|
|
10
|
+
Project-URL: PayPal, https://paypal.me/ktusar
|
|
11
|
+
Author-email: Klemen Tusar <techouse@gmail.com>
|
|
12
|
+
License-Expression: BSD-3-Clause
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: arrays,brackets,codec,form-urlencoded,httpx,nested,percent-encoding,qs,query,query-string,querystring,rfc3986,url,urldecode,urlencode
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Environment :: Web Environment
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: License :: OSI Approved :: BSD License
|
|
19
|
+
Classifier: Operating System :: OS Independent
|
|
20
|
+
Classifier: Programming Language :: Python
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
28
|
+
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
29
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
30
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
31
|
+
Classifier: Typing :: Typed
|
|
32
|
+
Requires-Python: >=3.9
|
|
33
|
+
Requires-Dist: httpx>=0.28.1
|
|
34
|
+
Requires-Dist: qs-codec>=1.2.3
|
|
35
|
+
Provides-Extra: dev
|
|
36
|
+
Requires-Dist: black; extra == 'dev'
|
|
37
|
+
Requires-Dist: isort; extra == 'dev'
|
|
38
|
+
Requires-Dist: mypy>=1.15.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
|
|
40
|
+
Requires-Dist: pytest>=8.3.5; extra == 'dev'
|
|
41
|
+
Requires-Dist: toml>=0.10.2; extra == 'dev'
|
|
42
|
+
Requires-Dist: tox; extra == 'dev'
|
|
43
|
+
Description-Content-Type: text/x-rst
|
|
44
|
+
|
|
45
|
+
httpx-qs
|
|
46
|
+
========
|
|
47
|
+
|
|
48
|
+
Smart, policy-driven query string merging & encoding for `httpx <https://www.python-httpx.org>`_ powered by
|
|
49
|
+
`qs-codec <https://techouse.github.io/qs_codec/>`_.
|
|
50
|
+
|
|
51
|
+
.. image:: https://img.shields.io/pypi/v/httpx-qs
|
|
52
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
53
|
+
:alt: PyPI version
|
|
54
|
+
|
|
55
|
+
.. image:: https://img.shields.io/pypi/status/httpx-qs
|
|
56
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
57
|
+
:alt: PyPI - Status
|
|
58
|
+
|
|
59
|
+
.. image:: https://img.shields.io/pypi/pyversions/httpx-qs
|
|
60
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
61
|
+
:alt: Supported Python versions
|
|
62
|
+
|
|
63
|
+
.. image:: https://img.shields.io/pypi/format/httpx-qs
|
|
64
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
65
|
+
:alt: PyPI - Format
|
|
66
|
+
|
|
67
|
+
.. image:: https://github.com/techouse/httpx_qs/actions/workflows/test.yml/badge.svg
|
|
68
|
+
:target: https://github.com/techouse/httpx_qs/actions/workflows/test.yml
|
|
69
|
+
:alt: Tests
|
|
70
|
+
|
|
71
|
+
.. image:: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql/badge.svg
|
|
72
|
+
:target: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql
|
|
73
|
+
:alt: CodeQL
|
|
74
|
+
|
|
75
|
+
.. image:: https://img.shields.io/github/license/techouse/httpx_qs
|
|
76
|
+
:target: https://github.com/techouse/httpx_qs/blob/master/LICENSE
|
|
77
|
+
:alt: License
|
|
78
|
+
|
|
79
|
+
.. image:: https://codecov.io/gh/techouse/httpx_qs/graph/badge.svg?token=JMt8akIZFh
|
|
80
|
+
:target: https://codecov.io/gh/techouse/httpx_qs
|
|
81
|
+
:alt: Codecov
|
|
82
|
+
|
|
83
|
+
.. image:: https://app.codacy.com/project/badge/Grade/420bf66ab90d4b3798573b6ff86d02af
|
|
84
|
+
:target: https://app.codacy.com/gh/techouse/httpx_qs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
|
|
85
|
+
:alt: Codacy Quality
|
|
86
|
+
|
|
87
|
+
.. image:: https://img.shields.io/github/sponsors/techouse
|
|
88
|
+
:target: https://github.com/sponsors/techouse
|
|
89
|
+
:alt: GitHub Sponsors
|
|
90
|
+
|
|
91
|
+
.. image:: https://img.shields.io/github/stars/techouse/qs_codec
|
|
92
|
+
:target: https://github.com/techouse/qs_codec/stargazers
|
|
93
|
+
:alt: GitHub Repo stars
|
|
94
|
+
|
|
95
|
+
.. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
|
|
96
|
+
:target: CODE-OF-CONDUCT.md
|
|
97
|
+
:alt: Contributor Covenant
|
|
98
|
+
|
|
99
|
+
.. |flake8| image:: https://img.shields.io/badge/flake8-checked-blueviolet.svg
|
|
100
|
+
:target: https://flake8.pycqa.org/en/latest/
|
|
101
|
+
|
|
102
|
+
.. image:: https://img.shields.io/badge/mypy-checked-blue.svg
|
|
103
|
+
:target: https://mypy.readthedocs.io/en/stable/
|
|
104
|
+
:alt: mypy
|
|
105
|
+
|
|
106
|
+
.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen.svg
|
|
107
|
+
:target: https://github.com/pylint-dev/pylint
|
|
108
|
+
:alt: pylint
|
|
109
|
+
|
|
110
|
+
.. image:: https://img.shields.io/badge/imports-isort-blue.svg
|
|
111
|
+
:target: https://pycqa.github.io/isort/
|
|
112
|
+
:alt: isort
|
|
113
|
+
|
|
114
|
+
.. image:: https://img.shields.io/badge/security-bandit-blue.svg
|
|
115
|
+
:target: https://github.com/PyCQA/bandit
|
|
116
|
+
:alt: Security Status
|
|
117
|
+
|
|
118
|
+
Overview
|
|
119
|
+
--------
|
|
120
|
+
|
|
121
|
+
``httpx-qs`` provides:
|
|
122
|
+
|
|
123
|
+
* A transport wrapper ``SmartQueryStrings`` that merges *existing* URL query parameters with *additional* ones supplied via ``request.extensions``.
|
|
124
|
+
* A flexible ``merge_query`` utility with selectable conflict resolution policies.
|
|
125
|
+
* Consistent, standards-aware encoding via ``qs-codec`` (RFC3986 percent-encoding, structured arrays, nested objects, etc.).
|
|
126
|
+
|
|
127
|
+
Why?
|
|
128
|
+
----
|
|
129
|
+
|
|
130
|
+
HTTPX already lets you pass ``params=`` when making requests, but sometimes you need to:
|
|
131
|
+
|
|
132
|
+
* Inject **additional** query parameters from middleware/transport layers (e.g., auth tags, tracing IDs, feature flags) *without losing* the caller's original intent.
|
|
133
|
+
* Combine repeated keys or treat them deterministically (replace / keep / error) rather than always flattening.
|
|
134
|
+
* Support nested data or list semantics consistent across clients and services.
|
|
135
|
+
|
|
136
|
+
``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.
|
|
137
|
+
|
|
138
|
+
Installation
|
|
139
|
+
------------
|
|
140
|
+
|
|
141
|
+
.. code-block:: bash
|
|
142
|
+
|
|
143
|
+
pip install httpx-qs
|
|
144
|
+
|
|
145
|
+
Minimal Example
|
|
146
|
+
---------------
|
|
147
|
+
|
|
148
|
+
.. code-block:: python
|
|
149
|
+
|
|
150
|
+
import httpx
|
|
151
|
+
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
|
|
152
|
+
|
|
153
|
+
client = httpx.Client(transport=SmartQueryStrings(httpx.HTTPTransport()))
|
|
154
|
+
|
|
155
|
+
response = client.get(
|
|
156
|
+
"https://www.google.com",
|
|
157
|
+
params={"a": "b", "c": "d"},
|
|
158
|
+
extensions={"extra_query_params": {"c": "D", "tags": ["x", "y"]}},
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
print(str(response.request.url))
|
|
162
|
+
# Example (order may vary): https://www.google.com/?a=b&c=d&c=D&tags=x&tags=y
|
|
163
|
+
|
|
164
|
+
Using Merge Policies
|
|
165
|
+
--------------------
|
|
166
|
+
|
|
167
|
+
Conflict resolution when a key already exists is controlled by ``MergePolicy``.
|
|
168
|
+
|
|
169
|
+
Available policies:
|
|
170
|
+
|
|
171
|
+
* ``combine`` (default): concatenate values → existing first, new afterward (``a=1&a=2``)
|
|
172
|
+
* ``replace``: last-wins, existing value is overwritten (``a=2``)
|
|
173
|
+
* ``keep``: first-wins, ignore the new value (``a=1``)
|
|
174
|
+
* ``error``: raise ``ValueError`` on duplicate key
|
|
175
|
+
|
|
176
|
+
Specify per request:
|
|
177
|
+
|
|
178
|
+
.. code-block:: python
|
|
179
|
+
|
|
180
|
+
from httpx_qs import MergePolicy
|
|
181
|
+
|
|
182
|
+
r = client.get(
|
|
183
|
+
"https://api.example.com/resources",
|
|
184
|
+
params={"dup": "original"},
|
|
185
|
+
extensions={
|
|
186
|
+
"extra_query_params": {"dup": "override"},
|
|
187
|
+
"extra_query_params_policy": MergePolicy.REPLACE,
|
|
188
|
+
},
|
|
189
|
+
)
|
|
190
|
+
# Query contains only dup=override
|
|
191
|
+
|
|
192
|
+
Async Usage
|
|
193
|
+
-----------
|
|
194
|
+
|
|
195
|
+
``SmartQueryStrings`` works equally for ``AsyncClient``:
|
|
196
|
+
|
|
197
|
+
.. code-block:: python
|
|
198
|
+
|
|
199
|
+
import httpx
|
|
200
|
+
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
|
|
201
|
+
|
|
202
|
+
async def main() -> None:
|
|
203
|
+
async with httpx.AsyncClient(transport=SmartQueryStrings(httpx.AsyncHTTPTransport())) as client:
|
|
204
|
+
r = await client.get(
|
|
205
|
+
"https://example.com/items",
|
|
206
|
+
params={"filters": "active"},
|
|
207
|
+
extensions={"extra_query_params": {"page": 2}},
|
|
208
|
+
)
|
|
209
|
+
print(r.request.url)
|
|
210
|
+
|
|
211
|
+
# Run with: asyncio.run(main())
|
|
212
|
+
|
|
213
|
+
``merge_query`` Utility
|
|
214
|
+
-----------------------
|
|
215
|
+
|
|
216
|
+
You can use the underlying function directly:
|
|
217
|
+
|
|
218
|
+
.. code-block:: python
|
|
219
|
+
|
|
220
|
+
from httpx_qs import merge_query, MergePolicy
|
|
221
|
+
from qs_codec import EncodeOptions, ListFormat
|
|
222
|
+
|
|
223
|
+
new_url = merge_query(
|
|
224
|
+
"https://example.com?a=1",
|
|
225
|
+
{"a": 2, "tags": ["x", "y"]},
|
|
226
|
+
options=EncodeOptions(list_format=ListFormat.REPEAT),
|
|
227
|
+
policy=MergePolicy.COMBINE,
|
|
228
|
+
)
|
|
229
|
+
# → https://example.com/?a=1&a=2&tags=x&tags=y
|
|
230
|
+
|
|
231
|
+
Why ``ListFormat.REPEAT`` by Default?
|
|
232
|
+
-------------------------------------
|
|
233
|
+
|
|
234
|
+
``qs-codec`` exposes several list formatting strategies (e.g. repeat, brackets, indices). ``httpx-qs`` defaults to
|
|
235
|
+
``ListFormat.REPEAT`` because:
|
|
236
|
+
|
|
237
|
+
* It matches common server expectations (``key=value&key=value``) without requiring bracket parsing logic.
|
|
238
|
+
* It preserves original ordering while remaining unambiguous and simple for log inspection.
|
|
239
|
+
* Many API gateways / proxies / caches reliably forward repeated keys whereas bracket syntaxes can be normalized away.
|
|
240
|
+
|
|
241
|
+
If your API prefers another convention (e.g. ``tags[]=x&tags[]=y`` or ``tags[0]=x``) just pass a custom ``EncodeOptions`` via
|
|
242
|
+
``extensions['extra_query_params_options']`` or parameter ``options`` when calling ``merge_query`` directly.
|
|
243
|
+
|
|
244
|
+
Advanced Per-Request Customization
|
|
245
|
+
----------------------------------
|
|
246
|
+
|
|
247
|
+
.. code-block:: python
|
|
248
|
+
|
|
249
|
+
from qs_codec import EncodeOptions, ListFormat
|
|
250
|
+
|
|
251
|
+
r = client.get(
|
|
252
|
+
"https://service.local/search",
|
|
253
|
+
params={"q": "test"},
|
|
254
|
+
extensions={
|
|
255
|
+
"extra_query_params": {"debug": True, "tags": ["alpha", "beta"]},
|
|
256
|
+
"extra_query_params_policy": "combine", # also accepts string values
|
|
257
|
+
"extra_query_params_options": EncodeOptions(list_format=ListFormat.BRACKETS),
|
|
258
|
+
},
|
|
259
|
+
)
|
|
260
|
+
# Example: ?q=test&debug=true&tags[]=alpha&tags[]=beta
|
|
261
|
+
|
|
262
|
+
Error Policy Example
|
|
263
|
+
--------------------
|
|
264
|
+
|
|
265
|
+
.. code-block:: python
|
|
266
|
+
|
|
267
|
+
try:
|
|
268
|
+
client.get(
|
|
269
|
+
"https://example.com",
|
|
270
|
+
params={"token": "abc"},
|
|
271
|
+
extensions={
|
|
272
|
+
"extra_query_params": {"token": "xyz"},
|
|
273
|
+
"extra_query_params_policy": "error",
|
|
274
|
+
},
|
|
275
|
+
)
|
|
276
|
+
except ValueError as exc:
|
|
277
|
+
print("Duplicate detected:", exc)
|
|
278
|
+
|
|
279
|
+
Testing Strategy
|
|
280
|
+
----------------
|
|
281
|
+
|
|
282
|
+
The project includes unit tests covering policy behaviors, error handling, and transport-level integration. Run them with:
|
|
283
|
+
|
|
284
|
+
.. code-block:: bash
|
|
285
|
+
|
|
286
|
+
pytest
|
|
287
|
+
|
|
288
|
+
Further Reading
|
|
289
|
+
---------------
|
|
290
|
+
|
|
291
|
+
* HTTPX documentation: https://www.python-httpx.org
|
|
292
|
+
* qs-codec documentation: https://techouse.github.io/qs_codec/
|
|
293
|
+
|
|
294
|
+
License
|
|
295
|
+
-------
|
|
296
|
+
|
|
297
|
+
BSD-3-Clause. See ``LICENSE`` for details.
|
|
298
|
+
|
|
299
|
+
Contributing
|
|
300
|
+
------------
|
|
301
|
+
|
|
302
|
+
Issues & PRs welcome. Please add tests for new behavior and keep doc examples in sync.
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
httpx-qs
|
|
2
|
+
========
|
|
3
|
+
|
|
4
|
+
Smart, policy-driven query string merging & encoding for `httpx <https://www.python-httpx.org>`_ powered by
|
|
5
|
+
`qs-codec <https://techouse.github.io/qs_codec/>`_.
|
|
6
|
+
|
|
7
|
+
.. image:: https://img.shields.io/pypi/v/httpx-qs
|
|
8
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
9
|
+
:alt: PyPI version
|
|
10
|
+
|
|
11
|
+
.. image:: https://img.shields.io/pypi/status/httpx-qs
|
|
12
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
13
|
+
:alt: PyPI - Status
|
|
14
|
+
|
|
15
|
+
.. image:: https://img.shields.io/pypi/pyversions/httpx-qs
|
|
16
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
17
|
+
:alt: Supported Python versions
|
|
18
|
+
|
|
19
|
+
.. image:: https://img.shields.io/pypi/format/httpx-qs
|
|
20
|
+
:target: https://pypi.org/project/httpx-qs/
|
|
21
|
+
:alt: PyPI - Format
|
|
22
|
+
|
|
23
|
+
.. image:: https://github.com/techouse/httpx_qs/actions/workflows/test.yml/badge.svg
|
|
24
|
+
:target: https://github.com/techouse/httpx_qs/actions/workflows/test.yml
|
|
25
|
+
:alt: Tests
|
|
26
|
+
|
|
27
|
+
.. image:: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql/badge.svg
|
|
28
|
+
:target: https://github.com/techouse/httpx_qs/actions/workflows/github-code-scanning/codeql
|
|
29
|
+
:alt: CodeQL
|
|
30
|
+
|
|
31
|
+
.. image:: https://img.shields.io/github/license/techouse/httpx_qs
|
|
32
|
+
:target: https://github.com/techouse/httpx_qs/blob/master/LICENSE
|
|
33
|
+
:alt: License
|
|
34
|
+
|
|
35
|
+
.. image:: https://codecov.io/gh/techouse/httpx_qs/graph/badge.svg?token=JMt8akIZFh
|
|
36
|
+
:target: https://codecov.io/gh/techouse/httpx_qs
|
|
37
|
+
:alt: Codecov
|
|
38
|
+
|
|
39
|
+
.. image:: https://app.codacy.com/project/badge/Grade/420bf66ab90d4b3798573b6ff86d02af
|
|
40
|
+
:target: https://app.codacy.com/gh/techouse/httpx_qs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
|
|
41
|
+
:alt: Codacy Quality
|
|
42
|
+
|
|
43
|
+
.. image:: https://img.shields.io/github/sponsors/techouse
|
|
44
|
+
:target: https://github.com/sponsors/techouse
|
|
45
|
+
:alt: GitHub Sponsors
|
|
46
|
+
|
|
47
|
+
.. image:: https://img.shields.io/github/stars/techouse/qs_codec
|
|
48
|
+
:target: https://github.com/techouse/qs_codec/stargazers
|
|
49
|
+
:alt: GitHub Repo stars
|
|
50
|
+
|
|
51
|
+
.. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
|
|
52
|
+
:target: CODE-OF-CONDUCT.md
|
|
53
|
+
:alt: Contributor Covenant
|
|
54
|
+
|
|
55
|
+
.. |flake8| image:: https://img.shields.io/badge/flake8-checked-blueviolet.svg
|
|
56
|
+
:target: https://flake8.pycqa.org/en/latest/
|
|
57
|
+
|
|
58
|
+
.. image:: https://img.shields.io/badge/mypy-checked-blue.svg
|
|
59
|
+
:target: https://mypy.readthedocs.io/en/stable/
|
|
60
|
+
:alt: mypy
|
|
61
|
+
|
|
62
|
+
.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen.svg
|
|
63
|
+
:target: https://github.com/pylint-dev/pylint
|
|
64
|
+
:alt: pylint
|
|
65
|
+
|
|
66
|
+
.. image:: https://img.shields.io/badge/imports-isort-blue.svg
|
|
67
|
+
:target: https://pycqa.github.io/isort/
|
|
68
|
+
:alt: isort
|
|
69
|
+
|
|
70
|
+
.. image:: https://img.shields.io/badge/security-bandit-blue.svg
|
|
71
|
+
:target: https://github.com/PyCQA/bandit
|
|
72
|
+
:alt: Security Status
|
|
73
|
+
|
|
74
|
+
Overview
|
|
75
|
+
--------
|
|
76
|
+
|
|
77
|
+
``httpx-qs`` provides:
|
|
78
|
+
|
|
79
|
+
* A transport wrapper ``SmartQueryStrings`` that merges *existing* URL query parameters with *additional* ones supplied via ``request.extensions``.
|
|
80
|
+
* A flexible ``merge_query`` utility with selectable conflict resolution policies.
|
|
81
|
+
* Consistent, standards-aware encoding via ``qs-codec`` (RFC3986 percent-encoding, structured arrays, nested objects, etc.).
|
|
82
|
+
|
|
83
|
+
Why?
|
|
84
|
+
----
|
|
85
|
+
|
|
86
|
+
HTTPX already lets you pass ``params=`` when making requests, but sometimes you need to:
|
|
87
|
+
|
|
88
|
+
* Inject **additional** query parameters from middleware/transport layers (e.g., auth tags, tracing IDs, feature flags) *without losing* the caller's original intent.
|
|
89
|
+
* Combine repeated keys or treat them deterministically (replace / keep / error) rather than always flattening.
|
|
90
|
+
* Support nested data or list semantics consistent across clients and services.
|
|
91
|
+
|
|
92
|
+
``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.
|
|
93
|
+
|
|
94
|
+
Installation
|
|
95
|
+
------------
|
|
96
|
+
|
|
97
|
+
.. code-block:: bash
|
|
98
|
+
|
|
99
|
+
pip install httpx-qs
|
|
100
|
+
|
|
101
|
+
Minimal Example
|
|
102
|
+
---------------
|
|
103
|
+
|
|
104
|
+
.. code-block:: python
|
|
105
|
+
|
|
106
|
+
import httpx
|
|
107
|
+
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
|
|
108
|
+
|
|
109
|
+
client = httpx.Client(transport=SmartQueryStrings(httpx.HTTPTransport()))
|
|
110
|
+
|
|
111
|
+
response = client.get(
|
|
112
|
+
"https://www.google.com",
|
|
113
|
+
params={"a": "b", "c": "d"},
|
|
114
|
+
extensions={"extra_query_params": {"c": "D", "tags": ["x", "y"]}},
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
print(str(response.request.url))
|
|
118
|
+
# Example (order may vary): https://www.google.com/?a=b&c=d&c=D&tags=x&tags=y
|
|
119
|
+
|
|
120
|
+
Using Merge Policies
|
|
121
|
+
--------------------
|
|
122
|
+
|
|
123
|
+
Conflict resolution when a key already exists is controlled by ``MergePolicy``.
|
|
124
|
+
|
|
125
|
+
Available policies:
|
|
126
|
+
|
|
127
|
+
* ``combine`` (default): concatenate values → existing first, new afterward (``a=1&a=2``)
|
|
128
|
+
* ``replace``: last-wins, existing value is overwritten (``a=2``)
|
|
129
|
+
* ``keep``: first-wins, ignore the new value (``a=1``)
|
|
130
|
+
* ``error``: raise ``ValueError`` on duplicate key
|
|
131
|
+
|
|
132
|
+
Specify per request:
|
|
133
|
+
|
|
134
|
+
.. code-block:: python
|
|
135
|
+
|
|
136
|
+
from httpx_qs import MergePolicy
|
|
137
|
+
|
|
138
|
+
r = client.get(
|
|
139
|
+
"https://api.example.com/resources",
|
|
140
|
+
params={"dup": "original"},
|
|
141
|
+
extensions={
|
|
142
|
+
"extra_query_params": {"dup": "override"},
|
|
143
|
+
"extra_query_params_policy": MergePolicy.REPLACE,
|
|
144
|
+
},
|
|
145
|
+
)
|
|
146
|
+
# Query contains only dup=override
|
|
147
|
+
|
|
148
|
+
Async Usage
|
|
149
|
+
-----------
|
|
150
|
+
|
|
151
|
+
``SmartQueryStrings`` works equally for ``AsyncClient``:
|
|
152
|
+
|
|
153
|
+
.. code-block:: python
|
|
154
|
+
|
|
155
|
+
import httpx
|
|
156
|
+
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
|
|
157
|
+
|
|
158
|
+
async def main() -> None:
|
|
159
|
+
async with httpx.AsyncClient(transport=SmartQueryStrings(httpx.AsyncHTTPTransport())) as client:
|
|
160
|
+
r = await client.get(
|
|
161
|
+
"https://example.com/items",
|
|
162
|
+
params={"filters": "active"},
|
|
163
|
+
extensions={"extra_query_params": {"page": 2}},
|
|
164
|
+
)
|
|
165
|
+
print(r.request.url)
|
|
166
|
+
|
|
167
|
+
# Run with: asyncio.run(main())
|
|
168
|
+
|
|
169
|
+
``merge_query`` Utility
|
|
170
|
+
-----------------------
|
|
171
|
+
|
|
172
|
+
You can use the underlying function directly:
|
|
173
|
+
|
|
174
|
+
.. code-block:: python
|
|
175
|
+
|
|
176
|
+
from httpx_qs import merge_query, MergePolicy
|
|
177
|
+
from qs_codec import EncodeOptions, ListFormat
|
|
178
|
+
|
|
179
|
+
new_url = merge_query(
|
|
180
|
+
"https://example.com?a=1",
|
|
181
|
+
{"a": 2, "tags": ["x", "y"]},
|
|
182
|
+
options=EncodeOptions(list_format=ListFormat.REPEAT),
|
|
183
|
+
policy=MergePolicy.COMBINE,
|
|
184
|
+
)
|
|
185
|
+
# → https://example.com/?a=1&a=2&tags=x&tags=y
|
|
186
|
+
|
|
187
|
+
Why ``ListFormat.REPEAT`` by Default?
|
|
188
|
+
-------------------------------------
|
|
189
|
+
|
|
190
|
+
``qs-codec`` exposes several list formatting strategies (e.g. repeat, brackets, indices). ``httpx-qs`` defaults to
|
|
191
|
+
``ListFormat.REPEAT`` because:
|
|
192
|
+
|
|
193
|
+
* It matches common server expectations (``key=value&key=value``) without requiring bracket parsing logic.
|
|
194
|
+
* It preserves original ordering while remaining unambiguous and simple for log inspection.
|
|
195
|
+
* Many API gateways / proxies / caches reliably forward repeated keys whereas bracket syntaxes can be normalized away.
|
|
196
|
+
|
|
197
|
+
If your API prefers another convention (e.g. ``tags[]=x&tags[]=y`` or ``tags[0]=x``) just pass a custom ``EncodeOptions`` via
|
|
198
|
+
``extensions['extra_query_params_options']`` or parameter ``options`` when calling ``merge_query`` directly.
|
|
199
|
+
|
|
200
|
+
Advanced Per-Request Customization
|
|
201
|
+
----------------------------------
|
|
202
|
+
|
|
203
|
+
.. code-block:: python
|
|
204
|
+
|
|
205
|
+
from qs_codec import EncodeOptions, ListFormat
|
|
206
|
+
|
|
207
|
+
r = client.get(
|
|
208
|
+
"https://service.local/search",
|
|
209
|
+
params={"q": "test"},
|
|
210
|
+
extensions={
|
|
211
|
+
"extra_query_params": {"debug": True, "tags": ["alpha", "beta"]},
|
|
212
|
+
"extra_query_params_policy": "combine", # also accepts string values
|
|
213
|
+
"extra_query_params_options": EncodeOptions(list_format=ListFormat.BRACKETS),
|
|
214
|
+
},
|
|
215
|
+
)
|
|
216
|
+
# Example: ?q=test&debug=true&tags[]=alpha&tags[]=beta
|
|
217
|
+
|
|
218
|
+
Error Policy Example
|
|
219
|
+
--------------------
|
|
220
|
+
|
|
221
|
+
.. code-block:: python
|
|
222
|
+
|
|
223
|
+
try:
|
|
224
|
+
client.get(
|
|
225
|
+
"https://example.com",
|
|
226
|
+
params={"token": "abc"},
|
|
227
|
+
extensions={
|
|
228
|
+
"extra_query_params": {"token": "xyz"},
|
|
229
|
+
"extra_query_params_policy": "error",
|
|
230
|
+
},
|
|
231
|
+
)
|
|
232
|
+
except ValueError as exc:
|
|
233
|
+
print("Duplicate detected:", exc)
|
|
234
|
+
|
|
235
|
+
Testing Strategy
|
|
236
|
+
----------------
|
|
237
|
+
|
|
238
|
+
The project includes unit tests covering policy behaviors, error handling, and transport-level integration. Run them with:
|
|
239
|
+
|
|
240
|
+
.. code-block:: bash
|
|
241
|
+
|
|
242
|
+
pytest
|
|
243
|
+
|
|
244
|
+
Further Reading
|
|
245
|
+
---------------
|
|
246
|
+
|
|
247
|
+
* HTTPX documentation: https://www.python-httpx.org
|
|
248
|
+
* qs-codec documentation: https://techouse.github.io/qs_codec/
|
|
249
|
+
|
|
250
|
+
License
|
|
251
|
+
-------
|
|
252
|
+
|
|
253
|
+
BSD-3-Clause. See ``LICENSE`` for details.
|
|
254
|
+
|
|
255
|
+
Contributing
|
|
256
|
+
------------
|
|
257
|
+
|
|
258
|
+
Issues & PRs welcome. Please add tests for new behavior and keep doc examples in sync.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "httpx-qs"
|
|
7
|
+
description = "HTTPX transport leveraging qs-codec for advanced query string encoding and decoding."
|
|
8
|
+
readme = { file = "README.rst", content-type = "text/x-rst" }
|
|
9
|
+
license = "BSD-3-Clause"
|
|
10
|
+
license-files = ["LICENSE"]
|
|
11
|
+
requires-python = ">=3.9"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Klemen Tusar", email = "techouse@gmail.com" },
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"httpx", "qs", "codec", "url", "query", "querystring", "query-string",
|
|
17
|
+
"urlencode", "urldecode", "form-urlencoded", "percent-encoding",
|
|
18
|
+
"rfc3986", "arrays", "nested", "brackets"
|
|
19
|
+
]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 3 - Alpha",
|
|
22
|
+
"Environment :: Web Environment",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"License :: OSI Approved :: BSD License",
|
|
25
|
+
"Operating System :: OS Independent",
|
|
26
|
+
"Programming Language :: Python",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3.9",
|
|
29
|
+
"Programming Language :: Python :: 3.10",
|
|
30
|
+
"Programming Language :: Python :: 3.11",
|
|
31
|
+
"Programming Language :: Python :: 3.12",
|
|
32
|
+
"Programming Language :: Python :: 3.13",
|
|
33
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
34
|
+
"Programming Language :: Python :: Implementation :: CPython",
|
|
35
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
36
|
+
"Topic :: Software Development :: Libraries",
|
|
37
|
+
"Typing :: Typed",
|
|
38
|
+
]
|
|
39
|
+
dependencies = [
|
|
40
|
+
"httpx>=0.28.1",
|
|
41
|
+
"qs-codec>=1.2.3",
|
|
42
|
+
]
|
|
43
|
+
dynamic = ["version"]
|
|
44
|
+
|
|
45
|
+
[project.urls]
|
|
46
|
+
Homepage = "https://techouse.github.io/httpx_qs/"
|
|
47
|
+
Repository = "https://github.com/techouse/httpx_qs.git"
|
|
48
|
+
Issues = "https://github.com/techouse/httpx_qs/issues"
|
|
49
|
+
Changelog = "https://github.com/techouse/httpx_qs/blob/master/CHANGELOG.md"
|
|
50
|
+
Sponsor = "https://github.com/sponsors/techouse"
|
|
51
|
+
PayPal = "https://paypal.me/ktusar"
|
|
52
|
+
|
|
53
|
+
[project.optional-dependencies]
|
|
54
|
+
dev = [
|
|
55
|
+
"pytest>=8.3.5",
|
|
56
|
+
"pytest-cov>=6.0.0",
|
|
57
|
+
"mypy>=1.15.0",
|
|
58
|
+
"toml>=0.10.2",
|
|
59
|
+
"tox",
|
|
60
|
+
"black",
|
|
61
|
+
"isort"
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[tool.hatch.version]
|
|
65
|
+
path = "src/httpx_qs/__init__.py"
|
|
66
|
+
|
|
67
|
+
[tool.hatch.build.targets.sdist]
|
|
68
|
+
include = [
|
|
69
|
+
"src",
|
|
70
|
+
"tests",
|
|
71
|
+
"README.rst",
|
|
72
|
+
"CHANGELOG.md",
|
|
73
|
+
"CODE-OF-CONDUCT.md",
|
|
74
|
+
"LICENSE",
|
|
75
|
+
"requirements_dev.txt",
|
|
76
|
+
]
|
|
77
|
+
|
|
78
|
+
[tool.hatch.build.targets.wheel]
|
|
79
|
+
packages = ["src/httpx_qs"]
|
|
80
|
+
include = ["src/httpx_qs/py.typed"]
|
|
81
|
+
|
|
82
|
+
[tool.black]
|
|
83
|
+
line-length = 120
|
|
84
|
+
target-version = ["py39", "py310", "py311", "py312", "py313"]
|
|
85
|
+
include = '\.pyi?$'
|
|
86
|
+
exclude = '''
|
|
87
|
+
(
|
|
88
|
+
/(
|
|
89
|
+
\.eggs
|
|
90
|
+
| \.git
|
|
91
|
+
| \.hg
|
|
92
|
+
| \.mypy_cache
|
|
93
|
+
| \.tox
|
|
94
|
+
| \.venv
|
|
95
|
+
| _build
|
|
96
|
+
| buck-out
|
|
97
|
+
| build
|
|
98
|
+
| dist
|
|
99
|
+
| docs
|
|
100
|
+
)/
|
|
101
|
+
| foo.py
|
|
102
|
+
)
|
|
103
|
+
'''
|
|
104
|
+
|
|
105
|
+
[tool.isort]
|
|
106
|
+
line_length = 120
|
|
107
|
+
profile = "black"
|
|
108
|
+
lines_after_imports = 2
|
|
109
|
+
known_first_party = "httpx_qs"
|
|
110
|
+
skip_gitignore = true
|
|
111
|
+
|
|
112
|
+
[tool.pytest.ini_options]
|
|
113
|
+
pythonpath = ["src"]
|
|
114
|
+
testpaths = ["tests"]
|
|
115
|
+
norecursedirs = [".*", "venv", "env", "*.egg", "dist", "build"]
|
|
116
|
+
minversion = "8.1.1"
|
|
117
|
+
addopts = "-rsxX -l --tb=short --strict-markers"
|
|
118
|
+
markers = []
|
|
119
|
+
|
|
120
|
+
[tool.mypy]
|
|
121
|
+
mypy_path = "src"
|
|
122
|
+
python_version = "3.9"
|
|
123
|
+
exclude = [
|
|
124
|
+
"tests",
|
|
125
|
+
"docs",
|
|
126
|
+
"build",
|
|
127
|
+
"dist",
|
|
128
|
+
"venv",
|
|
129
|
+
"env",
|
|
130
|
+
]
|
|
131
|
+
show_error_codes = true
|
|
132
|
+
warn_return_any = true
|
|
133
|
+
warn_unused_configs = true
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""httpx-qs: A library for smart query string handling with httpx."""
|
|
2
|
+
|
|
3
|
+
__version__ = "0.1.0"
|
|
4
|
+
|
|
5
|
+
from .enums.merge_policy import MergePolicy
|
|
6
|
+
from .transporters import smart_query_strings
|
|
7
|
+
from .utils.merge_query import merge_query
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"smart_query_strings",
|
|
12
|
+
"MergePolicy",
|
|
13
|
+
"merge_query",
|
|
14
|
+
]
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Policy that determines how to handle keys that already exist in the query string."""
|
|
2
|
+
|
|
3
|
+
from enum import Enum
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class MergePolicy(str, Enum):
|
|
7
|
+
"""Policy that determines how to handle keys that already exist in the query string.
|
|
8
|
+
|
|
9
|
+
Values:
|
|
10
|
+
COMBINE: (default) Combine existing and new values into a list (preserving order: existing then new).
|
|
11
|
+
REPLACE: Replace existing value with the new one (last-wins).
|
|
12
|
+
KEEP: Keep the existing value, ignore the new one (first-wins).
|
|
13
|
+
ERROR: Raise a ValueError if a key collision occurs.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
COMBINE = "combine"
|
|
17
|
+
REPLACE = "replace"
|
|
18
|
+
KEEP = "keep"
|
|
19
|
+
ERROR = "error"
|
|
File without changes
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""A transport that merges extra query params supplied via request.extensions."""
|
|
2
|
+
|
|
3
|
+
import typing as t
|
|
4
|
+
|
|
5
|
+
import httpx
|
|
6
|
+
from qs_codec import EncodeOptions, ListFormat
|
|
7
|
+
|
|
8
|
+
from httpx_qs.utils.merge_query import MergePolicy, merge_query
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class SmartQueryStrings(httpx.BaseTransport):
|
|
12
|
+
"""A transport that merges extra query params supplied via request.extensions."""
|
|
13
|
+
|
|
14
|
+
def __init__(self, next_transport: httpx.BaseTransport) -> None:
|
|
15
|
+
"""Initialize with the next transport in the chain."""
|
|
16
|
+
self.next_transport = next_transport
|
|
17
|
+
|
|
18
|
+
def handle_request(self, request: httpx.Request) -> httpx.Response:
|
|
19
|
+
"""Handle the request, merging extra query params if provided."""
|
|
20
|
+
extra_params: t.Dict[t.Any, t.Any] = request.extensions.get("extra_query_params", {})
|
|
21
|
+
extra_params_options: t.Optional[EncodeOptions] = request.extensions.get("extra_query_params_options", None)
|
|
22
|
+
merge_policy: t.Optional[t.Union[MergePolicy, str]] = request.extensions.get("extra_query_params_policy")
|
|
23
|
+
if extra_params:
|
|
24
|
+
request.url = httpx.URL(
|
|
25
|
+
merge_query(
|
|
26
|
+
str(request.url),
|
|
27
|
+
extra_params,
|
|
28
|
+
(
|
|
29
|
+
extra_params_options
|
|
30
|
+
if extra_params_options is not None
|
|
31
|
+
else EncodeOptions(list_format=ListFormat.REPEAT)
|
|
32
|
+
),
|
|
33
|
+
policy=merge_policy if merge_policy is not None else MergePolicy.COMBINE,
|
|
34
|
+
)
|
|
35
|
+
)
|
|
36
|
+
return self.next_transport.handle_request(request)
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
"""Utility to merge query parameters into a URL's query string.
|
|
2
|
+
|
|
3
|
+
Provides different merge policies controlling how conflicting keys are handled.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import typing as t
|
|
7
|
+
from urllib.parse import SplitResult, urlsplit, urlunsplit
|
|
8
|
+
|
|
9
|
+
from qs_codec import EncodeOptions, ListFormat, decode, encode
|
|
10
|
+
|
|
11
|
+
from httpx_qs.enums.merge_policy import MergePolicy
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _combine(existing_value: t.Any, new_value: t.Any) -> t.List[t.Any]:
|
|
15
|
+
"""Return a combined list ensuring list semantics for multiple values.
|
|
16
|
+
|
|
17
|
+
Always returns a list (copy) even if both inputs are scalar values.
|
|
18
|
+
"""
|
|
19
|
+
left_list: t.List[t.Any]
|
|
20
|
+
if isinstance(existing_value, list):
|
|
21
|
+
# slice copy then cast to satisfy type checker
|
|
22
|
+
left_list = t.cast(t.List[t.Any], existing_value[:])
|
|
23
|
+
else:
|
|
24
|
+
left_list = [existing_value]
|
|
25
|
+
|
|
26
|
+
right_list: t.List[t.Any]
|
|
27
|
+
if isinstance(new_value, list):
|
|
28
|
+
right_list = t.cast(t.List[t.Any], new_value[:])
|
|
29
|
+
else:
|
|
30
|
+
right_list = [new_value]
|
|
31
|
+
# Return a new list (avoid mutating originals if lists)
|
|
32
|
+
return list(left_list) + list(right_list)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def merge_query(
|
|
36
|
+
url: str,
|
|
37
|
+
extra: t.Mapping[str, t.Any],
|
|
38
|
+
options: EncodeOptions = EncodeOptions(list_format=ListFormat.REPEAT),
|
|
39
|
+
policy: t.Union[MergePolicy, str] = MergePolicy.COMBINE,
|
|
40
|
+
) -> str:
|
|
41
|
+
"""Merge extra query parameters into a URL's existing query string.
|
|
42
|
+
|
|
43
|
+
Args:
|
|
44
|
+
url: The original URL which may contain an existing query string.
|
|
45
|
+
extra: Mapping of additional query parameters to merge into the URL.
|
|
46
|
+
options: Optional :class:`qs_codec.EncodeOptions` to customize encoding behavior.
|
|
47
|
+
policy: Merge policy to apply when a key already exists (``combine`` | ``replace`` | ``keep`` | ``error``).
|
|
48
|
+
Returns:
|
|
49
|
+
The URL with the merged query string.
|
|
50
|
+
Raises:
|
|
51
|
+
ValueError: If ``policy == 'error'`` and a duplicate key is encountered.
|
|
52
|
+
"""
|
|
53
|
+
policy_enum: MergePolicy = MergePolicy(policy) if not isinstance(policy, MergePolicy) else policy
|
|
54
|
+
|
|
55
|
+
parts: SplitResult = urlsplit(url)
|
|
56
|
+
existing: t.Dict[str, t.Any] = decode(parts.query) if parts.query else {}
|
|
57
|
+
|
|
58
|
+
for k, v in extra.items():
|
|
59
|
+
if k not in existing:
|
|
60
|
+
existing[k] = v
|
|
61
|
+
continue
|
|
62
|
+
|
|
63
|
+
# k exists already
|
|
64
|
+
if policy_enum is MergePolicy.COMBINE:
|
|
65
|
+
existing[k] = _combine(existing[k], v)
|
|
66
|
+
elif policy_enum is MergePolicy.REPLACE:
|
|
67
|
+
existing[k] = v
|
|
68
|
+
elif policy_enum is MergePolicy.KEEP:
|
|
69
|
+
# Leave existing value untouched
|
|
70
|
+
continue
|
|
71
|
+
elif policy_enum is MergePolicy.ERROR:
|
|
72
|
+
raise ValueError(f"Duplicate query parameter '{k}' encountered while policy=error")
|
|
73
|
+
else: # pragma: no cover - defensive (should not happen due to Enum validation)
|
|
74
|
+
existing[k] = _combine(existing[k], v)
|
|
75
|
+
|
|
76
|
+
return urlunsplit(
|
|
77
|
+
(
|
|
78
|
+
parts.scheme,
|
|
79
|
+
parts.netloc,
|
|
80
|
+
parts.path,
|
|
81
|
+
encode(existing, options),
|
|
82
|
+
parts.fragment,
|
|
83
|
+
)
|
|
84
|
+
)
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
|
|
3
|
+
from httpx_qs import MergePolicy, merge_query
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class TestMergeQuery:
|
|
7
|
+
def setup_method(self) -> None: # noqa: D401 - simple state holder setup
|
|
8
|
+
self.base_existing = "https://example.com?a=1"
|
|
9
|
+
|
|
10
|
+
def teardown_method(self) -> None: # noqa: D401 - no resources to release
|
|
11
|
+
# Placeholder for symmetry / future resource cleanup
|
|
12
|
+
pass
|
|
13
|
+
|
|
14
|
+
@pytest.mark.parametrize(
|
|
15
|
+
"policy,expected",
|
|
16
|
+
[
|
|
17
|
+
(MergePolicy.COMBINE, "a=1&a=2"),
|
|
18
|
+
(MergePolicy.REPLACE, "a=2"),
|
|
19
|
+
(MergePolicy.KEEP, "a=1"),
|
|
20
|
+
],
|
|
21
|
+
)
|
|
22
|
+
def test_merge_policies(self, policy: MergePolicy, expected: str) -> None:
|
|
23
|
+
result: str = merge_query(self.base_existing, {"a": 2}, policy=policy)
|
|
24
|
+
assert result.endswith(expected)
|
|
25
|
+
|
|
26
|
+
def test_merge_error_policy(self) -> None:
|
|
27
|
+
with pytest.raises(ValueError):
|
|
28
|
+
merge_query(self.base_existing, {"a": 2}, policy=MergePolicy.ERROR)
|
|
29
|
+
|
|
30
|
+
def test_merge_new_keys(self) -> None:
|
|
31
|
+
result: str = merge_query(self.base_existing, {"b": 2})
|
|
32
|
+
assert result.endswith("a=1&b=2") or result.endswith("b=2&a=1")
|
|
33
|
+
|
|
34
|
+
def test_merge_list_with_list_combines_both_sides(self) -> None:
|
|
35
|
+
# base URL has repeated key so decode() yields a list for 'a'
|
|
36
|
+
base_with_list: str = "https://example.com?a=1&a=2"
|
|
37
|
+
result: str = merge_query(base_with_list, {"a": ["3", "4"]})
|
|
38
|
+
# Expect four occurrences preserving first two then the added two
|
|
39
|
+
assert result.count("a=") == 4
|
|
40
|
+
assert "a=1" in result and "a=2" in result and "a=3" in result and "a=4" in result
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
from httpx import BaseTransport, Client, Request, Response
|
|
3
|
+
|
|
4
|
+
from httpx_qs import MergePolicy
|
|
5
|
+
from httpx_qs.transporters.smart_query_strings import SmartQueryStrings
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class TestTransport:
|
|
9
|
+
client: Client
|
|
10
|
+
|
|
11
|
+
def setup_method(self) -> None:
|
|
12
|
+
self.client = Client(transport=SmartQueryStrings(DummyTransport()))
|
|
13
|
+
|
|
14
|
+
def teardown_method(self) -> None:
|
|
15
|
+
self.client.close()
|
|
16
|
+
|
|
17
|
+
def test_example_usage_combine_default(self) -> None:
|
|
18
|
+
res: Response = self.client.get(
|
|
19
|
+
"https://www.google.com",
|
|
20
|
+
params={"a": "b", "c": "d"},
|
|
21
|
+
extensions={"extra_query_params": {"c": "D", "tags": ["x", "y"]}},
|
|
22
|
+
)
|
|
23
|
+
url_str: str = str(res.request.url)
|
|
24
|
+
# Expect duplicate 'c' values and two tags entries
|
|
25
|
+
assert "a=b" in url_str
|
|
26
|
+
assert url_str.count("c=") == 2 # c=d and c=D
|
|
27
|
+
assert "c=d" in url_str and "c=D" in url_str
|
|
28
|
+
assert url_str.count("tags=") == 2
|
|
29
|
+
assert "tags=x" in url_str and "tags=y" in url_str
|
|
30
|
+
|
|
31
|
+
def test_replace_policy(self) -> None:
|
|
32
|
+
res: Response = self.client.get(
|
|
33
|
+
"https://example.com",
|
|
34
|
+
params={"a": "1", "dup": "old"},
|
|
35
|
+
extensions={
|
|
36
|
+
"extra_query_params": {"dup": "new"},
|
|
37
|
+
"extra_query_params_policy": MergePolicy.REPLACE,
|
|
38
|
+
},
|
|
39
|
+
)
|
|
40
|
+
qp: str = str(res.request.url)
|
|
41
|
+
assert "dup=new" in qp and "dup=old" not in qp
|
|
42
|
+
|
|
43
|
+
def test_keep_policy(self) -> None:
|
|
44
|
+
res: Response = self.client.get(
|
|
45
|
+
"https://example.com",
|
|
46
|
+
params={"dup": "old"},
|
|
47
|
+
extensions={
|
|
48
|
+
"extra_query_params": {"dup": "new"},
|
|
49
|
+
"extra_query_params_policy": MergePolicy.KEEP,
|
|
50
|
+
},
|
|
51
|
+
)
|
|
52
|
+
qp: str = str(res.request.url)
|
|
53
|
+
# original preserved, new ignored
|
|
54
|
+
assert "dup=old" in qp and "dup=new" not in qp
|
|
55
|
+
|
|
56
|
+
def test_error_policy(self) -> None:
|
|
57
|
+
with pytest.raises(ValueError):
|
|
58
|
+
self.client.get(
|
|
59
|
+
"https://example.com",
|
|
60
|
+
params={"dup": "old"},
|
|
61
|
+
extensions={
|
|
62
|
+
"extra_query_params": {"dup": "new"},
|
|
63
|
+
"extra_query_params_policy": MergePolicy.ERROR,
|
|
64
|
+
},
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
def test_new_keys_added(self) -> None:
|
|
68
|
+
res: Response = self.client.get(
|
|
69
|
+
"https://example.com",
|
|
70
|
+
params={"a": 1},
|
|
71
|
+
extensions={"extra_query_params": {"b": 2}},
|
|
72
|
+
)
|
|
73
|
+
qp: str = str(res.request.url)
|
|
74
|
+
assert "a=1" in qp and "b=2" in qp
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class DummyTransport(BaseTransport):
|
|
78
|
+
"""A dummy transport that simply returns a 200 response without real I/O."""
|
|
79
|
+
|
|
80
|
+
def handle_request(self, request: Request) -> Response: # type: ignore[override]
|
|
81
|
+
return Response(200, text="ok", request=request)
|