Pydocs from code

Client class

class roundup.cgi.client.Client(instance, request, env, form=None, translator=None)

Instantiate to handle one CGI request.

See inner_main for request processing.

Client attributes at instantiation:

  • “path” is the PATH_INFO inside the instance (with no leading ‘/’)

  • “base” is the base URL for the instance

  • “form” is the cgi form, an instance of FieldStorage from the standard cgi module

  • “additional_headers” is a dictionary of additional HTTP headers that should be sent to the client

  • “response_code” is the HTTP response code to send to the client

  • “translator” is TranslationService instance

  • “clientnonce” is a unique value for this client connection. Can be used as a nonce for CSP headers and to sign javascript code presented to the browser. This is different from the CSRF nonces and can not be used for anti-csrf measures.

During the processing of a request, the following attributes are used:

  • “db”

  • “_error_message” holds a list of error messages

  • “_ok_message” holds a list of OK messages

  • “session” is deprecated in favor of session_api (XXX remove)

  • “session_api” is the interface to store data in session

  • “user” is the current user’s name

  • “userid” is the current user’s id

  • “template” is the current :template context

  • “classname” is the current class context name

  • “nodeid” is the current context item id

Note: _error_message and _ok_message should not be modified directly, use add_ok_message and add_error_message, these, by default, escape the message added to avoid XSS security issues.

User Identification:

Users that are absent in session data are anonymous and are logged in as that user. This typically gives them all Permissions assigned to the Anonymous Role.

Every user is assigned a session. “session_api” is the interface to work with session data.

Special form variables:

Note that in various places throughout this code, special form variables of the form :<name> are used. The colon (“:”) part may actually be one of either “:” or “@”.

Templating Utils class

class roundup.cgi.templating.TemplatingUtils(client)

Utilities for templating

expandfile(name, values=None, optional=False)

Read a file and replace token placeholders.

Given a file name and a dict of tokens and replacements, read the file from the tracker template directory. Then replace all tokens of the form ‘%(token_name)s’ with the values in the dict. If the values dict is set to None, it acts like readfile(). In addition to values passed into the method, the value for the tracker base directory taken from TRACKER_WEB is available as the ‘base’ token. The client_nonce used for Content Security Policy (CSP) is available as ‘client_nonce’. If a token is not in the dict, an empty string is returned and an error log message is logged. See readfile for an usage example.

html_calendar(request)

Generate a HTML calendar.

request - the roundup.request object

  • @template : name of the template

  • form : name of the form to store back the date

  • property : name of the property of the form to store back the date

  • date : date marked as current value on calendar

  • display : when browsing, specifies year and month

html will simply be a table.

html_quote(html)

HTML-quote the supplied text.

readfile(name, optional=False)

Used to inline a file from the template directory.

Used to inline file content into a template. If file is not found in the template directory and optional=False, it reports an error to the user via a NoTemplate exception. If optional=True it returns an empty string when it can’t find the file.

Useful for inlining JavaScript kept in an external file where you can use linters/minifiers and other tools on it.

A TAL example:

<script tal:attributes="nonce request/client/client_nonce"
tal:content="python:utils.readfile('mylibrary.js')"></script>

This method does not expands any tokens in the file. See expandfile() for replacing tokens in the file.

set_http_response(code)

Set the HTTP response code to the integer code. Example:

<tal:x
 tal:replace="python:utils.set_response(404);"
/>

will make the template return code 404 (not found).

url_quote(url)

URL-quote the supplied text.