Site Configuration

Site configuration adheres to QP’s simple and flexible configuration
mechanism, that consists of a configuration dictionary instance
attached to the site’s publisher instance.
The only difference is that Gizmo(QP) adds a few more configuration
parameters to the already comprehensive list offered by QP.

Every Gizmo(QP) site provides a SitePublisher class that is a subclass
of gz.pub.publisher.Publisher and that defines a configuration
class dict attribute for controlling many aspects of the site
e.g. the scgi server/port, durus database server/port,
max number of child web processes, etc.
Usage is not limited to predefined configuration keys —
a web application is free to add its own custom configuration items
and use them as it needs.

Configuration items are accessed with publisher.get(key, default).

QP configuration parameters

name type default sample description
durus_address (host:str, port:int) | str | None (‘127.0.0.1’, 6073) The address at which the Durus StorageServer listens.
scgi_address (host:str, port:int) | None (‘127.0.0.1’, 7073) The address at which the SCGI service listens.
http_address (host:str, port:int) | None (‘127.0.0.1’, 8073) The address at which the HTTP service listens.
as_https_address (host:str, port:int) | None (‘127.0.0.1’, 9073) The address at which the HTTP service listens and treats all connections
as if they have been forwarded through an SSL tunnel. The cgi
environment for these connections has HTTP set to ‘on’, so the url
scheme is treated as ‘https’.
https_address (host:str, port:int) | None (‘demo.gizmojo.org’, 443) The address at which the SSL tunnel or proxy accepts HTTPS requests.
QP itself does not listen on this address.
max_children int 5 The maximum number of child processes to be allowed for the QP web server.
live_host str gizmojo.org The name of the live host. Publisher.is_live_host() returns True when this value matches socket.getfqdn()
var_directory str <package_directory> / var The directory where durus and pid files usually reside.
static_directory str <package_directory> / static The directory where static content is expected.
logfile str <var_directory> / <site_name>.log The name of the file where the site logs events.
durus_logginglevel int 20 Lower levels log more.
durus_file str <var_directory> / <site_name>.durus The name of the file containing the Durus database.
banned str <var_directory> / <site_name>.banned The name of the file containing addresses for which access to the site should be denied.
durus_pidfile str <var_directory> / <site_name>.durus.pid The name of the file used to hold the process id of the running Durus StorageServer process.
web_pidfile str <var_directory> / <site_name>.web.pid The name of the file used to hold the process id of the running QP web server process.
busy_limit int 1 Returns the maximum number of child processes allowed to be
busy at one time working on requests from the same IP address.
durus_cache_size int 500000 The target number of loaded instances to keep in the Durus ClientStorage cache.
script_name str ” (empty string) The str value to use for CGI environment’s SCRIPT_NAME
variable. This does not normally end with a ‘/’. This is the
part of the path that is not involved in the Publisher’s
traversal.
daemon_uid str nobody To ensure that current user/group is not root, this specifies
the uid to change to if user *is* root.

Gizmo(QP) configuration extensions

Some of configuration parameters added by Gizmo(QP) are themselves
open-ended dictionaries.
To facilitate usage of these configuration sub-dictionaries,
Gizmo(QP) provides the following function:

publisher.has_key_path(primarykey, subkey) -> bool
Just checks if Publisher.configuration has a primarykey dictionary
attribute that itself has an entry for subkey.

URL paths

To specify arbitrary URL paths, than may be referenced (used to build HTML links)
anywhere in the application. As URL paths require special processing,
all values are processed with the following dedicated function:

publisher.get_url_path_for(basekey, filename=None) -> str
Calculates the proper script_named URL path for the given filename.
Filenames should be specified either relative to the base path
for basekey or as root-relative (must start with a slash, and
value of basekey is ignored).

name type default sample description
url_paths dict
url_paths[‘assets’] str /assets/ URL base path for static files of the site.
url_paths[‘gza’] str /gza/ URL base path for static files for gizmo objects.
url_paths[‘login’] str /login/ URL path for form login page.
url_paths[‘logout’] str /login/logout URL path for form logout.
url_paths[‘register’] str /register/ URL path for user registration page.

File paths

To specify arbitrary file system deployment paths, than may be referenced
anywhere in the application. As file paths require special processing,
all values are processed with the following dedicated function:

publisher.get_file_path_for(basekey, filename=None)-> str
Return the absolute file path for basekey and, if not None,
filename.
If filename is already an absolute path, return it unchanged
(ignoring the supplied value of basekey).
All relative results are assumed to be relative to
site.get_package_directory().

name type default sample description
file_paths dict
file_paths[‘favicon’] str static/favicon.png Location on file system of the favicon of the site.
file_paths[‘assets’] str static Location on file system of a or the static directory of the site.
file_paths[‘gza’] str <gz.gizmo.__file__> / assets Location on file system of the directory for the static files required by the various gizmo objects.

Specs

name type default sample description
spec_hints dict Used by the included user registration facility. See gz.fill.admin_users.
spec_hints[‘userid’] (spec:Spec, hint:str) Defines policy for acceptable user IDs.
spec_hints[’email’] (spec:Spec, hint:str) Defines policy for acceptable email addresses.
spec_hints[password’] (spec:Spec, hint:str) Defines policy for acceptable passwords.

Other simple parameters defined by Gizmo(QP)

name type default sample description
robotstxt str ‘User-agent: *\nDisallow: /\n’ The value is the body of the HTTP text/plain response generated by calling publisher.respond_robotstxt()
doctype str XHTML_10_Transitional The dictionary key for the X/HTML document type (see gz.fill.doctypes) to be used on each HTML document response.
static_cache_time int 600 Number of seconds to cache any static files. Gizmo(QP) actually does nothing with this, it is for the application to use for initialising StaticDirectory, StaticFile, etc.
permissions [str] [‘administrator’] Declares permissions that may then be assigned via User Admin facility, gz.fill.admin_users. [Should be part of the Users db model]
realms [str] [‘demo’] Declares a ist of realms to be used by the User Admin facility for password management. The first element, if any, is the default realm, otherwise fallback on the qp_site name.

Other parameters, refactored from QP Publisher configuration methods

QP offers methods on Publisher to be called dynamically for the value (or action)
of the following configuration paremeters.
Gizmo(QP) refactors them as declarative parameters to remove the need to
specify different code for development or deployment contexts — any differences
there may be handled via management of configuration for dev and live deployments
(see below) thus from the same identical code base.

name type default sample description
webmaster_address str webmaster@<socket.getfqdn()> [email protected] Email address to send error emails to. Replaces Publisher.get_webmaster_address()
is_email_enabled bool True The qp.mail.send.Email class will only send any email if this is True. Replaces Publisher.is_email_enabled()
display_exceptions bool True Should the details of error exceptions be reported in responses? Replaces Publisher.display_exceptions()
secure bool True If True and the scheme is not https then redirect so that it will be (call QP Publisher’s secure()).

Note that the QP Publisher class offers some other “configuration”
methods, such as:
get_smtp_server(),
get_debug_address().
See QP docs/source for more details.

Managing configuration for dev and live deployments

When (qp) Publisher.is_live_host() returns True, the method
(gz) Publisher.set_live_configuration() gets called.
To specify any configuration modifications for live deployment it is only
necessary to supply a second dict instance that specifies only the
changed values and supply a definition of this method.
For example, if the live dict we use is called configuration_live,
an example of the method we need to provide is:

def set_live_configuration(self):
from configuration import configuration_live
self.update_configuration(configuration_live)

More Information