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