webhelpers.util

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.

Usage:

>>> update_params("foo", new1="NEW1")
'foo?new1=NEW1'
>>> update_params("foo?p=1", p="2")
'foo?p=2'
>>> update_params("foo?p=1", p=None)
'foo'
>>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1")
'http://example.com/foo?new1=NEW1#myfrag'
>>> 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)
'http://www.mau.de?foo=2&brrr=3'
>>> update_params("http://www.mau.de?foo=A&foo=B", foo=["C", "D"])
'http://www.mau.de?foo=C&foo=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.

webhelpers.util.html_escape(s)

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.

webhelpers.util.iri_to_uri(iri)

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.

clear()

copy()

dict_of_lists()

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

getall(key)

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

getone(key)

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

has_key(key)

items()

iteritems()

iterkeys()

itervalues()

keys()

mixed()

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)

popitem()

setdefault(key, default=None)

values()