calingen.models

Calingen’s implementations of django.db.models.Model.

In the context of a Django application, models define the app’s core data, that is persisted in a database layer (abstracted by DJango’s ORM).

This package also includes model-related implementations of django.db.models.QuerySet, django.db.models.Manager and django.forms.ModelForm.

Notes

It’s kind of recommended to have fat models in a Django application, that handle most of the app’s business logic.

However, fat models might lead to models, that are too tightly connected to each other.

Calingen’s models aim to present and manage the app’s data and enable working with that data.

Submodules

Package Contents

Classes

Event

Represents one event in a user's calendar.

Profile

Represents the app-specific profile.
class calingen.models.Event(*args, **kwargs)

Bases: django.db.models.Model

Represents one event in a user’s calendar.

Warning

The class documentation only includes code that is actually shipped by the calingen app. Inherited attributes/methods (provided by Django’s Model) are not documented here.

class Meta
app_label = calingen
unique_together = ['profile', 'title', 'start']
verbose_name
verbose_name_plural
calingen_manager

App-/model-specific manager, that provides additional functionality.

This manager is set to calingen.models.event.EventManager. Its implementation provides augmentations of Event objects, by annotating them on database level. This will reduce the number of required database queries, if attributes of the object are accessed.

The manager has to be used explicitly.

category

The category of this Event.

Notes

Some functionalities of the Event class depend on the actual EventCategory stored in this attribute.

The attribute is implemented as CharField with its possible values limited by calingen.constants.EventCategory.

objects

The model’s default manager.

The default manager is set to django.db.models.Manager, which is the default value. In order to add the custom calingen_manager as an additional manager, the default manager has to be provided explicitly (see topics/db/managers/#default-managers).

profile

Reference to a Profile object.

Notes

This is implemented as a ForeignKey with on_delete=CASCADE, meaning: if the referenced Profile object is deleted, all referencing Event objects are discarded aswell.

The backwards relation (see ForeignKey.related_name) is named "events".

start

Date and time of a recurring event (datetime.datetime).

Warning

The name of this attribute might be misleading at first. calingen will be developed in small steps, of which the first one will be to track annual aniversaries with the Event class. Nevertheless, it is planned to enable calingen to track generic recurring events. In that implementation step, Event instances will have a start and end datetime.

To ease the refactoring, this attribute is already named start.

Notes

The attribute is implemented as DateTimeField.

title

The actual title of this Event (str).

Notes

The attribute is implemented as CharField.

__str__()

Return str(self).

get_absolute_url()

Return the absolute URL for instances of this model.

Returns:

The absolute URL for instances of this model.

Return type:

str

resolve(year=None)

Resolve this object’s start for a given year.

Parameters:

year (int, optional) – The year to resolve for. Will use the current year if not specified.

Returns:

The method returns a CalendarEntryList with entries for the given year.

Return type:

CalendarEntryList

class calingen.models.Profile(*args, **kwargs)

Bases: django.db.models.Model

Represents the app-specific profile.

Warning

The class documentation only includes code that is actually shipped by the calingen app. Inherited attributes/methods (provided by Django’s Model) are not documented here.

class Meta
app_label = calingen
verbose_name
verbose_name_plural
property event_provider

Get and set the list of EventProvider.

This method is used to access the Profile’s EventProvider. The returned object will have three attributes, active, unavailable and newly_unavailable: active contains the selected EventProvider plugins, that are currently active in this project. If the user had selected EventProvider plugins, that are currently not available in this project, i.e. because they were deactivated by the administrator, these plugins are moved to unavailable. Also, these plugins are included in newly_unavailable and then picked up in the get_context_data() method to provide messages to the user.

Notes

While the implementation of the getter involves some logic to perform the operations as described above, the setter simply applies the provided value to _event_provider. This means, that if the user did not actually update its profile, the operation performed by the getter is simply discarded.

_event_provider

Manage EventProvider plugins for this profile.

Notes

This is implemented as a JSONField and should be interfaced by its custom event_provider() getter and setter methods, provided as a property.

calingen_manager

App-/model-specific manager, that provides additional functionality.

This manager is set to calingen.models.profile.ProfileManager. Its implementation provides augmentations of Profile objects, by annotating them on database level. This will reduce the number of required database queries, if attributes of the object are accessed.

The manager has to be used explicitly.

objects

The model’s default manager.

The default manager is set to django.db.models.Manager, which is the default value. In order to add the custom calingen_manager as an additional manager, the default manager has to be provided explicitly (see topics/db/managers/#default-managers).

owner

Reference to a Django User.

Notes

This is implemented as a OneToOneField with on_delete=CASCADE, meaning: if the referenced User object is deleted, the referencing Profile object is discarded aswell.

To keep this application as pluggable as possible, the referenced class is dependent on AUTH_USER_MODEL. With this implementation, the project may substitute the User model provided by Django without breaking any functionality in calingen (see Reusable Apps and AUTH_USER_MODEL).

__str__()

Return str(self).

get_absolute_url()

Return the absolute URL for instances of this model.

Returns:

The absolute URL for instances of this model.

Return type:

str

resolve(year=None)

Combine all event providers results for a given year into one CalendarEntryList.

Parameters:

year (int, optional) – The year to use for resolving the EventProvider.

Returns:

A single instance including all events from all active providers.

Return type:

CalendarEntryList