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 __str__, 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

creator

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
Return type:

None
__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
all_day

Return: bool: self is an all-day event

begin

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
duration

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]
end

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
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.
Return type:

None
__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
action

VALARM action to be implemented by concrete classes

duration

Duration between alarm repeats

Returns a timedelta object
Timespan must return positive total_seconds() value
Return type:Optional[timedelta]
repeat

Number of times to repeat alarm

Returns an integer for number of alarm repeats
Value must be >= 0
Return type:Optional[int]
trigger

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.
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.
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.
class ics.alarm.none.NoneAlarm(trigger=None, repeat=None, duration=None)[source]

A calendar event VALARM with NONE option.

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.
Return type:

None
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
Return type:None
__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(day, 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)