Mercurial > p > roundup > code

annotate doc/design.txt @ 1356:83f33642d220 maint-0.5

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