API description

Calendar

class ics.icalendar.Calendar(imports=None, events=None, todos=None, creator=None)[source]

Represents an unique rfc5545 iCalendar.

events

a set of Event contained in the Calendar

todos

a set of Todo contained in the Calendar

timeline

a Timeline instance linked to this Calendar

__eq__(other)[source]

Return self==value.

Return type

bool

__init__(imports=None, events=None, todos=None, creator=None)[source]

Instantiates a new Calendar.

Parameters

  • imports (str) – data to be imported into the Calendar,

  • events (Set[Event]) – Events to be added to the calendar

  • todos (Set[Todo]) – Todos to be added to the calendar

  • creator (string) – uid of the creator program.

If imports is specified, every other argument will be ignored.

__iter__()[source]

Returns: iterable: an iterable version of seralize(), line per line (with line-endings).

Example

Can be used to write calendar to a file:

>>> c = Calendar(); c.events.add(Event(name="My cool event"))
>>> open('my.ics', 'w').writelines(c)
Return type

Iterable[str]

__ne__(other)[source]

Return self!=value.

Return type

bool

__repr__()[source]

Return repr(self).

Return type

str

clone()[source]
Returns

an exact deep copy of self

Return type

Calendar

classmethod parse_multiple(string)[source]

” Parses an input string that may contain mutiple calendars and retruns a list of ics.event.Calendar

__hash__ = None
property creator: Optional[str]

Get or set the calendar’s creator.

Will return a string.
May be set to a string.
Creator is the PRODID iCalendar property.
It uniquely identifies the program that created the calendar.
Return type

Optional[str]

Event

class ics.event.Event(name=None, begin=None, end=None, duration=None, uid=None, description=None, created=None, last_modified=None, location=None, url=None, transparent=None, alarms=None, attendees=None, categories=None, status=None, organizer=None, geo=None, classification=None)[source]

A calendar event.

Can be full-day or between two instants. Can be defined by a beginning instant and a duration or end instant.

Unsupported event attributes can be found in event.extra, a ics.parse.Container. You may add some by appending a ics.parse.ContentLine to .extra

__and__(other, *args, **kwarg)

Create a new event which covers the time range of two intersecting events

All extra parameters are passed to the Event constructor.

Parameters

other – the other event

Returns

a new Event instance

__eq__(other)[source]

Return self==value.

Return type

bool

__ge__(other)[source]

Return self>=value.

Return type

bool

__gt__(other)[source]

Return self>value.

Return type

bool

__hash__()[source]
Returns

hash of self. Based on self.uid.

Return type

int

__init__(name=None, begin=None, end=None, duration=None, uid=None, description=None, created=None, last_modified=None, location=None, url=None, transparent=None, alarms=None, attendees=None, categories=None, status=None, organizer=None, geo=None, classification=None)[source]

Instantiates a new ics.event.Event.

Parameters

  • name (Optional[str]) – rfc5545 SUMMARY property

  • begin (Arrow-compatible) –

  • end (Arrow-compatible) –

  • duration (Optional[timedelta]) –

  • uid (Optional[str]) – must be unique

  • description (Optional[str]) –

  • created (Arrow-compatible) –

  • last_modified (Arrow-compatible) –

  • location (Optional[str]) –

  • url (Optional[str]) –

  • transparent (Optional[bool]) –

  • alarms (Optional[Iterable[BaseAlarm]]) –

  • attendees (Optional[Iterable[Attendee]]) –

  • categories (Optional[Iterable[str]]) –

  • status (Optional[str]) –

  • organizer (Optional[Organizer]) –

  • classification (Optional[str]) –

Raises

ValueError – if end and duration are specified at the same time

__le__(other)[source]

Return self<=value.

Return type

bool

__lt__(other)[source]

Return self<value.

Return type

bool

__repr__()[source]

Return repr(self).

Return type

str

add_attendee(attendee)[source]

Add an attendee to the attendees set

clone()[source]
Returns

an exact copy of self

Return type

Event

has_end()[source]
Returns

self has an end

