Mercurial Repository: p/roundup/code: doc/design.txt comparison

comparison doc/design.txt @ 1661:b9c1226cb600

Reflowed text to 72 cols... ...made leading whitespace before headings consistent, and got rid of references to <display> and <property>.

author	Jean Jordaan <neaj@users.sourceforge.net>
date	Mon, 16 Jun 2003 15:27:15 +0000
parents	f5d53a939b67
children	eb3c348676ed

comparison

equal deleted inserted replaced

-:2c4ec168e72f
+:b9c1226cb600
 .. contents::
 Introduction
 ---------------
-This document presents a description of the components
+This document presents a description of the components of the Roundup
-of the Roundup system and specifies their interfaces and
+system and specifies their interfaces and behaviour in sufficient detail
-behaviour in sufficient detail to guide an implementation.
+to guide an implementation. For the philosophy and rationale behind the
-For the philosophy and rationale behind the Roundup design,
+Roundup design, see the first-round Software Carpentry submission for
-see the first-round Software Carpentry submission for Roundup.
+Roundup. This document fleshes out that design as well as specifying
-This document fleshes out that design as well as specifying
 interfaces so that the components can be developed separately.
 The Layer Cake
 -----------------
-Lots of software design documents come with a picture of
+Lots of software design documents come with a picture of a cake.
-a cake.  Everybody seems to like them.  I also like cakes
+Everybody seems to like them.  I also like cakes (i think they are
-(i think they are tasty).  So i, too, shall include
+tasty).  So I, too, shall include a picture of a cake here::
-a picture of a cake here::
 _________________________________________________________________________
 |  E-mail Client   |   Web Browser   |   Detector Scripts   |    Shell    |
 |------------------+-----------------+----------------------+-------------|
 |   E-mail User    |    Web User     |      Detector        |   Command   |
 |                          Hyperdatabase Layer                            |
 |-------------------------------------------------------------------------|
 |                             Storage Layer                               |
 -------------------------------------------------------------------------
-The colourful parts of the cake are part of our system;
+The colourful parts of the cake are part of our system; the faint grey
-the faint grey parts of the cake are external components.
+parts of the cake are external components.
-I will now proceed to forgo all table manners and
+I will now proceed to forgo all table manners and eat from the bottom of
-eat from the bottom of the cake to the top.  You may want
+the cake to the top.  You may want to stand back a bit so you don't get
-to stand back a bit so you don't get covered in crumbs.
+covered in crumbs.
 Hyperdatabase
 -------------
-The lowest-level component to be implemented is the hyperdatabase.
+The lowest-level component to be implemented is the hyperdatabase. The
-The hyperdatabase is intended to be
+hyperdatabase is intended to be a flexible data store that can hold
-a flexible data store that can hold configurable data in
+configurable data in records which we call items.
-records which we call items.
+The hyperdatabase is implemented on top of the storage layer, an
-The hyperdatabase is implemented on top of the storage layer,
+external module for storing its data.  The storage layer could be a
-an external module for storing its data.  The storage layer could
+third-party RDBMS; for a "batteries-included" distribution, implementing
-be a third-party RDBMS; for a "batteries-included" distribution,
+the hyperdatabase on the standard bsddb module is suggested.
-implementing the hyperdatabase on the standard bsddb
-module is suggested.
 Dates and Date Arithmetic
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-Before we get into the hyperdatabase itself, we need a
+Before we get into the hyperdatabase itself, we need a way of handling
-way of handling dates.  The hyperdatabase module provides
+dates.  The hyperdatabase module provides Timestamp objects for
-Timestamp objects for
+representing date-and-time stamps and Interval objects for representing
-representing date-and-time stamps and Interval objects for
+date-and-time intervals.
-representing date-and-time intervals.
+As strings, date-and-time stamps are specified with the date in
-As strings, date-and-time stamps are specified with
+international standard format (``yyyy-mm-dd``) joined to the time
-the date in international standard format
+(``hh:mm:ss``) by a period "``.``".  Dates in this form can be easily
-(``yyyy-mm-dd``)
+compared and are fairly readable when printed.  An example of a valid
-joined to the time (``hh:mm:ss``)
+stamp is "``2000-06-24.13:03:59``". We'll call this the "full date
-by a period "``.``".  Dates in
+format".  When Timestamp objects are printed as strings, they appear in
-this form can be easily compared and are fairly readable
+the full date format with the time always given in GMT.  The full date
-when printed.  An example of a valid stamp is
+format is always exactly 19 characters long.
-"``2000-06-24.13:03:59``".
-We'll call this the "full date format".  When Timestamp objects are
+For user input, some partial forms are also permitted: the whole time or
-printed as strings, they appear in the full date format with
+just the seconds may be omitted; and the whole date may be omitted or
-the time always given in GMT.  The full date format is always
+just the year may be omitted.  If the time is given, the time is
-exactly 19 characters long.
+interpreted in the user's local time zone. The Date constructor takes
+care of these conversions. In the following examples, suppose that
-For user input, some partial forms are also permitted:
+``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is
-the whole time or just the seconds may be omitted; and the whole date
+the current day of the month; and suppose that the user is on Eastern
-may be omitted or just the year may be omitted.  If the time is given,
+Standard Time.
-the time is interpreted in the user's local time zone.
-The Date constructor takes care of these conversions.
-In the following examples, suppose that ``yyyy`` is the current year,
-``mm`` is the current month, and ``dd`` is the current
-day of the month; and suppose that the user is on Eastern Standard Time.
 -   "2000-04-17" means <Date 2000-04-17.00:00:00>
 -   "01-25" means <Date yyyy-01-25.00:00:00>
 -   "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
 -   "08-13.22:13" means <Date yyyy-08-14.03:13:00>
 -   "8:47:11" means
 -   <Date yyyy-mm-dd.13:47:11>
 -   the special date "." means "right now"
-Date intervals are specified using the suffixes
+Date intervals are specified using the suffixes "y", "m", and "d".  The
-"y", "m", and "d".  The suffix "w" (for "week") means 7 days.
+suffix "w" (for "week") means 7 days. Time intervals are specified in
-Time intervals are specified in hh:mm:ss format (the seconds
+hh:mm:ss format (the seconds may be omitted, but the hours and minutes
-may be omitted, but the hours and minutes may not).
+may not).
 -   "3y" means three years
 -   "2y 1m" means two years and one month
 -   "1m 25d" means one month and 25 days
 -   "2w 3d" means two weeks and three days
 -   "1d 2:50" means one day, two hours, and 50 minutes
 -   "14:00" means 14 hours
 -   "0:04:33" means four minutes and 33 seconds
 The Date class should understand simple date expressions of the form
