Mercurial > p > roundup > code

annotate doc/design.txt @ 928:23c9d4f86380

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added the web access and email access permissions.. ...so people can restrict access to users who register through the email interface (for example). Also added "security" command to the roundup-admin interface to display the Role/Permission config for an instance.
author Richard Jones <richard@users.sourceforge.net>
date Thu, 01 Aug 2002 00:56:22 +0000
parents 299f4890427d
children 42924a2fcacf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 ========================================================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Roundup - An Issue-Tracking System for Knowledge Workers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 ========================================================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 :Authors: Ka-Ping Yee (original__), Richard Jones (implementation)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 __ spec.html
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9 .. contents::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 Introduction
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 ---------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 This document presents a description of the components
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 of the Roundup system and specifies their interfaces and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 behaviour in sufficient detail to guide an implementation.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 For the philosophy and rationale behind the Roundup design,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18 see the first-round Software Carpentry submission for Roundup.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 This document fleshes out that design as well as specifying
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 interfaces so that the components can be developed separately.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 The Layer Cake
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 -----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 Lots of software design documents come with a picture of
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 a cake. Everybody seems to like them. I also like cakes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 (i think they are tasty). So i, too, shall include
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 a picture of a cake here::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 _________________________________________________________________________
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 | E-mail Client | Web Browser | Detector Scripts | Shell |
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 |------------------+-----------------+----------------------+-------------|
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 | E-mail User | Web User | Detector | Command |
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 |-------------------------------------------------------------------------|
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 | Roundup Database Layer |
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 |-------------------------------------------------------------------------|
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38 | Hyperdatabase Layer |
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 |-------------------------------------------------------------------------|
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 | Storage Layer |
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 -------------------------------------------------------------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 The colourful parts of the cake are part of our system;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 the faint grey parts of the cake are external components.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 I will now proceed to forgo all table manners and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 eat from the bottom of the cake to the top. You may want
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 to stand back a bit so you don't get covered in crumbs.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 Hyperdatabase
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 -------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 The lowest-level component to be implemented is the hyperdatabase.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 The hyperdatabase is intended to be
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56 a flexible data store that can hold configurable data in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57 records which we call nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59 The hyperdatabase is implemented on top of the storage layer,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 an external module for storing its data. The storage layer could
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 be a third-party RDBMS; for a "batteries-included" distribution,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 implementing the hyperdatabase on the standard bsddb
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 module is suggested.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 Dates and Date Arithmetic
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 ~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 Before we get into the hyperdatabase itself, we need a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 way of handling dates. The hyperdatabase module provides
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 Timestamp objects for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 representing date-and-time stamps and Interval objects for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 representing date-and-time intervals.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 As strings, date-and-time stamps are specified with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 the date in international standard format
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76 (``yyyy-mm-dd``)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 joined to the time (``hh:mm:ss``)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 by a period "``.``". Dates in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 this form can be easily compared and are fairly readable
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 when printed. An example of a valid stamp is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 "``2000-06-24.13:03:59``".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 We'll call this the "full date format". When Timestamp objects are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83 printed as strings, they appear in the full date format with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 the time always given in GMT. The full date format is always
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 exactly 19 characters long.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87 For user input, some partial forms are also permitted:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88 the whole time or just the seconds may be omitted; and the whole date
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 may be omitted or just the year may be omitted. If the time is given,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 the time is interpreted in the user's local time zone.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 The Date constructor takes care of these conversions.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92 In the following examples, suppose that ``yyyy`` is the current year,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 ``mm`` is the current month, and ``dd`` is the current
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 day of the month; and suppose that the user is on Eastern Standard Time.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 - "2000-04-17" means <Date 2000-04-17.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 - "01-25" means <Date yyyy-01-25.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 - "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 - "08-13.22:13" means <Date yyyy-08-14.03:13:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 - "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101 - "14:25" means
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 - <Date yyyy-mm-dd.19:25:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103 - "8:47:11" means
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104 - <Date yyyy-mm-dd.13:47:11>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 - the special date "." means "right now"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 Date intervals are specified using the suffixes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 "y", "m", and "d". The suffix "w" (for "week") means 7 days.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 Time intervals are specified in hh:mm:ss format (the seconds
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 may be omitted, but the hours and minutes may not).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 - "3y" means three years
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 - "2y 1m" means two years and one month
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115 - "1m 25d" means one month and 25 days
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116 - "2w 3d" means two weeks and three days
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117 - "1d 2:50" means one day, two hours, and 50 minutes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 - "14:00" means 14 hours
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 - "0:04:33" means four minutes and 33 seconds
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 The Date class should understand simple date expressions of the form
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 *stamp* ``+`` *interval* and *stamp* ``-`` *interval*.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 When adding or subtracting intervals involving months or years, the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 components are handled separately. For example, when evaluating
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 "``2000-06-25 + 1m 10d``", we first add one month to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 get 2000-07-25, then add 10 days to get
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128 2000-08-04 (rather than trying to decide whether
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 1m 10d means 38 or 40 or 41 days).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 Here is an outline of the Date and Interval classes::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 class Date:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 def __init__(self, spec, offset):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 """Construct a date given a specification and a time zone offset.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 'spec' is a full date or a partial form, with an optional
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 added or subtracted interval. 'offset' is the local time
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 zone offset from GMT in hours.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 def __add__(self, interval):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 """Add an interval to this date to produce another date."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 def __sub__(self, interval):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 """Subtract an interval from this date to produce another date."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 def __cmp__(self, other):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 """Compare this date to another date."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 def __str__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 def local(self, offset):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 class Interval:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 def __init__(self, spec):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 """Construct an interval given a specification."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 def __cmp__(self, other):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 """Compare this interval to another interval."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 def __str__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 """Return this interval as a string."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 Here are some examples of how these classes would behave in practice.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 For the following examples, assume that we are on Eastern Standard
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 Time and the current local time is 19:34:02 on 25 June 2000::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 >>> Date(".")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 <Date 2000-06-26.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 >>> _.local(-5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 "2000-06-25.19:34:02"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 >>> Date(". + 2d")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 <Date 2000-06-28.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 >>> Date("1997-04-17", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 <Date 1997-04-17.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 >>> Date("01-25", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 <Date 2000-01-25.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183 >>> Date("08-13.22:13", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 <Date 2000-08-14.03:13:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185 >>> Date("14:25", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186 <Date 2000-06-25.19:25:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 >>> Interval(" 3w 1 d 2:00")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 <Interval 22d 2:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 >>> Date(". + 2d") - Interval("3w")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190 <Date 2000-06-07.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192 Nodes and Classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193 ~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195 Nodes contain data in properties. To Python, these
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 properties are presented as the key-value pairs of a dictionary.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 Each node belongs to a class which defines the names
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 and types of its properties. The database permits the creation
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 and modification of classes as well as nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 Identifiers and Designators
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204 Each node has a numeric identifier which is unique among
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 nodes in its class. The nodes are numbered sequentially
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206 within each class in order of creation, starting from 1.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 The designator
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 for a node is a way to identify a node in the database, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 consists of the name of the node's class concatenated with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 the node's numeric identifier.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212 For example, if "spam" and "eggs" are classes, the first
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213 node created in class "spam" has id 1 and designator "spam1".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 The first node created in class "eggs" also has id 1 but has
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 the distinct designator "eggs1". Node designators are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 conventionally enclosed in square brackets when mentioned
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 in plain text. This permits a casual mention of, say,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 "[patch37]" in an e-mail message to be turned into an active
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 hyperlink.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 Property Names and Types
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222 ~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 Property names must begin with a letter.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 A property may be one of five basic types:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 - String properties are for storing arbitrary-length strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230 - Boolean properties are for storing true/false, or yes/no values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 - Number properties are for storing numeric values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234 - Date properties store date-and-time stamps.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235 Their values are Timestamp objects.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 - A Link property refers to a single other node
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 selected from a specified class. The class is part of the property;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 the value is an integer, the id of the chosen node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 - A Multilink property refers to possibly many nodes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242 in a specified class. The value is a list of integers.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 *None* is also a permitted value for any of these property
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245 types. An attempt to store None into a Multilink property stores an empty list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247 A property that is not specified will return as None from a *get*
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 operation.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 Hyperdb Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
253 TODO: replace the Interface Specifications with links to the pydoc
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
254
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255 The hyperdb module provides property objects to designate
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 the different kinds of properties. These objects are used when
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 specifying what properties belong in classes::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 class String:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260 def __init__(self, indexme='no'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 """An object designating a String property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 class Boolean:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 """An object designating a Boolean property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 class Number:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 """An object designating a Number property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 class Date:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273 """An object designating a Date property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 class Link:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276 def __init__(self, classname, do_journal='yes'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
277 """An object designating a Link property that links to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278 nodes in a specified class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280 If the do_journal argument is not 'yes' then changes to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 the property are not journalled in the linked node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 class Multilink:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285 def __init__(self, classname, do_journal='yes'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286 """An object designating a Multilink property that links
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 to nodes in a specified class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
288
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289 If the do_journal argument is not 'yes' then changes to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 the property are not journalled in the linked node(s).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 Here is the interface provided by the hyperdatabase::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
296 class Database:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297 """A database for storing records containing flexible data types."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
299 def __init__(self, config, journaltag=None):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300 """Open a hyperdatabase given a specifier to some storage.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
302 The 'storagelocator' is obtained from config.DATABASE.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303 The meaning of 'storagelocator' depends on the particular
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304 implementation of the hyperdatabase. It could be a file name,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305 a directory path, a socket descriptor for a connection to a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 database over the network, etc.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308 The 'journaltag' is a token that will be attached to the journal
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 entries for any edits done on the database. If 'journaltag' is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310 None, the database is opened in read-only mode: the Class.create(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 Class.set(), and Class.retire() methods are disabled.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314 def __getattr__(self, classname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 """A convenient way of calling self.getclass(classname)."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317 def getclasses(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
318 """Return a list of the names of all existing classes."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320 def getclass(self, classname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 """Get the Class object representing a particular class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323 If 'classname' is not a valid class name, a KeyError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 class Class:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327 """The handle to a particular class of nodes in a hyperdatabase."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 def __init__(self, db, classname, **properties):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 """Create a new class with a given name and property specification.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 'classname' must not collide with the name of an existing class,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333 or a ValueError is raised. The keyword arguments in 'properties'
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
334 must map names to property objects, or a TypeError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
335 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
336
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
337 # Editing nodes:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
338
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339 def create(self, **propvalues):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340 """Create a new node of this class and return its id.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
341
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
342 The keyword arguments in 'propvalues' map property names to values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
343 The values of arguments must be acceptable for the types of their
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
344 corresponding properties or a TypeError is raised. If this class
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
345 has a key property, it must be present and its value must not
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
346 collide with other key strings or a ValueError is raised. Any other
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
347 properties on this class that are missing from the 'propvalues'
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
348 dictionary are set to None. If an id in a link or multilink
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349 property does not refer to a valid node, an IndexError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
351
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352 def get(self, nodeid, propname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353 """Get the value of a property on an existing node of this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355 'nodeid' must be the id of an existing node of this class or an
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356 IndexError is raised. 'propname' must be the name of a property
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357 of this class or a KeyError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
359
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
360 def set(self, nodeid, **propvalues):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361 """Modify a property on an existing node of this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363 'nodeid' must be the id of an existing node of this class or an
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364 IndexError is raised. Each key in 'propvalues' must be the name
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 of a property of this class or a KeyError is raised. All values
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366 in 'propvalues' must be acceptable types for their corresponding
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 properties or a TypeError is raised. If the value of the key
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368 property is set, it must not collide with other key strings or a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 ValueError is raised. If the value of a Link or Multilink
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370 property contains an invalid node id, a ValueError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373 def retire(self, nodeid):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374 """Retire a node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376 The properties on the node remain available from the get() method,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377 and the node's id is never reused. Retired nodes are not returned
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 by the find(), list(), or lookup() methods, and other nodes may
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379 reuse the values of their key properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 def history(self, nodeid):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383 """Retrieve the journal of edits on a particular node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385 'nodeid' must be the id of an existing node of this class or an
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 IndexError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388 The returned list contains tuples of the form
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390 (date, tag, action, params)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392 'date' is a Timestamp object specifying the time of the change and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 'tag' is the journaltag specified when the database was opened.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394 'action' may be:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396 'create' or 'set' -- 'params' is a dictionary of property values
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397 'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 'retire' -- 'params' is None
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401 # Locating nodes:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403 def setkey(self, propname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 """Select a String property of this class to be the key property.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406 'propname' must be the name of a String property of this class or
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 None, or a TypeError is raised. The values of the key property on
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408 all existing nodes must be unique or a ValueError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 def getkey(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 """Return the name of the key property for this class or None."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414 def lookup(self, keyvalue):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 """Locate a particular node by its key property and return its id.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 If this class has no key property, a TypeError is raised. If the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418 'keyvalue' matches one of the values for the key property among
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419 the nodes in this class, the matching node's id is returned;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420 otherwise a KeyError is raised.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423 def find(self, propname, nodeid):
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
424 """Get the ids of nodes in this class which link to the given nodes.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
425
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
426 'propspec' consists of keyword args propname={nodeid:1,}
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427 'propname' must be the name of a property in this class, or a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428 KeyError is raised. That property must be a Link or Multilink
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
429 property, or a TypeError is raised.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
430
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
431 Any node in this class whose 'propname' property links to any of the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
432 nodeids will be returned. Used by the full text indexing, which
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
433 knows that "foo" occurs in msg1, msg3 and file7, so we have hits
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
434 on these issues:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
435
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
436 db.issue.find(messages={'1':1,'3':1}, files={'7':1})
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
439 def filter(self, search_matches, filterspec, sort, group):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
440 ''' Return a list of the ids of the active nodes in this class that
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
441 match the 'filter' spec, sorted by the group spec and then the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
442 sort spec.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
443 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
444
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 def list(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446 """Return a list of the ids of the active nodes in this class."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448 def count(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449 """Get the number of nodes in this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 If the returned integer is 'numnodes', the ids of all the nodes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452 in this class run from 1 to numnodes, and numnodes+1 will be the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 id of the next node to be created in this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 # Manipulating properties:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458 def getprops(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459 """Return a dictionary mapping property names to property objects."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 def addprop(self, **properties):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462 """Add properties to this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464 The keyword arguments in 'properties' must map names to property
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 objects, or a TypeError is raised. None of the keys in 'properties'
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466 may collide with the names of existing properties, or a ValueError
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 is raised before any properties have been added.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
470 def getnode(self, nodeid, cache=1):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
471 ''' Return a Node convenience wrapper for the node.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
472
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
473 'nodeid' must be the id of an existing node of this class or an
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
474 IndexError is raised.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
475
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
476 'cache' indicates whether the transaction cache should be queried
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
477 for the node. If the node has been modified and you need to
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
478 determine what its values prior to modification are, you need to
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
479 set cache=0.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
480 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
481
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
482 class Node:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
483 ''' A convenience wrapper for the given node. It provides a mapping
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
484 interface to a single node's properties
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
485 '''
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 Hyperdatabase Implementations
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 Hyperdatabase implementations exist to create the interface described in the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 `hyperdb interface specification`_
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492 over an existing storage mechanism. Examples are relational databases,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493 \*dbm key-value databases, and so on.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
495 Several implementations are provided - they belong in the roundup.backends
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
496 package.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 Application Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 ~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502 Here is an example of how the hyperdatabase module would work in practice::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504 >>> import hyperdb
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505 >>> db = hyperdb.Database("foo.db", "ping")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 >>> db
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507 <hyperdb.Database "foo.db" opened by "ping">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508 >>> hyperdb.Class(db, "status", name=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 <hyperdb.Class "status">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510 >>> _.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 >>> db.status.create(name="unread")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512 1
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513 >>> db.status.create(name="in-progress")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 >>> db.status.create(name="testing")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516 3
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
517 >>> db.status.create(name="resolved")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
519 >>> db.status.count()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521 >>> db.status.list()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 [1, 2, 3, 4]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523 >>> db.status.lookup("in-progress")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
524 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
525 >>> db.status.retire(3)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
526 >>> db.status.list()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
527 [1, 2, 4]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
528 >>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 <hyperdb.Class "issue">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530 >>> db.issue.create(title="spam", status=1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
531 1
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
532 >>> db.issue.create(title="eggs", status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
533 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
534 >>> db.issue.create(title="ham", status=4)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535 3
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536 >>> db.issue.create(title="arguments", status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538 >>> db.issue.create(title="abuse", status=1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539 5
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 >>> hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 <hyperdb.Class "user">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 >>> db.issue.addprop(fixer=hyperdb.Link("user"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543 >>> db.issue.getprops()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544 {"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545 "user": <hyperdb.Link to "user">}
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546 >>> db.issue.set(5, status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 >>> db.issue.get(5, "status")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 >>> db.status.get(2, "name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550 "in-progress"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 >>> db.issue.get(5, "title")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 "abuse"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553 >>> db.issue.find("status", db.status.lookup("in-progress"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554 [2, 4, 5]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555 >>> db.issue.history(5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556 [(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse", "status": 1}),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
557 (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558 >>> db.status.history(1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559 [(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 >>> db.status.history(2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562 [(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
563
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565 For the purposes of journalling, when a Multilink property is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566 set to a new list of nodes, the hyperdatabase compares the old
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567 list to the new list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 The journal records "unlink" events for all the nodes that appear
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569 in the old list but not the new list,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 and "link" events for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 all the nodes that appear in the new list but not in the old list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574 Roundup Database
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 ----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 The Roundup database layer is implemented on top of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 hyperdatabase and mediates calls to the database.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 Some of the classes in the Roundup database are considered
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580 issue classes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 The Roundup database layer adds detectors and user nodes,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582 and on issues it provides mail spools, nosy lists, and superseders.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 Reserved Classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585 ~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 Internal to this layer we reserve three special classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 of nodes that are not issues.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 Users
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
591 """""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 Users are stored in the hyperdatabase as nodes of
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 class "user". The "user" class has the definition::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 hyperdb.Class(db, "user", username=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 password=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 address=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 db.user.setkey("username")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 Messages
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
602 """"""""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 E-mail messages are represented by hyperdatabase nodes of class "msg".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 The actual text content of the messages is stored in separate files.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606 (There's no advantage to be gained by stuffing them into the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 hyperdatabase, and if messages are stored in ordinary text files,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 they can be grepped from the command line.) The text of a message is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 saved in a file named after the message node designator (e.g. "msg23")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 for the sake of the command interface (see below). Attachments are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 stored separately and associated with "file" nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612 The "msg" class has the definition::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 recipients=hyperdb.Multilink("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616 date=hyperdb.Date(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 summary=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
618 files=hyperdb.Multilink("file"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
619
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
620 The "author" property indicates the author of the message
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621 (a "user" node must exist in the hyperdatabase for any messages
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
622 that are stored in the system).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623 The "summary" property contains a summary of the message for display
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624 in a message index.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
626 Files
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
627 """""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
629 Submitted files are represented by hyperdatabase
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
630 nodes of class "file". Like e-mail messages, the file content
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
631 is stored in files outside the database,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
632 named after the file node designator (e.g. "file17").
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
633 The "file" class has the definition::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
635 hyperdb.Class(db, "file", user=hyperdb.Link("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
636 name=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637 type=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
639 The "user" property indicates the user who submitted the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
640 file, the "name" property holds the original name of the file,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
641 and the "type" property holds the MIME type of the file as received.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
642
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
643 Issue Classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
644 ~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
645
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646 All issues have the following standard properties:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
648 =========== ==========================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
649 Property Definition
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650 =========== ==========================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651 title hyperdb.String()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
652 messages hyperdb.Multilink("msg")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
653 files hyperdb.Multilink("file")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654 nosy hyperdb.Multilink("user")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
655 superseder hyperdb.Multilink("issue")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
656 =========== ==========================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
657
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
658 Also, two Date properties named "creation" and "activity" are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
659 fabricated by the Roundup database layer. By "fabricated" we
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
660 mean that no such properties are actually stored in the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
661 hyperdatabase, but when properties on issues are requested, the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
662 "creation" and "activity" properties are made available.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
663 The value of the "creation" property is the date when an issue was
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
664 created, and the value of the "activity" property is the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
665 date when any property on the issue was last edited (equivalently,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
666 these are the dates on the first and last records in the issue's journal).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
667
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
668 Roundupdb Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
669 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
670
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
671 The interface to a Roundup database delegates most method
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
672 calls to the hyperdatabase, except for the following
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
673 changes and additional methods::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
674
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
675 class Database:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
676 def getuid(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
677 """Return the id of the "user" node associated with the user
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678 that owns this connection to the hyperdatabase."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680 class Class:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681 # Overridden methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
682
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
683 def create(self, **propvalues):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
684 def set(self, **propvalues):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
685 def retire(self, nodeid):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
686 """These operations trigger detectors and can be vetoed. Attempts
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
687 to modify the "creation" or "activity" properties cause a KeyError.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
688 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
689
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
690 # New methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
691
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
692 def audit(self, event, detector):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
693 def react(self, event, detector):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
694 """Register a detector (see below for more details)."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
695
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
696 class IssueClass(Class):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
697 # Overridden methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
698
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
699 def __init__(self, db, classname, **properties):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
700 """The newly-created class automatically includes the "messages",
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
701 "files", "nosy", and "superseder" properties. If the 'properties'
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
702 dictionary attempts to specify any of these properties or a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
703 "creation" or "activity" property, a ValueError is raised."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
704
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
705 def get(self, nodeid, propname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
706 def getprops(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
707 """In addition to the actual properties on the node, these
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
708 methods provide the "creation" and "activity" properties."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
709
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
710 # New methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
711
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
712 def addmessage(self, nodeid, summary, text):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
713 """Add a message to an issue's mail spool.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
714
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
715 A new "msg" node is constructed using the current date, the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
716 user that owns the database connection as the author, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
717 the specified summary text. The "files" and "recipients"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
718 fields are left empty. The given text is saved as the body
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
719 of the message and the node is appended to the "messages"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
720 field of the specified issue.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
721 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
722
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
723 def sendmessage(self, nodeid, msgid):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
724 """Send a message to the members of an issue's nosy list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
725
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
726 The message is sent only to users on the nosy list who are not
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
727 already on the "recipients" list for the message. These users
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
728 are then added to the message's "recipients" list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
729 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
730
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
731
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
732 Default Schema
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
733 ~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
734
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
735 The default schema included with Roundup turns it into a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
736 typical software bug tracker. The database is set up like this::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
737
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
738 pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
739 pri.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
740 pri.create(name="critical", order="1")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
741 pri.create(name="urgent", order="2")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
742 pri.create(name="bug", order="3")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
743 pri.create(name="feature", order="4")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
744 pri.create(name="wish", order="5")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
745
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
746 stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
747 stat.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
748 stat.create(name="unread", order="1")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
749 stat.create(name="deferred", order="2")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
750 stat.create(name="chatting", order="3")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
751 stat.create(name="need-eg", order="4")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752 stat.create(name="in-progress", order="5")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
753 stat.create(name="testing", order="6")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
754 stat.create(name="done-cbb", order="7")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
755 stat.create(name="resolved", order="8")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
756
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 Class(db, "keyword", name=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
758
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
759 Class(db, "issue", fixer=hyperdb.Multilink("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
760 topic=hyperdb.Multilink("keyword"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
761 priority=hyperdb.Link("priority"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762 status=hyperdb.Link("status"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
764 (The "order" property hasn't been explained yet. It
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765 gets used by the Web user interface for sorting.)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
766
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
767 The above isn't as pretty-looking as the schema specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
768 in the first-stage submission, but it could be made just as easy
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769 with the addition of a convenience function like Choice
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 for setting up the "priority" and "status" classes::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772 def Choice(name, *options):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773 cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774 for i in range(len(options)):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775 cl.create(name=option[i], order=i)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 return hyperdb.Link(name)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 Detector Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780 ------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782 Detectors are Python functions that are triggered on certain
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
783 kinds of events. The definitions of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784 functions live in Python modules placed in a directory set aside
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 for this purpose. Importing the Roundup database module also
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786 imports all the modules in this directory, and the ``init()``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
787 function of each module is called when a database is opened to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
788 provide it a chance to register its detectors.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790 There are two kinds of detectors:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 1. an auditor is triggered just before modifying an node
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793 2. a reactor is triggered just after an node has been modified
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
795 When the Roundup database is about to perform a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
796 ``create()``, ``set()``, or ``retire()``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797 operation, it first calls any *auditors* that
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 have been registered for that operation on that class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
799 Any auditor may raise a *Reject* exception
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800 to abort the operation.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
801
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
802 If none of the auditors raises an exception, the database
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803 proceeds to carry out the operation. After it's done, it
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804 then calls all of the *reactors* that have been registered
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805 for the operation.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
806
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807 Detector Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
808 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810 The ``audit()`` and ``react()`` methods
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 register detectors on a given class of nodes::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813 class Class:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 def audit(self, event, detector):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815 """Register an auditor on this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 'event' should be one of "create", "set", or "retire".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818 'detector' should be a function accepting four arguments.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 def react(self, event, detector):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822 """Register a reactor on this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824 'event' should be one of "create", "set", or "retire".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
825 'detector' should be a function accepting four arguments.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
826 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
827
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828 Auditors are called with the arguments::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
829
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
830 audit(db, cl, nodeid, newdata)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
831
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
832 where ``db`` is the database, ``cl`` is an
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833 instance of Class or IssueClass within the database, and ``newdata``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 is a dictionary mapping property names to values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
835
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
836 For a ``create()``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 operation, the ``nodeid`` argument is None and newdata
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838 contains all of the initial property values with which the node
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 is about to be created.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841 For a ``set()`` operation, newdata
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 contains only the names and values of properties that are about
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 to be changed.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
845 For a ``retire()`` operation, newdata is None.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
846
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847 Reactors are called with the arguments::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
849 react(db, cl, nodeid, olddata)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851 where ``db`` is the database, ``cl`` is an
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 instance of Class or IssueClass within the database, and ``olddata``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853 is a dictionary mapping property names to values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855 For a ``create()``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
856 operation, the ``nodeid`` argument is the id of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857 newly-created node and ``olddata`` is None.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
858
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
859 For a ``set()`` operation, ``olddata``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
860 contains the names and previous values of properties that were changed.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
861
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
862 For a ``retire()`` operation, ``nodeid`` is the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
863 id of the retired node and ``olddata`` is None.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
864
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
865 Detector Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
866 ~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
867
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
868 Here is an example of detectors written for a hypothetical
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
869 project-management application, where users can signal approval
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
870 of a project by adding themselves to an "approvals" list, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
871 a project proceeds when it has three approvals::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
872
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873 # Permit users only to add themselves to the "approvals" list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
874
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875 def check_approvals(db, cl, id, newdata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876 if newdata.has_key("approvals"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
877 if cl.get(id, "status") == db.status.lookup("approved"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
878 raise Reject, "You can't modify the approvals list " \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
879 "for a project that has already been approved."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
880 old = cl.get(id, "approvals")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
881 new = newdata["approvals"]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
882 for uid in old:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
883 if uid not in new and uid != db.getuid():
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884 raise Reject, "You can't remove other users from the "
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
885 "approvals list; you can only remove yourself."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
886 for uid in new:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
887 if uid not in old and uid != db.getuid():
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
888 raise Reject, "You can't add other users to the approvals "
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
889 "list; you can only add yourself."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891 # When three people have approved a project, change its
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 # status from "pending" to "approved".
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
894 def approve_project(db, cl, id, olddata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895 if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
896 if cl.get(id, "status") == db.status.lookup("pending"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
897 cl.set(id, status=db.status.lookup("approved"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
898
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899 def init(db):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
900 db.project.audit("set", check_approval)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
901 db.project.react("set", approve_project)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
902
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903 Here is another example of a detector that can allow or prevent
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
904 the creation of new nodes. In this scenario, patches for a software
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
905 project are submitted by sending in e-mail with an attached file,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906 and we want to ensure that there are text/plain attachments on
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
907 the message. The maintainer of the package can then apply the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908 patch by setting its status to "applied"::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910 # Only accept attempts to create new patches that come with patch files.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
911
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912 def check_new_patch(db, cl, id, newdata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
913 if not newdata["files"]:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
914 raise Reject, "You can't submit a new patch without " \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
915 "attaching a patch file."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
916 for fileid in newdata["files"]:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
917 if db.file.get(fileid, "type") != "text/plain":
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
918 raise Reject, "Submitted patch files must be text/plain."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
919
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
920 # When the status is changed from "approved" to "applied", apply the patch.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
921
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
922 def apply_patch(db, cl, id, olddata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
923 if cl.get(id, "status") == db.status.lookup("applied") and \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
924 olddata["status"] == db.status.lookup("approved"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
925 # ...apply the patch...
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
926
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
927 def init(db):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
928 db.patch.audit("create", check_new_patch)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
929 db.patch.react("set", apply_patch)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
930
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
931
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
932 Command Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
933 -----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
934
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
935 The command interface is a very simple and minimal interface,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
936 intended only for quick searches and checks from the shell prompt.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
937 (Anything more interesting can simply be written in Python using
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
938 the Roundup database module.)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
939
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
940 Command Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
941 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
942
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
943 A single command, roundup, provides basic access to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
944 the hyperdatabase from the command line::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
945
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
946 roundup-admin help
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
947 roundup-admin get [-list] designator[, designator,...] propname
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
948 roundup-admin set designator[, designator,...] propname=value ...
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
949 roundup-admin find [-list] classname propname=value ...
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
950
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
951 See ``roundup-admin help commands`` for a complete list of commands.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
952
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
953 Property values are represented as strings in command arguments
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
954 and in the printed results:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
955
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
956 - Strings are, well, strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
957
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
958 - Numbers are displayed the same as strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
959
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
960 - Booleans are displayed as 'Yes' or 'No'.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
961
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
962 - Date values are printed in the full date format in the local
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
963 time zone, and accepted in the full format or any of the partial
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
964 formats explained above.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
965
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
966 - Link values are printed as node designators. When given as
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
967 an argument, node designators and key strings are both accepted.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
968
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
969 - Multilink values are printed as lists of node designators
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
970 joined by commas. When given as an argument, node designators
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
971 and key strings are both accepted; an empty string, a single node,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
972 or a list of nodes joined by commas is accepted.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
973
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
974 When multiple nodes are specified to the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
975 roundup get or roundup set
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
976 commands, the specified properties are retrieved or set
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
977 on all the listed nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
978
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
979 When multiple results are returned by the roundup get
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
980 or roundup find commands, they are printed one per
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
981 line (default) or joined by commas (with the -list) option.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
982
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
983 Usage Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
984 ~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
985
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
986 To find all messages regarding in-progress issues that
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
987 contain the word "spam", for example, you could execute the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
988 following command from the directory where the database
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
989 dumps its files::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
990
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
991 shell% for issue in `roundup find issue status=in-progress`; do
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
992 > grep -l spam `roundup get $issue messages`
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
993 > done
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
994 msg23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
995 msg49
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
996 msg50
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
997 msg61
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
998 shell%
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
999
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1000 Or, using the -list option, this can be written as a single command::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1001
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1002 shell% grep -l spam `roundup get \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1003 \`roundup find -list issue status=in-progress\` messages`
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1004 msg23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1005 msg49
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1006 msg50
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1007 msg61
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1008 shell%
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1009
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1010
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1011 E-mail User Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1012 ---------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1013
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1014 The Roundup system must be assigned an e-mail address
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1015 at which to receive mail. Messages should be piped to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1016 the Roundup mail-handling script by the mail delivery
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1017 system (e.g. using an alias beginning with "|" for sendmail).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1018
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1019 Message Processing
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1020 ~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1021
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1022 Incoming messages are examined for multiple parts.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1023 In a multipart/mixed message or part, each subpart is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1024 extracted and examined. In a multipart/alternative
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1025 message or part, we look for a text/plain subpart and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1026 ignore the other parts. The text/plain subparts are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1027 assembled to form the textual body of the message, to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1028 be stored in the file associated with a "msg" class node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1029 Any parts of other types are each stored in separate
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1030 files and given "file" class nodes that are linked to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1031 the "msg" node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1032
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1033 The "summary" property on message nodes is taken from
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1034 the first non-quoting section in the message body.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1035 The message body is divided into sections by blank lines.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1036 Sections where the second and all subsequent lines begin
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1037 with a ">" or "|" character are considered "quoting
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1038 sections". The first line of the first non-quoting
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1039 section becomes the summary of the message.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1040
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1041 All of the addresses in the To: and Cc: headers of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1042 incoming message are looked up among the user nodes, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1043 the corresponding users are placed in the "recipients"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1044 property on the new "msg" node. The address in the From:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1045 header similarly determines the "author" property of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1046 new "msg" node.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1047 The default handling for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1048 addresses that don't have corresponding users is to create
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1049 new users with no passwords and a username equal to the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1050 address. (The web interface does not permit logins for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1051 users with no passwords.) If we prefer to reject mail from
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1052 outside sources, we can simply register an auditor on the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1053 "user" class that prevents the creation of user nodes with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1054 no passwords.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1055
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1056 The subject line of the incoming message is examined to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1057 determine whether the message is an attempt to create a new
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1058 issue or to discuss an existing issue. A designator enclosed
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1059 in square brackets is sought as the first thing on the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1060 subject line (after skipping any "Fwd:" or "Re:" prefixes).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1061
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1062 If an issue designator (class name and id number) is found
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1063 there, the newly created "msg" node is added to the "messages"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1064 property for that issue, and any new "file" nodes are added to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1065 the "files" property for the issue.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1066
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1067 If just an issue class name is found there, we attempt to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1068 create a new issue of that class with its "messages" property
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1069 initialized to contain the new "msg" node and its "files"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1070 property initialized to contain any new "file" nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1071
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1072 Both cases may trigger detectors (in the first case we
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1073 are calling the set() method to add the message to the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1074 issue's spool; in the second case we are calling the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1075 create() method to create a new node). If an auditor
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1076 raises an exception, the original message is bounced back to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1077 the sender with the explanatory message given in the exception.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1078
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1079 Nosy Lists
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1080 ~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1081
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1082 A standard detector is provided that watches for additions
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1083 to the "messages" property. When a new message is added, the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1084 detector sends it to all the users on the "nosy" list for the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1085 issue that are not already on the "recipients" list of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1086 message. Those users are then appended to the "recipients"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1087 property on the message, so multiple copies of a message
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1088 are never sent to the same user. The journal recorded by
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1089 the hyperdatabase on the "recipients" property then provides
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1090 a log of when the message was sent to whom.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1091
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1092 Setting Properties
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1093 ~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1094
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1095 The e-mail interface also provides a simple way to set
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1096 properties on issues. At the end of the subject line,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1097 ``propname=value`` pairs can be
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1098 specified in square brackets, using the same conventions
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1099 as for the roundup ``set`` shell command.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1100
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1101
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1102 Web User Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1103 ------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1104
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1105 The web interface is provided by a CGI script that can be
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1106 run under any web server. A simple web server can easily be
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1107 built on the standard CGIHTTPServer module, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1108 should also be included in the distribution for quick
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1109 out-of-the-box deployment.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1110
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1111 The user interface is constructed from a number of template
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1112 files containing mostly HTML. Among the HTML tags in templates
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1113 are interspersed some nonstandard tags, which we use as
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1114 placeholders to be replaced by properties and their values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1115
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1116 Views and View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1117 ~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1118
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1119 There are two main kinds of views: *index* views and *issue* views.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1120 An index view displays a list of issues of a particular class,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1121 optionally sorted and filtered as requested. An issue view
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1122 presents the properties of a particular issue for editing
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1123 and displays the message spool for the issue.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1124
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1125 A view specifier is a string that specifies
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1126 all the options needed to construct a particular view.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1127 It goes after the URL to the Roundup CGI script or the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1128 web server to form the complete URL to a view. When the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1129 result of selecting a link or submitting a form takes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1130 the user to a new view, the Web browser should be redirected
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1131 to a canonical location containing a complete view specifier
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1132 so that the view can be bookmarked.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1133
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1134 Displaying Properties
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1135 ~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1136
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1137 Properties appear in the user interface in three contexts:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1138 in indices, in editors, and as filters. For each type of
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1139 property, there are several display possibilities. For example,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1140 in an index view, a string property may just be printed as
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1141 a plain string, but in an editor view, that property should
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1142 be displayed in an editable field.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1143
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1144 The display of a property is handled by functions in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1145 a displayers module. Each function accepts at
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1146 least three standard arguments -- the database, class name,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1147 and node id -- and returns a chunk of HTML.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1148
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1149 Displayer functions are triggered by <display>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1150 tags in templates. The call attribute of the tag
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1151 provides a Python expression for calling the displayer
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1152 function. The three standard arguments are inserted in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1153 front of the arguments given. For example, the occurrence of::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1154
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1155 <display call="plain('status', max=30)">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1156
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1157 in a template triggers a call to::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1158
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1159 plain(db, "issue", 13, "status", max=30)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1160
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1161
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1162 when displaying issue 13 in the "issue" class. The displayer
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1163 functions can accept extra arguments to further specify
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1164 details about the widgets that should be generated. By defining new
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1165 displayer functions, the user interface can be highly customized.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1166
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1167 Some of the standard displayer functions include:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1168
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1169 ========= ====================================================================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1170 Function Description
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1171 ========= ====================================================================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1172 plain display a String property directly;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1173 display a Date property in a specified time zone with an option
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1174 to omit the time from the date stamp; for a Link or Multilink
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1175 property, display the key strings of the linked nodes (or the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1176 ids if the linked class has no key property)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1177 field display a property like the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1178 plain displayer above, but in a text field
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1179 to be edited
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1180 menu for a Link property, display
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1181 a menu of the available choices
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1182 link for a Link or Multilink property,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1183 display the names of the linked nodes, hyperlinked to the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1184 issue views on those nodes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1185 count for a Multilink property, display
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1186 a count of the number of links in the list
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1187 reldate display a Date property in terms
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1188 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1189 download show a Link("file") or Multilink("file")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1190 property using links that allow you to download files
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1191 checklist for a Link or Multilink property,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1192 display checkboxes for the available choices to permit filtering
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1193 ========= ====================================================================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1194
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1195 TODO: See the htmltemplate pydoc for a complete list of the functions
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1196
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1197
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1198 Index Views
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1199 ~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1200
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1201 An index view contains two sections: a filter section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1202 and an index section.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1203 The filter section provides some widgets for selecting
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1204 which issues appear in the index. The index section is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1205 a table of issues.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1206
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1207 Index View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1208 """""""""""""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1209
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1210 An index view specifier looks like this (whitespace
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1211 has been added for clarity)::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1212
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1213 /issue?status=unread,in-progress,resolved&amp;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1214 topic=security,ui&amp;
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1215 :group=priority&amp;
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1216 :sort=-activity&amp;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1217 :filters=status,topic&amp;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1218 :columns=title,status,fixer
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1219
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1220
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1221 The index view is determined by two parts of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1222 specifier: the layout part and the filter part.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1223 The layout part consists of the query parameters that
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1224 begin with colons, and it determines the way that the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1225 properties of selected nodes are displayed.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1226 The filter part consists of all the other query parameters,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1227 and it determines the criteria by which nodes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1228 are selected for display.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1229
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1230 The filter part is interactively manipulated with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1231 the form widgets displayed in the filter section. The
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1232 layout part is interactively manipulated by clicking
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1233 on the column headings in the table.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1234
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1235 The filter part selects the union of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1236 sets of issues with values matching any specified Link
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1237 properties and the intersection of the sets
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1238 of issues with values matching any specified Multilink
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1239 properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1240
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1241 The example specifies an index of "issue" nodes.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1242 Only issues with a "status" of either
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1243 "unread" or "in-progres" or "resolved" are displayed,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1244 and only issues with "topic" values including both
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1245 "security" and "ui" are displayed. The issues
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1246 are grouped by priority, arranged in ascending order;
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1247 and within groups, sorted by activity, arranged in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1248 descending order. The filter section shows filters
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1249 for the "status" and "topic" properties, and the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1250 table includes columns for the "title", "status", and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1251 "fixer" properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1252
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1253 Associated with each issue class is a default
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1254 layout specifier. The layout specifier in the above
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1255 example is the default layout to be provided with
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1256 the default bug-tracker schema described above in
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1257 section 4.4.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1258
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1259 Filter Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1260 """"""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1261
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1262 The template for a filter section provides the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1263 filtering widgets at the top of the index view.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1264 Fragments enclosed in ``<property>...</property>``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1265 tags are included or omitted depending on whether the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1266 view specifier requests a filter for a particular property.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1267
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1268 Here's a simple example of a filter template::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1269
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1270 <property name=status>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1271 <display call="checklist('status')">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1272 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1273 <br>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1274 <property name=priority>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1275 <display call="checklist('priority')">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1276 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1277 <br>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1278 <property name=fixer>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1279 <display call="menu('fixer')">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1280 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1281
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1282 Index Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1283 """""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1284
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1285 The template for an index section describes one row of
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1286 the index table.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1287 Fragments enclosed in ``<property>...</property>``
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1288 tags are included or omitted depending on whether the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1289 view specifier requests a column for a particular property.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1290 The table cells should contain <display> tags
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1291 to display the values of the issue's properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1292
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1293 Here's a simple example of an index template::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1294
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1295 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1296 <property name=title>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1297 <td><display call="plain('title', max=50)"></td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1298 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1299 <property name=status>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1300 <td><display call="plain('status')"></td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1301 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1302 <property name=fixer>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1303 <td><display call="plain('fixer')"></td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1304 </property>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1305 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1306
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1307 Sorting
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1308 """""""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1309
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1310 String and Date values are sorted in the natural way.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1311 Link properties are sorted according to the value of the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1312 "order" property on the linked nodes if it is present; or
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1313 otherwise on the key string of the linked nodes; or
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1314 finally on the node ids. Multilink properties are
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1315 sorted according to how many links are present.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1316
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1317 Issue Views
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1318 ~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1319
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1320 An issue view contains an editor section and a spool section.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1321 At the top of an issue view, links to superseding and superseded
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1322 issues are always displayed.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1323
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1324 Issue View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1325 """""""""""""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1326
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1327 An issue view specifier is simply the issue's designator::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1328
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1329 /patch23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1330
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1331
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1332 Editor Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1333 """"""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1334
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1335 The editor section is generated from a template
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1336 containing <display> tags to insert
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1337 the appropriate widgets for editing properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1338
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1339 Here's an example of a basic editor template::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1340
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1341 <table>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1342 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1343 <td colspan=2>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1344 <display call="field('title', size=60)">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1345 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1346 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1347 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1348 <td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1349 <display call="field('fixer', size=30)">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1350 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1351 <td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1352 <display call="menu('status')>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1353 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1354 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1355 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1356 <td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1357 <display call="field('nosy', size=30)">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1358 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1359 <td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1360 <display call="menu('priority')>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1361 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1362 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1363 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1364 <td colspan=2>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1365 <display call="note()">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1366 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1367 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1368 </table>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1369
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1370 As shown in the example, the editor template can also
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1371 request the display of a "note" field, which is a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1372 text area for entering a note to go along with a change.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1373
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1374 When a change is submitted, the system automatically
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1375 generates a message describing the changed properties.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1376 The message displays all of the property values on the
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1377 issue and indicates which ones have changed.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1378 An example of such a message might be this::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1379
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1380 title: Polly Parrot is dead
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1381 priority: critical
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1382 status: unread -> in-progress
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1383 fixer: (none)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1384 keywords: parrot,plumage,perch,nailed,dead
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1385
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1386 If a note is given in the "note" field, the note is
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1387 appended to the description. The message is then added
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1388 to the issue's message spool (thus triggering the standard
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1389 detector to react by sending out this message to the nosy list).
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1390
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1391 Spool Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1392 """""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1393
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1394 The spool section lists messages in the issue's "messages"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1395 property. The index of messages displays the "date", "author",
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1396 and "summary" properties on the message nodes, and selecting a
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1397 message takes you to its content.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1398
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1399 Access Control
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1400 --------------
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1401
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1402 At each point that requires an action to be performed, the security mechanisms
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1403 are asked if the current user has permission. This permission is defined as a
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1404 Permission.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1405
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1406 Individual assignment of Permission to user is unwieldy. The concept of a
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1407 Role, which encompasses several Permissions and may be assigned to many Users,
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1408 is quite well developed in many projects. Roundup will take this path, and
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1409 allow the multiple assignment of Roles to Users, and multiple Permissions to
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1410 Roles. These definitions are not persistent - they're defined when the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1411 application initialises.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1412
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1413 There will be two levels of Permission. The Class level permissions define
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1414 logical permissions associated with all nodes of a particular class (or all
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1415 classes). The Node level permissions define logical permissions associated
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1416 with specific nodes by way of their user-linked properties.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1417
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1418
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1419 Access Control Interface Specification
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1421
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1422 The security module defines::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1423
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1424 class Permission:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1425 ''' Defines a Permission with the attributes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1426 - name
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1427 - description
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1428 - klass (optional)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1429
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1430 The klass may be unset, indicating that this permission is not
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1431 locked to a particular hyperdb class. There may be multiple
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1432 Permissions for the same name for different classes.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1433 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1434
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1435 class Role:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1436 ''' Defines a Role with the attributes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1437 - name
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1438 - description
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1439 - permissions
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1440 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1441
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1442 class Security:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1443 def __init__(self, db):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1444 ''' Initialise the permission and role stores, and add in the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1445 base roles (for admin user).
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1446 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1447
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1448 def getPermission(self, permission, classname=None):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1449 ''' Find the Permission matching the name and for the class, if the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1450 classname is specified.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1451
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1452 Raise ValueError if there is no exact match.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1453 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1454
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1455 def hasPermission(self, permission, userid, classname=None):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1456 ''' Look through all the Roles, and hence Permissions, and see if
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1457 "permission" is there for the specified classname.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1458 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1459
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1460 def hasNodePermission(self, classname, nodeid, **propspec):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1461 ''' Check the named properties of the given node to see if the
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1462 userid appears in them. If it does, then the user is granted
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1463 this permission check.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1464
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1465 'propspec' consists of a set of properties and values that
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1466 must be present on the given node for access to be granted.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1467
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1468 If a property is a Link, the value must match the property
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1469 value. If a property is a Multilink, the value must appear
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1470 in the Multilink list.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1471 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1472
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1473 def addPermission(self, **propspec):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1474 ''' Create a new Permission with the properties defined in
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1475 'propspec'
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1476 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1477
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1478 def addRole(self, **propspec):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1479 ''' Create a new Role with the properties defined in 'propspec'
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1480 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1481
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1482 def addPermissionToRole(self, rolename, permission):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1483 ''' Add the permission to the role's permission list.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1484
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1485 'rolename' is the name of the role to add permission to.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1486 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1487
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1488 Modules such as ``cgi_client.py`` and ``mailgw.py`` define their own
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1489 permissions like so (this example is ``cgi_client.py``)::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1490
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1491 def initialiseSecurity(security):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1492 ''' Create some Permissions and Roles on the security object
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1493
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1494 This function is directly invoked by security.Security.__init__()
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1495 as a part of the Security object instantiation.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1496 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1497 p = security.addPermission(name="Web Registration",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1498 description="Anonymous users may register through the web")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1499 security.addToRole('Anonymous', p)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1500
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1501 Detectors may also define roles in their init() function::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1502
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1503 def init(db):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1504 # register an auditor that checks that a user has the "May Resolve"
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1505 # Permission before allowing them to set an issue status to "resolved"
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1506 db.issue.audit('set', checkresolvedok)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1507 p = db.security.addPermission(name="May Resolve", klass="issue")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1508 security.addToRole('Manager', p)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1509
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1510 The instance dbinit module then has in ``open()``::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1511
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1512 # open the database - it must be modified to init the Security class
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1513 # from security.py as db.security
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1514 db = Database(instance_config, name)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1515
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1516 # add some extra permissions and associate them with roles
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1517 ei = db.security.addPermission(name="Edit", klass="issue",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1518 description="User is allowed to edit issues")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1519 db.security.addPermissionToRole('User', ei)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1520 ai = db.security.addPermission(name="View", klass="issue",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1521 description="User is allowed to access issues")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1522 db.security.addPermissionToRole('User', ai)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1523
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1524 In the dbinit ``init()``::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1525
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1526 # create the two default users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1527 user.create(username="admin", password=Password(adminpw),
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1528 address=instance_config.ADMIN_EMAIL, roles='Admin')
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1529 user.create(username="anonymous", roles='Anonymous')
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1530
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1531 Then in the code that matters, calls to ``hasPermission`` and
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1532 ``hasNodePermission`` are made to determine if the user has permission
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1533 to perform some action::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1534
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1535 if db.security.hasPermission('issue', 'Edit', userid):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1536 # all ok
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1537
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1538 if db.security.hasNodePermission('issue', nodeid, assignedto=userid):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1539 # all ok
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1540
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1541 Code in the core will make use of these methods, as should code in auditors in
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1542 custom templates. The htmltemplate will implement a new tag, ``<require>``
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1543 which has the form::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1544
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1545 <require permission="name,name,name" assignedto="$userid" status="open">
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1546 HTML to display if the user has the permission.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1547 <else>
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1548 HTML to display if the user does not have the permission.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1549 </require>
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1550
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1551 where:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1552
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1553 - the permission attribute gives a comma-separated list of permission names.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1554 These are checked in turn using ``hasPermission`` and requires one to
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1555 be OK.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1556 - the other attributes are lookups on the node using ``hasNodePermission``. If
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1557 the attribute value is "$userid" then the current user's userid is tested.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1558
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1559 Any of these tests must pass or the ``<require>`` check will fail. The section
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1560 of html within the side of the ``<else>`` that fails is remove from processing.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1561
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1562 Authentication of Users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1563 ~~~~~~~~~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1564
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1565 Users must be authenticated correctly for the above controls to work. This is
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1566 not done in the current mail gateway at all. Use of digital signing of
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1567 messages could alleviate this problem.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1568
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1569 The exact mechanism of registering the digital signature should be flexible,
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1570 with perhaps a level of trust. Users who supply their signature through their
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1571 first message into the tracker should be at a lower level of trust to those
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1572 who supply their signature to an admin for submission to their user details.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1573
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1574
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1575 Anonymous Users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1576 ~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1577
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1578 The "anonymous" user must always exist, and defines the access permissions for
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1579 anonymous users. Unknown users accessing Roundup through the web or email
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1580 interfaces will be logged in as the "anonymous" user.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1581
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1582
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1583 Use Cases
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1584 ~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1585
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1586 public - end users can submit bugs, request new features, request support
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1587 The Users would be given the default "User" Role which gives "View" and
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1588 "Edit" Permission to the "issue" class.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1589 developer - developers can fix bugs, implement new features, provide support
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1590 A new Role "Developer" is created with the Permission "Fixer" which is
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1591 checked for in custom auditors that see whether the issue is being
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1592 resolved with a particular resolution ("fixed", "implemented",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1593 "supported") and allows that resolution only if the permission is
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1594 available.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1595 manager - approvers/managers can approve new features and signoff bug fixes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1596 A new Role "Manager" is created with the Permission "Signoff" which is
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1597 checked for in custom auditors that see whether the issue status is being
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1598 changed similar to the developer example.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1599 admin - administrators can add users and set user's roles
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1600 The existing Role "Admin" has the Permissions "Edit" for all classes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1601 (including "user") and "Web Roles" which allow the desired actions.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1602 system - automated request handlers running various report/escalation scripts
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1603 A combination of existing and new Roles, Permissions and auditors could
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1604 be used here.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1605 privacy - issues that are only visible to some users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1606 A new property is added to the issue which marks the user or group of
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1607 users who are allowed to view and edit the issue. An auditor will check
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1608 for edit access, and the htmltemplate <require> tag can check for view
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1609 access.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1610
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1611
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1612 Deployment Scenarios
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1613 --------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1614
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1615 The design described above should be general enough
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1616 to permit the use of Roundup for bug tracking, managing
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1617 projects, managing patches, or holding discussions. By
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1618 using nodes of multiple types, one could deploy a system
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1619 that maintains requirement specifications, catalogs bugs,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1620 and manages submitted patches, where patches could be
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1621 linked to the bugs and requirements they address.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1622
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1623
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1624 Acknowledgements
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1625 ----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1626
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1627 My thanks are due to Christy Heyl for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1628 reviewing and contributing suggestions to this paper
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1629 and motivating me to get it done, and to
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1630 Jesse Vincent, Mark Miller, Christopher Simons,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1631 Jeff Dunmall, Wayne Gramlich, and Dean Tribble for
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1632 their assistance with the first-round submission.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1633
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1634 Changes to this document
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1635 ------------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1636
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1637 - Added Boolean and Number types
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1638 - Added section Hyperdatabase Implementations
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1639 - "Item" has been renamed to "Issue" to account for the more specific nature
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1640 of the Class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1641
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1642
Roundup Issue Tracker: http://roundup-tracker.org/