Return type

bool

join(other, *args, **kwarg)[source]

Create a new event which covers the time range of two intersecting events

All extra parameters are passed to the Event constructor.

Parameters

other – the other event

Returns

a new Event instance

make_all_day()[source]

Transforms self to an all-day event.

The event will span all the days from the begin to the end day.

Return type

None

property all_day

Return: bool: self is an all-day event

property begin: Arrow

Get or set the beginning of the event.

Will return an Arrow object.
May be set to anything that Arrow.get() understands.
If an end is defined (not a duration), .begin must not be set to a superior value.
Return type

Arrow

property duration: Optional[timedelta]

Get or set the duration of the event.

Will return a timedelta object.
May be set to anything that timedelta() understands.
May be set with a dict ({“days”:2, “hours”:6}).
If set to a non null value, removes any already existing end time.
Return type

Optional[timedelta]

property end: Arrow

Get or set the end of the event.

Will return an Arrow object.
May be set to anything that Arrow.get() understands.
If set to a non null value, removes any already existing duration.
Setting to None will have unexpected behavior if begin is not None.
Must not be set to an inferior value than self.begin.
Return type

Arrow

property geo: Optional[Geo]

Get or set the geo position of the event.

Will return a namedtuple object.
May be set to any Geo, tuple or dict with latitude and longitude keys.
If set to a non null value, removes any already existing geo.
Return type

Optional[Geo]

Alarms

class ics.alarm.base.BaseAlarm(trigger=None, repeat=None, duration=None)[source]

A calendar event VALARM base class

__eq__(other)[source]

Two alarms are considered equal if they have the same type and base values.

Return type

bool

__init__(trigger=None, repeat=None, duration=None)[source]

Instantiates a new ics.alarm.BaseAlarm.

Adheres to RFC5545 VALARM standard: http://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html

Parameters

  • trigger (datetime.timedelta OR datetime.datetime) – Timespan to alert before parent action, or absolute time to alert

  • repeat (integer) – How many times to repeat the alarm

  • duration (datetime.timedelta) – Duration between repeats

Raises

ValueError – If trigger, repeat, or duration do not match the RFC spec.

__ne__(other)[source]

Return self!=value.

Return type

bool

__repr__()[source]

Return repr(self).

clone()[source]
Returns

an exact copy of self

Return type

Alarm

__hash__ = None
abstract property action

VALARM action to be implemented by concrete classes

property duration: Optional[timedelta]

Duration between alarm repeats

Returns a timedelta object
Timespan must return positive total_seconds() value
Return type

Optional[timedelta]

property repeat: Optional[int]

Number of times to repeat alarm

Returns an integer for number of alarm repeats
Value must be >= 0
Return type

Optional[int]

property trigger: Optional[Union[timedelta, datetime]]

The trigger condition for the alarm

Returns either a timedelta or datetime object
Return type

Union[timedelta, datetime, None]

class ics.alarm.AudioAlarm(trigger=None, repeat=None, duration=None)[source]

A calendar event VALARM with AUDIO option.

__init__(trigger=None, repeat=None, duration=None)[source]

Instantiates a new ics.alarm.BaseAlarm.

Adheres to RFC5545 VALARM standard: http://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html

Parameters

  • trigger (datetime.timedelta OR datetime.datetime) – Timespan to alert before parent action, or absolute time to alert

  • repeat (integer) – How many times to repeat the alarm

  • duration (datetime.timedelta) – Duration between repeats

Raises

ValueError – If trigger, repeat, or duration do not match the RFC spec.

property action

VALARM action to be implemented by concrete classes

class ics.alarm.DisplayAlarm(trigger=None, repeat=None, duration=None, display_text=None)[source]

A calendar event VALARM with DISPLAY option.

__init__(trigger=None, repeat=None, duration=None, display_text=None)[source]

Instantiates a new ics.alarm.BaseAlarm.

Adheres to RFC5545 VALARM standard: http://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html