-*stamp* ``+`` *interval* and *stamp* ``-`` *interval*.
+*stamp* ``+`` *interval* and *stamp* ``-`` *interval*. When adding or
-When adding or subtracting intervals involving months or years, the
+subtracting intervals involving months or years, the components are
-components are handled separately.  For example, when evaluating
+handled separately.  For example, when evaluating "``2000-06-25 + 1m
-"``2000-06-25 + 1m 10d``", we first add one month to
+10d``", we first add one month to get 2000-07-25, then add 10 days to
-get 2000-07-25, then add 10 days to get
+get 2000-08-04 (rather than trying to decide whether 1m 10d means 38 or
-2000-08-04 (rather than trying to decide whether
+40 or 41 days).
-1m 10d means 38 or 40 or 41 days).
 Here is an outline of the Date and Interval classes::
 class Date:
 def __init__(self, spec, offset):
 """Return this interval as a string."""
 Here are some examples of how these classes would behave in practice.
-For the following examples, assume that we are on Eastern Standard
+For the following examples, assume that we are on Eastern Standard Time
-Time and the current local time is 19:34:02 on 25 June 2000::
+and the current local time is 19:34:02 on 25 June 2000::
 >>> Date(".")
 <Date 2000-06-26.00:34:02>
 >>> _.local(-5)
 "2000-06-25.19:34:02"
 <Date 2000-06-07.00:34:02>
 Items and Classes
 ~~~~~~~~~~~~~~~~~
-Items contain data in properties.  To Python, these
+Items contain data in properties.  To Python, these properties are
-properties are presented as the key-value pairs of a dictionary.
+presented as the key-value pairs of a dictionary. Each item belongs to a
-Each item belongs to a class which defines the names
+class which defines the names and types of its properties.  The database
-and types of its properties.  The database permits the creation
+permits the creation and modification of classes as well as items.
-and modification of classes as well as items.
 Identifiers and Designators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Each item has a numeric identifier which is unique among
+Each item has a numeric identifier which is unique among items in its
-items in its class.  The items are numbered sequentially
+class.  The items are numbered sequentially within each class in order
-within each class in order of creation, starting from 1.
+of creation, starting from 1. The designator for an item is a way to
-The designator
+identify an item in the database, and consists of the name of the item's
-for an item is a way to identify an item in the database, and
+class concatenated with the item's numeric identifier.
-consists of the name of the item's class concatenated with
-the item's numeric identifier.
+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
-For example, if "spam" and "eggs" are classes, the first
+class "eggs" also has id 1 but has the distinct designator "eggs1".
-item created in class "spam" has id 1 and designator "spam1".
+Item designators are conventionally enclosed in square brackets when
-The first item created in class "eggs" also has id 1 but has
+mentioned in plain text.  This permits a casual mention of, say,
-the distinct designator "eggs1".  Item designators are
+"[patch37]" in an e-mail message to be turned into an active hyperlink.
-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.
 Property Names and Types
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Property names must begin with a letter.
 - Boolean properties are for storing true/false, or yes/no values.
 - Number properties are for storing numeric values.
-- Date properties store date-and-time stamps.
+- Date properties store date-and-time stamps. Their values are Timestamp
-Their values are Timestamp objects.
+objects.
-- A Link property refers to a single other item
+- A Link property refers to a single other item selected from a
-selected from a specified class.  The class is part of the property;
+specified class.  The class is part of the property; the value is an
-the value is an integer, the id of the chosen item.
+integer, the id of the chosen item.
-- A Multilink property refers to possibly many items
+- A Multilink property refers to possibly many items in a specified
-in a specified class.  The value is a list of integers.
+class.  The value is a list of integers.
-*None* is also a permitted value for any of these property
+*None* is also a permitted value for any of these property types.  An
-types.  An attempt to store None into a Multilink property stores an empty list.
+attempt to store None into a Multilink property stores an empty list.
 A property that is not specified will return as None from a *get*
 operation.
 Hyperdb Interface Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 TODO: replace the Interface Specifications with links to the pydoc
-The hyperdb module provides property objects to designate
+The hyperdb module provides property objects to designate the different
-the different kinds of properties.  These objects are used when
+kinds of properties.  These objects are used when specifying what
-specifying what properties belong in classes::
+properties belong in classes::
 class String:
 def __init__(self, indexme='no'):
 """An object designating a String property."""
 """A database for storing records containing flexible data types."""
 def __init__(self, config, journaltag=None):
 """Open a hyperdatabase given a specifier to some storage.
-The 'storagelocator' is obtained from config.DATABASE.
+The 'storagelocator' is obtained from config.DATABASE. The
-The meaning of 'storagelocator' depends on the particular
+meaning of 'storagelocator' depends on the particular
-implementation of the hyperdatabase.  It could be a file name,
+implementation of the hyperdatabase.  It could be a file
-a directory path, a socket descriptor for a connection to a
+name, a directory path, a socket descriptor for a connection
-database over the network, etc.
+to a database over the network, etc.
-The 'journaltag' is a token that will be attached to the journal
+The 'journaltag' is a token that will be attached to the
-entries for any edits done on the database.  If 'journaltag' is
+journal entries for any edits done on the database.  If
-None, the database is opened in read-only mode: the Class.create(),
+'journaltag' is None, the database is opened in read-only
-Class.set(), Class.retire(), and Class.restore() methods are
+mode: the Class.create(), Class.set(), Class.retire(), and
-disabled.
+Class.restore() methods are disabled.
 """
 def __getattr__(self, classname):
 """A convenient way of calling self.getclass(classname)."""
 by the find(), list(), or lookup() methods, and other items may
 reuse the values of their key properties.
 """
 def restore(self, nodeid):
-'''Restpre a retired node.
+'''Restore a retired node.
 Make node available for all operations like it was before retirement.
 '''
 def history(self, itemid):
 '''
 Hyperdatabase Implementations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Hyperdatabase implementations exist to create the interface described in the
+Hyperdatabase implementations exist to create the interface described in
-`hyperdb interface specification`_
+the `hyperdb interface specification`_ over an existing storage
-over an existing storage mechanism. Examples are relational databases,
+mechanism. Examples are relational databases, \*dbm key-value databases,
-\*dbm key-value databases, and so on.
+and so on.
-Several implementations are provided - they belong in the roundup.backends
+Several implementations are provided - they belong in the
-package.
+roundup.backends package.
 Application Example
 ~~~~~~~~~~~~~~~~~~~
-Here is an example of how the hyperdatabase module would work in practice::
+Here is an example of how the hyperdatabase module would work in
+practice::
 >>> import hyperdb
 >>> db = hyperdb.Database("foo.db", "ping")
 >>> db
 <hyperdb.Database "foo.db" opened by "ping">
 (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]
 >>> db.status.history(2)
 [(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]
-For the purposes of journalling, when a Multilink property is
+For the purposes of journalling, when a Multilink property is set to a
-set to a new list of items, the hyperdatabase compares the old
+new list of items, the hyperdatabase compares the old list to the new
-list to the new list.
+list. The journal records "unlink" events for all the items that appear
-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
-in the old list but not the new list,
+items that appear in the new list but not in the old list.
-and "link" events for
-all the items that appear in the new list but not in the old list.
 Roundup Database
 ----------------
-The Roundup database layer is implemented on top of the
+The Roundup database layer is implemented on top of the hyperdatabase
-hyperdatabase and mediates calls to the database.
+and mediates calls to the database. Some of the classes in the Roundup
-Some of the classes in the Roundup database are considered
+database are considered issue classes. The Roundup database layer adds
-issue classes.
+detectors and user items, and on issues it provides mail spools, nosy
-The Roundup database layer adds detectors and user items,
+lists, and superseders.
-and on issues it provides mail spools, nosy lists, and superseders.
 Reserved Classes
 ~~~~~~~~~~~~~~~~
-Internal to this layer we reserve three special classes
+Internal to this layer we reserve three special classes of items that
-of items that are not issues.
+are not issues.
 Users
 """""
