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).

Return type:

Iterable[str]

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)
__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: str | None

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.

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.
property duration: timedelta | None

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.
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.
property geo: Geo | None

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.

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: timedelta | None

Duration between alarm repeats

Returns a timedelta object
Timespan must return positive total_seconds() value
property repeat: int | None

Number of times to repeat alarm

Returns an integer for number of alarm repeats
Value must be >= 0
property trigger: timedelta | datetime | None

The trigger condition for the alarm

Returns either a timedelta or datetime object
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

Return type:

Iterator[Event]

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)

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)