Parameters

  • trigger (datetime.timedelta OR datetime.datetime) – Timespan to alert before parent action, or absolute time to alert

  • repeat (integer) – How many times to repeat the alarm

  • duration (datetime.timedelta) – Duration between repeats

Raises

ValueError – If trigger, repeat, or duration do not match the RFC spec.

property action

VALARM action to be implemented by concrete classes

class ics.alarm.EmailAlarm(trigger=None, repeat=None, duration=None, subject=None, body=None, recipients=None)[source]

A calendar event VALARM with Email option.

__init__(trigger=None, repeat=None, duration=None, subject=None, body=None, recipients=None)[source]

Instantiates a new ics.alarm.BaseAlarm.

Adheres to RFC5545 VALARM standard: http://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html

Parameters

  • trigger (datetime.timedelta OR datetime.datetime) – Timespan to alert before parent action, or absolute time to alert

  • repeat (integer) – How many times to repeat the alarm

  • duration (datetime.timedelta) – Duration between repeats

Raises

ValueError – If trigger, repeat, or duration do not match the RFC spec.

property action

VALARM action to be implemented by concrete classes

class ics.alarm.none.NoneAlarm(trigger=None, repeat=None, duration=None)[source]

A calendar event VALARM with NONE option.

property action

VALARM action to be implemented by concrete classes

class ics.alarm.custom.CustomAlarm(trigger=None, repeat=None, duration=None, action=None)[source]

A calendar event VALARM with custom ACTION.

__init__(trigger=None, repeat=None, duration=None, action=None)[source]

Instantiates a new ics.alarm.BaseAlarm.

Adheres to RFC5545 VALARM standard: http://icalendar.org/iCalendar-RFC-5545/3-6-6-alarm-component.html

Parameters

  • trigger (datetime.timedelta OR datetime.datetime) – Timespan to alert before parent action, or absolute time to alert

  • repeat (integer) – How many times to repeat the alarm

  • duration (datetime.timedelta) – Duration between repeats

Raises

ValueError – If trigger, repeat, or duration do not match the RFC spec.

property action

VALARM action to be implemented by concrete classes

Timeline

class ics.timeline.Timeline(calendar)[source]
__init__(calendar)[source]

Instanciates a new Timeline. (You should not have to instanciate a new timeline by yourself)

Parameters

calendar – ics.icalendar.Calendar

__iter__()[source]

Iterates on every event from the ics.icalendar.Calendar in chronological order

Note :

  • chronological order is defined by the comparaison operators in ics.event.Event

  • Events with no begin will not appear here. (To list all events in a Calendar use Calendar.events)

Return type

Iterator[Event]

at(instant)[source]

Iterates (in chronological order) over all events that are occuring during instant.

Parameters

instant (Arrow object) –

Return type

Iterator[Event]

included(start, stop)[source]

Iterates (in chronological order) over every event that is included in the timespan between start and stop

Parameters

  • start (Arrow) – (Arrow object)

  • stop (Arrow) – (Arrow object)

Return type

Iterator[Event]

now()[source]

Iterates (in chronological order) over all events that occurs now

Return type

Iterator[Event]

on(day, strict=False)[source]

Iterates (in chronological order) over all events that occurs on day

Parameters

  • day (Arrow object) –

  • strict (bool) – if True events will be returned only if they are strictly included in day.

Return type

Iterator[Event]

overlapping(start, stop)[source]

Iterates (in chronological order) over every event that has an intersection with the timespan between start and stop

Parameters

  • start (Arrow) – (Arrow object)

  • stop (Arrow) – (Arrow object)

Return type

Iterator[Event]

start_after(instant)[source]

Iterates (in chronological order) on every event from the ics.icalendar.Calendar in chronological order. The first event of the iteration has a starting date greater (later) than instant

Parameters

instant (Arrow) – (Arrow object) starting point of the iteration

Return type

Iterator[Event]

today(strict=False)[source]

Iterates (in chronological order) over all events that occurs today

Parameters

strict (bool) – if True events will be returned only if they are strictly included in day.

Return type

Iterator[Event]

__weakref__

list of weak references to the object (if defined)