-Users are stored in the hyperdatabase as items of
+Users are stored in the hyperdatabase as items of class "user".  The
-class "user".  The "user" class has the definition::
+"user" class has the definition::
 hyperdb.Class(db, "user", username=hyperdb.String(),
 password=hyperdb.String(),
 address=hyperdb.String())
 db.user.setkey("username")
 """"""""
 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,
+hyperdatabase, and if messages are stored in ordinary text files, they
-they can be grepped from the command line.)  The text of a message is
+can be grepped from the command line.)  The text of a message is saved
-saved in a file named after the message item designator (e.g. "msg23")
+in a file named after the message item designator (e.g. "msg23") for the
-for the sake of the command interface (see below).  Attachments are
+sake of the command interface (see below).  Attachments are stored
-stored separately and associated with "file" items.
+separately and associated with "file" items. The "msg" class has the
-The "msg" class has the definition::
+definition::
 hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
 recipients=hyperdb.Multilink("user"),
 date=hyperdb.Date(),
 summary=hyperdb.String(),
 files=hyperdb.Multilink("file"))
-The "author" property indicates the author of the message
+The "author" property indicates the author of the message (a "user" item
-(a "user" item must exist in the hyperdatabase for any messages
+must exist in the hyperdatabase for any messages that are stored in the
-that are stored in the system).
+system). The "summary" property contains a summary of the message for
-The "summary" property contains a summary of the message for display
+display in a message index.
-in a message index.
 Files
 """""
-Submitted files are represented by hyperdatabase
+Submitted files are represented by hyperdatabase items of class "file".
-items of class "file".  Like e-mail messages, the file content
+Like e-mail messages, the file content is stored in files outside the
-is stored in files outside the database,
+database, named after the file item designator (e.g. "file17"). The
-named after the file item designator (e.g. "file17").
+"file" class has the definition::
-The "file" class has the definition::
 hyperdb.Class(db, "file", user=hyperdb.Link("user"),
 name=hyperdb.String(),
 type=hyperdb.String())
-The "user" property indicates the user who submitted the
+The "user" property indicates the user who submitted the file, the
-file, the "name" property holds the original name of the file,
+"name" property holds the original name of the file, and the "type"
-and the "type" property holds the MIME type of the file as received.
+property holds the MIME type of the file as received.
 Issue Classes
 ~~~~~~~~~~~~~
 All issues have the following standard properties:
 files       hyperdb.Multilink("file")
 nosy        hyperdb.Multilink("user")
 superseder  hyperdb.Multilink("issue")
 =========== ==========================
-Also, two Date properties named "creation" and "activity" are
+Also, two Date properties named "creation" and "activity" are fabricated
-fabricated by the Roundup database layer.  By "fabricated" we
+by the Roundup database layer.  By "fabricated" we mean that no such
-mean that no such properties are actually stored in the
+properties are actually stored in the hyperdatabase, but when properties
-hyperdatabase, but when properties on issues are requested, the
+on issues are requested, the "creation" and "activity" properties are
-"creation" and "activity" properties are made available.
+made available. The value of the "creation" property is the date when an
-The value of the "creation" property is the date when an issue was
+issue was created, and the value of the "activity" property is the date
-created, and the value of the "activity" property is the
+when any property on the issue was last edited (equivalently, these are
-date when any property on the issue was last edited (equivalently,
+the dates on the first and last records in the issue's journal).
-these are the dates on the first and last records in the issue's journal).
 Roundupdb Interface Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The interface to a Roundup database delegates most method
+The interface to a Roundup database delegates most method calls to the
-calls to the hyperdatabase, except for the following
+hyperdatabase, except for the following changes and additional methods::
-changes and additional methods::
 class Database:
 def getuid(self):
 """Return the id of the "user" item associated with the user
 that owns this connection to the hyperdatabase."""
 # Overridden methods:
 def create(self, **propvalues):
 def set(self, **propvalues):
 def retire(self, itemid):
-"""These operations trigger detectors and can be vetoed.  Attempts
+"""These operations trigger detectors and can be vetoed.
-to modify the "creation" or "activity" properties cause a KeyError.
+Attempts to modify the "creation" or "activity" properties
+cause a KeyError.
 """
 # New methods:
 def audit(self, event, detector):
 class IssueClass(Class):
 # Overridden methods:
 def __init__(self, db, classname, **properties):
-"""The newly-created class automatically includes the "messages",
+"""The newly-created class automatically includes the
-"files", "nosy", and "superseder" properties.  If the 'properties'
+"messages", "files", "nosy", and "superseder" properties.
-dictionary attempts to specify any of these properties or a
+If the 'properties' dictionary attempts to specify any of
-"creation" or "activity" property, a ValueError is raised."""
+these properties or a "creation" or "activity" property, a
+ValueError is raised."""
 def get(self, itemid, propname):
 def getprops(self):
 """In addition to the actual properties on the item, these
 methods provide the "creation" and "activity" properties."""
 """
 def sendmessage(self, itemid, msgid):
 """Send a message to the members of an issue's nosy list.
