Dates and Date Arithmetic

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.

As strings, date-and-time stamps are specified with the date in ISO8601 international standard format (yyyy-mm-dd) joined to the time (hh:mm:ss) by a period “.“. Dates in this form can be easily compared and are fairly readable when printed. An example of a valid stamp is “2000-06-24.13:03:59“. 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.

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 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>
• “11-07.09:32:43” means <Date yyyy-11-07.14:32:43>
• “14:25” means <Date yyyy-mm-dd.19:25: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 “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).

• “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. When adding or subtracting intervals involving months or years, the components are handled separately. For example, when evaluating “2000-06-25 + 1m 10d“, we first add one month to get 2000-07-25, then add 10 days to get 2000-08-04 (rather than trying to decide whether 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):
        """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 __add__(self, interval):
        """Add an interval to this date to produce another date."""

    def __sub__(self, interval):
        """Subtract an interval from this date to produce another
        date.
        """

    def __cmp__(self, other):
        """Compare this date to another date."""

    def __str__(self):
        """Return this date as a string in the yyyy-mm-dd.hh:mm:ss
        format.
        """

    def local(self, offset):
        """Return this date as yyyy-mm-dd.hh:mm:ss in a local time
        zone.
        """

class Interval:
    def __init__(self, spec):
        """Construct an interval given a specification."""

    def __cmp__(self, other):
        """Compare this interval to another interval."""

    def __str__(self):
        """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 Time 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(". + 2d")
<Date 2000-06-28.00:34:02>
>>> Date("1997-04-17", -5)
<Date 1997-04-17.00:00:00>
>>> Date("01-25", -5)
<Date 2000-01-25.00:00:00>
>>> Date("08-13.22:13", -5)
<Date 2000-08-14.03:13:00>
>>> Date("14:25", -5)
<Date 2000-06-25.19:25:00>
>>> Interval("  3w  1  d  2:00")
<Interval 22d 2:00>
>>> Date(". + 2d") - Interval("3w")
<Date 2000-06-07.00:34:02>

Items and Classes

Items contain data in properties. To Python, these properties are presented as the key-value pairs of a dictionary. Each item belongs to a class which defines the names and types of its properties. The database permits the creation and modification of classes as well as items.

Identifiers and Designators

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 designator 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.

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.

Property Names and Types

Property names must begin with a letter.

A property may be one of five basic types:

• String properties are for storing arbitrary-length strings.
• 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. Their values are Timestamp objects.
• A Link 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.
• A Multilink property refers to possibly many items in a specified class. The value is a list of integers.

None is also a permitted value for any of these property types. An 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 different kinds of properties. These objects are used when specifying what properties belong in classes:

class String:
    def __init__(self, indexme='no'):
        """An object designating a String property."""

class Boolean:
    def __init__(self):
        """An object designating a Boolean property."""

class Number:
    def __init__(self):
        """An object designating a Number property."""

class Date:
    def __init__(self):
        """An object designating a Date property."""

class Link:
    def __init__(self, classname, do_journal='yes'):
        """An object designating a Link property that links to
        items in a specified class.

        If the do_journal argument is not 'yes' then changes to
        the property are not journalled in the linked item.
        """

class Multilink:
    def __init__(self, classname, do_journal='yes'):
        """An object designating a Multilink property that links
        to items in a specified class.

        If the do_journal argument is not 'yes' then changes to
        the property are not journalled in the linked item(s).
        """

Here is the interface provided by the hyperdatabase:

class Database:
    """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
        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(), Class.retire(), and
        Class.restore() methods are disabled.
        """

    def __getattr__(self, classname):
        """A convenient way of calling self.getclass(classname)."""

    def getclasses(self):
        """Return a list of the names of all existing classes."""

    def getclass(self, classname):
        """Get the Class object representing a particular class.

        If 'classname' is not a valid class name, a KeyError is
        raised.
        """

