0
# Query Parameters
1
2
The Query class handles URL query string manipulation with support for multiple values per key, custom encoding options, and ordered parameter dictionaries. It provides comprehensive query parameter management while maintaining proper URL encoding.
3
4
## Capabilities
5
6
### Query Construction and Loading
7
8
Create and load query objects from various input formats with automatic parsing and encoding.
9
10
```python { .api }
11
class Query:
12
def __init__(self, query='', strict=False):
13
"""
14
Initialize a Query object.
15
16
Args:
17
query (str): Query string to parse
18
strict (bool): Enable strict parsing mode
19
"""
20
21
def load(self, query):
22
"""
23
Load query string or parameters into the Query object.
24
25
Args:
26
query (str|dict|list): Query string, dictionary, or list of tuples
27
28
Returns:
29
Query: Self for method chaining
30
"""
31
```
32
33
**Usage:**
34
35
```python
36
from furl import Query
37
38
# Create from query string
39
q = Query('key1=value1&key2=value2&key1=another')
40
print(q.params.allitems()) # [('key1', 'value1'), ('key2', 'value2'), ('key1', 'another')]
41
42
# Create from dictionary
43
q = Query()
44
q.load({'name': 'John', 'age': '30'})
45
print(str(q)) # 'name=John&age=30'
46
47
# Create from list of tuples
48
q.load([('category', 'electronics'), ('category', 'computers')])
49
print(q.params.getlist('category')) # ['electronics', 'computers']
50
```
51
52
### Parameter Manipulation
53
54
Add, set, and remove query parameters with support for multiple values per key.
55
56
```python { .api }
57
class Query:
58
@property
59
def params(self) -> 'omdict1D':
60
"""
61
Ordered multivalue dictionary containing query parameters.
62
Supports multiple values per key and maintains insertion order.
63
"""
64
65
@params.setter
66
def params(self, params):
67
"""Set parameters from various input types"""
68
69
def add(self, args):
70
"""
71
Add query parameters without replacing existing ones.
72
73
Args:
74
args (dict|list|str): Parameters to add
75
76
Returns:
77
Query: Self for method chaining
78
"""
79
80
def set(self, mapping):
81
"""
82
Set query parameters, replacing existing ones.
83
84
Args:
85
mapping (dict|list|str): Parameters to set
86
87
Returns:
88
Query: Self for method chaining
89
"""
90
91
def remove(self, query):
92
"""
93
Remove query parameters.
94
95
Args:
96
query (list|str|bool): Parameter keys to remove, or True for all
97
98
Returns:
99
Query: Self for method chaining
100
"""
101
```
102
103
**Usage:**
104
105
```python
106
q = Query('existing=value')
107
108
# Add parameters (preserves existing)
109
q.add({'new': 'parameter', 'existing': 'another'})
110
print(q.params.allitems()) # [('existing', 'value'), ('new', 'parameter'), ('existing', 'another')]
111
112
# Set parameters (replaces existing)
113
q.set({'fresh': 'start', 'count': '5'})
114
print(str(q)) # 'fresh=start&count=5'
115
116
# Add multiple values for same key
117
q.add([('tags', 'python'), ('tags', 'url'), ('tags', 'parsing')])
118
print(q.params.getlist('tags')) # ['python', 'url', 'parsing']
119
120
# Remove specific parameters
121
q.remove(['count'])
122
print('count' in q.params) # False
123
124
# Remove all parameters
125
q.remove(True)
126
print(str(q)) # ''
127
```
128
129
### Parameter Access
130
131
Access individual parameters and handle multiple values per key.
132
133
```python { .api }
134
class omdict1D:
135
def __getitem__(self, key):
136
"""Get first value for key"""
137
138
def __setitem__(self, key, value):
139
"""Set value for key (replaces all existing values)"""
140
141
def __delitem__(self, key):
142
"""Remove all values for key"""
143
144
def __contains__(self, key):
145
"""Check if key exists"""
146
147
def get(self, key, default=None):
148
"""Get first value for key with default"""
149
150
def getlist(self, key):
151
"""Get all values for key as list"""
152
153
def setlist(self, key, values):
154
"""Set multiple values for key"""
155
156
def addlist(self, key, values):
157
"""Add multiple values for key"""
158
159
def items(self):
160
"""Iterator over (key, first_value) pairs"""
161
162
def allitems(self):
163
"""List of all (key, value) pairs including duplicates"""
164
165
def keys(self):
166
"""Iterator over unique keys"""
167
168
def values(self):
169
"""Iterator over first values"""
170
```
171
172
**Usage:**
173
174
```python
175
q = Query('name=John&skills=python&skills=django&skills=rest')
176
177
# Access first value
178
print(q.params['name']) # 'John'
179
print(q.params['skills']) # 'python' (first value)
180
181
# Access all values
182
print(q.params.getlist('skills')) # ['python', 'django', 'rest']
183
184
# Set single value
185
q.params['name'] = 'Jane'
186
print(q.params['name']) # 'Jane'
187
188
# Set multiple values
189
q.params.setlist('languages', ['python', 'javascript', 'go'])
190
print(q.params.getlist('languages')) # ['python', 'javascript', 'go']
191
192
# Add to existing values
193
q.params.addlist('skills', ['postgresql'])
194
print(q.params.getlist('skills')) # ['python', 'django', 'rest', 'postgresql']
195
196
# Check existence
197
print('name' in q.params) # True
198
print('age' in q.params) # False
199
200
# Iterate over parameters
201
for key, value in q.params.items():
202
print(f"{key}: {value}") # Prints first value for each key
203
204
# Iterate over all values
205
for key, value in q.params.allitems():
206
print(f"{key}: {value}") # Prints all key-value pairs
207
```
208
209
### Query String Encoding
210
211
Convert query objects to strings with customizable encoding options.
212
213
```python { .api }
214
class Query:
215
def encode(self, delimiter='&', quote_plus=True, dont_quote='',
216
delimeter=None):
217
"""
218
Encode query parameters to string.
219
220
Args:
221
delimiter (str): Separator between parameters
222
quote_plus (bool): Use '+' for spaces instead of '%20'
223
dont_quote (str): Characters not to percent-encode
224
delimeter (str): Deprecated alias for delimiter
225
226
Returns:
227
str: Encoded query string
228
"""
229
230
def __str__(self):
231
"""Default string encoding of query parameters"""
232
```
233
234
**Usage:**
235
236
```python
237
q = Query()
238
q.add({'name': 'John Doe', 'message': 'Hello World!', 'chars': 'special&chars'})
239
240
# Default encoding
241
print(str(q)) # 'name=John+Doe&message=Hello+World%21&chars=special%26chars'
242
243
# Custom delimiter
244
print(q.encode(delimiter=';')) # 'name=John+Doe;message=Hello+World%21;chars=special%26chars'
245
246
# Disable plus encoding for spaces
247
print(q.encode(quote_plus=False)) # 'name=John%20Doe&message=Hello%20World%21&chars=special%26chars'
248
249
# Don't quote certain characters
250
print(q.encode(dont_quote='!&')) # 'name=John+Doe&message=Hello+World!&chars=special&chars'
251
```
252
253
### Query Operations
254
255
Perform operations on query objects and convert to different formats.
256
257
```python { .api }
258
class Query:
259
def asdict(self):
260
"""
261
Convert query to dictionary representation.
262
263
Returns:
264
dict: Dictionary with query metadata and parameters
265
"""
266
267
def __eq__(self, other):
268
"""Check query equality"""
269
270
def __bool__(self):
271
"""Boolean evaluation (True if query has parameters)"""
272
```
273
274
**Usage:**
275
276
```python
277
q1 = Query('name=John&age=30')
278
q2 = Query('age=30&name=John')
279
280
# Query comparison (order matters)
281
print(q1 == q2) # False (different order)
282
283
# Boolean evaluation
284
empty_query = Query()
285
print(bool(empty_query)) # False
286
287
non_empty = Query('key=value')
288
print(bool(non_empty)) # True
289
290
# Dictionary representation
291
query_dict = q1.asdict()
292
print(query_dict) # Contains query metadata and parameters
293
```
294
295
## Advanced Parameter Handling
296
297
### Multiple Values Per Key
298
299
Handle parameters with multiple values using the ordered multivalue dictionary:
300
301
```python
302
q = Query()
303
304
# Multiple values for same parameter
305
q.params.addlist('colors', ['red', 'green', 'blue'])
306
q.params.add('colors', 'yellow')
307
308
print(q.params.getlist('colors')) # ['red', 'green', 'blue', 'yellow']
309
print(str(q)) # 'colors=red&colors=green&colors=blue&colors=yellow'
310
311
# Replace all values for a key
312
q.params.setlist('colors', ['black', 'white'])
313
print(q.params.getlist('colors')) # ['black', 'white']
314
```
315
316
### Parameter Order Preservation
317
318
The omdict1D maintains insertion order:
319
320
```python
321
q = Query()
322
q.add({'z': '1', 'a': '2', 'm': '3'})
323
print(str(q)) # 'z=1&a=2&m=3' (maintains insertion order)
324
325
# Adding more parameters maintains order
326
q.add({'b': '4'})
327
print(str(q)) # 'z=1&a=2&m=3&b=4'
328
```
329
330
### Complex Parameter Values
331
332
Handle complex parameter values with proper encoding:
333
334
```python
335
q = Query()
336
337
# Unicode values
338
q.add({'greeting': 'Hello ไธ็', 'emoji': '๐'})
339
340
# Special characters
341
q.add({'query': 'SELECT * FROM users WHERE name = "John"'})
342
343
# List-like values (automatically flattened)
344
q.params.addlist('items', ['item1', 'item2', 'item3'])
345
346
print(str(q)) # Properly encoded query string
347
```
348
349
## Error Handling
350
351
Query objects handle various edge cases:
352
353
- **Invalid encoding**: Malformed percent-encoded strings
354
- **Unicode characters**: Proper UTF-8 encoding/decoding
355
- **Special characters**: Automatic percent-encoding of reserved characters
356
- **Empty values**: Handling of parameters with empty or None values
357
- **Strict mode**: Additional validation when `strict=True`
358
359
```python
360
# Handling edge cases
361
q = Query(strict=False) # Lenient parsing
362
363
# Empty values
364
q.add({'empty': '', 'none_value': None})
365
366
# Invalid percent encoding (handled gracefully)
367
q.load('malformed=%ZZ&valid=ok')
368
369
# Unicode handling
370
q.add({'unicode': 'ๆต่ฏ'})
371
```