annotate doc/design.txt @ 3696:790363e96852

Sorting/grouping by multiple properties. - Implement sorting/grouping by multiple properties for the web interface. I'm now using @sort0/@sortdir0,@sort1/@sortdir1,... and @group0/@groupdir0,... when generating URLs from a search template. These are converted to a list internally. When saving URLs (e.g. when storing queries) I'm using @sort=prop1,prop2,... and @group=... with optional '-' prepended to individual props. This means saved URLs are backward compatible with existing trackers (and yes, this was a design goal). I need the clumsy version with @sort0,@sort1 etc, because I'm currently using several selectors and checkboxes (as the classic template does, too). I don't think there is a way around that in HTML? - Updated (hopefully all) documentation to reflect the new URL format and the consequences in the web-interface. - I've set the number of sort/group properties in the classic template to two -- this can easily be reverted by changing n_sort to 1. Richard, would you look over these changes? I've set a tag before and (will set) after commit, so that it would be easy to merge out. Don't be too scared about the size of the change, most is documentation, the guts are in cgi/templating.py and small changes in the classic template.
author Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
date Wed, 30 Aug 2006 20:28:26 +0000
parents 193f316dbbe9
children 0d561b24ceff
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
3527
8ee9b38789af *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3490
diff changeset
5 :Authors: Ka-Ping Yee (original), Richard Jones (implementation)
907
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 .. contents::
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 Introduction
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
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
12 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
13 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
14 to guide an implementation. For the philosophy and rationale behind the
3527
8ee9b38789af *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3490
diff changeset
15 Roundup design, see the first-round Software Carpentry `submission for
8ee9b38789af *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3490
diff changeset
16 Roundup`__. This document fleshes out that design as well as specifying
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 interfaces so that the components can be developed separately.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
3527
8ee9b38789af *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3490
diff changeset
19 __ spec.html
8ee9b38789af *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3490
diff changeset
20
907
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
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
29 ________________________________________________________________
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
30 | E-mail Client | Web Browser | Detector Scripts | Shell |
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
31 |---------------+---------------+--------------------+-----------|
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
32 | E-mail User | Web User | Detector | Command |
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
33 |----------------------------------------------------------------|
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
34 | Roundup Database Layer |
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
35 |----------------------------------------------------------------|
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
36 | Hyperdatabase Layer |
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
37 |----------------------------------------------------------------|
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
38 | Storage Layer |
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
39 ----------------------------------------------------------------
907
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
2951
2e3f3204afc9 merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2817
diff changeset
53 hyperdatabase is a flexible data store that can hold configurable data
2e3f3204afc9 merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2817
diff changeset
54 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
2951
2e3f3204afc9 merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2817
diff changeset
57 external module for storing its data. The "batteries-includes" distribution
2e3f3204afc9 merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2817
diff changeset
58 implements the hyperdatabase on the standard anydbm module. The storage
2817
80f7559933b8 bsddb is removed; stop suggesting it. suggest sqlite instead.
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2131
diff changeset
59 layer could be a third-party RDBMS; for a low-maintenance solution,
80f7559933b8 bsddb is removed; stop suggesting it. suggest sqlite instead.
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2131
diff changeset
60 implementing the hyperdatabase on the SQLite RDBMS is suggested.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61
2951
2e3f3204afc9 merge from maint-0-7
Richard Jones <richard@users.sourceforge.net>
parents: 2817
diff changeset
62
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 Dates and Date Arithmetic
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 ~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
66 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
67 dates. The hyperdatabase module provides Timestamp objects for
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
68 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
69 date-and-time intervals.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
71 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
72 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
73 (``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
74 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
75 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
76 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
77 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
78 format is always exactly 19 characters long.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
80 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
81 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
82 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
83 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
84 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
85 ``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
86 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
87 Standard Time.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 - "2000-04-17" means <Date 2000-04-17.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 - "01-25" means <Date yyyy-01-25.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 - "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
92 - "08-13.22:13" means <Date yyyy-08-14.03:13:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 - "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
94 - "14:25" means
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 - <Date yyyy-mm-dd.19:25:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 - "8:47:11" means
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 - <Date yyyy-mm-dd.13:47:11>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 - the special date "." means "right now"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
101 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
102 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
103 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
104 may not).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 - "3y" means three years
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 - "2y 1m" means two years and one month
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 - "1m 25d" means one month and 25 days
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 - "2w 3d" means two weeks and three days
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 - "1d 2:50" means one day, two hours, and 50 minutes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 - "14:00" means 14 hours
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112 - "0:04:33" means four minutes and 33 seconds
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
115 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
116 *stamp* ``+`` *interval* and *stamp* ``-`` *interval*. When adding or
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
117 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
118 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
119 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
120 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
121 40 or 41 days).
907
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 Here is an outline of the Date and Interval classes::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 class Date:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 def __init__(self, spec, offset):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
127 """Construct a date given a specification and a time zone
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
128 offset.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 'spec' is a full date or a partial form, with an optional
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 added or subtracted interval. 'offset' is the local time
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 zone offset from GMT in hours.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 """
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 __add__(self, interval):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 """Add an interval to 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 __sub__(self, interval):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
139 """Subtract an interval from this date to produce another
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
140 date.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
141 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 def __cmp__(self, other):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 """Compare this date to another date."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 def __str__(self):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
147 """Return this date as a string in the yyyy-mm-dd.hh:mm:ss
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
148 format.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
149 """
907
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 local(self, offset):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
152 """Return this date as yyyy-mm-dd.hh:mm:ss in a local time
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
153 zone.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
154 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 class Interval:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 def __init__(self, spec):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 """Construct an interval given a specification."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 def __cmp__(self, other):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 """Compare this interval to another interval."""
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 def __str__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 """Return this interval as a string."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 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
169 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
170 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
171
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 >>> Date(".")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 <Date 2000-06-26.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 >>> _.local(-5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 "2000-06-25.19:34:02"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 >>> Date(". + 2d")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 <Date 2000-06-28.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 >>> Date("1997-04-17", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 <Date 1997-04-17.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 >>> Date("01-25", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 <Date 2000-01-25.00:00:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 >>> Date("08-13.22:13", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183 <Date 2000-08-14.03:13:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 >>> Date("14:25", -5)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185 <Date 2000-06-25.19:25:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186 >>> Interval(" 3w 1 d 2:00")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 <Interval 22d 2:00>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 >>> Date(". + 2d") - Interval("3w")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 <Date 2000-06-07.00:34:02>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
191
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
192 Items and Classes
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193 ~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
195 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
196 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
197 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
198 permits the creation and modification of classes as well as items.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
200
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 Identifiers and Designators
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
204 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
205 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
206 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
207 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
208 class concatenated with the item's numeric identifier.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
210 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
211 class "spam" has id 1 and designator "spam1". The first item created in
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
212 class "eggs" also has id 1 but has the distinct designator "eggs1". Item
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
213 designators are conventionally enclosed in square brackets when
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
214 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
215 "[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
216
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
217
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 Property Names and Types
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 ~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 Property names must begin with a letter.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 A property may be one of five basic types:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225 - String properties are for storing arbitrary-length strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 - Boolean properties are for storing true/false, or yes/no values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 - Number properties are for storing numeric values.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
231 - 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
232 objects.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
234 - 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
235 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
236 integer, the id of the chosen item.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
238 - 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
239 class. The value is a list of integers.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
241 *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
242 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
243
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 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
245 operation.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
247
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 Hyperdb Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
251 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
252
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
253 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
254 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
255 properties belong in classes::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 class String:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 def __init__(self, indexme='no'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 """An object designating a String property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 class Boolean:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 """An object designating a Boolean property."""
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 class Number:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 """An object designating a Number property."""
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 Date:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270 def __init__(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 """An object designating a Date property."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273 class Link:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274 def __init__(self, classname, do_journal='yes'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 """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
276 items in a specified class.
907
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 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
279 the property are not journalled in the linked item.
907
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
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 class Multilink:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283 def __init__(self, classname, do_journal='yes'):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 """An object designating a Multilink property that links
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
285 to items in a specified class.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 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
288 the property are not journalled in the linked item(s).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292 Here is the interface provided by the hyperdatabase::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 class Database:
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
295 """A database for storing records containing flexible data
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
296 types.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
297 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
299 def __init__(self, config, journaltag=None):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300 """Open a hyperdatabase given a specifier to some storage.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
302 The 'storagelocator' is obtained from config.DATABASE. The
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
303 meaning of 'storagelocator' depends on the particular
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
304 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
305 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
306 to a database over the network, etc.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
308 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
309 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
310 '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
311 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
312 Class.restore() methods are disabled.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 def __getattr__(self, classname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316 """A convenient way of calling self.getclass(classname)."""
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 def getclasses(self):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319 """Return a list of the names of all existing classes."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 def getclass(self, classname):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 """Get the Class object representing a particular class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
324 If 'classname' is not a valid class name, a KeyError is
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
325 raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 """
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 class Class:
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
329 """The handle to a particular class of items in a hyperdatabase.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
330 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 def __init__(self, db, classname, **properties):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
333 """Create a new class with a given name and property
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
334 specification.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
335
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
336 'classname' must not collide with the name of an existing
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
337 class, or a ValueError is raised. The keyword arguments in
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
338 'properties' must map names to property objects, or a
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
339 TypeError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
341 A proxied reference to the database is available as the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
342 'db' attribute on instances. For example, in
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
343 'IssueClass.send_message', the following is used to lookup
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
344 users, messages and files::
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
345
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
346 users = self.db.user
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
347 messages = self.db.msg
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
348 files = self.db.file
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
351 # Editing items:
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353 def create(self, **propvalues):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
354 """Create a new item of this class and return its id.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
356 The keyword arguments in 'propvalues' map property names to
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
357 values. The values of arguments must be acceptable for the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
358 types of their corresponding properties or a TypeError is
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
359 raised. If this class has a key property, it must be
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
360 present and its value must not collide with other key
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
361 strings or a ValueError is raised. Any other properties on
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
362 this class that are missing from the 'propvalues' dictionary
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
363 are set to None. If an id in a link or multilink property
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
364 does not refer to a valid item, an IndexError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
367 def get(self, itemid, propname):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
368 """Get the value of a property on an existing item of this
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
369 class.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
371 'itemid' must be the id of an existing item of this class or
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
372 an IndexError is raised. 'propname' must be the name of a
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
373 property of this class or a KeyError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
376 def set(self, itemid, **propvalues):
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
377 """Modify a property on an existing item of this class.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
379 'itemid' must be the id of an existing item of this class or
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
380 an IndexError is raised. Each key in 'propvalues' must be
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
381 the name of a property of this class or a KeyError is
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
382 raised. All values in 'propvalues' must be acceptable types
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
383 for their corresponding properties or a TypeError is raised.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
384 If the value of the key property is set, it must not collide
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
385 with other key strings or a ValueError is raised. If the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
386 value of a Link or Multilink property contains an invalid
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
387 item id, a ValueError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
390 def retire(self, itemid):
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
391 """Retire an item.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
393 The properties on the item remain available from the get()
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
394 method, and the item's id is never reused. Retired items
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
395 are not returned by the find(), list(), or lookup() methods,
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
396 and other items may reuse the values of their key
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
397 properties.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399
1519
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
400 def restore(self, nodeid):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
401 '''Restore a retired node.
1519
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
402
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
403 Make node available for all operations like it was before
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
404 retirement.
1519
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
405 '''
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
406
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
407 def history(self, itemid):
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
408 """Retrieve the journal of edits on a particular item.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
410 'itemid' must be the id of an existing item of this class or
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
411 an IndexError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413 The returned list contains tuples of the form
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 (date, tag, action, params)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
417 'date' is a Timestamp object specifying the time of the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
418 change and 'tag' is the journaltag specified when the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
419 database was opened. 'action' may be:
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
421 'create' or 'set' -- 'params' is a dictionary of
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
422 property values
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
423 'link' or 'unlink' -- 'params' is (classname, itemid,
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
424 propname)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425 'retire' -- 'params' is None
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
428 # Locating items:
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 def setkey(self, propname):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
431 """Select a String property of this class to be the key
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
432 property.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
434 'propname' must be the name of a String property of this
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
435 class or None, or a TypeError is raised. The values of the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
436 key property on all existing items must be unique or a
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
437 ValueError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438 """
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 getkey(self):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
441 """Return the name of the key property for this class or
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
442 None.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
443 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 def lookup(self, keyvalue):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
446 """Locate a particular item by its key property and return
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
447 its id.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
449 If this class has no key property, a TypeError is raised.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
450 If the 'keyvalue' matches one of the values for the key
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
451 property among the items in this class, the matching item's
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
452 id is returned; otherwise a KeyError is raised.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454
3239
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
455 def find(self, **propspec):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
456 """Get the ids of items in this class which link to the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
457 given items.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
458
3239
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
459 'propspec' consists of keyword args propname=itemid or
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
460 propname={<itemid 1>:1, <itemid 2>: 1, ...}
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
461 'propname' must be the name of a property in this class,
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
462 or a KeyError is raised. That property must
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
463 be a Link or Multilink property, or a TypeError
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
464 is raised.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
465
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
466 Any item in this class whose 'propname' property links to
3239
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
467 any of the itemids will be returned. Examples::
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
468
3239
440f0a6a2e3c merge from maint-0-8
Richard Jones <richard@users.sourceforge.net>
parents: 3117
diff changeset
469 db.issue.find(messages='1')
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
470 db.issue.find(messages={'1':1,'3':1}, files={'7':1})
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
473 def filter(self, search_matches, filterspec, sort, group):
3682
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
474 """Return a list of the ids of the active nodes in this class that
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
475 match the 'filter' spec, sorted by the group spec and then the
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
476 sort spec.
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
477
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
478 "filterspec" is {propname: value(s)}
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
479
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
480 "sort" and "group" are [(dir, prop), ...] where dir is '+', '-'
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
481 or None and prop is a prop name or None. Note that for
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
482 backward-compatibility reasons a single (dir, prop) tuple is
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
483 also allowed.
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
484
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
485 "search_matches" is {nodeid: marker}
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
486
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
487 The filter must match all properties specificed. If the property
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
488 value to match is a list:
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
489
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
490 1. String properties must match all elements in the list, and
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
491 2. Other properties must match any of the elements in the list.
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
492
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
493 Note that now the propname in filterspec and prop in a
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
494 sort/group spec may be transitive, i.e., it may contain
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
495 properties of the form link.link.link.name, e.g. you can search
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
496 for all issues where a message was added by a certain user in
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
497 the last week with a filterspec of
193f316dbbe9 More transitive-property support.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3527
diff changeset
498 {'messages.author' : '42', 'messages.creation' : '.-1w;'}
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
499 """
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
500
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 def list(self):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
502 """Return a list of the ids of the active items in this
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
503 class.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
504 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 def count(self):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
507 """Get the number of items in this class.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
509 If the returned integer is 'numitems', the ids of all the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
510 items in this class run from 1 to numitems, and numitems+1
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
511 will be the id of the next item to be created in this class.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514 # Manipulating properties:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516 def getprops(self):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
517 """Return a dictionary mapping property names to property
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
518 objects.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
519 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521 def addprop(self, **properties):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 """Add properties to this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
524 The keyword arguments in 'properties' must map names to
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
525 property objects, or a TypeError is raised. None of the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
526 keys in 'properties' may collide with the names of existing
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
527 properties, or a ValueError is raised before any properties
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
528 have been added.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
531 def getitem(self, itemid, cache=1):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
532 """ 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
533
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
534 'itemid' must be the id of an existing item of this class or
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
535 an IndexError is raised.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
536
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
537 'cache' indicates whether the transaction cache should be
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
538 queried for the item. If the item has been modified and you
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
539 need to determine what its values prior to modification are,
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
540 you need to set cache=0.
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
541 """
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
542
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
543 class Item:
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
544 """ A convenience wrapper for the given item. It provides a
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
545 mapping interface to a single item's properties
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
546 """
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548 Hyperdatabase Implementations
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
551 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
552 the `hyperdb interface specification`_ over an existing storage
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
553 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
554 and so on.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
556 Several implementations are provided - they belong in the
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
557 ``roundup.backends`` package.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 Application Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 ~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
563 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
564 practice::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566 >>> import hyperdb
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567 >>> db = hyperdb.Database("foo.db", "ping")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 >>> db
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569 <hyperdb.Database "foo.db" opened by "ping">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 >>> hyperdb.Class(db, "status", name=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 <hyperdb.Class "status">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572 >>> _.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 >>> db.status.create(name="unread")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574 1
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 >>> db.status.create(name="in-progress")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 >>> db.status.create(name="testing")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578 3
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 >>> db.status.create(name="resolved")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 >>> db.status.count()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 >>> db.status.list()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 [1, 2, 3, 4]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585 >>> db.status.lookup("in-progress")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 >>> db.status.retire(3)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 >>> db.status.list()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 [1, 2, 4]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 >>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 <hyperdb.Class "issue">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 >>> db.issue.create(title="spam", status=1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 1
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 >>> db.issue.create(title="eggs", status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 >>> db.issue.create(title="ham", status=4)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 3
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 >>> db.issue.create(title="arguments", status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 4
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600 >>> db.issue.create(title="abuse", status=1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 5
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
602 >>> hyperdb.Class(db, "user", username=hyperdb.Key(),
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
603 ... password=hyperdb.String())
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 <hyperdb.Class "user">
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 >>> db.issue.addprop(fixer=hyperdb.Link("user"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606 >>> db.issue.getprops()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 {"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 "user": <hyperdb.Link to "user">}
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 >>> db.issue.set(5, status=2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 >>> db.issue.get(5, "status")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 2
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612 >>> db.status.get(2, "name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613 "in-progress"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 >>> db.issue.get(5, "title")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 "abuse"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616 >>> db.issue.find("status", db.status.lookup("in-progress"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 [2, 4, 5]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
618 >>> db.issue.history(5)
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
619 [(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse",
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
620 "status": 1}),
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621 (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
622 >>> db.status.history(1)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623 [(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624 (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625 >>> db.status.history(2)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
626 [(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
627
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
629 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
630 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
631 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
632 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
633 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
634
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 Roundup Database
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637 ----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
639 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
640 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
641 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
642 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
643 lists, and superseders.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
644
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
645
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646 Reserved Classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647 ~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
648
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
649 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
650 are not issues.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
652 Users
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
653 """""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
655 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
656 "user" class has the definition::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
657
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
658 hyperdb.Class(db, "user", username=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
659 password=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
660 address=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
661 db.user.setkey("username")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
662
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
663 Messages
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
664 """"""""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
665
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
666 E-mail messages are represented by hyperdatabase items of class "msg".
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
667 The actual text content of the messages is stored in separate files.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
668 (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
669 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
670 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
671 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
672 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
673 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
674 definition::
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 hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
677 recipients=hyperdb.Multilink("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678 date=hyperdb.Date(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679 summary=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680 files=hyperdb.Multilink("file"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
682 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
683 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
684 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
685 display in a message index.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
686
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
687
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
688 Files
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
689 """""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
690
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
691 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
692 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
693 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
694 "file" class has the definition::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
695
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
696 hyperdb.Class(db, "file", user=hyperdb.Link("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
697 name=hyperdb.String(),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
698 type=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
699
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
700 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
701 "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
702 property holds the MIME type of the file as received.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
703
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
704
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
705 Issue Classes
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
706 ~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
707
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
708 All issues have the following standard properties:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
709
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
710 =========== ==========================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
711 Property Definition
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
712 =========== ==========================
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
713 title hyperdb.String()
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
714 messages hyperdb.Multilink("msg")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
715 files hyperdb.Multilink("file")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
716 nosy hyperdb.Multilink("user")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
717 superseder hyperdb.Multilink("issue")
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
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
720 Also, two Date properties named "creation" and "activity" are fabricated
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
721 by the Roundup database layer. Two user Link properties, "creator" and
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
722 "actor" are also fabricated. By "fabricated" we mean that no such
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
723 properties are actually stored in the hyperdatabase, but when properties
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
724 on issues are requested, the "creation"/"creator" and "activity"/"actor"
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
725 properties are made available. The value of the "creation"/"creator"
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
726 properties relate to issue creation, and the value of the "activity"/
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
727 "actor" properties relate to the last editing of any property on the issue
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
728 (equivalently, these are the dates on the first and last records in the
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
729 issue's journal).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
730
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
731
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
732 Roundupdb Interface Specification
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
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
735 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
736 hyperdatabase, except for the following changes and additional methods::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
737
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
738 class Database:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
739 def getuid(self):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
740 """Return the id of the "user" item associated with the user
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
741 that owns this connection to the hyperdatabase."""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
742
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
743 class Class:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
744 # Overridden methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
745
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
746 def create(self, **propvalues):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
747 def set(self, **propvalues):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
748 def retire(self, itemid):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
749 """These operations trigger detectors and can be vetoed.
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
750 Attempts to modify the "creation", "creator", "activity"
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
751 properties or "actor" cause a KeyError.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
753
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
754 class IssueClass(Class):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
755 # Overridden methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
756
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 def __init__(self, db, classname, **properties):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
758 """The newly-created class automatically includes the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
759 "messages", "files", "nosy", and "superseder" properties.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
760 If the 'properties' dictionary attempts to specify any of
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
761 these properties or a "creation", "creator", "activity" or
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
762 "actor" property, a ValueError is raised."""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
764 def get(self, itemid, propname):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765 def getprops(self):
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
766 """In addition to the actual properties on the item, these
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
767 methods provide the "creation", "creator", "activity" and
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
768 "actor" properties."""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770 # New methods:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
772 def addmessage(self, itemid, summary, text):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773 """Add a message to an issue's mail spool.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
775 A new "msg" item is constructed using the current date, the
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 user that owns the database connection as the author, and
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777 the specified summary text. The "files" and "recipients"
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 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
779 of the message and the item is appended to the "messages"
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780 field of the specified issue.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782
1675
eb3c348676ed Updated deprecated 'sendmessage' to current 'nosymessage'
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1661
diff changeset
783 def nosymessage(self, itemid, msgid):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784 """Send a message to the members of an issue's nosy list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
786 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
787 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
788 users are then added to the message's "recipients" list.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 Default Schema
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793 ~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
795 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
796 software bug tracker. The database is set up like this::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
798 pri = Class(db, "priority", name=hyperdb.String(),
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
799 order=hyperdb.String())
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800 pri.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
801 pri.create(name="critical", order="1")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
802 pri.create(name="urgent", order="2")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803 pri.create(name="bug", order="3")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804 pri.create(name="feature", order="4")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805 pri.create(name="wish", order="5")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
806
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
807 stat = Class(db, "status", name=hyperdb.String(),
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
808 order=hyperdb.String())
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809 stat.setkey("name")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810 stat.create(name="unread", order="1")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 stat.create(name="deferred", order="2")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812 stat.create(name="chatting", order="3")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813 stat.create(name="need-eg", order="4")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 stat.create(name="in-progress", order="5")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815 stat.create(name="testing", order="6")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816 stat.create(name="done-cbb", order="7")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 stat.create(name="resolved", order="8")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819 Class(db, "keyword", name=hyperdb.String())
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 Class(db, "issue", fixer=hyperdb.Multilink("user"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822 topic=hyperdb.Multilink("keyword"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823 priority=hyperdb.Link("priority"),
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824 status=hyperdb.Link("status"))
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 (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
827 Web user interface for sorting.)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
829 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
830 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
831 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
832 "priority" and "status" classes::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 def Choice(name, *options):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
835 cl = Class(db, name, name=hyperdb.String(),
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
836 order=hyperdb.String())
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 for i in range(len(options)):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838 cl.create(name=option[i], order=i)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 return hyperdb.Link(name)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 Detector Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 ------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
845 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
846 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
847 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
848 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
849 ``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
850 to provide it a chance to register its detectors.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 There are two kinds of detectors:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
854 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
855 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
856
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
857 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
858 ``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
859 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
860 may raise a *Reject* exception to abort the operation.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
861
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
862 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
863 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
864 *reactors* that have been registered for the operation.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
865
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
866
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
867 Detector Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
868 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
869
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
870 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
871 class of items::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
872
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873 class Class:
3490
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
874 def audit(self, event, detector, priority=100):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875 """Register an auditor on this class.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
877 '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
878 "restore". 'detector' should be a function accepting four
3490
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
879 arguments. Detectors are called in priority order, execution
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
880 order is undefined for detectors with the same priority.
907
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
3490
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
883 def react(self, event, detector, priority=100):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884 """Register a reactor on this class.
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 '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
887 "restore". 'detector' should be a function accepting four
3490
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
888 arguments. Detectors are called in priority order, execution
976bd292eaa0 db detectors got priority numbers (rfe [SF#1413165])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3239
diff changeset
889 order is undefined for detectors with the same priority.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890 """
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 Auditors are called with the arguments::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
894 audit(db, cl, itemid, newdata)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
896 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
897 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
898 property names to values.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
900 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
901 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
902 is about to be created.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
904 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
905 properties that are about to be changed.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906
1519
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
907 For a ``retire()`` or ``restore()`` operation, newdata is None.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909 Reactors are called with the arguments::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
911 react(db, cl, itemid, olddata)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
913 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
914 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
915 property names to values.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
916
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
917 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
918 newly-created item and ``olddata`` is None.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
919
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
920 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
921 values of properties that were changed.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
922
1519
6fede2aa6a12 added ability to restore retired nodes
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1244
diff changeset
923 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
924 the retired or restored item and ``olddata`` is None.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
925
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
926
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
927 Detector Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
928 ~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
929
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
930 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
931 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
932 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
933 proceeds when it has three approvals::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
934
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
935 # Permit users only to add themselves to the "approvals" list.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
936
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
937 def check_approvals(db, cl, id, newdata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
938 if newdata.has_key("approvals"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
939 if cl.get(id, "status") == db.status.lookup("approved"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
940 raise Reject, "You can't modify the approvals list " \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
941 "for a project that has already been approved."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
942 old = cl.get(id, "approvals")
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
943 new = newdata["approvals"]
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
944 for uid in old:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
945 if uid not in new and uid != db.getuid():
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
946 raise Reject, "You can't remove other users from " \
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
947 "the approvals list; you can only remove " \
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
948 "yourself."
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
949 for uid in new:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
950 if uid not in old and uid != db.getuid():
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
951 raise Reject, "You can't add other users to the " \
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
952 "approvals list; you can only add yourself."
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
953
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
954 # When three people have approved a project, change its status from
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
955 # "pending" to "approved".
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
956
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
957 def approve_project(db, cl, id, olddata):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
958 if (olddata.has_key("approvals") and
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
959 len(cl.get(id, "approvals")) == 3):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
960 if cl.get(id, "status") == db.status.lookup("pending"):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
961 cl.set(id, status=db.status.lookup("approved"))
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
962
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
963 def init(db):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
964 db.project.audit("set", check_approval)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
965 db.project.react("set", approve_project)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
966
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
967 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
968 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
969 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
970 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
971 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
972 to "applied"::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
973
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
974 # Only accept attempts to create new patches that come with patch
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
975 # files.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
976
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
977 def check_new_patch(db, cl, id, newdata):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
978 if not newdata["files"]:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
979 raise Reject, "You can't submit a new patch without " \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
980 "attaching a patch file."
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
981 for fileid in newdata["files"]:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
982 if db.file.get(fileid, "type") != "text/plain":
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
983 raise Reject, "Submitted patch files must be " \
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
984 "text/plain."
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
985
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
986 # When the status is changed from "approved" to "applied", apply the
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
987 # patch.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
988
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
989 def apply_patch(db, cl, id, olddata):
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
990 if (cl.get(id, "status") == db.status.lookup("applied") and
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
991 olddata["status"] == db.status.lookup("approved")):
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
992 # ...apply the patch...
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 def init(db):
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
995 db.patch.audit("create", check_new_patch)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
996 db.patch.react("set", apply_patch)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
997
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
998
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
999 Command Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1000 -----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1001
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1002 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
1003 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
1004 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
1005 module.)
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1006
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1007
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1008 Command Interface Specification
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1009 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1010
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1011 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
1012 from the command line::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1013
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1014 roundup-admin help
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1015 roundup-admin get [-list] designator[, designator,...] propname
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1016 roundup-admin set designator[, designator,...] propname=value ...
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1017 roundup-admin find [-list] classname propname=value ...
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1018
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1019 See ``roundup-admin help commands`` for a complete list of commands.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1020
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1021 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
1022 the printed results:
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1023
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1024 - Strings are, well, strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1025
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1026 - Numbers are displayed the same as strings.
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1027
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1028 - Booleans are displayed as 'Yes' or 'No'.
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 - 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
1031 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
1032 explained above.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1033
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1034 - 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
1035 argument, item designators and key strings are both accepted.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1036
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1037 - 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
1038 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
1039 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
1040 joined by commas is accepted.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1041
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1042 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
1043 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
1044 listed 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 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
1047 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
1048 (with the -list) option.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1049
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1050
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1051 Usage Example
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1052 ~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1053
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1054 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
1055 "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
1056 directory where the database dumps its files::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1057
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1058 shell% for issue in `roundup find issue status=in-progress`; do
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1059 > grep -l spam `roundup get $issue messages`
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1060 > done
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1061 msg23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1062 msg49
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1063 msg50
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1064 msg61
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1065 shell%
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1066
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1067 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
1068
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1069 shell% grep -l spam `roundup get \
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1070 \`roundup find -list issue status=in-progress\` messages`
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1071 msg23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1072 msg49
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1073 msg50
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1074 msg61
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1075 shell%
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1076
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1077
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1078 E-mail User Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1079 ---------------------
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 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
1082 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
1083 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
1084 "|" for sendmail).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1085
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1086
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1087 Message Processing
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1088 ~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1089
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1090 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
1091 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
1092 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
1093 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
1094 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
1095 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
1096 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
1097 the "msg" item.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1098
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1099 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
1100 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
1101 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
1102 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
1103 "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
1104 becomes the summary of the message.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1105
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1106 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
1107 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
1108 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
1109 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
1110 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
1111 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
1112 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
1113 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
1114 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
1115 that prevents the creation of user items with no passwords.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1116
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1117 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
1118 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
1119 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
1120 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
1121 prefixes).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1122
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1123 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
1124 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
1125 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
1126 the issue.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1127
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1128 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
1129 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
1130 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
1131 new "file" items.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1132
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1133 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
1134 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
1135 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
1136 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
1137 with the explanatory message given in the exception.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1138
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1139
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1140 Nosy Lists
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1141 ~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1142
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1143 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
1144 "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
1145 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
1146 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
1147 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
1148 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
1149 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
1150 the message was sent to whom.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1151
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1152
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1153 Setting Properties
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1154 ~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1155
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1156 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
1157 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
1158 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
1159 roundup ``set`` shell command.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1160
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1161
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1162 Web User Interface
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1163 ------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1164
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1165 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
1166 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
1167 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
1168 for quick out-of-the-box deployment.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1169
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1170 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
1171 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
1172 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
1173 replaced by properties and their values.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1174
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1175
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1176 Views and View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1177 ~~~~~~~~~~~~~~~~~~~~~~~~~
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 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
1180 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
1181 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
1182 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
1183 issue.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1184
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1185 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
1186 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
1187 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
1188 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
1189 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
1190 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
1191
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1192
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1193 Displaying Properties
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1194 ~~~~~~~~~~~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1195
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1196 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
1197 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
1198 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
1199 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
1200 that property should be displayed in an editable field.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1201
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1202 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
1203 ``cgi.templating`` module.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1204
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1205 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
1206 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
1207 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
1208 occurrence of::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1209
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1210 tal:content="context/status/plain"
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1211
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1212 in a template triggers a call to::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1213
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1214 context['status'].plain()
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1215
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1216 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
1217 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
1218 the widgets that should be generated.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1219
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1220 Some of the standard displayer functions include:
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1221
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1222 ========= ==============================================================
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1223 Function Description
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1224 ========= ==============================================================
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1225 plain display a String property directly;
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1226 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
1227 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
1228 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
1229 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
1230 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
1231 text field to be edited
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1232 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
1233 ========= ==============================================================
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1234
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1235 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
1236
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1237
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1238 Index Views
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1239 ~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1240
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1241 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
1242 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
1243 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
1244
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1245
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1246 Index View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1247 """""""""""""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1248
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1249 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
1250 clarity)::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1251
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1252 /issue?status=unread,in-progress,resolved&
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1253 topic=security,ui&
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1254 :group=priority,-status&
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1255 :sort=-activity&
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1256 :filters=status,topic&
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1257 :columns=title,status,fixer
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1258
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1259
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1260 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
1261 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
1262 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
1263 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
1264 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
1265 items are selected for display.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1266
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1267 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
1268 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
1269 manipulated by clicking on the column headings in the table.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1270
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1271 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
1272 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
1273 of issues with values matching any specified Multilink properties.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1274
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1275 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
1276 "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
1277 and only issues with "topic" values including both "security" and "ui"
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1278 are displayed. The items are grouped by priority arranged in ascending
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1279 order and in descending order by status; and within groups, sorted by
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1280 activity, arranged in descending order. The filter section shows
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1281 filters for the "status" and "topic" properties, and the table includes
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3682
diff changeset
1282 columns for the "title", "status", and "fixer" properties.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1283
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1284 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
1285 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
1286 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
1287 4.4.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1288
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1289 Index Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1290 """""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1291
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1292 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
1293 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
1294 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
1295 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
1296 ``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
1297 of the property.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1298
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1299 Here's a simple example of an index template::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1300
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1301 <tr>
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1302 <td tal:condition="request/show/title"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1303 tal:content="contex/title"></td>
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1304 <td tal:condition="request/show/status"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1305 tal:content="contex/status"></td>
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1306 <td tal:condition="request/show/fixer"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1307 tal:content="contex/fixer"></td>
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1308 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1309
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1310 Sorting
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1311 """""""
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1312
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1313 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
1314 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
1315 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
1316 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
1317 according to how many links are present.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1318
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1319 Issue Views
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1320 ~~~~~~~~~~~
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1321
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1322 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
1323 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
1324 displayed.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1325
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1326 Issue View Specifiers
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1327 """""""""""""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1328
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1329 An issue view specifier is simply the issue's designator::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1330
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1331 /patch23
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1332
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1333
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1334 Editor Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1335 """"""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1336
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1337 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
1338 ``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
1339 appropriate widgets for editing properties.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1340
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1341 Here's an example of a basic editor template::
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1342
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1343 <table>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1344 <tr>
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1345 <td colspan=2
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1346 tal:content="python:context.title.field(size='60')"></td>
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1347 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1348 <tr>
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1349 <td tal:content="context/fixer/field"></td>
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1350 <td tal:content="context/status/menu"></td>
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1351 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1352 <tr>
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1353 <td tal:content="context/nosy/field"></td>
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1354 <td tal:content="context/priority/menu"></td>
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1355 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1356 <tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1357 <td colspan=2>
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1358 <textarea name=":note" rows=5 cols=60></textarea>
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1359 </td>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1360 </tr>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1361 </table>
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1362
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1363 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
1364 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
1365 change.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1366
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1367 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
1368 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
1369 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
1370 example of such a message might be this::
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1371
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1372 title: Polly Parrot is dead
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1373 priority: critical
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1374 status: unread -> in-progress
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1375 fixer: (none)
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1376 keywords: parrot,plumage,perch,nailed,dead
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1377
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1378 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
1379 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
1380 (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
1381 message to the nosy list).
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1382
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1383
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1384 Spool Section
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1385 """""""""""""
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1386
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1387 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
1388 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
1389 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
1390 its content.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1391
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1392 Access Control
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1393 --------------
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1394
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1395 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
1396 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
1397 is defined as a Permission.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1398
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1399 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
1400 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
1401 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
1402 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
1403 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
1404 they're defined when the application initialises.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1405
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1406 There will be three levels of Permission. The Class level permissions
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1407 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
1408 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
1409 permissions associated with specific items by way of their user-linked
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1410 properties. The Property level permissions define logical permissions
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1411 associated with a specific property of an item.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1412
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1413
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1414 Access Control Interface Specification
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1415 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1416
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1417 The security module defines::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1418
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1419 class Permission:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1420 ''' Defines a Permission with the attributes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1421 - name
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1422 - description
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1423 - klass (optional)
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1424 - properties (optional)
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1425 - check function (optional)
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1426
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1427 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
1428 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
1429 multiple Permissions for the same name for different
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1430 classes.
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1431
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1432 If property names are set, permission is restricted to those
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1433 properties only.
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1434
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1435 If check function is set, permission is granted only when
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1436 the function returns value interpreted as boolean true.
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2951
diff changeset
1437 The function is called with arguments db, userid, itemid.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1438 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1439
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1440 class Role:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1441 ''' Defines a Role with the attributes
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1442 - name
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1443 - description
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1444 - permissions
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1445 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1446
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1447 class Security:
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1448 def __init__(self, db):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1449 ''' 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
1450 the base roles (for admin user).
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1451 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1452
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1453 def getPermission(self, permission, classname=None, properties=None,
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1454 check=None):
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1455 ''' Find the Permission exactly matching the name, class,
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1456 properties list and check function.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1457
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1458 Raise ValueError if there is no exact match.
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1459 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1460
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1461 def hasPermission(self, permission, userid, classname=None,
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1462 property=None, itemid=None):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1463 ''' Look through all the Roles, and hence Permissions, and
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1464 see if "permission" exists given the constraints of
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1465 classname, property and itemid.
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1466
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1467 If classname is specified (and only classname) then the
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1468 search will match if there is *any* Permission for that
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1469 classname, even if the Permission has additional
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1470 constraints.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1471
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1472 If property is specified, the Permission matched must have
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1473 either no properties listed or the property must appear in
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1474 the list.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1475
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1476 If itemid is specified, the Permission matched must have
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1477 either no check function defined or the check function,
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1478 when invoked, must return a True value.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1479
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1480 Note that this functionality is actually implemented by the
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1481 Permission.test() method.
910
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
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1484 def addPermission(self, **propspec):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1485 ''' Create a new Permission with the properties defined in
3117
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1486 'propspec'. See the Permission class for the possible
460eb0209a9e Permissions improvements.
Richard Jones <richard@users.sourceforge.net>
parents: 2983
diff changeset
1487 keyword args.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1488 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1489
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1490 def addRole(self, **propspec):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1491 ''' 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
1492 'propspec'
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1493 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1494
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1495 def addPermissionToRole(self, rolename, permission):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1496 ''' 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
1497
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1498 '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
1499 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1500
1039
42924a2fcacf minor doc change for new cgi
Richard Jones <richard@users.sourceforge.net>
parents: 910
diff changeset
1501 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
1502 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
1503
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1504 def initialiseSecurity(security):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1505 ''' 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
1506
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1507 This function is directly invoked by
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1508 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
1509 object instantiation.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1510 '''
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1511 p = security.addPermission(name="Web Registration",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1512 description="Anonymous users may register through the web")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1513 security.addToRole('Anonymous', p)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1514
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1515 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
1516
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1517 def init(db):
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1518 # 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
1519 # 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
1520 # status to "resolved"
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1521 db.issue.audit('set', checkresolvedok)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1522 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
1523 security.addToRole('Manager', p)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1524
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
1525 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
1526
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1527 # 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
1528 # from security.py as db.security
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
1529 db = Database(config, name)
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1530
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1531 # 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
1532 ei = db.security.addPermission(name="Edit", klass="issue",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1533 description="User is allowed to edit issues")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1534 db.security.addPermissionToRole('User', ei)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1535 ai = db.security.addPermission(name="View", klass="issue",
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1536 description="User is allowed to access issues")
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1537 db.security.addPermissionToRole('User', ai)
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1538
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1539 In the dbinit ``init()``::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1540
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1541 # create the two default users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1542 user.create(username="admin", password=Password(adminpw),
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1039
diff changeset
1543 address=config.ADMIN_EMAIL, roles='Admin')
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1544 user.create(username="anonymous", roles='Anonymous')
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1545
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1546 Then in the code that matters, calls to ``hasPermission`` and
1091
d870139aeb5c more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1089
diff changeset
1547 ``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
1548 to perform some action::
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1549
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1550 if db.security.hasPermission('issue', 'Edit', userid):
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1551 # all ok
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1552
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1553 if db.security.hasItemPermission('issue', itemid,
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1554 assignedto=userid):
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1555 # all ok
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1556
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1557 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
1558 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
1559 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
1560 exposes a ``hasPermission()`` method::
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1561
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1562 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
1563
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1564 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
1565
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1566 tal:condition="python:request.user.hasPermission('Edit')"
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1567
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1568
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1569 Authentication of Users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1570 ~~~~~~~~~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1571
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1572 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
1573 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
1574 signing of messages could alleviate this problem.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1575
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1576 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
1577 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
1578 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
1579 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
1580 submission to their user details.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1581
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1582
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1583 Anonymous Users
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1584 ~~~~~~~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1585
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1586 The "anonymous" user must always exist, and defines the access
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1587 permissions for anonymous users. Unknown users accessing Roundup through
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1588 the web or email interfaces will be logged in as the "anonymous" user.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1589
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1590
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1591 Use Cases
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1592 ~~~~~~~~~
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1593
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1594 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
1595 support
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1596 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
1597 and "Edit" Permission to the "issue" class.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1598 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
1599 support
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1600 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
1601 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
1602 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
1603 "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
1604 available.
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1605 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
1606 fixes
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1607 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
1608 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
1609 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
1610 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
1611 "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
1612 "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
1613 system - automated request handlers running various report/escalation
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1614 scripts
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1615 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
1616 could be used here.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1617 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
1618 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
1619 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
1620 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
1621 view access.
910
299f4890427d documentation reorg post-new-security
Richard Jones <richard@users.sourceforge.net>
parents: 907
diff changeset
1622
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1623
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1624 Deployment Scenarios
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1625 --------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1626
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1627 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
1628 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
1629 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
1630 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
1631 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
1632 requirements they address.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1633
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1634
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1635 Acknowledgements
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1636 ----------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1637
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1638 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
1639 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
1640 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
1641 and Dean Tribble for their assistance with the first-round submission.
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1642
1711
3c3e44aacdb4 Documentation fixes.
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1675
diff changeset
1643
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1644 Changes to this document
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1645 ------------------------
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1646
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1647 - Added Boolean and Number types
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1648 - Added section Hyperdatabase Implementations
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1575
diff changeset
1649 - "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
1650 nature of the Class.
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1651 - New Templating
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1652 - Access Controls
2131
dc65f4a91433 add "actor" to design
Richard Jones <richard@users.sourceforge.net>
parents: 1800
diff changeset
1653 - Added "actor" property
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1654
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1655 ------------------
907
38a74d1351c5 documentation updates
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1656
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1657 Back to `Table of Contents`_
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1658
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1659 .. _`Table of Contents`: index.html
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1660 .. _customisation: customizing.html
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1091
diff changeset
1661

Roundup Issue Tracker: http://roundup-tracker.org/