Python QueryString Parser

1.2.4 · active · verified Thu Apr 09

querystring-parser is a Python library designed for parsing URL query strings, particularly within Python and Django projects. Its key feature is the ability to correctly interpret and construct nested dictionaries from complex query string data, such as that often sent from HTML forms. The current version is 1.2.4, and its release cadence appears mature with infrequent updates.

Warnings

gotcha Unlike Python's built-in `urllib.parse.parse_qs` which returns lists for all values and flattens nested structures (e.g., `a[b]=c` becomes `{'a[b]': ['c']}`), `querystring-parser` is specifically designed to correctly build nested dictionaries from such inputs. This difference is its primary purpose but can be a 'gotcha' if expecting standard library behavior.
Fix: Be aware of the distinction; use `querystring-parser` when nested dictionary output is desired for complex query strings. For simple key-value pairs where list values are acceptable, `urllib.parse.parse_qs` might suffice.
gotcha For complex query strings, especially those containing multidimensional arrays, `querystring-parser` can be significantly slower than standard parsing methods due to the overhead of constructing nested dictionaries. Benchmarks suggest similar performance for simple cases, but a performance penalty for highly nested structures.
Fix: Benchmark critical paths if parsing very long or deeply nested query strings frequently. Consider alternative strategies or simpler parsing if performance becomes an issue and full nested dictionary reconstruction is not strictly necessary.
gotcha Multiple Python libraries exist with similar names (e.g., `django-query-string-parser`, `pyquerystring`, `querystring`). Ensure you are installing and importing `querystring-parser` (from `bernii/querystring-parser` on GitHub) to get the specific functionality for nested dictionary parsing.
Fix: Always verify the correct package name (`pip install querystring-parser`) and import path (`from querystring_parser import parser`) to avoid accidental use of a different library.
gotcha While `querystring-parser` correctly handles nested structures, general security considerations for parsing user-supplied query strings still apply. Unsanitized input, regardless of parser, can lead to vulnerabilities like Injection Attacks or Cross-Site Scripting (XSS).
Fix: Always sanitize and validate any data extracted from query strings before using it in database queries, rendering HTML, or other sensitive operations, even after parsing with this library.

Install

pip install querystring-parser Install stable version

Imports

parser
```
from querystring_parser import parser
```

Quickstart

Parse a query string into a nested Python dictionary. The library automatically handles URL-encoded values and converts array-like syntax (e.g., `items[]=value`) and dot notation (e.g., `user.name=value`) into appropriate dictionary structures.

from querystring_parser import parser

query_string = 'name=John%20Doe&address[city]=New%20York&address[zip]=10001&items[]=apple&items[]=banana'
parsed_data = parser.parse(query_string)

print(parsed_data)
# Expected output: {'name': 'John Doe', 'address': {'city': 'New York', 'zip': '10001'}, 'items': ['apple', 'banana']}

# Example with Django-style nested dicts (though library handles both standard and Django form data)
query_string_django = 'user.name=Alice&user.email=alice@example.com'
parsed_data_django = parser.parse(query_string_django)
print(parsed_data_django)
# Expected output: {'user': {'name': 'Alice', 'email': 'alice@example.com'}}

view raw JSON →