class Class:
    """The handle to a particular class of items in a hyperdatabase.
    """

    def __init__(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.

        A proxied reference to the database is available as the
        'db' attribute on instances. For example, in
        'IssueClass.send_message', the following is used to lookup
        users, messages and files::

            users = self.db.user
            messages = self.db.msg
            files = self.db.file
        """

    # Editing items:

    def create(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 get(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 set(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 retire(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 restore(self, nodeid):
    '''Restore a retired node.

    Make node available for all operations like it was before
    retirement.
    '''

    def history(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 setkey(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 getkey(self):
        """Return the name of the key property for this class or
        None.
        """

    def lookup(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 find(self, **propspec):
        """Get the ids of items in this class which link to the
        given items.

        'propspec' consists of keyword args propname=itemid or
                   propname={<itemid 1>:1, <itemid 2>:1, ...}
        '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.

        Any item in this class whose 'propname' property links to
        any of the itemids will be returned. Examples::

            db.issue.find(messages='1')
            db.issue.find(messages={'1':1,'3':1}, files={'7':1})
        """

    def filter(self, search_matches, filterspec, sort, group):
        """Return a list of the ids of the active nodes in this class that
        match the 'filter' spec, sorted by the group spec and then the
        sort spec.

        "search_matches" is a container type

        "filterspec" is {propname: value(s)}

        "sort" and "group" are [(dir, prop), ...] where dir is '+', '-'
        or None and prop is a prop name or None. Note that for
        backward-compatibility reasons a single (dir, prop) tuple is
        also allowed.

        The filter must match all properties specificed. If the property
        value to match is a list:

        1. String properties must match all elements in the list, and
        2. Other properties must match any of the elements in the list.

        The propname in filterspec and prop in a sort/group spec may be
        transitive, i.e., it may contain properties of the form
        link.link.link.name, e.g. you can search for all issues where
        a message was added by a certain user in the last week with a
        filterspec of
        {'messages.author' : '42', 'messages.creation' : '.-1w;'}
        """

    def list(self):
        """Return a list of the ids of the active items in this
        class.
        """

    def count(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 getprops(self):
        """Return a dictionary mapping property names to property
        objects.
        """

    def addprop(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.
        """

    def getitem(self, itemid, cache=1):
        """ Return a Item convenience wrapper for the item.

        'itemid' must be the id of an existing item of this class or
        an IndexError is raised.

        'cache' indicates whether the transaction cache should be
        queried for the item. If the item has been modified and you
        need to determine what its values prior to modification are,
        you need to set cache=0.
        """

class Item:
    """ A convenience wrapper for the given item. It provides a
    mapping interface to a single item's properties
    """

Hyperdatabase Implementations

Hyperdatabase implementations exist to create the interface described in the hyperdb interface specification over an existing storage mechanism. Examples are relational databases, *dbm key-value databases, and so on.

Several implementations are provided - they belong in the roundup.backends package.

Application Example

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">
>>> hyperdb.Class(db, "status", name=hyperdb.String())
<hyperdb.Class "status">
>>> _.setkey("name")
>>> db.status.create(name="unread")
1
>>> db.status.create(name="in-progress")
2
>>> db.status.create(name="testing")
3
>>> db.status.create(name="resolved")
4
>>> db.status.count()
4
>>> db.status.list()
[1, 2, 3, 4]
>>> db.status.lookup("in-progress")
2
>>> db.status.retire(3)
>>> db.status.list()
[1, 2, 4]
>>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))
<hyperdb.Class "issue">
>>> db.issue.create(title="spam", status=1)
1
>>> db.issue.create(title="eggs", status=2)
2
>>> db.issue.create(title="ham", status=4)
3
>>> db.issue.create(title="arguments", status=2)
4
>>> db.issue.create(title="abuse", status=1)
5
>>> hyperdb.Class(db, "user", username=hyperdb.String(),
... password=hyperdb.String())
<hyperdb.Class "user">
>>> db.issue.addprop(fixer=hyperdb.Link("user"))
>>> db.issue.getprops()
{"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
 "user": <hyperdb.Link to "user">}
>>> db.issue.set(5, status=2)
>>> db.issue.get(5, "status")
2
>>> db.status.get(2, "name")
"in-progress"
>>> db.issue.get(5, "title")
"abuse"
>>> db.issue.find("status", db.status.lookup("in-progress"))
[2, 4, 5]
>>> db.issue.history(5)
[(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse",
"status": 1}),
 (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]