-The message is sent only to users on the nosy list who are not
+The message is sent only to users on the nosy list who are
-already on the "recipients" list for the message.  These users
+not already on the "recipients" list for the message.  These
-are then added to the message's "recipients" list.
+users are then added to the message's "recipients" list.
 """
 Default Schema
 ~~~~~~~~~~~~~~
-The default schema included with Roundup turns it into a
+The default schema included with Roundup turns it into a typical
-typical software bug tracker.  The database is set up like this::
+software bug tracker.  The database is set up like this::
 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")
 Class(db, "issue", fixer=hyperdb.Multilink("user"),
 topic=hyperdb.Multilink("keyword"),
 priority=hyperdb.Link("priority"),
 status=hyperdb.Link("status"))
-(The "order" property hasn't been explained yet.  It
+(The "order" property hasn't been explained yet.  It gets used by the
-gets used by the Web user interface for sorting.)
+Web user interface for sorting.)
-The above isn't as pretty-looking as the schema specification
+The above isn't as pretty-looking as the schema specification in the
-in the first-stage submission, but it could be made just as easy
+first-stage submission, but it could be made just as easy with the
-with the addition of a convenience function like Choice
+addition of a convenience function like Choice for setting up the
-for setting up the "priority" and "status" classes::
+"priority" and "status" classes::
 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)
 Detector Interface
 ------------------
-Detectors are Python functions that are triggered on certain
+Detectors are Python functions that are triggered on certain kinds of
-kinds of events.  The definitions of the
+events.  The definitions of the functions live in Python modules placed
-functions live in Python modules placed in a directory set aside
+in a directory set aside for this purpose.  Importing the Roundup
-for this purpose.  Importing the Roundup database module also
+database module also imports all the modules in this directory, and the
-imports all the modules in this directory, and the ``init()``
+``init()`` function of each module is called when a database is opened
-function of each module is called when a database is opened to
+to provide it a chance to register its detectors.
-provide it a chance to register its detectors.
 There are two kinds of detectors:
 1. an auditor is triggered just before modifying an item
 2. a reactor is triggered just after an item has been modified
-When the Roundup database is about to perform a
+When the Roundup database is about to perform a ``create()``, ``set()``,
-``create()``, ``set()``, ``retire()``, or ``restore``
+``retire()``, or ``restore`` operation, it first calls any *auditors*
-operation, it first calls any *auditors* that
+that have been registered for that operation on that class. Any auditor
-have been registered for that operation on that class.
+may raise a *Reject* exception to abort the operation.
-Any auditor may raise a *Reject* exception
-to abort the operation.
+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
-If none of the auditors raises an exception, the database
+*reactors* that have been registered for the operation.
-proceeds to carry out the operation.  After it's done, it
-then calls all of the *reactors* that have been registered
-for the operation.
 Detector Interface Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``audit()`` and ``react()`` methods
+The ``audit()`` and ``react()`` methods register detectors on a given
-register detectors on a given class of items::
+class of items::
 class Class:
 def audit(self, event, detector):
 """Register an auditor on this class.
-'event' should be one of "create", "set", "retire", or "restore".
+'event' should be one of "create", "set", "retire", or
-'detector' should be a function accepting four arguments.
+"restore". 'detector' should be a function accepting four
+arguments.
 """
 def react(self, event, detector):
 """Register a reactor on this class.
