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