API Reference¶
The Launch Function¶
-
launch
(fsroot=None, urlroot='/', multithread=True, logger=None, encoding='utf-8', static=False)¶
Launch and return a TinCan webapp object. Returns a tuple containing two items: an instance of tincan.TinCan
and an error count. This function does not run or serve the webapp; it is the caller’s responsibility to perform one of the latter operations. This function accepts the following keyword arguments:
- fsroot
Path to the root directory of this webapp on the filesystem. If no path is specified, the current working directory will be used.
- urlroot
This defines a directory prefix that is added to all routes. It is mostly for use by the
launch
shell command; when running under WSGI this should almost always be left to default to/
.- multithread
By default, TinCan assumes that multiple threads per process are being used. Setting this parameter to
False
will result in code that fails to multithread properly, but which runs more efficiently while not multithreading. It is recommended to set this toFalse
if you are not going to be using multithreading.- logger
If set, the name of the Python
logging.Logger
object to use for logging. If not set, no messages will be logged.- encoding
Character set used by all text files in the webapp. Note that this is different from the character set that TinCan will use to serve responses; the latter is inevitably UTF-8.
- static
Whether or not to create routes to serve static content in the webapp. If you’re using the built-in server, this should probably be
True
. If you’re running via WSGI, it should probably beFalse
.
The TinCan Object¶
This is a subclass of bottle.Bottle
. It is not intended for end users to create instances of this object themselves; use the launch
function above to do that.
This class contains one extra method above and beyond the methods bottle.Bottle
objects have:
-
forward
(target)¶
Perform a programmatic, request-time, server-side redirect to the route specified by target, which may be either relative to the route issuing the redirect or an absolute route. This differs from the #forward
header directive in that this method causes a server-side redirect to be set up the time a request is processed, not the when a route is created. That makes this method both more flexible and less efficient than #forward
.
One may only forward from a normal page to another normal page; neither the source nor the target of a forward may be an error page. Attempts to create forward loops will also cause an error.
TinCan Configuration Variables¶
The config
dictionary of a TinCan
object contains tincan.fsroot
, tincan.urlroot
, tincan.logger
, and tincan.encoding
keys (in addition to the standard ones defined by WSGI and Bottle); these contain the values of the corresponding parameters passed to the launch
function that created this webapp. In general, any key starting with tincan.
is reserved for use by TinCan.
Page, BasePage, and ErrorPage¶
These classes are typically subclassed in the code-behind for a page. Any page without code-behind will get a bare Page
or ErrorPage
object associated with it, as appropriate.
-
class
tincan.
BasePage
¶
This is the parent class of all code-behind classes. All such classes contain two standard methods:
-
handle
()¶
The handle
method is called by TinCan to handle a request. No arguments are passed to it (other than the implied self
argument). By default, this is a no-op method.
-
export
()¶
This is called by TinCan to export template variables; it must return a dict
or dict
-like object.
The default implementation exports all non-hidden instance variables; moreover, it does not export attributes that define callable objects (e.g. methods). A “hidden” instance variable means any one whose name does not start with an underscore; the request
and response
instance variables of class tincan.Page
are also considered hidden. Finally, self
is exported as the page
variable.
Note that the exporting happens after header processing; thus, if there is a conflict between a template variable defined by the #load
header directive and this exporting logic, the value exported by this method will always overwrite the earlier one.
If the above exporting behavior is for some reason unsuitable, it is permitted to override this method.
-
class
tincan.
Page
¶
The parent class of all normal (non-error) pages.
-
class
tincan.
ErrorPage
¶
The parent class of all error pages.
Exceptions¶
-
class
tincan.
TinCanException
¶
The parent class of all exceptions TinCan raises.
-
class
tincan.
TemplateHeaderError
¶
Raised upon encountering a syntax error in the template header directives.
-
class
tincan.
LoadError
¶
Raised when we run into problems #load
’ing something, usually because it doesn’t exist.
-
class
tincan.
TinCanError
¶
General-purpose exception raised by TinCan when things go wrong, either when attempting to launch webapps, or attempting to service requests. Often caused by errors in user-created files.
Request and Response Objects¶
The request
and response
instance variables of tincan.Page
are standard bottle.Request
and bottle.Response
objects. In the environ
attribute of the request
object, any key beginning with tincan.
is reserved.
Header Directives¶
A .pspx
file is a standard Chameleon template, plus a set of optional header directives that may be present to override the default behavior of the created page or its associated route.
#end
Marks the last line of the headers. This is not currently necessary, as headers are implicitly ended by the first line which does not start with a leading “#”. This directive is mainly here to facilitate future support of alternate templating engines.
#errors
This is an error page which handles the specified error codes; any code-behind associated with this page must be based on the
tincan.ErrorPage
class.#forward
Ignore everything else in this template (and any code-behind associated with it), using the specified route to serve it instead. The route specified with
#forward
may itself contain a#forward
, but attempts to create a#forward
loop are not allowed and will cause aTinCanError
to be raised at initialization time.#hidden
This is a hidden page; do not create a route for it. The page can only be displayed by a server-side forward.
#load
Load the specified Chameleon template file and make the loaded template available as a template variable. Useful for importing and invoking macros. See Loading Templates below for more information.
#methods
A list of HTTP request methods, separated by whitespace, follows. The route will allow all specified methods. Not specifying this line is equivalent to specifying
#methods GET
.#python
What follows is the name of the Python file containing the code-behind for this route; the file name must end in
.py
.#template
Ignore the body of this file and instead use the template in the body of the specified file, which must end in
.pspx
. Any headers in the referred template file are ignored.
Error Pages¶
Error pages supersede the standard Bottle error handling, and are created by using the #errors
page header. The #hidden
and #method
header directives are ignored in error pages (error pages are effectively hidden anyhow, by virtue of never having normal routes created for them).
The #errors
directive takes a list of numeric error codes (values from 400 to 599 are allowed), separated by spaces; the page is created to handle the specified errors. If no error codes are specified, the page will handle all errors. The behavior of specifying multiple error pages for the same error code is undefined; doing so is best avoided.
Templates with No Explicit Code-Behind¶
Code-behind is optional for both normal and error page templates. If code-behind is not provided, TinCan will use the Page
or ErrorPage
class as appropriate.
Loading Templates¶
The #load
directive may be used to load additional templates, e.g. ones containing macro definitions. Note that the loaded files are standard Chameleon templates and not TinCan .pspx
files (i.e. they cannot contain any header directives); as such, loaded files must have the standard .pt
extension for Chameleon template files.
In the normal case, #load foo.pt
will load a file relative to the same directory as the page containing the #load
directive itself. The loaded template object will be made available as a template variable matching the file name sans extension (e.g. foo
). One can change the name of the variable created by prefixing the file specification with a variable name followed by an equals sign, e.g. #load t=foo.pt
. If one places the specification inside angle brackets (e.g. #load <t=foo.pt>
), files to be loaded are searched for in WEB-INF/tlib
instead.
Finally, as is allowed for all arguments to header directives, one may enclose the argument to #load
inside single or double quotes and use the normal Python string syntax.
Using Loaded Macros¶
Once a template has been loaded, it will be available as a sub-attribute of the macros
attribute of the associated template object. E.g.:
#load foo.pt
<!DOCTYPE html>
<html>
<head>
<title>Macro Example</title>
</head><body>
<p metal:use-macro="foo.macros.bar"></p>
</body>
</html>
Chameleon Templates¶
TinCan templates are Chameleon templates, as documented here. Note that the templates in .pspx
files are processed as strings, so load:
expressions will not work in them (hence the #load
header directive). Templates loaded via #load
are processed as files, so the load:
expression will work from within them.
TinCan provides chameleon_template
and chameleon_view
callables, which follow the standard Bottle conventions for templating. Thus, if it is desired to define routes the “Bottle way”, the following import
line will make Chameleon the default templating engine:
from tincan import chameleon_view as view, chameleon_template as template