Architecture

Data storage is a separate interface. Key feature is the keying on a set of multiple key objects (for example a principle, a project, an activity and a boolean 'billable' flag); this keeps all scenario's open. The ITimeLogStore can then provide services such as recording, quering and totalling, optionally through iterators. The number of keys attached to a log-entry key is variable, giving it essentially limitless possibilities of marking logged time. The resolution of the log is 1 day.

Interfaces

These interfaces are being implemented in interfaces.py

A key:

class ITimeLogKey(Interface):
    domain = TextLine('Key source domain')
    id = TextLine('Key identifier')
    description = Text('Detailed description of the key')
    title = TextLine('A title for the key for UI purposes')

A domain of keys:

class ITimeLogKeyDomain(IEnumerableMapping):
    id = TextLine('Domain Id')

A log entry:

class ITimeLogEntry(Interface):
    keys = Set('Set of keys describing the entity against which time is logged.')
    date = Date('Date of log entry')
    duration = Timedelta('Logged time')
    comment = Text('Arbitrary notes')

The log store itself:

class ITimeLogStore(Interface):
    def recordTime(*entries):
        """Stores a series of time registrations

        entries is a sequence of ITimeLogEntries.

        """

    def queryKeys(keys, start_time=None, end_time=None):
        """Find completions for keys

        key: a set of ITimeLogKeys. Returns a sequence of 
        complete key sets that have been used to log time against, expanded 
        from the given ITimeLogKeys. So (A) could return ((A, B, C),
        (A, B, D)), while (D) would only return ((A, B, D),)

        start_time and end_time can be used to limit the search to a given
        timeframe.

        """

    def queryDateRange(keys):
        """Get the first and last date for which there are log entries matching

        Returns a (datetime.date, datetime.date) tuple specifing the range of
        dates there are log entries found.

        """

    def iterateDayTotals(keys, start_date=None):
        """Iterate over totalled log information

        Starting at start_date iterate over daily totals returned as ITimeLogEntries.

        """

    def queryTotal(keys, start_date=None, end_date=None):
        """Get the sum of time logged

        Returns the total duration of the entries matching the given keys and
        limited by the start_date and end_date.

        """

A timesheet itself. These collect the input for a given timeperiod and perform validation. This is also the place to implement workflow.

class ITimeSheet(ITimeLogStore):
    startDate = Date('Date of first log entry on this sheet')
    endDate = Date('Date of last log entry on this sheet')
    viewKeys = Set('This timesheet is a view limited by these keys',
                    readonly=True)