-'event' should be one of "create", "set", "retire", or "restore".
+'event' should be one of "create", "set", "retire", or
-'detector' should be a function accepting four arguments.
+"restore". 'detector' should be a function accepting four
+arguments.
 """
 Auditors are called with the arguments::
 audit(db, cl, itemid, newdata)
-where ``db`` is the database, ``cl`` is an
+where ``db`` is the database, ``cl`` is an instance of Class or
-instance of Class or IssueClass within the database, and ``newdata``
+IssueClass within the database, and ``newdata`` is a dictionary mapping
-is a dictionary mapping property names to values.
+property names to values.
-For a ``create()``
+For a ``create()`` operation, the ``itemid`` argument is None and
-operation, the ``itemid`` argument is None and newdata
+newdata contains all of the initial property values with which the item
-contains all of the initial property values with which the item
 is about to be created.
-For a ``set()`` operation, newdata
+For a ``set()`` operation, newdata contains only the names and values of
-contains only the names and values of properties that are about
+properties that are about to be changed.
-to be changed.
 For a ``retire()`` or ``restore()`` operation, newdata is None.
 Reactors are called with the arguments::
 react(db, cl, itemid, olddata)
-where ``db`` is the database, ``cl`` is an
+where ``db`` is the database, ``cl`` is an instance of Class or
-instance of Class or IssueClass within the database, and ``olddata``
+IssueClass within the database, and ``olddata`` is a dictionary mapping
-is a dictionary mapping property names to values.
+property names to values.
-For a ``create()``
+For a ``create()`` operation, the ``itemid`` argument is the id of the
-operation, the ``itemid`` argument is the id of the
 newly-created item and ``olddata`` is None.
-For a ``set()`` operation, ``olddata``
+For a ``set()`` operation, ``olddata`` contains the names and previous
-contains the names and previous values of properties that were changed.
+values of properties that were changed.
 For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
 the retired or restored item and ``olddata`` is None.
 Detector Example
 ~~~~~~~~~~~~~~~~
 Here is an example of detectors written for a hypothetical
-project-management application, where users can signal approval
+project-management application, where users can signal approval of a
-of a project by adding themselves to an "approvals" list, and
+project by adding themselves to an "approvals" list, and a project
-a project proceeds when it has three approvals::
+proceeds when it has three approvals::
 # Permit users only to add themselves to the "approvals" list.
 def check_approvals(db, cl, id, newdata):
 if newdata.has_key("approvals"):
 def init(db):
 db.project.audit("set", check_approval)
 db.project.react("set", approve_project)
-Here is another example of a detector that can allow or prevent
+Here is another example of a detector that can allow or prevent the
-the creation of new items.  In this scenario, patches for a software
+creation of new items.  In this scenario, patches for a software project
-project are submitted by sending in e-mail with an attached file,
+are submitted by sending in e-mail with an attached file, and we want to
-and we want to ensure that there are text/plain attachments on
+ensure that there are text/plain attachments on the message.  The
-the message.  The maintainer of the package can then apply the
+maintainer of the package can then apply the patch by setting its status
-patch by setting its status to "applied"::
+to "applied"::
 # Only accept attempts to create new patches that come with patch files.
 def check_new_patch(db, cl, id, newdata):
 if not newdata["files"]:
 Command Interface
 -----------------
-The command interface is a very simple and minimal interface,
+The command interface is a very simple and minimal interface, intended
-intended only for quick searches and checks from the shell prompt.
+only for quick searches and checks from the shell prompt. (Anything more
-(Anything more interesting can simply be written in Python using
+interesting can simply be written in Python using the Roundup database
-the Roundup database module.)
+module.)
 Command Interface Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A single command, roundup, provides basic access to
+A single command, roundup, provides basic access to the hyperdatabase
-the hyperdatabase from the command line::
+from the command line::
 roundup-admin help
 roundup-admin get [-list] designator[, designator,...] propname
 roundup-admin set designator[, designator,...] propname=value ...
 roundup-admin find [-list] classname propname=value ...
 See ``roundup-admin help commands`` for a complete list of commands.
-Property values are represented as strings in command arguments
+Property values are represented as strings in command arguments and in
-and in the printed results:
+the printed results:
 - Strings are, well, strings.
 - Numbers are displayed the same as strings.
 - Booleans are displayed as 'Yes' or 'No'.
-- Date values are printed in the full date format in the local
+- Date values are printed in the full date format in the local time
-time zone, and accepted in the full format or any of the partial
+zone, and accepted in the full format or any of the partial formats
-formats explained above.
+explained above.
-- Link values are printed as item designators.  When given as
+- Link values are printed as item designators.  When given as an
-an argument, item designators and key strings are both accepted.
+argument, item designators and key strings are both accepted.
-- Multilink values are printed as lists of item designators
+- Multilink values are printed as lists of item designators joined by
-joined by commas.  When given as an argument, item designators
+commas.  When given as an argument, item designators and key strings
-and key strings are both accepted; an empty string, a single item,
+are both accepted; an empty string, a single item, or a list of items
-or a list of items joined by commas is accepted.
+joined by commas is accepted.
-When multiple items are specified to the
+When multiple items are specified to the roundup get or roundup set
-roundup get or roundup set
+commands, the specified properties are retrieved or set on all the
-commands, the specified properties are retrieved or set
+listed items.
-on all the listed items.
+When multiple results are returned by the roundup get or roundup find
-When multiple results are returned by the roundup get
+commands, they are printed one per line (default) or joined by commas
-or roundup find commands, they are printed one per
+(with the -list) option.
-line (default) or joined by commas (with the -list) option.
 Usage Example
 ~~~~~~~~~~~~~
-To find all messages regarding in-progress issues that
+To find all messages regarding in-progress issues that contain the word
-contain the word "spam", for example, you could execute the
+"spam", for example, you could execute the following command from the
-following command from the directory where the database
+directory where the database dumps its files::
-dumps its files::
 shell% for issue in `roundup find issue status=in-progress`; do
 > grep -l spam `roundup get $issue messages`
 > done
 msg23
 E-mail User Interface
 ---------------------
-The Roundup system must be assigned an e-mail address
+The Roundup system must be assigned an e-mail address at which to
-at which to receive mail.  Messages should be piped to
+receive mail.  Messages should be piped to the Roundup mail-handling
-the Roundup mail-handling script by the mail delivery
+script by the mail delivery system (e.g. using an alias beginning with
-system (e.g. using an alias beginning with "|" for sendmail).
+"|" for sendmail).
 Message Processing
 ~~~~~~~~~~~~~~~~~~
-Incoming messages are examined for multiple parts.
+Incoming messages are examined for multiple parts. In a multipart/mixed
-In a multipart/mixed message or part, each subpart is
+message or part, each subpart is extracted and examined.  In a
-extracted and examined.  In a multipart/alternative
+multipart/alternative message or part, we look for a text/plain subpart
-message or part, we look for a text/plain subpart and
+and ignore the other parts.  The text/plain subparts are assembled to
-ignore the other parts.  The text/plain subparts are
+form the textual body of the message, to be stored in the file
-assembled to form the textual body of the message, to
+associated with a "msg" class item. Any parts of other types are each
-be stored in the file associated with a "msg" class item.
+stored in separate files and given "file" class items that are linked to
-Any parts of other types are each stored in separate
-files and given "file" class items that are linked to
 the "msg" item.
-The "summary" property on message items is taken from
+The "summary" property on message items is taken from the first
-the first non-quoting section in the message body.
+non-quoting section in the message body. The message body is divided
-The message body is divided into sections by blank lines.
+into sections by blank lines. Sections where the second and all
-Sections where the second and all subsequent lines begin
+subsequent lines begin with a ">" or "|" character are considered
-with a ">" or "|" character are considered "quoting
+"quoting sections".  The first line of the first non-quoting section
-sections".  The first line of the first non-quoting
+becomes the summary of the message.
-section becomes the summary of the message.
+All of the addresses in the To: and Cc: headers of the incoming message
-All of the addresses in the To: and Cc: headers of the
+are looked up among the user items, and the corresponding users are
-incoming message are looked up among the user items, and
+placed in the "recipients" property on the new "msg" item.  The address
-the corresponding users are placed in the "recipients"
+in the From: header similarly determines the "author" property of the
-property on the new "msg" item.  The address in the From:
+new "msg" item. The default handling for addresses that don't have
-header similarly determines the "author" property of the
+corresponding users is to create new users with no passwords and a
-new "msg" item.
+username equal to the address.  (The web interface does not permit
-The default handling for
+logins for users with no passwords.)  If we prefer to reject mail from
-addresses that don't have corresponding users is to create
+outside sources, we can simply register an auditor on the "user" class
-new users with no passwords and a username equal to the
+that prevents the creation of user items with no passwords.
-address.  (The web interface does not permit logins for
-users with no passwords.)  If we prefer to reject mail from
+The subject line of the incoming message is examined to determine
-outside sources, we can simply register an auditor on the
+whether the message is an attempt to create a new issue or to discuss an
-"user" class that prevents the creation of user items with
+existing issue.  A designator enclosed in square brackets is sought as
-no passwords.
+the first thing on the subject line (after skipping any "Fwd:" or "Re:"
+prefixes).
-The subject line of the incoming message is examined to
-determine whether the message is an attempt to create a new
+If an issue designator (class name and id number) is found there, the
-issue or to discuss an existing issue.  A designator enclosed
+newly created "msg" item is added to the "messages" property for that
-in square brackets is sought as the first thing on the
+issue, and any new "file" items are added to the "files" property for
-subject line (after skipping any "Fwd:" or "Re:" prefixes).
+the issue.
-If an issue designator (class name and id number) is found
+If just an issue class name is found there, we attempt to create a new
-there, the newly created "msg" item is added to the "messages"
+issue of that class with its "messages" property initialized to contain
-property for that issue, and any new "file" items are added to
+the new "msg" item and its "files" property initialized to contain any
-the "files" property for the issue.
+new "file" items.
-If just an issue class name is found there, we attempt to
+Both cases may trigger detectors (in the first case we are calling the
-create a new issue of that class with its "messages" property
+set() method to add the message to the issue's spool; in the second case
-initialized to contain the new "msg" item and its "files"
+we are calling the create() method to create a new item).  If an auditor
-property initialized to contain any new "file" items.
+raises an exception, the original message is bounced back to the sender
+with the explanatory message given in the exception.
-Both cases may trigger detectors (in the first case we
-are calling the set() method to add the message to the
-issue's spool; in the second case we are calling the
-create() method to create a new item).  If an auditor
-raises an exception, the original message is bounced back to
-the sender with the explanatory message given in the exception.
 Nosy Lists
 ~~~~~~~~~~
-A standard detector is provided that watches for additions
+A standard detector is provided that watches for additions to the
-to the "messages" property.  When a new message is added, the
+"messages" property.  When a new message is added, the detector sends it
-detector sends it to all the users on the "nosy" list for the
+to all the users on the "nosy" list for the issue that are not already
-issue that are not already on the "recipients" list of the
+on the "recipients" list of the message.  Those users are then appended
-message.  Those users are then appended to the "recipients"
+to the "recipients" property on the message, so multiple copies of a
-property on the message, so multiple copies of a message
+message are never sent to the same user.  The journal recorded by the
-are never sent to the same user.  The journal recorded by
+hyperdatabase on the "recipients" property then provides a log of when
-the hyperdatabase on the "recipients" property then provides
+the message was sent to whom.
-a log of when the message was sent to whom.
 Setting Properties
 ~~~~~~~~~~~~~~~~~~
-The e-mail interface also provides a simple way to set
+The e-mail interface also provides a simple way to set properties on
-properties on issues.  At the end of the subject line,
+issues.  At the end of the subject line, ``propname=value`` pairs can be
-``propname=value`` pairs can be
+specified in square brackets, using the same conventions as for the
-specified in square brackets, using the same conventions
+roundup ``set`` shell command.
-as for the roundup ``set`` shell command.
 Web User Interface
 ------------------
-The web interface is provided by a CGI script that can be
+The web interface is provided by a CGI script that can be run under any
-run under any web server.  A simple web server can easily be
+web server.  A simple web server can easily be built on the standard
-built on the standard CGIHTTPServer module, and
+CGIHTTPServer module, and should also be included in the distribution
-should also be included in the distribution for quick
+for quick out-of-the-box deployment.
-out-of-the-box deployment.
+The user interface is constructed from a number of template files
-The user interface is constructed from a number of template
+containing mostly HTML.  Among the HTML tags in templates are
-files containing mostly HTML.  Among the HTML tags in templates
+interspersed some nonstandard tags, which we use as placeholders to be
-are interspersed some nonstandard tags, which we use as
+replaced by properties and their values.
-placeholders to be replaced by properties and their values.
 Views and View Specifiers
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two main kinds of views: *index* views and *issue* views.
+There are two main kinds of views: *index* views and *issue* views. An
-An index view displays a list of issues of a particular class,
+index view displays a list of issues of a particular class, optionally
-optionally sorted and filtered as requested.  An issue view
+sorted and filtered as requested.  An issue view presents the properties
-presents the properties of a particular issue for editing
+of a particular issue for editing and displays the message spool for the
-and displays the message spool for the issue.
+issue.
-A view specifier is a string that specifies
+A view specifier is a string that specifies all the options needed to
-all the options needed to construct a particular view.
+construct a particular view. It goes after the URL to the Roundup CGI
-It goes after the URL to the Roundup CGI script or the
+script or the web server to form the complete URL to a view.  When the
-web server to form the complete URL to a view.  When the
+result of selecting a link or submitting a form takes the user to a new
-result of selecting a link or submitting a form takes
+view, the Web browser should be redirected to a canonical location
-the user to a new view, the Web browser should be redirected
+containing a complete view specifier so that the view can be bookmarked.
-to a canonical location containing a complete view specifier
-so that the view can be bookmarked.
 Displaying Properties
 ~~~~~~~~~~~~~~~~~~~~~
-Properties appear in the user interface in three contexts:
+Properties appear in the user interface in three contexts: in indices,
-in indices, in editors, and as search filters.  For each type of
+in editors, and as search filters.  For each type of property, there are
-property, there are several display possibilities.  For example,
+several display possibilities.  For example, in an index view, a string
-in an index view, a string property may just be printed as
+property may just be printed as a plain string, but in an editor view,
-a plain string, but in an editor view, that property should
+that property should be displayed in an editable field.
-be displayed in an editable field.
+The display of a property is handled by functions in the
-The display of a property is handled by functions in
+``cgi.templating`` module.
-the ``cgi.templating`` module.
 Displayer functions are triggered by ``tal:content`` or ``tal:replace``
-tag attributes in templates.  The value of the attribute
+tag attributes in templates.  The value of the attribute provides an
-provides an expression for calling the displayer function.
+expression for calling the displayer function. For example, the
-For example, the occurrence of::
+occurrence of::
 tal:content="context/status/plain"
 in a template triggers a call to::
 context['status'].plain()
 where the context would be an item of the "issue" class.  The displayer
-functions can accept extra arguments to further specify
+functions can accept extra arguments to further specify details about
-details about the widgets that should be generated.
+the widgets that should be generated.
 Some of the standard displayer functions include:
-========= ====================================================================
+========= ==============================================================
 Function  Description
-========= ====================================================================
+========= ==============================================================
 plain     display a String property directly;
-display a Date property in a specified time zone with an option
+display a Date property in a specified time zone with an
-to omit the time from the date stamp; for a Link or Multilink
+option to omit the time from the date stamp; for a Link or
-property, display the key strings of the linked items (or the
+Multilink property, display the key strings of the linked
-ids if the linked class has no key property)
+items (or the ids if the linked class has no key property)
-field     display a property like the plain displayer above, but in a text
+field     display a property like the plain displayer above, but in a
-field to be edited
+text field to be edited
 menu      for a Link property, display a menu of the available choices
-========= ====================================================================
+========= ==============================================================
 See the `customisation`_ documentation for the complete list.
 Index Views
 ~~~~~~~~~~~
-An index view contains two sections: a filter section
+An index view contains two sections: a filter section and an index
-and an index section.
+section. The filter section provides some widgets for selecting which
-The filter section provides some widgets for selecting
+issues appear in the index.  The index section is a table of issues.
-which issues appear in the index.  The index section is
-a table of issues.
 Index View Specifiers
 """""""""""""""""""""
