Event

Note

The documentation in this section is aimed at people wishing to contribute to rdial, and can be skipped if you are simply using the tool from the command line.

class rdial.events.Event(task, start=None, delta=None, message='')[source]

Initialise a new Event object.

Parameters:
running()[source]

Check if event is running.

Returns:Event name, if running
Return type:str
stop(message=None, force=False)[source]

Stop running event.

Parameters:
  • message (str) – Message to attach to event
  • force (bool) – Re-stop a previously stopped event
Raises:

TaskNotRunningError – Event not running

writer()[source]

Prepare object for export.

Returns:Event data for object storage
Return type:dict
class rdial.events.Events(iterable=None, backup=True)[source]

Initialise a new Events object.

Parameters:
  • iterable (list) – Objects to add to container
  • backup (bool) – Whether to create backup files
context(directory, backup=True, write_cache=True)[source]

Convenience context handler to manage reading and writing database.

Warning

Deprecated name for wrapping

dirty

Modified tasks requiring sync against storage.

filter(filt)[source]

Apply filter to events.

Parameters:filt (types.FunctionType) – Function to filter with
Returns:Events matching given filter function
Return type:Events
for_date(year, month=None, day=None)[source]

Filter events for a specific date.

Parameters:
  • year (int) – Year to filter on
  • month (int) – Month to filter on, or None
  • day (int) – Day to filter on, or None
Returns:

Events occurring within specified date

Return type:

Events

for_task(task)[source]

Filter events for a specific task.

Parameters:task (str) – Task name to filter on
Returns:Events marked with given task name
Return type:Events
for_week(year, week)[source]

Filter events for a specific ISO-8601 week.

Parameters:
  • year (int) – Year to filter events on
  • week (int) – ISO-8601 month number to filter events on
Returns:

Events occurring in given ISO-8601 week

Return type:

Events

last()[source]

Return current/last event.

This handles the empty database case by returning None

Returns:Last recorded event
Return type:Event
static read(directory, backup=True, write_cache=True)[source]

Read and parse database.

Assume a new Events object should be created if the file is missing

Parameters:
  • directory (str) – Location to read database files from
  • backup (bool) – Whether to create backup files
  • write_cache (bool) – Whether to write cache files
Returns:

Parsed events database

Return type:

Events

running()[source]

Check if an event is running.

We return the running task, if one exists, for easy access.

Returns:Running event, if an event running
Return type:Event
start(task, new=False, start='')[source]

Start a new event.

Parameters:
  • task (str) – Task name to tracking
  • start (str) – ISO-8601 start time for event
Raises:

TaskRunningError – An event is already running

stop(message=None, force=False)[source]

Stop running event.

Parameters:
  • message (str) – Message to attach to event
  • force (bool) – Re-stop a previously stopped event
Raises:

TaskNotRunningError – No task running!

sum()[source]

Sum duration of all events.

Returns:Sum of all event deltas
Return type:datetime.timedelta
tasks()[source]

Generate a list of tasks in the database.

Returns:Names of tasks in database
Return type:list of str
static wrapping(*args, **kwds)[source]

Convenience context handler to manage reading and writing database.

Parameters:
  • directory (str) – Database location
  • backup (bool) – Whether to create backup files
  • write_cache (bool) – Whether to write cache files
write(directory)[source]

Write database file.

Parameters:directory (str) – Location to write database files to
class rdial.events.RdialDialect[source]

CSV dialect for rdial data files.

Examples

>>> event = Event('test')
>>> event.running()
'test'
>>> event.stop('complete')
>>> event.running()
False
>>> data = event.writer()
>>> data['message']
'complete'
>>> event2 = Event('test', start="2013-01-01T12:00:00Z")

>>> events = Events([event, event2])
>>> events.filter(lambda x: x.message == 'complete')
Events([Event('test', '...', '...', 'complete')])
>>> events.for_date(2013, 1)
Events([Event('test', '2013-01-01T12:00:00Z', '', '')])
>>> events.for_week(2012, 53)
Events([Event('test', '2013-01-01T12:00:00Z', '', '')])
>>> events.running()
'test'