Package turbogears :: Module util

Module util

source code

The TurboGears utility module.

Classes
  Bunch
Simple but handy collector of a bunch of named stuff.
  DictObj
  DictWrapper
  setlike
Set preserving item order.
Functions
 
deprecated(message=None)
Decorator which can be used to mark functions as deprecated.
source code
 
Enum(*names)
True immutable symbolic enumeration with qualified value access.
source code
 
load_project_config(configfile=None)
Try to update the project settings from the config file specified.
source code
 
get_package_name()
Try to find out the package name of the current directory.
source code
 
get_model() source code
 
ensure_sequence(obj)
Construct a sequence from object.
source code
 
to_kw(func, args, kw, start=0)
Convert all applicable arguments to keyword arguments.
source code
 
from_kw(func, args, kw, start=0)
Extract named positional arguments from keyword arguments.
source code
 
adapt_call(func, args, kw, start=0)
Remove unsupported func arguments from given args list and kw dict.
source code
 
call_on_stack(func_name, kw, start=0)
Check if a call to function matching pattern is on stack.
source code
 
remove_keys(dict_, seq)
Gracefully remove keys from dict.
source code
 
has_arg(func, argname)
Check whether function has argument.
source code
 
arg_index(func, argname)
Find index of argument as declared for given function.
source code
 
inject_arg(func, argname, argval, args, kw, start=0)
Insert argument into call.
source code
 
inject_args(func, injections, args, kw, start=0)
Insert arguments into call.
source code
 
add_tg_args(func, args)
Add hint for special arguments that shall not be removed.
source code
 
bind_args(**add)
Call with arguments set to a predefined value.
source code
 
recursive_update(to_dict, from_dict)
Recursively update all dicts in to_dict with values from from_dict.
source code
 
combine_contexts(frames=None, depth=None)
Combine contexts (globals, locals) of frames.
source code
 
request_available()
Check if cherrypy.request is available.
source code
 
flatten_sequence(seq)
Flatten sequence.
source code
 
pop_from_nested_dict(params, keys)
Pop a value from a nested parameter dictionary.
source code
 
pop_request_params(keys)
Pop a value from the nested request parameter dictionary.
source code
 
load_class(dottedpath)
Load a class from a module in dotted-path notation.
source code
 
parse_http_accept_header(accept)
Parse an HTTP Accept header (RFC 2616) into a sorted list.
source code
 
simplify_http_accept_header(accept)
Parse an HTTP Accept header (RFC 2616) into a preferred value.
source code
 
to_unicode(value)
Convert encoded string to unicode string.
source code
 
to_utf8(value)
Convert a unicode string to utf-8 encoded plain string.
source code
 
get_template_encoding_default(engine_name=None)
Return default encoding for template files (Kid, Genshi, etc.).
source code
 
get_mime_type_for_format(format)
Return default MIME media type for a template format.
source code
 
mime_type_has_charset(mime_type)
Return whether the MIME media type supports a charset parameter.
source code
 
find_precision(value)
Find precision of some arbitrary value.
source code
 
copy_if_mutable(value, feedback=False)
Make a copy of the value if it is mutable.
source code
 
match_ip(cidr, ip)
Check whether IP address matches CIDR IP address block.
source code
Variables
  quote_cookie
  unquote_cookie
Function Details

deprecated(message=None)

source code 

Decorator which can be used to mark functions as deprecated.

It will result in a warning being emitted when the function is used.

Inspired by http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/391367

Enum(*names)

source code 

True immutable symbolic enumeration with qualified value access.

Written by Zoran Isailovski: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/413486

load_project_config(configfile=None)

source code 

Try to update the project settings from the config file specified.

If configfile is None, uses get_project_config to locate one.

adapt_call(func, args, kw, start=0)

source code 
Remove unsupported func arguments from given args list and kw dict.

@param func: the callable to inspect for supported arguments
@type func: callable

@param args: the names of the positional arguments intended to be passed
to func
@type args: list

@param kw: the keyword arguments intended to be passed to func
@type kw: dict

@keyparam start: the number of items from the start of the argument list of
func to disregard. Set start=1 to use adapt_call on a bound method to
disregard the implicit self argument.

@type start: int

Returns args list and kw dict from which arguments unsupported by func
have been removed. The passed in kw dict is also stripped as a side-effect.
The returned objects can then be used to call the target function.

Example:

    def myfunc(arg1, arg2, kwarg1='foo'):
        pass

    args, kw = adapt_call(myfunc, ['args1, 'bogus1'],
       {'kwargs1': 'bar', 'bogus2': 'spamm'})
    # --> ['args1'], {'kwargs1': 'bar'}
    myfunc(*args, **kw)

pop_from_nested_dict(params, keys)

source code 

Pop a value from a nested parameter dictionary.

You must pass a list or dotted key as the key chain to the value. If a value for this key chain is found, it will be removed and the value will be returned. If this creates empty subkeys, these will also be removed. If no single value is associated with the key chain, then None will be returned.

load_class(dottedpath)

source code 

Load a class from a module in dotted-path notation.

E.g.: load_class("package.module.class").

Based on recipe 16.3 from Python Cookbook, 2ed., by Alex Martelli, Anna Martelli Ravenscroft, and David Ascher (O'Reilly Media, 2005)

parse_http_accept_header(accept)

source code 

Parse an HTTP Accept header (RFC 2616) into a sorted list.

The quality factors in the header determine the sort order. The values can include possible media-range parameters. This function can also be used for the Accept-Charset, Accept-Encoding and Accept-Language headers.

simplify_http_accept_header(accept)

source code 

Parse an HTTP Accept header (RFC 2616) into a preferred value.

The quality factors in the header determine the preference. Possible media-range parameters are allowed, but will be ignored. This function can also be used for the Accept-Charset, Accept-Encoding and Accept-Language headers.

This is similar to parse_http_accept_header(accept)[0], but faster.

to_unicode(value)

source code 

Convert encoded string to unicode string.

Uses get_template_encoding_default() to guess source string encoding. Handles turbogears.i18n.lazystring correctly.

to_utf8(value)

source code 

Convert a unicode string to utf-8 encoded plain string.

Handles turbogears.i18n.lazystring correctly.

Does nothing to already encoded string.

get_mime_type_for_format(format)

source code 

Return default MIME media type for a template format.

Note: By default we are serving xhtml as "text/html" instead of the more correct "application/xhtml+xml", since many browsers, particularly MSIE, do not support this. We are assuming that xhtml means XHTML 1.0 here, where this approach is possible. It would be possible to use some kind of content negotiation to deliver a customized content type, but we avoid this because it causes more harm (e.g. with proxies involved) than good.

If you want to serve the proper content type (e.g. for XHTML 1.1), set tg.format_mime_types= {'xhtml': 'application/xhtml+xml'}. You can also set a particular content type per controller using the content_type parameter of the expose decorator.

For detailed information about this issues, see here: http://www.smackthemouse.com/xhtmlxml, http://schneegans.de/web/xhtml/.

mime_type_has_charset(mime_type)

source code 

Return whether the MIME media type supports a charset parameter.

Note: According to RFC4627, we do not output a charset parameter for "application/json" (this type always uses a UTF encoding).

find_precision(value)

source code 

Find precision of some arbitrary value.

The main intention for this function is to use it together with turbogears.i18n.format.format_decimal() where one has to inform the precision wanted. So, use it like this:

format_decimal(some_number, find_precision(some_number))

copy_if_mutable(value, feedback=False)

source code 

Make a copy of the value if it is mutable.

Returns the value. If feedback is set to true, also returns whether value was mutable as the second element of a tuple.