Module controllers

Validate input.

Parameters:

• form (a form instance) - a form instance that must be passed throught the validation process... you must give a the same form instance as the one that will be used to post data on the controller you are putting the validate decorator on.
• validators (dictionary or schema instance) - individual validators to use for parameters. If you use a schema for validation then the schema instance must be the sole argument. If you use simple validators, then you must pass a dictionary with each value name to validate as a key of the dictionary and the validator instance (eg: tg.validators.Int() for integer) as the value.
• failsafe_schema (errorhandling.FailsafeSchema) - a schema for handling failsafe values. The default is 'none', but you can also use 'values', 'map_errors', or 'defaults' to map erroneous inputs to values, corresponding exceptions or method defaults.
• failsafe_values (a dictionary or a single value) - replacements for erroneous inputs. You can either define replacements for every parameter, or a single replacement value for all parameters. This is only used when failsafe_schema is 'values'.
• state_factory (callable or None) - If this is None, the initial state for validation is set to None, otherwise this must be a callable that returns the initial state to be used for validation.

Exposes a method to the web.

By putting the expose decorator on a method, you tell TurboGears that
the method should be accessible via URL traversal. Additionally, expose
handles the output processing (turning a dictionary into finished
output) and is also responsible for ensuring that the request is
wrapped in a database transaction.

You can apply multiple expose decorators to a method, if
you'd like to support multiple output formats. The decorator that's
listed first in your code without as_format or accept_format is
the default that is chosen when no format is specifically asked for.
Any other expose calls that are missing as_format and accept_format
will have as_format implicitly set to the whatever comes before
the ":" in the template name (or the whole template name if there
is no ":". For example, <code>expose("json")</code>, if it's not
the default expose, will have as_format set to "json".

When as_format is set, passing the same value in the tg_format
parameter in a request will choose the options for that expose
decorator. Similarly, accept_format will watch for matching
Accept headers. You can also use both. expose("json", as_format="json",
accept_format="application/json") will choose JSON output for either
case: tg_format=json as a parameter or Accept: application/json as a
request header.

Passing allow_json=True to an expose decorator
is equivalent to adding the decorator just mentioned.

Each expose decorator has its own set of options, and each one
can choose a different template or even template engine (you can
use Kid for HTML output and Cheetah for plain text, for example).
See the other expose parameters below to learn about the options
you can pass to the template engine.

Take a look at the
<a href="tests/test_expose-source.html">test_expose.py</a> suite
for more examples.

@param template: "templateengine:dotted.reference" reference along the
        Python path for the template and the template engine. For
        example, "kid:foo.bar" will have Kid render the bar template in
        the foo package.
@keyparam format: format for the template engine to output (if the
        template engine can render different formats. Kid, for example,
        can render "html", "xml" or "xhtml")
@keyparam content_type: sets the content-type http header
@keyparam allow_json: allow the function to be exposed as json
@keyparam fragment: for template engines (like Kid) that generate
        DOCTYPE declarations and the like, this is a signal to
        just generate the immediate template fragment. Use this
        if you're building up a page from multiple templates or
        going to put something onto a page with .innerHTML.
@keyparam as_format: designates which value of tg_format will choose
        this expose.
@keyparam accept_format: which value of an Accept: header will
        choose this expose.

All additional keyword arguments are passed as keyword args to the render
method of the template engine.

Computes relocatable URLs.

tgpath can be a list or a string. If the path is absolute (starts with a "/"), the server.webpath, SCRIPT_NAME and the approot of the application are prepended to the path. In order for the approot to be detected properly, the root object must extend controllers.RootController.

Query parameters for the URL can be passed in as a dictionary in the second argument and/or as keyword parameters where keyword args overwrite entries in the dictionary.

Values which are a list or a tuple are used to create multiple key-value pairs.

tgpath may also already contain a (properly escaped) query string seperated by a question mark ('?'), in which case additional query params are appended.

Return name of the server this application runs on.

Respects 'Host' and 'X-Forwarded-Host' header.

See the docstring of the 'absolute_url' function for more information.

Return absolute URL (including schema and host to this server).

Tries to account for 'Host' header and reverse proxying
('X-Forwarded-Host').

The host name is determined this way:

* If the config setting 'tg.url_domain' is set and non-null, use this value.
* Else, if the 'base_url_filter.use_x_forwarded_host' config setting is
  True, use the value from the 'Host' or 'X-Forwarded-Host' request header.
* Else, if config setting 'base_url_filter.on' is True and
  'base_url_filter.base_url' is non-null, use its value for the host AND
  scheme part of the URL.
* As a last fallback, use the value of 'server.socket_host' and
  'server.socket_port' config settings (defaults to 'localhost:8080').

The URL scheme ('http' or 'http') used is determined in the following way:

* If 'base_url_filter.base_url' is used, use the scheme from this URL.
* If there is a 'X-Use-SSL' request header, use 'https'.
* Else, if the config setting 'tg.url_scheme' is set, use its value.
* Else, use the value of 'cherrypy.request.scheme'.

Redirect (via cherrypy.HTTPRedirect).

Raises the exception instead of returning it, this to allow users to both call it as a function or to raise it as an exception.