Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Side by Side Diff: README.md

Issue 29328521: Issue 133 - Add README to sitescripts repository (Closed)
Patch Set: Addressed some final nits Created Oct. 7, 2015, 1:35 p.m.
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
1 # Sitescripts
3 ## Introduction
5 The sitescripts repository contains many of the server side Python scripts that
6 we use. There are both web handlers, which can be used via the multiplexer, and
7 scripts that perform other tasks.
9 The scripts are often unrelated and as such will not all be documented here. For
10 more information about the individual scripts you will need to look at their
11 included README files. (For undocumented scripts you will need to either look at
12 the code itself, or refer to the issue numbers as mentioned in the related
13 commits.)
16 ## sitescripts.ini
18 Many of the scripts included in this repository need some configuration in order
19 to work. For this there is a shared configuration file called `sitescripts.ini`.
20 The file contains different sections for the different scripts and some shared
21 configuration.
23 The following paths will be checked - in order - for the scriptscripts
24 configuration file:
26 1. ~/.sitescripts
27 2. ~/sitescripts.ini
28 3. /etc/sitescripts
29 4. /etc/sitescripts.ini
31 There is also an environment variable `SITESCRIPTS_CONFIG` that can be used to
32 provide a custom path for the configuration file. This custom path will be
33 checked first, effectively at position 0 of the list above.
35 The first configuration file that is found will be used exclusively. So for
36 example if you have both a ~/.sitescripts file and a ~/sitescripts.ini file the
37 latter will be ignored, and if you specify a valid custom path with
38 `SITESCRIPTS_CONFIG` all the other files will be ignored.
40 The `DEFAULT` section contains some of the more generic configuration options
41 that are shared by the various scripts.
43 The `multiplexer` section is used to configure which URL handlers are included
44 by the multiplexing web server. Each option key specifies a module to import,
45 the values are not used and should be left blank.
47 We won't go into the other sections of the configuration file here, but for an
48 example that includes them all take a look at `.sitescripts.example`.
51 ## Multiplexer
53 Many of the scripts in this repository contain URL handlers which are used when
54 we need to dynamically handle web requests to our servers. For example, we might
55 need to automatically send an email after a web request has been received.
57 These URL handlers are functions that conform to [the WSGI standard as specified
58 in PEP-333](https://www.python.org/dev/peps/pep-0333/). They will almost always
59 use some of the decorators and utilities that are provided by `sitescripts.web`,
60 for example the `url_handler` decorator which registers a handling function with
61 the multiplexer for the given path.
63 The multiplexer imports each module that's listed in the `multiplexer` section
64 of the sitescripts configuration file, before providing a WSGI app that serves
65 any URL handlers that they have registered.
67 This WSGI app can then be served using `multiplexer.fcgi` in production, or
68 `multiplexer.py` in development. `multiplexer.fcgi` is a FCGI script and depends
69 on [the flup package](http://www.saddi.com/software/flup/).
70 `multiplexer.py` provides a complete web server and only optionally depends on
71 [the werkzeug package](http://werkzeug.pocoo.org/). (If werkzeug is available
72 its debugging facilities will be used.)
74 So, to test any of the URL handlers in development do the following:
76 1. Create a sitescripts configuration file that lists the web modules that you
77 are testing under the `multiplexer` section. (Depending on the modules you are
78 testing you may need to add additional configuration as well.)
79 2. Save the configuration file somewhere where it will be found, for example
80 `~/.sitescripts`.
81 3. Type `python multiplexer.py`, it will start a web server at
82 http://localhost:5000/ . This web server will use any URL handlers that have
83 been defined in the modules you are testing to respond to requests.
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld