README.md - Issue 29328521: Issue 133 - Add README to sitescripts repository

Delta Between Two Patch Sets: README.md

Issue 29328521: Issue 133 - Add README to sitescripts repository (Closed)

Left Patch Set: Created Sept. 23, 2015, 10:23 a.m.

Right Patch Set: Addressed some final nits Created Oct. 7, 2015, 1:35 p.m.

Left:
Right:

Use n/p to move between diff chunks; N/P to move between comments.

Jump to:

Left: Side by side diff | Download
Right: Side by side diff | Download

LEFT	RIGHT
1 # Sitescripts	1 # Sitescripts

2	2

3 ## Introduction	3 ## Introduction

4	4

5 The sitescripts repository contains many of the server side Python scripts that	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	6 we use. There are both web handlers, which can be used via the multiplexer, and

7 scripts that perform other tasks.	7 scripts that perform other tasks.

8	8

9 The scripts are often unrelated and as such will not all be documented here. For	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	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	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	12 the code itself, or refer to the issue numbers as mentioned in the related

13 commits.)	13 commits.)

14	14

15	15

16 ## sitescripts.ini	16 ## sitescripts.ini

17	17

18 Many of the scripts included in this repository need some configuration in order	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`.	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	20 The file contains different sections for the different scripts and some shared

21 configuration.	21 configuration.

22	22

23 The configuration file can be placed in a number of locations:	23 The following paths will be checked - in order - for the scriptscripts
Wladimir Palant 2015/10/05 11:22:20 Not just that, the code will actually look for it Not just that, the code will actually look for it in that specific order. So if ~/.sitescripts exists then it shadows all the other locations. kzar 2015/10/06 13:00:13 Done. Show quoted text On 2015/10/05 11:22:20, Wladimir Palant wrote: > Not just that, the code will actually look for it in that specific order. So if > ~/.sitescripts exists then it shadows all the other locations. Done.
	24 configuration file:

24	25

25 1.) ~/.sitescripts	26 1. ~/.sitescripts
Sebastian Noack 2015/10/05 10:56:57 Nit: Using closing parenthesis for numbered lists Nit: Using closing parenthesis for numbered lists in markdown looks weird to me. I just tested it, and in fact, this syntax isn't recognized by GitHub. kzar 2015/10/06 13:00:12 Done. Show quoted text On 2015/10/05 10:56:57, Sebastian Noack wrote: > Nit: Using closing parenthesis for numbered lists in markdown looks weird to me. > I just tested it, and in fact, this syntax isn't recognized by GitHub. Done.
26 2.) ~/sitescripts.ini	27 2. ~/sitescripts.ini

27 3.) /etc/sitescripts,	28 3. /etc/sitescripts
Sebastian Noack 2015/10/05 10:56:57 I guess the trailing comma is a typo? I guess the trailing comma is a typo? kzar 2015/10/06 13:00:13 Done. Show quoted text On 2015/10/05 10:56:57, Sebastian Noack wrote: > I guess the trailing comma is a typo? Done.
28 4.) /etc/sitescripts.ini	29 4. /etc/sitescripts.ini

29	30

30 _There is also an environment variable `SITESCRIPTS_CONFIG` that can be used to	31 There is also an environment variable `SITESCRIPTS_CONFIG` that can be used to

31 provide a custom path for the configuration._	32 provide a custom path for the configuration file. This custom path will be
Wladimir Palant 2015/10/05 11:22:20 Please note explicitly that it will override the d Please note explicitly that it will override the default configuration paths - so the individual configuration files aren't being merged or anything like that. kzar 2015/10/06 13:00:12 Done. Show quoted text On 2015/10/05 11:22:20, Wladimir Palant wrote: > Please note explicitly that it will override the default configuration paths - > so the individual configuration files aren't being merged or anything like that. Done.
	33 checked first, effectively at position 0 of the list above.

	34

	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.

32	39

33 The `DEFAULT` section contains some of the more generic configuration options	40 The `DEFAULT` section contains some of the more generic configuration options

34 that are shared by the various scripts.	41 that are shared by the various scripts.

35	42

36 The `multiplexer` section is used to configure which URL handlers should be	43 The `multiplexer` section is used to configure which URL handlers are included

37 included by the multiplexing web server. Each option key specifies an URL	44 by the multiplexing web server. Each option key specifies a module to import,

38 handling function, the values are not used. (So should be left blank.)	45 the values are not used and should be left blank.

39	46

40 We won't go into the other sections of the configuration file here, but for an	47 We won't go into the other sections of the configuration file here, but for an

41 example that includes them all take a look at `.sitescripts.example`.	48 example that includes them all take a look at `.sitescripts.example`.

42	49

43	50

44 ## Multiplexer	51 ## Multiplexer

45	52

46 Many of the scripts in this repository are URL handlers which are used when we	53 Many of the scripts in this repository contain URL handlers which are used when

47 need to dynamically handle web requests to our servers. For example, we might	54 we need to dynamically handle web requests to our servers. For example, we might

48 need to send an email after a web request has been received.	55 need to automatically send an email after a web request has been received.

49	56

50 These scripts are written in a standard way, using some of the decorators and	57 These URL handlers are functions that conform to [the WSGI standard as specified
Sebastian Noack 2015/10/05 10:56:57 I think it makes sense to explicitly refer to WSGI I think it makes sense to explicitly refer to WSGI and/or PEP-333 as the standard here. kzar 2015/10/06 13:00:13 Done. Show quoted text On 2015/10/05 10:56:57, Sebastian Noack wrote: > I think it makes sense to explicitly refer to WSGI and/or PEP-333 as the > standard here. Done.
51 utilities inside `sitescripts.web` so that they can be used by the multiplexer.	58 in PEP-333](https://www.python.org/dev/peps/pep-0333/). They will almost always

52 The multiplexer includes the URL handling function for each entry included in	59 use some of the decorators and utilities that are provided by `sitescripts.web`,

53 the `multiplexer` section of the configuration file and provides a WSGI app that	60 for example the `url_handler` decorator which registers a handling function with

54 serves them all.	61 the multiplexer for the given path.

55	62

56 This WSGI app can then be served by `multiplexer.fcgi` in production and	63 The multiplexer imports each module that's listed in the `multiplexer` section

57 `multiplexer.py` in development.	64 of the sitescripts configuration file, before providing a WSGI app that serves
Wladimir Palant 2015/10/05 11:22:20 Probably mention explicitly that multiplexer.py is Probably mention explicitly that multiplexer.py is a stand-alone server whereas multiplexer.fcgi is merely an FCGI script? Also, the latter requires flup whereas the latter doesn't have any dependencies but installing werkzeug will add debugging tools. kzar 2015/10/06 13:00:13 Done. Show quoted text On 2015/10/05 11:22:20, Wladimir Palant wrote: > Probably mention explicitly that multiplexer.py is a stand-alone server whereas > multiplexer.fcgi is merely an FCGI script? Also, the latter requires flup > whereas the latter doesn't have any dependencies but installing werkzeug will > add debugging tools. Done.
	65 any URL handlers that they have registered.

58	66

59 So, to test any of the URL handlers in development, simply include their names	67 This WSGI app can then be served using `multiplexer.fcgi` in production, or

60 in your configuration file and then type `python multiplexer.py`. A local web	68 `multiplexer.py` in development. `multiplexer.fcgi` is a FCGI script and depends

61 server should then be running on port 5000.	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.)

	73

	74 So, to test any of the URL handlers in development do the following:

	75

	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.

LEFT	RIGHT