-An index view specifier looks like this (whitespace
+An index view specifier looks like this (whitespace has been added for
-has been added for clarity)::
+clarity)::
 /issue?status=unread,in-progress,resolved&
 topic=security,ui&
 :group=priority&
 :sort=-activity&
 :filters=status,topic&
 :columns=title,status,fixer
-The index view is determined by two parts of the
+The index view is determined by two parts of the specifier: the layout
-specifier: the layout part and the filter part.
+part and the filter part. The layout part consists of the query
-The layout part consists of the query parameters that
+parameters that begin with colons, and it determines the way that the
-begin with colons, and it determines the way that the
+properties of selected items are displayed. The filter part consists of
-properties of selected items are displayed.
+all the other query parameters, and it determines the criteria by which
-The filter part consists of all the other query parameters,
+items are selected for display.
-and it determines the criteria by which items
-are selected for display.
+The filter part is interactively manipulated with the form widgets
+displayed in the filter section.  The layout part is interactively
-The filter part is interactively manipulated with
+manipulated by clicking on the column headings in the table.
-the form widgets displayed in the filter section.  The
-layout part is interactively manipulated by clicking
+The filter part selects the union of the sets of issues with values
-on the column headings in the table.
+matching any specified Link properties and the intersection of the sets
+of issues with values matching any specified Multilink properties.
-The filter part selects the union of the
-sets of issues with values matching any specified Link
+The example specifies an index of "issue" items. Only issues with a
-properties and the intersection of the sets
+"status" of either "unread" or "in-progres" or "resolved" are displayed,
-of issues with values matching any specified Multilink
+and only issues with "topic" values including both "security" and "ui"
-properties.
+are displayed.  The issues are grouped by priority, arranged in
+ascending order; and within groups, sorted by activity, arranged in
-The example specifies an index of "issue" items.
+descending order.  The filter section shows filters for the "status" and
-Only issues with a "status" of either
+"topic" properties, and the table includes columns for the "title",
-"unread" or "in-progres" or "resolved" are displayed,
+"status", and "fixer" properties.
-and only issues with "topic" values including both
-"security" and "ui" are displayed.  The issues
+Associated with each issue class is a default layout specifier.  The
-are grouped by priority, arranged in ascending order;
+layout specifier in the above example is the default layout to be
-and within groups, sorted by activity, arranged in
+provided with the default bug-tracker schema described above in section
-descending order.  The filter section shows filters
+4.4.
-for the "status" and "topic" properties, and the
-table includes columns for the "title", "status", and
-"fixer" properties.
-Associated with each issue class is a default
-layout specifier.  The layout specifier in the above
-example is the default layout to be provided with
-the default bug-tracker schema described above in
-section 4.4.
 Index Section
 """""""""""""
-The template for an index section describes one row of
+The template for an index section describes one row of the index table.
-the index table.
+Fragments protected by a ``tal:condition="request/show/<property>"`` are
-Fragments enclosed in ``<property>...</property>``
+included or omitted depending on whether the view specifier requests a
-tags are included or omitted depending on whether the
+column for a particular property. The table cells are filled by the
-view specifier requests a column for a particular property.
+``tal:content="context/<property>"`` directive, which displays the value
-The table cells should contain <display> tags
+of the property.
-to display the values of the issue's properties.
 Here's a simple example of an index template::
 <tr>
-<td tal:condition="request/show/title" tal:content="contex/title"></td>
+<td tal:condition="request/show/title"
-<td tal:condition="request/show/status" tal:content="contex/status"></td>
+tal:content="contex/title"></td>
-<td tal:condition="request/show/fixer" tal:content="contex/fixer"></td>
+<td tal:condition="request/show/status"
+tal:content="contex/status"></td>
+<td tal:condition="request/show/fixer"
+tal:content="contex/fixer"></td>
 </tr>
 Sorting
 """""""
-String and Date values are sorted in the natural way.
+String and Date values are sorted in the natural way. Link properties
-Link properties are sorted according to the value of the
+are sorted according to the value of the "order" property on the linked
-"order" property on the linked items if it is present; or
+items if it is present; or otherwise on the key string of the linked
-otherwise on the key string of the linked items; or
+items; or finally on the item ids.  Multilink properties are sorted
-finally on the item ids.  Multilink properties are
+according to how many links are present.
-sorted according to how many links are present.
 Issue Views
 ~~~~~~~~~~~
