Onegov Event API

Models

class onegov.event.models.Event(**kwargs)[source]

Defines an event.

Occurrences are stored in a seperate table containing only a minimal set of attributes from the event. This could also be archieved using postgres directly with dateutil/plpythonu/pg_rrule and materialized views.

Occurrences are only created/updated, if the event is published. Occurrences are created only for this and the next year.

id

Internal number of the event

state

State of the event

description = None

description of the event

organizer = None

the event organizer

organizer_email = None

the event organizer’s public e-mail address

price = None

the price of the event (a text field, not an amount)

source = None

the source of the event, if imported

source_updated = None

when the source of the event was last updated (if imported)

recurrence

Recurrence of the event (RRULE, see RFC2445)

image

The associated image

pdf

The associated PDF

set_blob(blob, content, filename=None)[source]

Adds or removes the given blob.

occurrences

Occurences of the event

property es_public

Returns True if the model is available to be found by the public. If false, only editors/admins will see this object in the search results.

property es_skip

Returns True if the indexing of this specific model instance should be skipped.

source_url(request)[source]

Returns an url pointing to the external event if imported.

property latest_occurrence

Returns the occurrence which is presently occurring, the next one to occur or the last occurrence.

validate_recurrence(key, r)[source]

Our rrules are quite limited in their complexity. This validator makes sure that is actually the case.

This is a somewhat harsh limit, but it mirrors the actual use of onegov.event at this point. More complex rrules are not handled by the UI, nor is there currently a plan to do so.

Currently supported are weekly recurrences and lists of rdates.

The rational is that people commonly add recurring events on a weekly basis (which is a lot of work for a whole year). Or on a monthly or yearly basis, in which case selection of single dates is acceptable, or even preferrable to complex rrules.

This UI talk doesn’t belong into a module of course, but it is again a reailty that only a strict subset of rules is handled and so we want to catch events which we cannot edit in our UI early if they are imported from outside.

occurrence_dates(limit=True, localize=False)[source]

Returns the start dates of all occurrences.

Returns non-localized dates per default. Limits the occurrences per default to this and the next year.

spawn_occurrence(start)[source]

Create an occurrence at the given date, without storing it.

property virtual_occurrence

Before the event is accepted, there are no real occurrences stored in the database.

At this time it is useful to be able to generate the latest occurence without storing it.

submit()[source]

Submit the event.

publish()[source]

Publish the event.

Publishing the event will generate the occurrences.

withdraw()[source]

Withdraw the event.

Withdraw the event will delete the occurrences.

get_ical_vevents(url=None)[source]

Returns the event and all its occurrences as icalendar objects.

If the calendar has a bunch of RDATE’s instead of a proper RRULE, we return every occurrence as seperate event since most calendars doen’t support RDATE’s.

as_ical(url=None)[source]

Returns the event and all its occurrences as iCalendar string.

class onegov.event.models.EventFile(**kwargs)[source]
class onegov.event.models.Occurrence(**kwargs)[source]

Defines an occurrence of an event.

id

Internal number of the occurence

event_id

Event this occurrence belongs to

as_ical(url=None)[source]

Returns the occurrence as iCalendar string.

Collections

class onegov.event.collections.EventCollection(session, page=0, state=None)[source]

Manage a list of events.

subset()[source]

Returns an SQLAlchemy query containing all records that should be considered for pagination.

property page_index

Returns the current page index (starting at 0).

page_by_index(index)[source]

Returns the page at the given index. A page here means an instance of the class inheriting from the Pagination base class.

for_state(state)[source]

Returns a new instance of the collection with the given state.

add(title, start, end, timezone, autoclean=True, **optional)[source]

Add a new event.

A unique, URL-friendly name is created automatically for this event using the title and optionally numbers for duplicate names.

Every time a new event is added, old, stale events are deleted unless disabled with the autoclean option.

Returns the created event or None if already automatically deleted.

delete(event)[source]

Delete an event.

remove_stale_events(max_stale=None)[source]

Remove events which have never been submitted and are created more than five days ago.

by_name(name)[source]

Returns an event by its URL-friendly name.

by_id(id)[source]

Return an event by its id.

from_import(items, purge=None)[source]

Add or updates the given events.

Only updates events which have changed. Uses Event.source_updated if available, falls back to comparing all relevant attributes.

Doesn’t change the states of events allowing to permanently withdraw imported events.

Items

A list of `EventImportItem`s or event sources to keep from purging.

Purge

Optionally removes all events with the given meta-source-prefix not present in the given events.

from_ical(ical)[source]

Imports the events from an iCalender string.

We assume the timezone to be Europe/Zurich!

class onegov.event.collections.OccurrenceCollection(session, page=0, range=None, start=None, end=None, outdated=False, tags=None, locations=None)[source]

Manages a list of occurrences.

Occurrences are read only (no add method here), they are generated automatically when adding a new event.

Occurrences can be filtered by relative date ranges (today, tomorrow, weekend, week, month) or by a given start date and/or end date. The range filter is dominant and overwrites the start and end dates if provided.

By default, only current occurrences are used.

Occurrences can be additionally filtered by tags and locations.

subset()[source]

Returns an SQLAlchemy query containing all records that should be considered for pagination.

property page_index

Returns the current page index (starting at 0).

page_by_index(index)[source]

Returns the page at the given index. A page here means an instance of the class inheriting from the Pagination base class.

range_to_dates(range, start=None, end=None)[source]

Returns the start and end date for the given range relative to now. Defaults to the given start and end date.

Valid ranges are:
  • today

  • tomorrow

  • weekend (next or current Friday to Sunday)

  • week (current Monday to Sunday)

  • month (current)

for_filter(**kwargs)[source]

Returns a new instance of the collection with the given filters and copies the current filters if not specified.

If a valid range is provided, start and end dates are ignored. If the range is invalid, it is ignored.

Adds or removes a single tag/location if given.

used_timezones

Returns a list of all the timezones used by the occurrences.

used_tags

Returns a list of all the tags used by the occurrences.

This could be solve possibly more effienciently with the skey function currently not supported by SQLAlchemy (e.g. select distinct(skeys(tags))), see http://stackoverflow.com/q/12015942/3690178

query()[source]

Queries occurrences with the set parameters.

Finds occurrences which: * are between start and end date * have any of the tags * have any of the locations (exact word)

Start and end date are assumed to be dates only and therefore without a timezone - we search for the given date in the timezone of the occurrence.

by_name(name)[source]

Returns an occurrence by its URL-friendly name.

The URL-friendly name is automatically constructed as follows:

unique name of the event-date of the occurrence

e.g.

squirrel-park-visit-6-2015-06-20

as_ical(request)[source]

Returns the the events of the given occurrences as iCalendar string.

Utils

class onegov.event.utils.GuidleExportData(root)[source]

Represents a whole guidle export.