Mercurial > p > roundup > code

annotate doc/html_extra/spec.html @ 5990:0face8e45224

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