>>> db.status.history(1)
[(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
 (<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 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.

Reserved Classes

Internal to this layer we reserve three special classes of items that are not issues.

hyperdb.Class(db, "user", username=hyperdb.String(),
                          password=hyperdb.String(),
                          address=hyperdb.String())
db.user.setkey("username")

hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
                         recipients=hyperdb.Multilink("user"),
                         date=hyperdb.Date(),
                         summary=hyperdb.String(),
                         files=hyperdb.Multilink("file"))

hyperdb.Class(db, "file", user=hyperdb.Link("user"),
                          name=hyperdb.String(),
                          type=hyperdb.String())

Issue Classes

All issues have the following standard properties:

Also, two Date properties named “creation” and “activity” are fabricated by the Roundup database layer. Two user Link properties, “creator” and “actor” are also fabricated. By “fabricated” we mean that no such properties are actually stored in the hyperdatabase, but when properties on issues are requested, the “creation”/”creator” and “activity”/”actor” properties are made available. The value of the “creation”/”creator” properties relate to issue creation, and the value of the “activity”/ “actor” properties relate to the last editing of any property on the issue (equivalently, 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 calls to the hyperdatabase, except for the following 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."""

class Class:
    # Overridden methods:

    def create(self, **propvalues):
    def set(self, **propvalues):
    def retire(self, itemid):
        """These operations trigger detectors and can be vetoed.
        Attempts to modify the "creation", "creator", "activity"
        properties or "actor" cause a KeyError.
        """

class IssueClass(Class):
    # Overridden methods:

    def __init__(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", "creator", "activity" or
        "actor" 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", "creator", "activity" and
        "actor" properties."""

    # New methods:

    def addmessage(self, itemid, summary, text):
        """Add a message to an issue'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 issue.
        """

    def nosymessage(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 already on the "recipients" list for the message.  These
        users are then added to the message's "recipients" list.
        """

Default Schema

The default schema included with Roundup turns it into a typical 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")
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"),
                   keyword=hyperdb.Multilink("keyword"),
                   priority=hyperdb.Link("priority"),
                   status=hyperdb.Link("status"))

(The “order” property hasn’t been explained yet. It gets used by the Web user interface for sorting.)

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 Choice for setting up the “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)
    return hyperdb.Link(name)

Detector Interface Specification

The audit() and react() methods register detectors on a given class of items:

class Class:
    def audit(self, event, detector, priority=100):
        """Register an auditor on this class.

        'event' should be one of "create", "set", "retire", or
        "restore". 'detector' should be a function accepting four
        arguments. Detectors are called in priority order, execution
        order is undefined for detectors with the same priority.
        """

    def react(self, event, detector, priority=100):
        """Register a reactor on this class.

        'event' should be one of "create", "set", "retire", or
        "restore". 'detector' should be a function accepting four
        arguments. Detectors are called in priority order, execution
        order is undefined for detectors with the same priority.
        """

Auditors are called with the arguments:

audit(db, cl, itemid, newdata)

where db is the database, cl is an instance of Class or IssueClass within the database, and newdata is a dictionary mapping property names to values.

For a create() operation, the itemid argument is None and newdata contains all of the initial property values with which the item is about to be created.

For a set() operation, newdata contains only the names and values of properties that are about 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 instance of Class or IssueClass within the database, and olddata is a dictionary mapping property names to values.

For a create() operation, the itemid argument is the id of the newly-created item and olddata is None.

For a set() operation, olddata contains the names and previous 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 of a project by adding themselves to an “approvals” list, and a project 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"):
        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)
    db.project.react("set", approve_project)

Here is another example of a detector that can allow or prevent the creation of new items. In this scenario, patches for a software project are submitted by sending in e-mail with an attached file, and we want to ensure that there are text/plain attachments on the message. The maintainer of the package can then apply the patch by setting its status 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"]:
        raise Reject, "You can't submit a new patch without " \
                      "attaching a patch file."
    for fileid in newdata["files"]:
        if db.file.get(fileid, "type") != "text/plain":
            raise Reject, "Submitted patch files must be " \
                          "text/plain."

# When the status is changed from "approved" to "applied", apply the
# patch.

def apply_patch(db, cl, id, olddata):
    if (cl.get(id, "status") == db.status.lookup("applied") and
        olddata["status"] == db.status.lookup("approved")):
        # ...apply the patch...

def init(db):
    db.patch.audit("create", check_new_patch)
    db.patch.react("set", apply_patch)

Command Interface Specification

A single command, roundup-admin, provides basic access to the hyperdatabase 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 and in 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 time zone, and accepted in the full format or any of the partial formats explained above.
• Link values are printed as item designators. When given as an argument, item designators and key strings are both accepted.
• Multilink values are printed as lists of item designators joined by commas. When given as an argument, item designators and key strings are both accepted; an empty string, a single item, or a list of items joined by commas is accepted.

When multiple items are specified to the roundup-admin get or roundup-admin set commands, the specified properties are retrieved or set on all the listed items.

When multiple results are returned by the roundup-admin get or roundup-admin find commands, they are printed one per line (default) or joined by commas (with the -list) option.

Usage Example

To find all messages regarding in-progress issues that contain the word “spam”, for example, you could execute the following command from the directory where the database dumps its files:

shell% for issue in `roundup-admin find issue status=in-progress`; do
> grep -l spam `roundup-admin get $issue messages`
> done
msg23
msg49
msg50
msg61
shell%

Or, using the -list option, this can be written as a single command:

shell% grep -l spam `roundup-admin get \
    \`roundup-admin find -list issue status=in-progress\` messages`
msg23
msg49
msg50
msg61
shell%

Message Processing

Incoming messages are examined for multiple parts. In a multipart/mixed message or part, each subpart is extracted and examined. In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. The text/plain subparts are assembled to form the textual body of the message, to be stored in the file associated with a “msg” class item. 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 first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin with a “>” or “|” character are considered “quoting sections”. The first line of the first non-quoting section becomes the summary of the message.

All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user items, and the corresponding users are placed in the “recipients” property on the new “msg” item. The address in the From: header similarly determines the “author” property of the new “msg” item. The default handling for addresses that don’t have corresponding users is to create new users with no passwords and a username equal to the address. (The web interface does not permit logins for users with no passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the “user” class that prevents the creation of user items with no passwords.

The subject line of the incoming message is examined to determine whether the message is an attempt to create a new issue or to discuss an existing issue. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any “Fwd:” or “Re:” prefixes).

If an issue designator (class name and id number) is found there, the newly created “msg” item is added to the “messages” property for that issue, and any new “file” items are added to the “files” property for the issue.

If just an issue class name is found there, we attempt to create a new issue of that class with its “messages” property initialized to contain the new “msg” item and its “files” property initialized to contain any new “file” items.

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 to the “messages” property. When a new message is added, the detector sends it to all the users on the “nosy” list for the issue that are not already on the “recipients” list of the message. Those users are then appended to the “recipients” property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the “recipients” property then provides a log of when the message was sent to whom.

Setting Properties

The e-mail interface also provides a simple way to set properties on issues. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup-admin set shell command.

Views and View Specifiers

There are two main kinds of views: index views and issue views. An index view displays a list of issues of a particular class, optionally sorted and filtered as requested. An issue view presents the properties of a particular issue for editing and displays the message spool for the issue.

A view specifier is a string that specifies all the options needed to construct a particular view. It goes after the URL to the Roundup CGI script or 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 view, the Web browser should be redirected 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: in indices, in editors, and as search filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field.

The display of a property is handled by functions in the cgi.templating module.

Displayer functions are triggered by tal:content or tal:replace tag attributes in templates. The value of the attribute provides an expression for calling the displayer function. For example, the 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 details about the widgets that should be generated.

Some of the standard displayer functions include:

See the customisation documentation for the complete list.

Index Views

An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which issues appear in the index. The index section is a table of issues.

/issue?status=unread,in-progress,resolved&
    keyword=security,ui&
    :group=priority,-status&
    :sort=-activity&
    :filters=status,keyword&
    :columns=title,status,fixer

<tr>
  <td tal:condition="request/show/title"
      tal:content="contex/title"></td>
  <td tal:condition="request/show/status"
      tal:content="contex/status"></td>
  <td tal:condition="request/show/fixer"
      tal:content="contex/fixer"></td>
</tr>

Issue Views

An issue view contains an editor section and a spool section. At the top of an issue view, links to superseding and superseded issues are always displayed.

/patch23

<table>
<tr>
    <td colspan=2
        tal:content="python:context.title.field(size='60')"></td>
</tr>
<tr>
    <td tal:content="context/fixer/field"></td>
    <td tal:content="context/status/menu"></td>
</tr>
<tr>
    <td tal:content="context/nosy/field"></td>
    <td tal:content="context/priority/menu"></td>
</tr>
<tr>
    <td colspan=2>
      <textarea name=":note" rows=5 cols=60></textarea>
    </td>
</tr>
</table>

title: Polly Parrot is dead
priority: critical
status: unread -> in-progress
fixer: (none)
keywords: parrot,plumage,perch,nailed,dead

Access Control Interface Specification

The security module defines:

class Permission:
    ''' Defines a Permission with the attributes
        - name
        - description
        - klass (optional)
        - properties (optional)
        - check function (optional)

        The klass may be unset, indicating that this permission is
        not locked to a particular hyperdb class. There may be
        multiple Permissions for the same name for different
        classes.

        If property names are set, permission is restricted to those
        properties only.

        If check function is set, permission is granted only when
        the function returns value interpreted as boolean true.
        The function is called with arguments db, userid, itemid.
    '''

class Role:
    ''' Defines a Role with the attributes
        - name
        - description
        - permissions
    '''

class Security:
    def __init__(self, db):
        ''' Initialise the permission and role stores, and add in
            the base roles (for admin user).
        '''

    def getPermission(self, permission, classname=None, properties=None,
            check=None):
        ''' Find the Permission exactly matching the name, class,
            properties list and check function.

            Raise ValueError if there is no exact match.
        '''

    def hasPermission(self, permission, userid, classname=None,
            property=None, itemid=None):
        ''' Look through all the Roles, and hence Permissions, and
            see if "permission" exists given the constraints of
            classname, property and itemid.

            If classname is specified (and only classname) then the
            search will match if there is *any* Permission for that
            classname, even if the Permission has additional
            constraints.

            If property is specified, the Permission matched must have
            either no properties listed or the property must appear in
            the list.

            If itemid is specified, the Permission matched must have
            either no check function defined or the check function,
            when invoked, must return a True value.

            Note that this functionality is actually implemented by the
            Permission.test() method.
        '''

    def addPermission(self, **propspec):
        ''' Create a new Permission with the properties defined in
            'propspec'. See the Permission class for the possible
            keyword args.
        '''

    def addRole(self, **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.

            'rolename' is the name of the role to add permission to.
        '''

Modules such as cgi/client.py and mailgw.py define their own 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__() 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" 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():

# open the database - it must be modified to init the Security class
# from security.py as db.security
db = Database(config, name)

# add some extra permissions and associate them with roles
ei = db.security.addPermission(name="Edit", klass="issue",
                description="User is allowed to edit issues")
db.security.addPermissionToRole('User', ei)
ai = db.security.addPermission(name="View", klass="issue",
                description="User is allowed to access issues")
db.security.addPermissionToRole('User', ai)

In the dbinit init():

# create the two default users
user.create(username="admin", password=Password(adminpw),
            address=config.ADMIN_EMAIL, roles='Admin')
user.create(username="anonymous", roles='Anonymous')

Then in the code that matters, calls to hasPermission and hasItemPermission are made to determine if the user has permission to perform some action:

if db.security.hasPermission('issue', 'Edit', userid):
    # 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 custom templates. The HTML templating may access the access controls through the user attribute of the request variable. It exposes a hasPermission() method:

tal:condition="python:request.user.hasPermission('Edit', 'issue')"

or, if the context is issue, then the following is the same:

tal:condition="python:request.user.hasPermission('Edit')"

Authentication of Users

Users must be authenticated correctly for the above controls to work. This is not done in the current mail gateway at all. Use of digital signing of messages could alleviate this problem.

The exact mechanism of registering the digital signature should be flexible, with perhaps a level of trust. Users who supply their signature through their first message into the tracker should be at a lower level of trust to those who supply their signature to an admin for submission to their user details.

Anonymous Users

The “anonymous” user must always exist, and defines the access permissions for anonymous users. Unknown users accessing Roundup through the web or email interfaces will be logged in as the “anonymous” user.

Use Cases

public - end users can submit bugs, request new features, request

support The Users would be given the default “User” Role which gives “View” and “Edit” Permission to the “issue” class.

developer - developers can fix bugs, implement new features, provide

support 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 A new Role “Manager” is created with the Permission “Signoff” which is checked for in custom auditors that see whether the issue status is being changed similar to the developer example. admin - administrators can add users and set user’s roles The existing Role “Admin” has the Permissions “Edit” for all classes (including “user”) and “Web Roles” which allow the desired actions.

system - automated request handlers running various report/escalation

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 users who are allowed to view and edit the issue. An auditor will check for edit access, and the template user object can check for view access.