Mercurial > p > roundup > code

annotate doc/html_extra/spec.html @ 8064:d6b447de4f59

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: set up for release documentation. Make changes to publish security.html with CVE announcements referring to the sections in upgrading.html rather than CVE.html. Remove templates.zip as part of html build in Makefile. Also update doc for using CVE.html.
author John Rouillard <rouilj@ieee.org>
date Tue, 09 Jul 2024 09:34:13 -0400
parents 6a53d46d1c57
children
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>
6791
c6e30c7b79af Add viewport nd content-type meta tags.
John Rouillard <rouilj@ieee.org>
parents: 4897
diff changeset
3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
c6e30c7b79af Add viewport nd content-type meta tags.
John Rouillard <rouilj@ieee.org>
parents: 4897
diff changeset
4 <meta name="viewport" content="width=device-width, initial-scale=1">
4897
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
5 <title>Software Carpentry Track: Roundup</title>
7085
7083d4bd89d6 maint: Add canonical link tags to original html documents.
John Rouillard <rouilj@ieee.org>
parents: 6971
diff changeset
6
7083d4bd89d6 maint: Add canonical link tags to original html documents.
John Rouillard <rouilj@ieee.org>
parents: 6971
diff changeset
7
7083d4bd89d6 maint: Add canonical link tags to original html documents.
John Rouillard <rouilj@ieee.org>
parents: 6971
diff changeset
8 <link rel="canonical"
7083d4bd89d6 maint: Add canonical link tags to original html documents.
John Rouillard <rouilj@ieee.org>
parents: 6971
diff changeset
9 href="https://www.roundup-tracker.org/docs/spec.html" />
7083d4bd89d6 maint: Add canonical link tags to original html documents.
John Rouillard <rouilj@ieee.org>
parents: 6971
diff changeset
10
8026
6a53d46d1c57 docs: Add meta descriptions for original proposal and spec docs.
John Rouillard <rouilj@ieee.org>
parents: 7747
diff changeset
11 <meta name="description" content="Ping's original specification for the Roundup Issue Tracker.">
6a53d46d1c57 docs: Add meta descriptions for original proposal and spec docs.
John Rouillard <rouilj@ieee.org>
parents: 7747
diff changeset
12
4897
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
13 </head>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
14 <body bgcolor=white>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
15
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
16 <table width="100%">
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
17 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
18
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
19 <td align="left">
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
20 <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
21 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
22 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
23
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
24 <td align="right">
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 <tr><td>
6971
861511d23a56 remove double / in path part of image url.
John Rouillard <rouilj@ieee.org>
parents: 6791
diff changeset
27 <a href="http://www.acl.lanl.gov"><img src="images/logo-acl-medium.png" alt="[ACL Logo]" border="0"></a>
4897
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
28 </td></tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
29 <tr><td><hr></td></tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
30 <tr><td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
31 <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
32 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
33 </td></tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
34 </table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
35 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
36
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
37 </tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
38 </table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
39
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
40 <hr><p>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
41
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
42 <h1 align=center>Roundup</h1>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
43 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
7712
a03f8f681992 doc: fix links: 302/302, images from lfw.org, wayback for sc
John Rouillard <rouilj@ieee.org>
parents: 7085
diff changeset
44 <h4 align=center><a href="http://lfw.org/ping/">Ka-Ping Yee</a><br>
4897
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
45 <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
46 <h3 align=center>Implementation Guide</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
47
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
48 <h2>Contents</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
49
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
50 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
51 <li>Introduction
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
52 <li>The Layer Cake
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
53 <li>Hyperdatabase
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>Dates and Date Arithmetic
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
56 <li>Items and Classes
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
57 <li>Identifiers and Designators
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
58 <li>Property Names and Types
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
59 <li>Interface Specification
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
60 <li>Application Example
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
61 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
62 <li>Roundup Database
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
63 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
64 <li>Reserved Classes
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
65 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
66 <li>Users
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
67 <li>Messages
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
68 <li>Files
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>Item Classes
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
71 <li>Interface Specification
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
72 <li>Default Schema
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
73 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
74 <li>Detector Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
75 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
76 <li>Interface Specification
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
77 <li>Detector Example
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
78 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
79 <li>Command Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
80 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
81 <li>Interface Specification
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
82 <li>Usage Example
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>E-mail User Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
85 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
86 <li>Message Processing
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
87 <li>Nosy Lists
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
88 <li>Setting Properties
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
89 <li>Workflow Example
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
90 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
91 <li>Web User Interface
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>Views and View Specifiers
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
94 <li>Displaying Properties
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
95 <li>Index Views
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
96 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
97 <li>Index View Specifiers
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
98 <li>Filter Section
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
99 <li>Index Section
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
100 <li>Sorting
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
101 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
102 <li>Item Views
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
103 <ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
104 <li>Item View Specifiers
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
105 <li>Editor Section
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
106 <li>Spool Section
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
107 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
108 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
109 <li>Deployment Scenarios
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
110 <li>Acknowledgements
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
111 </ol>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
112
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
113 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
114 <h2>1. Introduction</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
115
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
116 <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
117 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
118 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
119 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
120 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
121 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
122 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
123
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
124 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
125 <h2>2. The Layer Cake</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
126
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
127 <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
128 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
129 (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
130 a picture of a cake here.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
131
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
132 <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
133 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
134 <td bgcolor="#e8e8e8" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
135 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
136 E-mail Client
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
137 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
138 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
139 <td bgcolor="#e0e0e0" align="center">
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
140 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
141 Web Browser
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
142 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
143 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
144 <td bgcolor="#e8e8e8" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
145 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
146 Detector Scripts
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
147 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
148 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
149 <td bgcolor="#e0e0e0" align="center">
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
150 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
151 Shell
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
152 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
153 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
154 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
155 <td bgcolor="#d0d0f0" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
156 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
157 E-mail User Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
158 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
159 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
160 <td bgcolor="#f0d0d0" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
161 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
162 Web User Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
163 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
164 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
165 <td bgcolor="#d0f0d0" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
166 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
167 Detector Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
168 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
169 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
170 <td bgcolor="#f0d0f0" align=center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
171 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
172 Command Interface
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
173 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
174 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
175 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
176 <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
177 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
178 Roundup Database Layer
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
179 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
180 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
181 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
182 <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
183 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
184 Hyperdatabase Layer
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
185 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
186 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
187 <tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
188 <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
189 <p><font face="helvetica, arial"><small>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
190 Storage Layer
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
191 </small></font>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
192 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
193 </table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
194
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
195 <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
196 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
197
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
198 <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
199 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
200 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
201
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
202 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
203 <h2>3. Hyperdatabase</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
204
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
205 <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
206 The hyperdatabase is intended to be
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
207 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
208 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
209
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
210 <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
211 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
212 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
213 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
214 module is suggested.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
215
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
216 <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
217
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
218 <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
219 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
220 Timestamp objects for
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
221 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
222 representing date-and-time intervals.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
223
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
224 <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
225 the date in international standard format
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
226 (<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
227 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
228 by a period ("."). Dates in
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
229 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
230 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
231 "<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
232 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
233 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
234 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
235 exactly 19 characters long.
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 <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
238 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
239 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
240 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
241 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
242 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
243 <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
244 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
245
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
246 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
247 <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
248 <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
249 <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
250 <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
251 <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
252 <li>"<strong>14:25</strong>" means
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
253 &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
254 <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
255 &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
256 <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
257 </ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
258
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
259 <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
260 "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
261 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
262 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
263
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
264 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
265 <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
266 <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
267 <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
268 <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
269 <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
270 <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
271 <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
272 </ul>
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>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
275 <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
276 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
277 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
278 "<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
279 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
280 <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
281 <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
282
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
283 <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
284
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
285 <blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
286 <pre><small>class <strong>Date</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
287 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
288 """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
289
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
290 '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
291 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
292 zone offset from GMT in hours.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
293 """
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>__add__</strong>(self, interval):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
296 """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
297
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
298 def <strong>__sub__</strong>(self, interval):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
299 """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
300
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
301 def <strong>__cmp__</strong>(self, other):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
302 """Compare this date to another date."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
303
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
304 def <strong>__str__</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
305 """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
306
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
307 def <strong>local</strong>(self, offset):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
308 """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
309
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
310 class <strong>Interval</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
311 def <strong>__init__</strong>(self, spec):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
312 """Construct an interval given a specification."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
313
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
314 def <strong>__cmp__</strong>(self, other):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
315 """Compare this interval to another interval."""
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 def <strong>__str__</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
318 """Return this interval as a string."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
319 </small></pre>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
320 </blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
321
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
322 <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
323 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
324 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
325
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
326 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
327 >&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
328 <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
329 &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
330 <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
331 &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
332 <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
333 &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
334 <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
335 &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
336 <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
337 &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
338 <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
339 &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
340 <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
341 &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
342 <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
343 &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
344 <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
345 ></small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
346
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
347 <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
348
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
349 <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
350 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
351 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
352 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
353 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
354
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
355 <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
356
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
357 <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
358 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
359 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
360 The <em>designator</em>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
361 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
362 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
363 the item's numeric identifier.
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 <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
366 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
367 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
368 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
369 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
370 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
371 "[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
372 hyperlink.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
373
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
374 <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
375
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
376 <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
377
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
378 <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
379
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
380 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
381 <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
382 strings.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
383
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
384 <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
385 Their values are Timestamp objects.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
386
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
387 <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
388 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
389 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
390
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
391 <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
392 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
393 </ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
394
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
395 <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
396 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
397 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
398 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
399
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
400 <h3>3.5. Interface Specification</h3>
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 <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
403 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
404 specifying what properties belong in classes.
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 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
407 >class <strong>String</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
408 def <strong>__init__</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
409 """An object designating a String property."""
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>Date</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):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
413 """An object designating a Date property."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
414
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
415 class <strong>Link</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
416 def <strong>__init__</strong>(self, classname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
417 """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
418 items in a specified class."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
419
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
420 class <strong>Multilink</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
421 def <strong>__init__</strong>(self, classname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
422 """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
423 to items in a specified class."""
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
424 </small></pre></blockquote>
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 <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
427
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
428 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
429 >class <strong>Database</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
430 """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
431
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
432 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
433 """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
434
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
435 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
436 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
437 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
438 database over the network, etc.
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 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
441 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
442 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
443 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
444 """
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 def <strong>__getattr__</strong>(self, classname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
447 """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
448
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
449 def <strong>getclasses</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
450 """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
451
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
452 def <strong>getclass</strong>(self, classname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
453 """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
454
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
455 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
456 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
457
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
458 class <strong>Class</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
459 """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
460
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
461 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
462 """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
463
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
464 '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
465 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
466 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
467 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
468
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
469 # Editing items:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
470
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
471 def <strong>create</strong>(self, **propvalues):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
472 """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
473
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
474 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
475 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
476 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
477 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
478 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
479 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
480 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
481 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
482 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
483
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
484 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
485 """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
486
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
487 '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
488 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
489 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
490 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
491
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
492 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
493 """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
494
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
495 '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
496 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
497 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
498 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
499 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
500 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
501 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
502 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
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>retire</strong>(self, itemid):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
506 """Retire an 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 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
509 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
510 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
511 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
512 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
513
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
514 def <strong>history</strong>(self, itemid):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
515 """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
516
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
517 '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
518 IndexError is raised.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
519
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
520 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
521
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
522 (date, tag, action, params)
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 '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
525 '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
526 'action' may be:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
527
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
528 '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
529 '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
530 'retire' -- 'params' is None
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
531 """
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 # Locating items:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
534
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
535 def <strong>setkey</strong>(self, propname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
536 """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
537
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
538 '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
539 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
540 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
541 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
542
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
543 def <strong>getkey</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
544 """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
545
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
546 def <strong>lookup</strong>(self, keyvalue):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
547 """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
548
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
549 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
550 '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
551 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
552 otherwise a KeyError is raised.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
553 """
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 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
556 """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
557
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
558 '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
559 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
560 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
561 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
562 or an IndexError is raised.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
563 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
564
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
565 def <strong>list</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
566 """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
567
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
568 def <strong>count</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
569 """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
570
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
571 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
572 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
573 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
574 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
575
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
576 # Manipulating properties:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
577
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
578 def <strong>getprops</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
579 """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
580
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
581 def <strong>addprop</strong>(self, **properties):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
582 """Add properties to this class.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
583
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
584 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
585 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
586 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
587 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
588 """</small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
589
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
590 <h3>3.6. Application Example</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
591
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
592 <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
593
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
594 <blockquote><pre><small
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">import hyperdb</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
596 &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
597 &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
598 <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
599 &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
600 <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
601 &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
602 &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
603 <span class="output">1</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
604 &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
605 <span class="output">2</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
606 &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
607 <span class="output">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.create(name="resolved")</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
609 <span class="output">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">db.status.count()</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
611 <span class="output">4</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.status.list()</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
613 <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
614 &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
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.status.retire(3)</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
617 &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
618 <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
619 &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
620 <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
621 &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
622 <span class="output">1</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
623 &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
624 <span class="output">2</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.create(title="ham", status=4)</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
626 <span class="output">3</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
627 &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
628 <span class="output">4</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.create(title="abuse", status=1)</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
630 <span class="output">5</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
631 &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
632 <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
633 &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
634 &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
635 <span class="output"
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
636 >{"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
637 "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
638 &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
639 &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
640 <span class="output">2</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
641 &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
642 <span class="output">"in-progress"</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
643 &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
644 <span class="output">"abuse"</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
645 &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
646 <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
647 &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
648 <span class="output"
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
649 >[(&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
650 (&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
651 &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
652 <span class="output"
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
653 >[(&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
654 (&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
655 &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
656 <span class="output"
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
657 >[(&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
658 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
659
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
660 <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
661 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
662 list to the new list.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
663 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
664 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
665 and "link" events for
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
666 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
667
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
668 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
669 <h2>4. Roundup Database</h2>
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>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
672 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
673 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
674 <em>item classes</em>.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
675 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
676 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
677
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
678 <h3>4.1. Reserved Classes</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
679
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
680 <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
681 of items that are not items.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
682
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
683 <h4>4.1.1. Users</h4>
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 <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
686 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
687
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
688 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
689 >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
690 password=hyperdb.String(),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
691 address=hyperdb.String())
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
692 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
693
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
694 <h4>4.1.2. Messages</h4>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
695
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
696 <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
697 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
698 (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
699 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
700 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
701 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
702 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
703 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
704 The "msg" class has the definition:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
705
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
706 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
707 >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
708 recipients=hyperdb.Multilink("user"),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
709 date=hyperdb.Date(),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
710 summary=hyperdb.String(),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
711 files=hyperdb.Multilink("file"))</small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
712 ></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
713
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
714 <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
715 (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
716 that are stored in the system).
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
717 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
718 in a message index.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
719
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
720 <h4>4.1.3. Files</h4>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
721
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
722 <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
723 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
724 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
725 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
726 The "file" class has the definition:
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 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
729 >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
730 name=hyperdb.String(),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
731 type=hyperdb.String())</small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
732
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
733 <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
734 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
735 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
736
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
737 <h3>4.2. Item Classes</h3>
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>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
740
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
741 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
742 >title=hyperdb.String()
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
743 messages=hyperdb.Multilink("msg")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
744 files=hyperdb.Multilink("file")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
745 nosy=hyperdb.Multilink("user")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
746 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
747
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
748 <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
749 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
750 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
751 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
752 "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
753 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
754 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
755 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
756 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
757
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
758 <h3>4.3. Interface Specification</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
759
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
760 <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
761 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
762 changes and additional methods.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
763
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
764 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
765 >class <strong>Database</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
766 # Overridden methods:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
767
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
768 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
769 """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
770 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
771
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
772 def <strong>getclass</strong>(self, classname):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
773 """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
774 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
775
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
776 # New methods:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
777
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
778 def <strong>getuid</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
779 """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
780 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
781
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
782 class <strong>Class</strong>:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
783 # Overridden 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>create</strong>(self, **propvalues):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
786 def <strong>set</strong>(self, **propvalues):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
787 def <strong>retire</strong>(self, itemid):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
788 """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
789 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
790 """
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 # New methods:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
793
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
794 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
795 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
796 """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
797
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
798 class <strong>ItemClass</strong>(Class):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
799 # Overridden methods:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
800
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
801 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
802 """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
803 "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
804 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
805 "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
806
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
807 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
808 def <strong>getprops</strong>(self):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
809 """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
810 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
811
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
812 # New methods:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
813
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
814 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
815 """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
816
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
817 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
818 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
819 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
820 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
821 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
822 field of the specified item.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
823 """
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 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
826 """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
827
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
828 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
829 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
830 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
831 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
832 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
833
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
834 <h3>4.4. Default Schema</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
835
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
836 <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
837 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
838
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
839 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
840 >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
841 pri.setkey("name")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
842 pri.create(name="critical", order="1")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
843 pri.create(name="urgent", order="2")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
844 pri.create(name="bug", order="3")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
845 pri.create(name="feature", order="4")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
846 pri.create(name="wish", order="5")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
847
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
848 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
849 stat.setkey("name")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
850 stat.create(name="unread", order="1")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
851 stat.create(name="deferred", order="2")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
852 stat.create(name="chatting", order="3")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
853 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
854 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
855 stat.create(name="testing", order="6")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
856 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
857 stat.create(name="resolved", order="8")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
858
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
859 Class(db, "keyword", name=hyperdb.String())
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 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
862 topic=hyperdb.Multilink("keyword"),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
863 priority=hyperdb.Link("priority"),
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
864 status=hyperdb.Link("status"))
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
865 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
866
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
867 <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
868 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
869
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
870 <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
871 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
872 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
873 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
874
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
875 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
876 >def Choice(name, *options):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
877 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
878 for i in range(len(options)):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
879 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
880 return hyperdb.Link(name)
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
881 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
882
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
883 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
884 <h2>5. Detector Interface</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
885
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
886 <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
887 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
888 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
889 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
890 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
891 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
892 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
893
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
894 <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
895
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
896 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
897 <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
898 <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
899 </ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
900
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
901 <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
902 <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
903 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
904 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
905 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
906 to abort the operation.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
907
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
908 <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
909 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
910 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
911 for the operation.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
912
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
913 <h3>5.1. Interface Specification</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
914
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
915 <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
916 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
917
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
918 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
919 >class Class:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
920 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
921 """Register an auditor on this class.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
922
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
923 '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
924 '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
925 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
926
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
927 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
928 """Register a reactor on this class.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
929
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
930 '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
931 '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
932 """
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
933 </small></pre></blockquote>
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 <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
936
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
937 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
938 >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
939
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
940 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
941 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
942 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
943
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
944 For a <tt>create()</tt>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
945 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
946 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
947 is about to be created.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
948
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
949 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
950 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
951 to be changed.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
952
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
953 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
954
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
955 <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
956
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
957 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
958 >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
959
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
960 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
961 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
962 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
963
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
964 For a <tt>create()</tt>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
965 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
966 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
967
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
968 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
969 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
970
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
971 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
972 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
973
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
974 <h3>5.2. Detector Example</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
975
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
976 <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
977 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
978 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
979 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
980
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
981 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
982 ># 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
983
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
984 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
985 if newdata.has_key("approvals"):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
986 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
987 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
988 "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
989 old = cl.get(id, "approvals")
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
990 new = newdata["approvals"]
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
991 for uid in old:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
992 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
993 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
994 "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
995 for uid in new:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
996 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
997 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
998 "list; you can only add yourself."
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
999
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1000 # 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
1001 # status from "pending" to "approved".
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1002
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1003 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
1004 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
1005 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
1006 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
1007
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1008 def init(db):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1009 db.project.audit("set", check_approval)
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1010 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
1011 ></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1012
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1013 <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
1014 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
1015 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
1016 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
1017 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
1018 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
1019
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1020 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1021 ># 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
1022
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1023 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
1024 if not newdata["files"]:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1025 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
1026 "attaching a patch file."
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1027 for fileid in newdata["files"]:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1028 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
1029 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
1030
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1031 # 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
1032
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1033 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
1034 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
1035 olddata["status"] == db.status.lookup("approved"):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1036 # ...apply the patch...
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1037
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1038 def init(db):
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1039 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
1040 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
1041 ></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1042
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1043 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1044 <h2>6. Command Interface</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1045
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1046 <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
1047 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
1048 (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
1049 the Roundup database module.)
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1050
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1051 <h3>6.1. Interface Specification</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1052
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1053 <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
1054 the hyperdatabase from the command line.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1055
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 <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
1058 ><em>designator</em>[<tt>,</tt
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1059 ><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
1060 <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
1061 ><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
1062 ><tt>=</tt><em>value</em> ...
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1063 <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
1064 ><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
1065 </ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1066
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1067 <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
1068 and in the printed results:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1069
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1070 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1071 <li>Strings are, well, strings.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1072
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1073 <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
1074 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
1075 formats explained above.
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 <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
1078 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
1079
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1080 <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
1081 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
1082 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
1083 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
1084 </ul>
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 <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
1087 <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
1088 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
1089 on all the listed items.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1090
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1091 <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
1092 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
1093 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
1094
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1095 <h3>6.2. Usage Example</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1096
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1097 <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
1098 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
1099 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
1100 dumps its files:
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1101
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1102 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1103 >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
1104 &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
1105 &gt; <span class="input">done</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1106 <span class="output">msg23
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1107 msg49
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1108 msg50
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1109 msg61</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1110 shell%</small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1111
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1112 <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
1113
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1114 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1115 >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
1116 \`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
1117 <span class="output">msg23
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1118 msg49
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1119 msg50
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1120 msg61</span>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1121 shell%</small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1122
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1123 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1124 <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
1125
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1126 <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
1127 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
1128 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
1129 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
1130
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1131 <h3>7.1. Message Processing</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1132
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1133 <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
1134 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
1135 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
1136 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
1137 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
1138 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
1139 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
1140 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
1141 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
1142 the "msg" item.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1143
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1144 <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
1145 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
1146 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
1147 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
1148 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
1149 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
1150 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
1151
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1152 <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
1153 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
1154 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
1155 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
1156 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
1157 new "msg" item.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1158 The default handling for
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1159 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
1160 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
1161 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
1162 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
1163 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
1164 "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
1165 no passwords.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1166
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1167 <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
1168 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
1169 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
1170 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
1171 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
1172
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1173 <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
1174 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
1175 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
1176 the "files" property for the item.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1177
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1178 <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
1179 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
1180 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
1181 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
1182
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1183 <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
1184 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
1185 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
1186 <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
1187 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
1188 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
1189
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1190 <h3>7.2. Nosy Lists</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1191
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1192 <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
1193 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
1194 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
1195 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
1196 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
1197 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
1198 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
1199 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
1200 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
1201
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1202 <h3>7.3. Setting Properties</h3>
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 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
1205 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
1206 <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
1207 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
1208 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
1209
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1210 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1211 <h2>8. Web User Interface</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1212
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1213 <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
1214 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
1215 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
1216 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
1217 out-of-the-box deployment.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1218
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1219 <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
1220 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
1221 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
1222 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
1223
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1224 <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
1225
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1226 <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
1227 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
1228 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
1229 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
1230 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
1231
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1232 <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
1233 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
1234 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
1235 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
1236 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
1237 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
1238 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
1239 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
1240
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1241 <h3>8.2. Displaying Properties</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1242
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1243 <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
1244 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
1245 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
1246 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
1247 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
1248 be displayed in an editable field.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1249
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1250 <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
1251 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
1252 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
1253 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
1254
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1255 <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
1256 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
1257 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
1258 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
1259 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
1260
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1261 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1262 > &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
1263 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1264
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1265 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
1266
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1267 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1268 > 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
1269 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1270
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1271 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
1272 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
1273 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
1274 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
1275
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1276 <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
1277
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1278 <ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1279 <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
1280 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
1281 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
1282 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
1283 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
1284
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1285 <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
1286 <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
1287 to be edited
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1288
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1289 <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
1290 a menu of the available choices
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1291
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1292 <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
1293 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
1294 item views on those items
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>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
1297 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
1298
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1299 <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
1300 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
1301
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1302 <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
1303 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
1304
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1305 <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
1306 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
1307 </ul>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1308
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1309 <h3>8.3. Index Views</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1310
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1311 <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
1312 and an index section.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1313 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
1314 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
1315 a table of items.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1316
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1317 <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
1318
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1319 <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
1320 has been added for clarity):
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 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1323 >/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
1324 topic=security,ui&amp;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1325 :group=+priority&amp;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1326 :sort=-activity&amp;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1327 :filters=status,topic&amp;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1328 :columns=title,status,fixer
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1329 </small></pre></blockquote>
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 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
1332 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
1333 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
1334 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
1335 properties of selected items are displayed.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1336 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
1337 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
1338 are selected for display.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1339
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1340 <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
1341 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
1342 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
1343 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
1344
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1345 <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
1346 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
1347 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
1348 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
1349 properties.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1350
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1351 <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
1352 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
1353 "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
1354 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
1355 "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
1356 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
1357 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
1358 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
1359 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
1360 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
1361 "fixer" properties.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1362
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1363 <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
1364 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
1365 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
1366 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
1367 section 4.4.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1368
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1369 <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
1370
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1371 <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
1372 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
1373 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
1374 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
1375 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
1376
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1377 <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
1378
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1379 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1380 >&lt;property name=status&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1381 &lt;display call="checklist('status')"&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1382 &lt;/property&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1383 &lt;br&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1384 &lt;property name=priority&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1385 &lt;display call="checklist('priority')"&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1386 &lt;/property&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1387 &lt;br&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1388 &lt;property name=fixer&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1389 &lt;display call="menu('fixer')"&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1390 &lt;/property&gt;</small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1391
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1392 <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
1393
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1394 <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
1395 the index table.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1396 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
1397 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
1398 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
1399 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
1400 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
1401
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1402 <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
1403
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1404 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1405 >&lt;tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1406 &lt;property name=title&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1407 &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
1408 &lt;/property&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1409 &lt;property name=status&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1410 &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
1411 &lt;/property&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1412 &lt;property name=fixer&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1413 &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
1414 &lt;/property&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1415 &lt;/tr&gt;</small></pre></blockquote>
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 <h4>8.3.4. Sorting</h4>
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>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
1420 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
1421 "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
1422 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
1423 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
1424 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
1425
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1426 <h3>8.4. Item Views</h3>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1427
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1428 <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
1429 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
1430 items are always displayed.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1431
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1432 <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
1433
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1434 <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
1435
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1436 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1437 >/patch23
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1438 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1439
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1440 <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
1441
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1442 <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
1443 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
1444 the appropriate widgets for editing properties.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1445
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1446 <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
1447
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1448 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1449 >&lt;table&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1450 &lt;tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1451 &lt;td colspan=2&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1452 &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
1453 &lt;/td&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;tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1456 &lt;td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1457 &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
1458 &lt;/td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1459 &lt;td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1460 &lt;display call="menu('status')&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1461 &lt;/td&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;tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1464 &lt;td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1465 &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
1466 &lt;/td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1467 &lt;td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1468 &lt;display call="menu('priority')&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1469 &lt;/td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1470 &lt;/tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1471 &lt;tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1472 &lt;td colspan=2&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1473 &lt;display call="note()"&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1474 &lt;/td&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1475 &lt;/tr&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1476 &lt;/table&gt;
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1477 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1478
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1479 <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
1480 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
1481 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
1482
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1483 <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
1484 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
1485 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
1486 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
1487 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
1488
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1489 <blockquote><pre><small
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1490 >title: Polly Parrot is dead
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1491 priority: critical
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1492 status: unread -&gt; in-progress
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1493 fixer: (none)
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1494 keywords: parrot,plumage,perch,nailed,dead
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1495 </small></pre></blockquote>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1496
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1497 <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
1498 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
1499 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
1500 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
1501
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1502 <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
1503
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1504 <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
1505 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
1506 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
1507 message takes you to its content.
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1508
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1509 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1510 <h2>9. Deployment Scenarios</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1511
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1512 <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
1513 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
1514 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
1515 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
1516 that maintains requirement specifications, catalogs bugs,
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1517 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
1518 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
1519
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1520 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1521 <h2>10. Acknowledgements</h2>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1522
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1523 <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
1524 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
1525 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
1526 Jesse Vincent, Mark Miller, Christopher Simons,
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1527 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
1528 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
1529 </td>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1530 </tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1531 </table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1532
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1533 <p>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1534
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1535 <center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1536 <table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1537 <tr>
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/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
1539 <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
1540 <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
1541 <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
1542 <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
1543 <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
1544 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_test/"><b>[Test]</b></a>&nbsp;&nbsp;&nbsp;</td>
7747
8d50f1c054fb doc: redirect software-carpentry sc_track link to wayback machine.
John Rouillard <rouilj@ieee.org>
parents: 7712
diff changeset
1545 <td>&nbsp;&nbsp;&nbsp;<a href="https://web.archive.org/web/20010828124306/http://software-carpentry.codesourcery.com/sc_track"><b>[Track]</b></a>&nbsp;&nbsp;&nbsp;</td>
4897
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1546 <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
1547 <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
1548 </tr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1549 </table>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1550 </center>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1551
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1552 <p><hr>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1553 <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
1554 </BODY>
b26176334c88 Fix broken links to static html doc files (issue2550840)
John Kristensen <john@jerrykan.com>
parents:
diff changeset
1555 </HTML>
Roundup Issue Tracker: http://roundup-tracker.org/