calingen.interfaces.data_exchange

Provides data exchange formats.

Module Contents

Classes

CalendarEntry

Data structure to pass calendar entries around.

CalendarEntryList

A list of calendar entries.

Attributes

SOURCE_EXTERNAL

Constant for entries provided by implementations of calingen.interfaces.plugin_api.EventProvider

SOURCE_INTERNAL

Constant for app-internal Event instances.
class calingen.interfaces.data_exchange.CalendarEntry(title, category, timestamp, source)

Data structure to pass calendar entries around.

Parameters:
title

The actual title of the entry.

Type:

str

category

While this is actually a simple str, it is expected to be of the specified type. A lookup against EventCategory.values is performed, but this is not an enforced validation!

If the constructor was called with an instance of EventCategory.value, this will be a translateable string.

Type:

str

timestamp

The paremeter accepts the specified types and will convert them to datetime.datetime internally. If a str is given, dateutil.parser.parse() is used and may raise an exception, if the provided string could not be parsed.

Type:

datetime.datetime

source

Expected is a tuple of the form ("INTERNAL", [int]), where [int] is interpreted as an id of an Event instance, or ("EXTERNAL", [str]), where [str] is used as a plain string.

For implementations of EventProvider it is recommended to provide its title attribute.

Type:

tuple

Raises:

  • CalendarEntry.CalendarEntryException – Raised if source was not provided as tuple

  • dateutil.parser._parser.ParserError – Raised if timestamp is provided as str and could not be parsed by dateutil.parser.parse()

Warning

The instance’s source attribute is not included in checks for equality (__eq__()) or during hash-processing (__hash__())!

This means, that if an event is specified by an external provider and by using the app’s calingen.models.event.Event model, using the same title, category and timestamp, they are considered equal.

The implementation of calingen.interfaces.data_exchange.CalendarEntryList relies internally on a set, which means the entries are unique. So, only one of the events will be present in the resulting CalendarEntryList.

Notes

Instances of this class are single, self-contained entries in a calendar. They provide an abstraction and common interface to events provided by the app’s user (instances of Event) and events provided by plugins (implementations of EventProvider).

However, there is no real case of using this class without and accompanying CalendarEntryList. Actually, all resolve() operations are required to return an instance of CalendarEntryList with instances of this class as its payload.

As you can see, the documentation of the class’s magic methods is kept at a minimum. See the source code for further details!

__eq__(other)

Check equality with other object.

__hash__()

Provide a unique representation of the instance.

__key()

Provide internal representation of the instance.

__lt__(other)

Provide less than comparison with other object.

__repr__()

Provide an instance’s representation.

__str__()

Provide a string representation of the instance.

class calingen.interfaces.data_exchange.CalendarEntryList

A list of calendar entries.

_entries

This attribute stores the list of calendar entries. It is implemented as a set, which makes it mutable and unordered. Primarily a set is used to ensure that all included items are unique.

Type:

set

Warning

While objects of this class are intended to store / handle instances of CalendarEntry, this is not enforced or validated (EAFP).

Notes

This class is a close companion of CalendarEntry instances.

Internally, the app expects the result of any resolve() operation to be an instance of this class with a set (or list) of CalendarEntry instances.

__len__()
add(entry)

Add a CalendarEntry to the list.

Parameters:

entry (CalendarEntry) – The entry to be added to this class’s list.

Raises:

CalendarEntryList.CalendarEntryListException – Raised if no entry is provided.

Warning

There is no validation of the input type!

merge(entry_list_instance)

Merge two instances of CalendarEntryList.

Parameters:

entry_list_instance (CalendarEntryList) – The instance to be merged into this one.

Warning

There is no validation of the input type!

Notes

Providing a merge() method instead of enabling addition of objects of this type is a design choice and may be subject to change.

sorted()

Return the object’s _entries sorted by start.

Returns:

The sorted list of CalendarEntry.

Return type:

list

Warning

While this class uses internally a set to manage the entries, this method returns a list.

If consuming code requires uniqueness of items, use this method as late as possible.

calingen.interfaces.data_exchange.SOURCE_EXTERNAL = EXTERNAL

Constant for entries provided by implementations of calingen.interfaces.plugin_api.EventProvider

calingen.interfaces.data_exchange.SOURCE_INTERNAL = INTERNAL

Constant for app-internal Event instances.