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(**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', short_empty_elements=False)¶
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
orstr
/FieldStorages
(as is returned by thepaste.request.parse()
functions).Can optionally also decode keys when the
decode_keys
argument is True.FieldStorage
instances are cloned, and the clone’sfilename
variable is decoded. Itsname
variable is decoded whendecode_keys
is enabled.- add(key, value)¶
Add the key and value, not overwriting any previous value.
- clear() → None. Remove all items from D.¶
- 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() → a set-like object providing a view on D’s items¶
- iteritems()¶
- iterkeys()¶
- itervalues()¶
- keys() → a set-like object providing a view on D’s 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(k[, d]) → v, remove specified key and return the corresponding value.¶
If key is not found, d is returned if given, otherwise KeyError is raised.
- popitem() → (k, v), remove and return some (key, value) pair¶
as a 2-tuple; but raise KeyError if D is empty.
- setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶
- values() → an object providing a view on D’s values¶