`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(_Event__task, start=None, delta=None, message='')[source]¶

Initialise a new Event object.

Parameters

__task – Task name to track
start (Union[datetime, str, None]) – Start time for event
delta (Union[timedelta, str, None]) – Duration for event
message (Optional[str]) – Message to attach to event

running()[source]¶

Check if event is running.

Return type: Union[str, bool]
Returns: Event name, if running

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

Stop running event.

Parameters

message (Optional[str]) – Message to attach to event
force (bool) – Re-stop a previously stopped event

Raises

TaskNotRunningError – Event not running

Return type

None

writer()[source]¶

Prepare object for export.

Return type: Dict[str, Optional[str]]
Returns: Event data for object storage

class rdial.events.Events(_Events__iterable=None, backup=True)[source]¶

Initialise a new Events object.

Parameters

__iterable – Objects to add to container
backup (bool) – Whether to create backup files

property dirty¶

Modified tasks requiring sync against storage.

Return type: Iterable[str]

filter(_Events__filt)[source]¶

Apply filter to events.

Parameters: __filt – Function to filter with
Return type: Events
Returns: Events matching given filter function

for_date(year, month=None, day=None)[source]¶

Filter events for a specific date.

Parameters

year (int) – Year to filter on
month (Optional[int]) – Month to filter on
day (Optional[int]) – Day to filter on

Return type

Events

Returns

Events occurring within specified date

for_task(_Events__task)[source]¶

Filter events for a specific task.

Parameters: __task – Task name to filter on
Return type: Events
Returns: Events marked with given task name

for_week(_Events__year, _Events__week)[source]¶

Filter events for a specific ISO-8601 week.

Parameters

__year – Year to filter events on
__week – ISO-8601 week number to filter events on

Return type

Events

Returns

Events occurring in given ISO-8601 week

last()[source]¶

Return current/last event.

Note

This handles the empty database case by returning None.

Return type: Optional[Event]
Returns: Last recorded event

static read(_Events__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 – Location to read database files from
backup (bool) – Whether to create backup files
write_cache (bool) – Whether to write cache files

Return type

Events

Returns

Parsed events database

running()[source]¶

Check if an event is running.

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

Return type: Union[str, bool]
Returns: Running event, if an event running

start(_Events__task, new=False, start='')[source]¶

Start a new event.

Parameters

__task – Task name to track
new (bool) – Whether to create a new task
start (Union[datetime, str]) – ISO-8601 start time for event

Raises

TaskRunningError – An event is already running

Return type

None

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

Stop running event.

Parameters

message (Optional[str]) – Message to attach to event
force (bool) – Re-stop a previously stopped event

Raises

TaskNotRunningError – No task running!

Return type

None

sum()[source]¶

Sum duration of all events.

Return type: timedelta
Returns: Sum of all event deltas

tasks()[source]¶

Generate a list of tasks in the database.

Return type: List[str]
Returns: Names of tasks in database

static wrapping(_Events__directory, backup=True, write_cache=True)[source]¶

Convenience context handler to manage reading and writing database.

Parameters

__directory – Database location
backup (bool) – Whether to create backup files
write_cache (bool) – Whether to write cache files

Return type

Iterator[Events]

write(_Events__directory)[source]¶

Write database file.

Parameters: __directory – Location to write database files to
Return type: None

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'

Event¶

Examples¶

`Event`¶