Mercurial > p > roundup > code

annotate doc/design.txt @ 8506:b6c6891754e9

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