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

static 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

  • day (int) – Day to filter on

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.

Note

Assumes a new Events object should be created if the directory 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

  • new (bool) – Whether to create a new task

  • 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(directory, backup=True, write_cache=True)[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'