Utility functions used by various web helpers.

This module contains support functions used by other helpers, and functions for URL manipulation. Most of these helpers predate the 0.6 reorganization; they would have been put in other subpackages if they have been created later.

webhelpers.util.update_params(_url, _debug=False, **params)

Update query parameters in a URL.

_url is any URL, with or without a query string.

\*\*params are query parameters to add or replace. Each value may be a string, a list of strings, or None. Passing a list generates multiple values for the same parameter. Passing None deletes the corresponding parameter if present.

Return the new URL.

Debug mode: if a pseudo-parameter _debug=True is passed, return a tuple: [0] is the URL without query string or fragment, [1] is the final query parameters as a dict, and [2] is the fragment part of the original URL or the empty string.


>>> update_params("foo", new1="NEW1")
>>> update_params("foo?p=1", p="2")
>>> update_params("foo?p=1", p=None)
>>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1")
>>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1", _debug=True)
('http://example.com/foo', {'new1': 'NEW1'}, 'myfrag')
>>> update_params("http://www.mau.de?foo=2", brrr=3)
>>> update_params("http://www.mau.de?foo=A&foo=B", foo=["C", "D"])
webhelpers.util.cgi_escape(s, quote=False)

Replace special characters ‘&’, ‘<’ and ‘>’ by SGML entities.

This is a slightly more efficient version of the cgi.escape by using ‘in’ membership to test if the replace is needed.

This function returns a plain string. Programs using the HTML builder should call webhelpers.html.builder.escape() instead of this to prevent double-escaping.

Changed in WebHelpers 1.2: escape single-quote as well as double-quote.


HTML-escape a string or object.

This converts any non-string objects passed into it to strings (actually, using unicode()). All values returned are non-unicode strings (using &#num; entities for all non-ASCII characters).

None is treated specially, and returns the empty string.

This function returns a plain string. Programs using the HTML builder should wrap the result in literal() to prevent double-escaping.


Convert an IRI portion to a URI portion suitable for inclusion in a URL.

(An IRI is an Internationalized Resource Identifier.)

This is the algorithm from section 3.1 of RFC 3987. However, since we are assuming input is either UTF-8 or unicode already, we can simplify things a little from the full method.

Returns an ASCII string containing the encoded result.

class webhelpers.util.Partial(*args, **kw)

A partial function object.

Equivalent to functools.partial, which was introduced in Python 2.5.

class webhelpers.util.SimplerXMLGenerator(out=None, encoding='iso-8859-1')

A subclass of Python’s SAX XMLGenerator.

addQuickElement(name, contents=None, attrs=None)

Add an element with no children.

class webhelpers.util.UnicodeMultiDict(multi=None, encoding=None, errors='strict', decode_keys=False)

A MultiDict wrapper that decodes returned values to unicode on the fly.

Decoding is not applied to assigned values.

The key/value contents are assumed to be str/strs or str/FieldStorages (as is returned by the paste.request.parse() functions).

Can optionally also decode keys when the decode_keys argument is True.

FieldStorage instances are cloned, and the clone’s filename variable is decoded. Its name variable is decoded when decode_keys is enabled.

add(key, value)

Add the key and value, not overwriting any previous value.


Return dict where each key is associated with a list of values.


Return list of all values matching the key (may be an empty list).


Return one value matching key. Raise KeyError if multiple matches.


Return dict where values are single values or a list of values.

The value is a single value if key appears just once. It is a list of values when a key/value appears more than once in this dictionary. This is similar to the kind of dictionary often used to represent the variables in a web request.

pop(key, *args)
setdefault(key, default=None)