annotate doc/api_reference.rst @ 61:55828c01e38f draft

More documenting.
author David Barts <n5jrn@me.com>
date Sun, 09 Jun 2019 10:37:45 -0700
parents
children fd8c558a89bb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
61
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
1 *************
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
2 API Reference
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
3 *************
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
4
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
5 ===================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
6 The Launch Function
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
7 ===================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
8
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
9 .. function:: launch(fsroot=None, urlroot='/', multithread=True, logger=None, encoding='utf-8', static=False)
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
10
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
11 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:
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
12
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
13 *fsroot*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
14 Path to the root directory of this webapp on the filesystem. If no path is specified, the current working directory will be used.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
15
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
16 *urlroot*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
17 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 ``/``.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
18
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
19 *multithread*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
20 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 to ``False`` if you are not going to be using multithreading.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
21
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
22 *logger*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
23 If set, the name of the Python ``logging.Logger`` object to use for logging. If not set, no messages will be logged.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
24
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
25 *encoding*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
26 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
27
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
28 *static*
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
29 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 be ``False``.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
30
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
31 =================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
32 The TinCan Object
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
33 =================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
34
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
35 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
36
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
37 This class contains one extra method above and beyond the methods ``bottle.Bottle`` objects have:
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
38
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
39 .. method:: forward(target)
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
40
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
41 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 at route creation time. The ``#forward`` directive is both more efficient and less flexible than the ``forward`` method.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
42
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
43 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
44
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
45 TinCan Configuration Variables
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
46 ------------------------------
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
47
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
48 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
49
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
50 =============================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
51 Page, BasePage, and ErrorPage
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
52 =============================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
53
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
54 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
55
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
56 .. class:: tincan.BasePage
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
57
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
58 This is the parent class of all code-behind classes. All such classes contain two standard methods:
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
59
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
60 .. method:: handle()
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
61
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
62 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
63
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
64 .. method:: export()
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
65
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
66 This exports all non-hidden instance variables; 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 type ``tincan.Page`` are also considered hidden. Finally, this object itself is exported as the ``page`` variable. This method returns a dict containing the exported items.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
67
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
68 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
69
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
70 If the above exporting behavior is for some reason unsuitable, it is permitted to override this method.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
71
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
72 .. class tincan.Page
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
73
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
74 The parent class of all normal (non-error) pages. This is a subclass of ``tincan.BasePage`` above.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
75
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
76 .. class tincan.ErrorPage
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
77
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
78 The parent class of all error pages.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
79
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
80 ============================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
81 Request and Response Objects
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
82 ============================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
83
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
84 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
85
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
86 =================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
87 Header Directives
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
88 =================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
89
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
90 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
91
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
92 ``#end``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
93 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 mainly here to facilitate future support of alternate templating engines.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
94
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
95 ``#errors``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
96 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
97
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
98 ``#forward``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
99 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 a ``TinCanError`` to be raised at initialization time.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
100
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
101 ``#hidden``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
102 This is a hidden page; do not create a route for it. The page can only be displayed by a server-side forward.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
103
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
104 ``#load``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
105 Load the specified Chameleon template file and make the loaded template available as a template variable. Useful for importing and invoking macros. See the :ref:`loading-templates` below for more information.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
106
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
107 ``#methods``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
108 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``.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
109
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
110 ``#python``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
111 What follows is the name of the Python file containing the code-behind for this route; the file name must end in ``.py``.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
112
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
113 ``#template``
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
114 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
115
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
116 Error Pages
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
117 -----------
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
118
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
119 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).
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
120
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
121 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
122
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
123 Templates with No Explicit Code-Behind
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
124 --------------------------------------
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
125
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
126 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
127
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
128 .. _loading-templates:
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
129
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
130 Loading Templates
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
131 -----------------
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
132
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
133 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
134
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
135 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>``), loaded files are searched for in ``WEB-INF/tlib`` instead.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
136
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
137 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
138
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
139 Using Loaded Macros
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
140 -------------------
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
141
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
142 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.::
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
143
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
144 #load foo.pt
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
145 <!DOCTYPE html>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
146 <html>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
147 <head>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
148 <title>Macro Example</title>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
149 </head><body>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
150 <p metal:use-macro="foo.macros.bar"></p>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
151 </body>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
152 </html>
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
153
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
154 ===================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
155 Chameleon Templates
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
156 ===================
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
157
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
158 TinCan templates are Chameleon templates, as documented `here <http://chameleon.readthedocs.io/en/latest/>`_. 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.
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
159
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
160 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::
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
161
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
162 from tincan import chameleon_view as view, chameleon_template as template
55828c01e38f More documenting.
David Barts <n5jrn@me.com>
parents:
diff changeset
163