-
Notifications
You must be signed in to change notification settings - Fork 15
Expand file tree
/
Copy pathspec.html
More file actions
1546 lines (1262 loc) · 57.3 KB
/
spec.html
File metadata and controls
1546 lines (1262 loc) · 57.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<title>Software Carpentry Track: Roundup</title>
</head>
<body bgcolor=white>
<table width="100%">
<tr>
<td align="left">
<a href="http://www.software-carpentry.com"><img
src="images/logo-software-carpentry-standard.png" alt="[Software Carpentry logo]" border="0"></a>
</td>
<td align="right">
<table>
<tr><td>
<a href="http://www.acl.lanl.gov"><img src="images//logo-acl-medium.png" alt="[ACL Logo]" border="0"></a>
</td></tr>
<tr><td><hr></td></tr>
<tr><td>
<a href="http://www.codesourcery.com"><img
src="images/logo-codesourcery-medium.png" alt="[CodeSourcery Logo]" border="0"></a>
</td></tr>
</table>
</td>
</tr>
</table>
<hr><p>
<h1 align=center>Roundup</h1>
<h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
<h4 align=center><a href="http://www.lfw.org/ping/">Ka-Ping Yee</a><br>
<a href="mailto:ping@lfw.org">ping@lfw.org</a></h4>
<h3 align=center>Implementation Guide</h3>
<h2>Contents</h2>
<ol>
<li>Introduction
<li>The Layer Cake
<li>Hyperdatabase
<ol>
<li>Dates and Date Arithmetic
<li>Items and Classes
<li>Identifiers and Designators
<li>Property Names and Types
<li>Interface Specification
<li>Application Example
</ol>
<li>Roundup Database
<ol>
<li>Reserved Classes
<ol>
<li>Users
<li>Messages
<li>Files
</ol>
<li>Item Classes
<li>Interface Specification
<li>Default Schema
</ol>
<li>Detector Interface
<ol>
<li>Interface Specification
<li>Detector Example
</ol>
<li>Command Interface
<ol>
<li>Interface Specification
<li>Usage Example
</ol>
<li>E-mail User Interface
<ol>
<li>Message Processing
<li>Nosy Lists
<li>Setting Properties
<li>Workflow Example
</ol>
<li>Web User Interface
<ol>
<li>Views and View Specifiers
<li>Displaying Properties
<li>Index Views
<ol>
<li>Index View Specifiers
<li>Filter Section
<li>Index Section
<li>Sorting
</ol>
<li>Item Views
<ol>
<li>Item View Specifiers
<li>Editor Section
<li>Spool Section
</ol>
</ol>
<li>Deployment Scenarios
<li>Acknowledgements
</ol>
<p><hr>
<h2>1. Introduction</h2>
<p>This document presents a description of the components
of the Roundup system and specifies their interfaces and
behaviour in sufficient detail to guide an implementation.
For the philosophy and rationale behind the Roundup design,
see the first-round Software Carpentry submission for Roundup.
This document fleshes out that design as well as specifying
interfaces so that the components can be developed separately.
<p><hr>
<h2>2. The Layer Cake</h2>
<p>Lots of software design documents come with a picture of
a cake. Everybody seems to like them. I also like cakes
(i think they are tasty). So i, too, shall include
a picture of a cake here.
<p align=center><table cellspacing=0 cellpadding=10 border=0 align=center>
<tr>
<td bgcolor="#e8e8e8" align=center>
<p><font face="helvetica, arial"><small>
E-mail Client
</small></font>
</td>
<td bgcolor="#e0e0e0" align="center">
<p><font face="helvetica, arial"><small>
Web Browser
</small></font>
</td>
<td bgcolor="#e8e8e8" align=center>
<p><font face="helvetica, arial"><small>
Detector Scripts
</small></font>
</td>
<td bgcolor="#e0e0e0" align="center">
<p><font face="helvetica, arial"><small>
Shell
</small></font>
</td>
<tr>
<td bgcolor="#d0d0f0" align=center>
<p><font face="helvetica, arial"><small>
E-mail User Interface
</small></font>
</td>
<td bgcolor="#f0d0d0" align=center>
<p><font face="helvetica, arial"><small>
Web User Interface
</small></font>
</td>
<td bgcolor="#d0f0d0" align=center>
<p><font face="helvetica, arial"><small>
Detector Interface
</small></font>
</td>
<td bgcolor="#f0d0f0" align=center>
<p><font face="helvetica, arial"><small>
Command Interface
</small></font>
</td>
<tr>
<td bgcolor="#f0f0d0" colspan=4 align=center>
<p><font face="helvetica, arial"><small>
Roundup Database Layer
</small></font>
</td>
<tr>
<td bgcolor="#d0f0f0" colspan=4 align=center>
<p><font face="helvetica, arial"><small>
Hyperdatabase Layer
</small></font>
</td>
<tr>
<td bgcolor="#e8e8e8" colspan=4 align=center>
<p><font face="helvetica, arial"><small>
Storage Layer
</small></font>
</td>
</table>
<p>The colourful parts of the cake are part of our system;
the faint grey parts of the cake are external components.
<p>I will now proceed to forgo all table manners and
eat from the bottom of the cake to the top. You may want
to stand back a bit so you don't get covered in crumbs.
<p><hr>
<h2>3. Hyperdatabase</h2>
<p>The lowest-level component to be implemented is the hyperdatabase.
The hyperdatabase is intended to be
a flexible data store that can hold configurable data in
records which we call <em>items</em>.
<p>The hyperdatabase is implemented on top of the storage layer,
an external module for storing its data. The storage layer could
be a third-party RDBMS; for a "batteries-included" distribution,
implementing the hyperdatabase on the standard <tt>bsddb</tt>
module is suggested.
<h3>3.1. Dates and Date Arithmetic</h3>
<p>Before we get into the hyperdatabase itself, we need a
way of handling dates. The hyperdatabase module provides
Timestamp objects for
representing date-and-time stamps and Interval objects for
representing date-and-time intervals.
<p>As strings, date-and-time stamps are specified with
the date in international standard format
(<em>yyyy</em>-<em>mm</em>-<em>dd</em>)
joined to the time (<em>hh</em>:<em>mm</em>:<em>ss</em>)
by a period ("."). Dates in
this form can be easily compared and are fairly readable
when printed. An example of a valid stamp is
"<strong>2000-06-24.13:03:59</strong>".
We'll call this the "full date format". When Timestamp objects are
printed as strings, they appear in the full date format with
the time always given in GMT. The full date format is always
exactly 19 characters long.
<p>For user input, some partial forms are also permitted:
the whole time or just the seconds may be omitted; and the whole date
may be omitted or just the year may be omitted. If the time is given,
the time is interpreted in the user's local time zone.
The <tt>Date</tt> constructor takes care of these conversions.
In the following examples, suppose that <em>yyyy</em> is the current year,
<em>mm</em> is the current month, and <em>dd</em> is the current
day of the month; and suppose that the user is on Eastern Standard Time.
<ul>
<li>"<strong>2000-04-17</strong>" means <Date 2000-04-17.00:00:00>
<li>"<strong>01-25</strong>" means <Date <em>yyyy</em>-01-25.00:00:00>
<li>"<strong>2000-04-17.03:45</strong>" means <Date 2000-04-17.08:45:00>
<li>"<strong>08-13.22:13</strong>" means <Date <em>yyyy</em>-08-14.03:13:00>
<li>"<strong>11-07.09:32:43</strong>" means <Date <em>yyyy</em>-11-07.14:32:43>
<li>"<strong>14:25</strong>" means
<Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.19:25:00>
<li>"<strong>8:47:11</strong>" means
<Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.13:47:11>
<li>the special date "<strong>.</strong>" means "right now"
</ul>
<p>Date intervals are specified using the suffixes
"y", "m", and "d". The suffix "w" (for "week") means 7 days.
Time intervals are specified in hh:mm:ss format (the seconds
may be omitted, but the hours and minutes may not).
<ul>
<li>"<strong>3y</strong>" means three years
<li>"<strong>2y 1m</strong>" means two years and one month
<li>"<strong>1m 25d</strong>" means one month and 25 days
<li>"<strong>2w 3d</strong>" means two weeks and three days
<li>"<strong>1d 2:50</strong>" means one day, two hours, and 50 minutes
<li>"<strong>14:00</strong>" means 14 hours
<li>"<strong>0:04:33</strong>" means four minutes and 33 seconds
</ul>
<p>The Date class should understand simple date expressions of the form
<em>stamp</em> + <em>interval</em> and <em>stamp</em> - <em>interval</em>.
When adding or subtracting intervals involving months or years, the
components are handled separately. For example, when evaluating
"<strong>2000-06-25 + 1m 10d</strong>", we first add one month to
get <strong>2000-07-25</strong>, then add 10 days to get
<strong>2000-08-04</strong> (rather than trying to decide whether
<strong>1m 10d</strong> means 38 or 40 or 41 days).
<p>Here is an outline of the Date and Interval classes.
<blockquote>
<pre><small>class <strong>Date</strong>:
def <strong>__init__</strong>(self, spec, offset):
"""Construct a date given a specification and a time zone offset.
'spec' is a full date or a partial form, with an optional
added or subtracted interval. 'offset' is the local time
zone offset from GMT in hours.
"""
def <strong>__add__</strong>(self, interval):
"""Add an interval to this date to produce another date."""
def <strong>__sub__</strong>(self, interval):
"""Subtract an interval from this date to produce another date."""
def <strong>__cmp__</strong>(self, other):
"""Compare this date to another date."""
def <strong>__str__</strong>(self):
"""Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
def <strong>local</strong>(self, offset):
"""Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
class <strong>Interval</strong>:
def <strong>__init__</strong>(self, spec):
"""Construct an interval given a specification."""
def <strong>__cmp__</strong>(self, other):
"""Compare this interval to another interval."""
def <strong>__str__</strong>(self):
"""Return this interval as a string."""
</small></pre>
</blockquote>
<p>Here are some examples of how these classes would behave in practice.
For the following examples, assume that we are on Eastern Standard
Time and the current local time is 19:34:02 on 25 June 2000.
<blockquote><pre><small
>>>> <span class="input">Date(".")</span>
<span class="output"><Date 2000-06-26.00:34:02></span>
>>> <span class="input">_.local(-5)</span>
<span class="output">"2000-06-25.19:34:02"</span>
>>> <span class="input">Date(". + 2d")</span>
<span class="output"><Date 2000-06-28.00:34:02></span>
>>> <span class="input">Date("1997-04-17", -5)</span>
<span class="output"><Date 1997-04-17.00:00:00></span>
>>> <span class="input">Date("01-25", -5)</span>
<span class="output"><Date 2000-01-25.00:00:00></span>
>>> <span class="input">Date("08-13.22:13", -5)</span>
<span class="output"><Date 2000-08-14.03:13:00></span>
>>> <span class="input">Date("14:25", -5)</span>
<span class="output"><Date 2000-06-25.19:25:00></span>
>>> <span class="input">Interval(" 3w 1 d 2:00")</span>
<span class="output"><Interval 22d 2:00></span>
>>> <span class="input">Date(". + 2d") - Interval("3w")</span>
<span class="output"><Date 2000-06-07.00:34:02></span
></small></pre></blockquote>
<h3>3.2. Items and Classes</h3>
<p>Items contain data in <em>properties</em>. To Python, these
properties are presented as the key-value pairs of a dictionary.
Each item belongs to a <em>class</em> which defines the names
and types of its properties. The database permits the creation
and modification of classes as well as items.
<h3>3.3. Identifiers and Designators</h3>
<p>Each item has a numeric identifier which is unique among
items in its class. The items are numbered sequentially
within each class in order of creation, starting from 1.
The <em>designator</em>
for an item is a way to identify an item in the database, and
consists of the name of the item's class concatenated with
the item's numeric identifier.
<p>For example, if "spam" and "eggs" are classes, the first
item created in class "spam" has id 1 and designator "spam1".
The first item created in class "eggs" also has id 1 but has
the distinct designator "eggs1". Item designators are
conventionally enclosed in square brackets when mentioned
in plain text. This permits a casual mention of, say,
"[patch37]" in an e-mail message to be turned into an active
hyperlink.
<h3>3.4. Property Names and Types</h3>
<p>Property names must begin with a letter.
<p>A property may be one of five <em>basic types</em>:
<ul>
<li><em>String</em> properties are for storing arbitrary-length
strings.
<li><em>Date</em> properties store date-and-time stamps.
Their values are Timestamp objects.
<li>A <em>Link</em> property refers to a single other item
selected from a specified class. The class is part of the property;
the value is an integer, the id of the chosen item.
<li>A <em>Multilink</em> property refers to possibly many items
in a specified class. The value is a list of integers.
</ul>
<p><tt>None</tt> is also a permitted value for any of these property
types. An attempt to store <tt>None</tt> into a String property
stores the empty string; an attempt to store <tt>None</tt>
into a Multilink property stores an empty list.
<h3>3.5. Interface Specification</h3>
<p>The hyperdb module provides property objects to designate
the different kinds of properties. These objects are used when
specifying what properties belong in classes.
<blockquote><pre><small
>class <strong>String</strong>:
def <strong>__init__</strong>(self):
"""An object designating a String property."""
class <strong>Date</strong>:
def <strong>__init__</strong>(self):
"""An object designating a Date property."""
class <strong>Link</strong>:
def <strong>__init__</strong>(self, classname):
"""An object designating a Link property that links to
items in a specified class."""
class <strong>Multilink</strong>:
def <strong>__init__</strong>(self, classname):
"""An object designating a Multilink property that links
to items in a specified class."""
</small></pre></blockquote>
<p>Here is the interface provided by the hyperdatabase.
<blockquote><pre><small
>class <strong>Database</strong>:
"""A database for storing records containing flexible data types."""
def <strong>__init__</strong>(self, storagelocator, journaltag):
"""Open a hyperdatabase given a specifier to some storage.
The meaning of 'storagelocator' depends on the particular
implementation of the hyperdatabase. It could be a file name,
a directory path, a socket descriptor for a connection to a
database over the network, etc.
The 'journaltag' is a token that will be attached to the journal
entries for any edits done on the database. If 'journaltag' is
None, the database is opened in read-only mode: the Class.create(),
Class.set(), and Class.retire() methods are disabled.
"""
def <strong>__getattr__</strong>(self, classname):
"""A convenient way of calling self.getclass(classname)."""
def <strong>getclasses</strong>(self):
"""Return a list of the names of all existing classes."""
def <strong>getclass</strong>(self, classname):
"""Get the Class object representing a particular class.
If 'classname' is not a valid class name, a KeyError is raised.
"""
class <strong>Class</strong>:
"""The handle to a particular class of items in a hyperdatabase."""
def <strong>__init__</strong>(self, db, classname, **properties):
"""Create a new class with a given name and property specification.
'classname' must not collide with the name of an existing class,
or a ValueError is raised. The keyword arguments in 'properties'
must map names to property objects, or a TypeError is raised.
"""
# Editing items:
def <strong>create</strong>(self, **propvalues):
"""Create a new item of this class and return its id.
The keyword arguments in 'propvalues' map property names to values.
The values of arguments must be acceptable for the types of their
corresponding properties or a TypeError is raised. If this class
has a key property, it must be present and its value must not
collide with other key strings or a ValueError is raised. Any other
properties on this class that are missing from the 'propvalues'
dictionary are set to None. If an id in a link or multilink
property does not refer to a valid item, an IndexError is raised.
"""
def <strong>get</strong>(self, itemid, propname):
"""Get the value of a property on an existing item of this class.
'itemid' must be the id of an existing item of this class or an
IndexError is raised. 'propname' must be the name of a property
of this class or a KeyError is raised.
"""
def <strong>set</strong>(self, itemid, **propvalues):
"""Modify a property on an existing item of this class.
'itemid' must be the id of an existing item of this class or an
IndexError is raised. Each key in 'propvalues' must be the name
of a property of this class or a KeyError is raised. All values
in 'propvalues' must be acceptable types for their corresponding
properties or a TypeError is raised. If the value of the key
property is set, it must not collide with other key strings or a
ValueError is raised. If the value of a Link or Multilink
property contains an invalid item id, a ValueError is raised.
"""
def <strong>retire</strong>(self, itemid):
"""Retire an item.
The properties on the item remain available from the get() method,
and the item's id is never reused. Retired items are not returned
by the find(), list(), or lookup() methods, and other items may
reuse the values of their key properties.
"""
def <strong>history</strong>(self, itemid):
"""Retrieve the journal of edits on a particular item.
'itemid' must be the id of an existing item of this class or an
IndexError is raised.
The returned list contains tuples of the form
(date, tag, action, params)
'date' is a Timestamp object specifying the time of the change and
'tag' is the journaltag specified when the database was opened.
'action' may be:
'create' or 'set' -- 'params' is a dictionary of property values
'link' or 'unlink' -- 'params' is (classname, itemid, propname)
'retire' -- 'params' is None
"""
# Locating items:
def <strong>setkey</strong>(self, propname):
"""Select a String property of this class to be the key property.
'propname' must be the name of a String property of this class or
None, or a TypeError is raised. The values of the key property on
all existing items must be unique or a ValueError is raised.
"""
def <strong>getkey</strong>(self):
"""Return the name of the key property for this class or None."""
def <strong>lookup</strong>(self, keyvalue):
"""Locate a particular item by its key property and return its id.
If this class has no key property, a TypeError is raised. If the
'keyvalue' matches one of the values for the key property among
the items in this class, the matching item's id is returned;
otherwise a KeyError is raised.
"""
def <strong>find</strong>(self, propname, itemid):
"""Get the ids of items in this class which link to a given item.
'propname' must be the name of a property in this class, or a
KeyError is raised. That property must be a Link or Multilink
property, or a TypeError is raised. 'itemid' must be the id of
an existing item in the class linked to by the given property,
or an IndexError is raised.
"""
def <strong>list</strong>(self):
"""Return a list of the ids of the active items in this class."""
def <strong>count</strong>(self):
"""Get the number of items in this class.
If the returned integer is 'numitems', the ids of all the items
in this class run from 1 to numitems, and numitems+1 will be the
id of the next item to be created in this class.
"""
# Manipulating properties:
def <strong>getprops</strong>(self):
"""Return a dictionary mapping property names to property objects."""
def <strong>addprop</strong>(self, **properties):
"""Add properties to this class.
The keyword arguments in 'properties' must map names to property
objects, or a TypeError is raised. None of the keys in 'properties'
may collide with the names of existing properties, or a ValueError
is raised before any properties have been added.
"""</small></pre></blockquote>
<h3>3.6. Application Example</h3>
<p>Here is an example of how the hyperdatabase module would work in practice.
<blockquote><pre><small
>>>> <span class="input">import hyperdb</span>
>>> <span class="input">db = hyperdb.Database("foo.db", "ping")</span>
>>> <span class="input">db</span>
<span class="output"><hyperdb.Database "foo.db" opened by "ping"></span>
>>> <span class="input">hyperdb.Class(db, "status", name=hyperdb.String())</span>
<span class="output"><hyperdb.Class "status"></span>
>>> <span class="input">_.setkey("name")</span>
>>> <span class="input">db.status.create(name="unread")</span>
<span class="output">1</span>
>>> <span class="input">db.status.create(name="in-progress")</span>
<span class="output">2</span>
>>> <span class="input">db.status.create(name="testing")</span>
<span class="output">3</span>
>>> <span class="input">db.status.create(name="resolved")</span>
<span class="output">4</span>
>>> <span class="input">db.status.count()</span>
<span class="output">4</span>
>>> <span class="input">db.status.list()</span>
<span class="output">[1, 2, 3, 4]</span>
>>> <span class="input">db.status.lookup("in-progress")</span>
<span class="output">2</span>
>>> <span class="input">db.status.retire(3)</span>
>>> <span class="input">db.status.list()</span>
<span class="output">[1, 2, 4]</span>
>>> <span class="input">hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))</span>
<span class="output"><hyperdb.Class "issue"></span>
>>> <span class="input">db.issue.create(title="spam", status=1)</span>
<span class="output">1</span>
>>> <span class="input">db.issue.create(title="eggs", status=2)</span>
<span class="output">2</span>
>>> <span class="input">db.issue.create(title="ham", status=4)</span>
<span class="output">3</span>
>>> <span class="input">db.issue.create(title="arguments", status=2)</span>
<span class="output">4</span>
>>> <span class="input">db.issue.create(title="abuse", status=1)</span>
<span class="output">5</span>
>>> <span class="input">hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())</span>
<span class="output"><hyperdb.Class "user"></span>
>>> <span class="input">db.issue.addprop(fixer=hyperdb.Link("user"))</span>
>>> <span class="input">db.issue.getprops()</span>
<span class="output"
>{"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
"user": <hyperdb.Link to "user">}</span>
>>> <span class="input">db.issue.set(5, status=2)</span>
>>> <span class="input">db.issue.get(5, "status")</span>
<span class="output">2</span>
>>> <span class="input">db.status.get(2, "name")</span>
<span class="output">"in-progress"</span>
>>> <span class="input">db.issue.get(5, "title")</span>
<span class="output">"abuse"</span>
>>> <span class="input">db.issue.find("status", db.status.lookup("in-progress"))</span>
<span class="output">[2, 4, 5]</span>
>>> <span class="input">db.issue.history(5)</span>
<span class="output"
>[(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse", "status": 1}),
(<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]</span>
>>> <span class="input">db.status.history(1)</span>
<span class="output"
>[(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
(<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]</span>
>>> <span class="input">db.status.history(2)</span>
<span class="output"
>[(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]</span>
</small></pre></blockquote>
<p>For the purposes of journalling, when a Multilink property is
set to a new list of items, the hyperdatabase compares the old
list to the new list.
The journal records "unlink" events for all the items that appear
in the old list but not the new list,
and "link" events for
all the items that appear in the new list but not in the old list.
<p><hr>
<h2>4. Roundup Database</h2>
<p>The Roundup database layer is implemented on top of the
hyperdatabase and mediates calls to the database.
Some of the classes in the Roundup database are considered
<em>item classes</em>.
The Roundup database layer adds detectors and user items,
and on items it provides mail spools, nosy lists, and superseders.
<h3>4.1. Reserved Classes</h3>
<p>Internal to this layer we reserve three special classes
of items that are not items.
<h4>4.1.1. Users</h4>
<p>Users are stored in the hyperdatabase as items of
class "user". The "user" class has the definition:
<blockquote><pre><small
>hyperdb.Class(db, "user", username=hyperdb.String(),
password=hyperdb.String(),
address=hyperdb.String())
db.user.setkey("username")</small></pre></blockquote>
<h4>4.1.2. Messages</h4>
<p>E-mail messages are represented by hyperdatabase items of class "msg".
The actual text content of the messages is stored in separate files.
(There's no advantage to be gained by stuffing them into the
hyperdatabase, and if messages are stored in ordinary text files,
they can be grepped from the command line.) The text of a message is
saved in a file named after the message item designator (e.g. "msg23")
for the sake of the command interface (see below). Attachments are
stored separately and associated with "file" items.
The "msg" class has the definition:
<blockquote><pre><small
>hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
recipients=hyperdb.Multilink("user"),
date=hyperdb.Date(),
summary=hyperdb.String(),
files=hyperdb.Multilink("file"))</small
></pre></blockquote>
<p>The "author" property indicates the author of the message
(a "user" item must exist in the hyperdatabase for any messages
that are stored in the system).
The "summary" property contains a summary of the message for display
in a message index.
<h4>4.1.3. Files</h4>
<p>Submitted files are represented by hyperdatabase
items of class "file". Like e-mail messages, the file content
is stored in files outside the database,
named after the file item designator (e.g. "file17").
The "file" class has the definition:
<blockquote><pre><small
>hyperdb.Class(db, "file", user=hyperdb.Link("user"),
name=hyperdb.String(),
type=hyperdb.String())</small></pre></blockquote>
<p>The "user" property indicates the user who submitted the
file, the "name" property holds the original name of the file,
and the "type" property holds the MIME type of the file as received.
<h3>4.2. Item Classes</h3>
<p>All items have the following standard properties:
<blockquote><pre><small
>title=hyperdb.String()
messages=hyperdb.Multilink("msg")
files=hyperdb.Multilink("file")
nosy=hyperdb.Multilink("user")
superseder=hyperdb.Multilink("item")</small></pre></blockquote>
<p>Also, two Date properties named "creation" and "activity" are
fabricated by the Roundup database layer. By "fabricated" we
mean that no such properties are actually stored in the
hyperdatabase, but when properties on items are requested, the
"creation" and "activity" properties are made available.
The value of the "creation" property is the date when an item was
created, and the value of the "activity" property is the
date when any property on the item was last edited (equivalently,
these are the dates on the first and last records in the item's journal).
<h3>4.3. Interface Specification</h3>
<p>The interface to a Roundup database delegates most method
calls to the hyperdatabase, except for the following
changes and additional methods.
<blockquote><pre><small
>class <strong>Database</strong>:
# Overridden methods:
def <strong>__init__</strong>(self, storagelocator, journaltag):
"""When the Roundup database is opened by a particular user,
the 'journaltag' is the id of the user's "user" item."""
def <strong>getclass</strong>(self, classname):
"""This method now returns an instance of either Class or
ItemClass depending on whether an item class is specified."""
# New methods:
def <strong>getuid</strong>(self):
"""Return the id of the "user" item associated with the user
that owns this connection to the hyperdatabase."""
class <strong>Class</strong>:
# Overridden methods:
def <strong>create</strong>(self, **propvalues):
def <strong>set</strong>(self, **propvalues):
def <strong>retire</strong>(self, itemid):
"""These operations trigger detectors and can be vetoed. Attempts
to modify the "creation" or "activity" properties cause a KeyError.
"""
# New methods:
def <strong>audit</strong>(self, event, detector):
def <strong>react</strong>(self, event, detector):
"""Register a detector (see below for more details)."""
class <strong>ItemClass</strong>(Class):
# Overridden methods:
def <strong>__init__</strong>(self, db, classname, **properties):
"""The newly-created class automatically includes the "messages",
"files", "nosy", and "superseder" properties. If the 'properties'
dictionary attempts to specify any of these properties or a
"creation" or "activity" property, a ValueError is raised."""
def <strong>get</strong>(self, itemid, propname):
def <strong>getprops</strong>(self):
"""In addition to the actual properties on the item, these
methods provide the "creation" and "activity" properties."""
# New methods:
def <strong>addmessage</strong>(self, itemid, summary, text):
"""Add a message to an item's mail spool.
A new "msg" item is constructed using the current date, the
user that owns the database connection as the author, and
the specified summary text. The "files" and "recipients"
fields are left empty. The given text is saved as the body
of the message and the item is appended to the "messages"
field of the specified item.
"""
def <strong>nosymessage</strong>(self, itemid, msgid):
"""Send a message to the members of an item's nosy list.
The message is sent only to users on the nosy list who are not
already on the "recipients" list for the message. These users
are then added to the message's "recipients" list.
"""
</small></pre></blockquote>
<h3>4.4. Default Schema</h3>
<p>The default schema included with Roundup turns it into a
typical software bug tracker. The database is set up like this:
<blockquote><pre><small
>pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
pri.setkey("name")
pri.create(name="critical", order="1")
pri.create(name="urgent", order="2")
pri.create(name="bug", order="3")
pri.create(name="feature", order="4")
pri.create(name="wish", order="5")
stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
stat.setkey("name")
stat.create(name="unread", order="1")
stat.create(name="deferred", order="2")
stat.create(name="chatting", order="3")
stat.create(name="need-eg", order="4")
stat.create(name="in-progress", order="5")
stat.create(name="testing", order="6")
stat.create(name="done-cbb", order="7")
stat.create(name="resolved", order="8")
Class(db, "keyword", name=hyperdb.String())
Class(db, "issue", fixer=hyperdb.Multilink("user"),
topic=hyperdb.Multilink("keyword"),
priority=hyperdb.Link("priority"),
status=hyperdb.Link("status"))
</small></pre></blockquote>
<p>(The "order" property hasn't been explained yet. It
gets used by the Web user interface for sorting.)
<p>The above isn't as pretty-looking as the schema specification
in the first-stage submission, but it could be made just as easy
with the addition of a convenience function like <tt>Choice</tt>
for setting up the "priority" and "status" classes:
<blockquote><pre><small
>def Choice(name, *options):
cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
for i in range(len(options)):
cl.create(name=option[i], order=i)
return hyperdb.Link(name)
</small></pre></blockquote>
<p><hr>
<h2>5. Detector Interface</h2>
<p>Detectors are Python functions that are triggered on certain
kinds of events. The definitions of the
functions live in Python modules placed in a directory set aside
for this purpose. Importing the Roundup database module also
imports all the modules in this directory, and the <tt>init()</tt>
function of each module is called when a database is opened to
provide it a chance to register its detectors.
<p>There are two kinds of detectors:
<ul>
<li>an <em>auditor</em> is triggered just before modifying an item
<li>a <em>reactor</em> is triggered just after an item has been modified
</ul>
<p>When the Roundup database is about to perform a
<tt>create()</tt>, <tt>set()</tt>, or <tt>retire()</tt>
operation, it first calls any auditors that
have been registered for that operation on that class.
Any auditor may raise a <tt>Reject</tt> exception
to abort the operation.
<p>If none of the auditors raises an exception, the database
proceeds to carry out the operation. After it's done, it
then calls all of the reactors that have been registered
for the operation.
<h3>5.1. Interface Specification</h3>
<p>The <tt>audit()</tt> and <tt>react()</tt> methods
register detectors on a given class of items.
<blockquote><pre><small
>class Class:
def <strong>audit</strong>(self, event, detector):
"""Register an auditor on this class.
'event' should be one of "create", "set", or "retire".
'detector' should be a function accepting four arguments.
"""
def <strong>react</strong>(self, event, detector):
"""Register a reactor on this class.
'event' should be one of "create", "set", or "retire".
'detector' should be a function accepting four arguments.
"""
</small></pre></blockquote>
<p>Auditors are called with the arguments:
<blockquote><pre><small
>audit(db, cl, itemid, newdata)</small></pre></blockquote>
where <tt>db</tt> is the database, <tt>cl</tt> is an
instance of Class or ItemClass within the database, and <tt>newdata</tt>
is a dictionary mapping property names to values.
For a <tt>create()</tt>
operation, the <tt>itemid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
contains all of the initial property values with which the item
is about to be created.
For a <tt>set()</tt> operation, <tt>newdata</tt>
contains only the names and values of properties that are about
to be changed.
For a <tt>retire()</tt> operation, <tt>newdata</tt> is <tt>None</tt>.
<p>Reactors are called with the arguments:
<blockquote><pre><small
>react(db, cl, itemid, olddata)</small></pre></blockquote>
where <tt>db</tt> is the database, <tt>cl</tt> is an
instance of Class or ItemClass within the database, and <tt>olddata</tt>
is a dictionary mapping property names to values.
For a <tt>create()</tt>
operation, the <tt>itemid</tt> argument is the id of the
newly-created item and <tt>olddata</tt> is None.
For a <tt>set()</tt> operation, <tt>olddata</tt>
contains the names and previous values of properties that were changed.
For a <tt>retire()</tt> operation, <tt>itemid</tt> is the
id of the retired item and <tt>olddata</tt> is <tt>None</tt>.
<h3>5.2. Detector Example</h3>
<p>Here is an example of detectors written for a hypothetical
project-management application, where users can signal approval
of a project by adding themselves to an "approvals" list, and
a project proceeds when it has three approvals.
<blockquote><pre><small
># Permit users only to add themselves to the "approvals" list.
def check_approvals(db, cl, id, newdata):
if newdata.has_key("approvals"):
if cl.get(id, "status") == db.status.lookup("approved"):
raise Reject, "You can't modify the approvals list " \
"for a project that has already been approved."
old = cl.get(id, "approvals")
new = newdata["approvals"]
for uid in old:
if uid not in new and uid != db.getuid():
raise Reject, "You can't remove other users from the "
"approvals list; you can only remove yourself."
for uid in new:
if uid not in old and uid != db.getuid():
raise Reject, "You can't add other users to the approvals "
"list; you can only add yourself."
# When three people have approved a project, change its
# status from "pending" to "approved".
def approve_project(db, cl, id, olddata):
if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
if cl.get(id, "status") == db.status.lookup("pending"):
cl.set(id, status=db.status.lookup("approved"))
def init(db):
db.project.audit("set", check_approval)