-An issue view contains an editor section and a spool section.
+An issue view contains an editor section and a spool section. At the top
-At the top of an issue view, links to superseding and superseded
+of an issue view, links to superseding and superseded issues are always
-issues are always displayed.
+displayed.
 Issue View Specifiers
 """""""""""""""""""""
 An issue view specifier is simply the issue's designator::
 Editor Section
 """"""""""""""
-The editor section is generated from a template
+The editor section is generated from a template containing
-containing <display> tags to insert
+``tal:content="context/<property>/<widget>"`` directives to insert the
-the appropriate widgets for editing properties.
+appropriate widgets for editing properties.
 Here's an example of a basic editor template::
 <table>
 <tr>
 <textarea name=":note" rows=5 cols=60></textarea>
 </td>
 </tr>
 </table>
-As shown in the example, the editor template can also include a ":note" field,
+As shown in the example, the editor template can also include a ":note"
-which is a text area for entering a note to go along with a change.
+field, which is a text area for entering a note to go along with a
+change.
-When a change is submitted, the system automatically
-generates a message describing the changed properties.
+When a change is submitted, the system automatically generates a message
-The message displays all of the property values on the
+describing the changed properties. The message displays all of the
-issue and indicates which ones have changed.
+property values on the issue and indicates which ones have changed. An
-An example of such a message might be this::
+example of such a message might be this::
 title: Polly Parrot is dead
 priority: critical
 status: unread -> in-progress
 fixer: (none)
 keywords: parrot,plumage,perch,nailed,dead
-If a note is given in the ":note" field, the note is
+If a note is given in the ":note" field, the note is appended to the
-appended to the description.  The message is then added
+description.  The message is then added to the issue's message spool
-to the issue's message spool (thus triggering the standard
+(thus triggering the standard detector to react by sending out this
-detector to react by sending out this message to the nosy list).
+message to the nosy list).
 Spool Section
 """""""""""""
-The spool section lists messages in the issue's "messages"
+The spool section lists messages in the issue's "messages" property.
-property.  The index of messages displays the "date", "author",
+The index of messages displays the "date", "author", and "summary"
-and "summary" properties on the message items, and selecting a
+properties on the message items, and selecting a message takes you to
-message takes you to its content.
+its content.
 Access Control
 --------------
-At each point that requires an action to be performed, the security mechanisms
+At each point that requires an action to be performed, the security
-are asked if the current user has permission. This permission is defined as a
+mechanisms are asked if the current user has permission. This permission
-Permission.
+is defined as a Permission.
-Individual assignment of Permission to user is unwieldy. The concept of a
+Individual assignment of Permission to user is unwieldy. The concept of
-Role, which encompasses several Permissions and may be assigned to many Users,
+a Role, which encompasses several Permissions and may be assigned to
-is quite well developed in many projects. Roundup will take this path, and
+many Users, is quite well developed in many projects. Roundup will take
-allow the multiple assignment of Roles to Users, and multiple Permissions to
+this path, and allow the multiple assignment of Roles to Users, and
-Roles. These definitions are not persistent - they're defined when the
+multiple Permissions to Roles. These definitions are not persistent -
-application initialises.
+they're defined when the application initialises.
-There will be two levels of Permission. The Class level permissions define
+There will be two levels of Permission. The Class level permissions
-logical permissions associated with all items of a particular class (or all
+define logical permissions associated with all items of a particular
-classes). The Item level permissions define logical permissions associated
+class (or all classes). The Item level permissions define logical
-with specific items by way of their user-linked properties.
+permissions associated with specific items by way of their user-linked
+properties.
 Access Control Interface Specification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ''' Defines a Permission with the attributes
 - name
 - description
 - klass (optional)
-The klass may be unset, indicating that this permission is not
+The klass may be unset, indicating that this permission is
-locked to a particular hyperdb class. There may be multiple
+not locked to a particular hyperdb class. There may be
-Permissions for the same name for different classes.
+multiple Permissions for the same name for different
+classes.
 '''
 class Role:
 ''' Defines a Role with the attributes
 - name
 - permissions
 '''
 class Security:
 def __init__(self, db):
-''' Initialise the permission and role stores, and add in the
+''' Initialise the permission and role stores, and add in
-base roles (for admin user).
+the base roles (for admin user).
 '''
 def getPermission(self, permission, classname=None):
-''' Find the Permission matching the name and for the class, if the
+''' Find the Permission matching the name and for the class,
-classname is specified.
+if the classname is specified.
 Raise ValueError if there is no exact match.
 '''
 def hasPermission(self, permission, userid, classname=None):
-''' Look through all the Roles, and hence Permissions, and see if
+''' Look through all the Roles, and hence Permissions, and
-"permission" is there for the specified classname.
+see if "permission" is there for the specified
+classname.
 '''
 def hasItemPermission(self, classname, itemid, **propspec):
-''' Check the named properties of the given item to see if the
+''' Check the named properties of the given item to see if
-userid appears in them. If it does, then the user is granted
+the userid appears in them. If it does, then the user is
-this permission check.
+granted this permission check.
-'propspec' consists of a set of properties and values that
+'propspec' consists of a set of properties and values
-must be present on the given item for access to be granted.
+that must be present on the given item for access to be
+granted.
-If a property is a Link, the value must match the property
-value. If a property is a Multilink, the value must appear
+If a property is a Link, the value must match the
-in the Multilink list.
+property value. If a property is a Multilink, the value
+must appear in the Multilink list.
 '''
 def addPermission(self, **propspec):
 ''' Create a new Permission with the properties defined in
 'propspec'
 '''
 def addRole(self, **propspec):
-''' Create a new Role with the properties defined in 'propspec'
+''' Create a new Role with the properties defined in
+'propspec'
 '''
 def addPermissionToRole(self, rolename, permission):
 ''' Add the permission to the role's permission list.
 permissions like so (this example is ``cgi/client.py``)::
 def initialiseSecurity(security):
 ''' Create some Permissions and Roles on the security object
-This function is directly invoked by security.Security.__init__()
+This function is directly invoked by
-as a part of the Security object instantiation.
+security.Security.__init__() as a part of the Security
+object instantiation.
 '''
 p = security.addPermission(name="Web Registration",
 description="Anonymous users may register through the web")
 security.addToRole('Anonymous', p)
 Detectors may also define roles in their init() function::
 def init(db):
-# register an auditor that checks that a user has the "May Resolve"
+# register an auditor that checks that a user has the "May
-# Permission before allowing them to set an issue status to "resolved"
+# Resolve" Permission before allowing them to set an issue
+# status to "resolved"
 db.issue.audit('set', checkresolvedok)
 p = db.security.addPermission(name="May Resolve", klass="issue")
 security.addToRole('Manager', p)
 The tracker dbinit module then has in ``open()``::
 # all ok
 if db.security.hasItemPermission('issue', itemid, assignedto=userid):
 # all ok
-Code in the core will make use of these methods, as should code in auditors in
+Code in the core will make use of these methods, as should code in
-custom templates. The HTML templating may access the access controls through
+auditors in custom templates. The HTML templating may access the access
-the *user* attribute of the *request* variable. It exposes a ``hasPermission()``
+controls through the *user* attribute of the *request* variable. It
-method::
+exposes a ``hasPermission()`` method::
 tal:condition="python:request.user.hasPermission('Edit', 'issue')"
 or, if the *context* is *issue*, then the following is the same::
 Authentication of Users
 ~~~~~~~~~~~~~~~~~~~~~~~
-Users must be authenticated correctly for the above controls to work. This is
+Users must be authenticated correctly for the above controls to work.
-not done in the current mail gateway at all. Use of digital signing of
+This is not done in the current mail gateway at all. Use of digital
-messages could alleviate this problem.
+signing of messages could alleviate this problem.
-The exact mechanism of registering the digital signature should be flexible,
+The exact mechanism of registering the digital signature should be
-with perhaps a level of trust. Users who supply their signature through their
+flexible, with perhaps a level of trust. Users who supply their
-first message into the tracker should be at a lower level of trust to those
+signature through their first message into the tracker should be at a
-who supply their signature to an admin for submission to their user details.
+lower level of trust to those who supply their signature to an admin for
+submission to their user details.
 Anonymous Users
 ~~~~~~~~~~~~~~~
 Use Cases
 ~~~~~~~~~
-public - end users can submit bugs, request new features, request support
+public - end users can submit bugs, request new features, request
-The Users would be given the default "User" Role which gives "View" and
+support
-"Edit" Permission to the "issue" class.
+The Users would be given the default "User" Role which gives "View"
-developer - developers can fix bugs, implement new features, provide support
+and "Edit" Permission to the "issue" class.
-A new Role "Developer" is created with the Permission "Fixer" which is
+developer - developers can fix bugs, implement new features, provide
-checked for in custom auditors that see whether the issue is being
+support
-resolved with a particular resolution ("fixed", "implemented",
+A new Role "Developer" is created with the Permission "Fixer" which
+is checked for in custom auditors that see whether the issue is
+being resolved with a particular resolution ("fixed", "implemented",
 "supported") and allows that resolution only if the permission is
 available.
-manager - approvers/managers can approve new features and signoff bug fixes
+manager - approvers/managers can approve new features and signoff bug
-A new Role "Manager" is created with the Permission "Signoff" which is
+fixes
-checked for in custom auditors that see whether the issue status is being
+A new Role "Manager" is created with the Permission "Signoff" which
-changed similar to the developer example.
+is checked for in custom auditors that see whether the issue status
-admin - administrators can add users and set user's roles
+is being changed similar to the developer example. admin -
-The existing Role "Admin" has the Permissions "Edit" for all classes
+administrators can add users and set user's roles The existing Role
-(including "user") and "Web Roles" which allow the desired actions.
+"Admin" has the Permissions "Edit" for all classes (including
-system - automated request handlers running various report/escalation scripts
+"user") and "Web Roles" which allow the desired actions.
-A combination of existing and new Roles, Permissions and auditors could
+system - automated request handlers running various report/escalation
-be used here.
+scripts
+A combination of existing and new Roles, Permissions and auditors
+could be used here.
 privacy - issues that are only visible to some users
-A new property is added to the issue which marks the user or group of
+A new property is added to the issue which marks the user or group
-users who are allowed to view and edit the issue. An auditor will check
+of users who are allowed to view and edit the issue. An auditor will
-for edit access, and the template user object can check for view access.
+check for edit access, and the template user object can check for
+view access.
 Deployment Scenarios
 --------------------
-The design described above should be general enough
+The design described above should be general enough to permit the use of
-to permit the use of Roundup for bug tracking, managing
+Roundup for bug tracking, managing projects, managing patches, or
-projects, managing patches, or holding discussions.  By
+holding discussions.  By using items of multiple types, one could deploy
-using items of multiple types, one could deploy a system
+a system that maintains requirement specifications, catalogs bugs, and
-that maintains requirement specifications, catalogs bugs,
+manages submitted patches, where patches could be linked to the bugs and
-and manages submitted patches, where patches could be
+requirements they address.
-linked to the bugs and requirements they address.
 Acknowledgements
 ----------------
-My thanks are due to Christy Heyl for
+My thanks are due to Christy Heyl for reviewing and contributing
-reviewing and contributing suggestions to this paper
+suggestions to this paper and motivating me to get it done, and to Jesse
-and motivating me to get it done, and to
+Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich,
-Jesse Vincent, Mark Miller, Christopher Simons,
+and Dean Tribble for their assistance with the first-round submission.
-Jeff Dunmall, Wayne Gramlich, and Dean Tribble for
-their assistance with the first-round submission.
 Changes to this document
 ------------------------
 - Added Boolean and Number types
 - Added section Hyperdatabase Implementations
-- "Item" has been renamed to "Issue" to account for the more specific nature
+- "Item" has been renamed to "Issue" to account for the more specific
-of the Class.
+nature of the Class.
 - New Templating
 - Access Controls
 ------------------

Mercurial > p > roundup > code

comparison doc/design.txt @ 1661:b9c1226cb600