Mercurial > p > roundup > code

annotate doc/design.txt @ 8519:19152fd94fcf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bug: move import findargspec out of Permission __init__ method We have a few places where imports are done inside a method/function. For methods that are called once it's not an issue but the Permissions __init__ method is called often and accounts for > 10% of the time in the __init__ function when looking at wsgi-lineprof output. So move it to the module level.
author John Rouillard <rouilj@ieee.org>
date Mon, 02 Feb 2026 23:41:36 -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/