Mercurial > p > roundup > code

annotate doc/design.txt @ 1661:b9c1226cb600

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