recurring-ical-events


Namerecurring-ical-events JSON
Version 3.5.1 PyPI version JSON
download
home_pageNone
SummaryCalculate recurrence times of events, todos, alarms and journals based on icalendar RFC5545.
upload_time2025-02-12 19:53:25
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseGNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. 0. Additional Definitions. As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. "The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. 1. Exception to Section 3 of the GNU GPL. You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. 2. Conveying Modified Versions. If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. 3. Object Code Incorporating Material from Library Header Files. The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the object code with a copy of the GNU GPL and this license document. 4. Combined Works. You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the Combined Work with a copy of the GNU GPL and this license document. c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. d) Do one of the following: 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) 5. Combined Libraries. You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 6. Revised Versions of the GNU Lesser General Public License. The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.
keywords alarm calendar events icalendar ics journal rfc5545 scheduling todo
VCS
bugtrack_url
requirements click icalendar python-dateutil six tzdata x-wr-timezone
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            Recurring ICal events for Python
================================

.. image:: https://github.com/niccokunzmann/python-recurring-ical-events/actions/workflows/tests.yml/badge.svg
   :target: https://github.com/niccokunzmann/python-recurring-ical-events/actions/workflows/tests.yml
   :alt: GitHub CI build and test status
.. image:: https://badge.fury.io/py/recurring-ical-events.svg
   :target: https://pypi.python.org/pypi/recurring-ical-events
   :alt: Python Package Version on Pypi
.. image:: https://img.shields.io/pypi/dm/recurring-ical-events.svg
   :target: https://pypi.org/project/recurring-ical-events/#files
   :alt: Downloads from Pypi
.. image:: https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective
   :target: https://opencollective.com/open-web-calendar/
   :alt: Support on Open Collective
.. image:: https://img.shields.io/github/issues/niccokunzmann/python-recurring-ical-events?logo=github&label=issues%20seek%20funding&color=%230062ff
   :target: https://polar.sh/niccokunzmann/python-recurring-ical-events
   :alt: issues seek funding



ICal has some complexity to it:
Events, TODOs, Journal entries and Alarms can be repeated, removed from the feed and edited later on.
This tool takes care of these circumstances.

Let's put our expertise together and build a tool that can solve this!

.. image:: https://img.shields.io/badge/RFC_2445-deprecated-red
   :target: https://datatracker.ietf.org/doc/html/rfc2445#section-4.8.5.2
   :alt: RFC 2445 is deprecated
.. image:: https://img.shields.io/badge/RFC_5545-supported-green
   :target: https://datatracker.ietf.org/doc/html/rfc5545
   :alt: RFC 5545 is supported
.. image:: https://img.shields.io/badge/RFC_7529-todo-red
   :target: https://github.com/niccokunzmann/python-recurring-ical-events/issues/142
   :alt: RFC 7529 is not implemented
.. image:: https://img.shields.io/badge/RFC_7953-todo-red
   :target: https://github.com/niccokunzmann/python-recurring-ical-events/issues/143
   :alt: RFC 7953 is not implemented

* day light saving time (DONE)
* recurring events (DONE)
* recurring events with edits (DONE)
* recurring events where events are omitted (DONE)
* recurring events events where the edit took place later (DONE)
* normal events (DONE)
* recurrence of dates but not hours, minutes, and smaller (DONE)
* endless recurrence (DONE)
* ending recurrence (DONE)
* events with start date and no end date (DONE)
* events with start as date and start as datetime (DONE)
* `RRULE <https://www.kanzaki.com/docs/ical/rrule.html>`_ (DONE)
* events with multiple RRULE (DONE)
* `RDATE <https://www.kanzaki.com/docs/ical/rdate.html>`_ (DONE)
* `DURATION <https://www.kanzaki.com/docs/ical/duration.html>`_ (DONE)
* `EXDATE <https://www.kanzaki.com/docs/ical/exdate.html>`_ (DONE)
* `X-WR-TIMEZONE` compatibilty (DONE)
* non-gregorian event repetitions (TODO)
* RECURRENCE-ID with THISANDFUTURE - modify all future events (DONE)

Not included:

* EXRULE (deprecated), see `8.3.2.  Properties Registry
  <https://tools.ietf.org/html/rfc5545#section-8.3.2>`_

Installation
------------

You can install this package using ``pip``.

.. code:: shell

    pip install 'recurring-ical-events==3.*'

On Debian/Ubuntu, you use the package manager to install `python-recurring-ical-events <https://tracker.debian.org/pkg/python-recurring-ical-events>`_.

.. code:: shell

    sudo apt-get install python-recurring-ical-events

If you would like to use this functionality on the command line or in the shell, you can use
`ics-query`_.

Support
-------

- `Support using GitHub Sponsors <https://github.com/sponsors/niccokunzmann>`_
- `Fund specific issues using Polar <https://polar.sh/niccokunzmann/python-recurring-ical-events>`_
- `Support using Open Collective <https://opencollective.com/open-web-calendar/>`_
- `Support using thanks.dev <https://thanks.dev>`_

We accept donations to sustain our work, once or regular.
Consider donating money to open-source as everyone benefits.

Usage
-----

The `icalendar <https://pypi.org/project/icalendar/>`_ module is responsible for parsing and converting calendars.
The `recurring_ical_events <https://pypi.org/project/recurring-ical-events/>`_ module uses such a `calendar`_ and creates all repetitions of its events within a time span.

To import this module, write

.. code-block:: python

    >>> import recurring_ical_events

There are several methods you can use to unfold repeating events, such as ``at(a_time)`` and ``between(a_start, an_end)``.

Example
-------

.. code-block:: python

    >>> import icalendar
    >>> import recurring_ical_events
    >>> from pathlib import Path

    # read the calendar file and parse it
    # CALENDARS = Path("to/your/calendar/directory")
    >>> calendar_file : Path = CALENDARS / "fablab_cottbus.ics"
    >>> ical_string = calendar_file.read_bytes()
    >>> print(ical_string[:28])
    BEGIN:VCALENDAR
    VERSION:2.0
    >>> a_calendar = icalendar.Calendar.from_ical(ical_string)
 
    # request the events in a specific interval
    # start on the 1st of January 2017 0:00
    >>> start_date = (2017, 1, 1)

    # the event on the 1st of January 2018 is not included
    >>> end_date =   (2018,  1, 1)
    >>> events = recurring_ical_events.of(a_calendar).between(start_date, end_date)
    >>> for event in events:
    ...     start = event["DTSTART"].dt
    ...     summary = event["SUMMARY"]
    ...     print(f"start {start} summary {summary}")
    start 2017-03-11 17:00:00+01:00 summary Vereinssitzung
    start 2017-06-10 10:00:00+02:00 summary Repair und Recycling Café
    start 2017-06-11 16:30:00+02:00 summary Brandenburger Maker-Treffen
    start 2017-07-05 17:45:00+02:00 summary Der Computer-Treff fällt aus
    start 2017-07-29 14:00:00+02:00 summary Sommerfest
    start 2017-10-19 16:00:00+02:00 summary 3D-Modelle programmieren mit OpenSCAD
    start 2017-10-20 16:00:00+02:00 summary Programmier dir deine eigene Crypto-Währung
    start 2017-10-21 13:00:00+02:00 summary Programmiere deine eigene Wetterstation
    start 2017-10-22 13:00:00+02:00 summary Luftqualität: Ein Workshop zum selber messen (Einsteiger)
    start 2017-10-22 13:00:00+02:00 summary Websites selbst programmieren


``at(a_date)``
**************

You can get all events which take place at ``a_date``.
A date can be a year, e.g. ``2023``, a month of a year e.g. January in 2023 ``(2023, 1)``, a day of a certain month e.g. ``(2023, 1, 1)``, an hour e.g. ``(2023, 1, 1, 0)``, a minute e.g. ``(2023, 1, 1, 0, 0)``, or second as well as a `datetime.date <https://docs.python.org/3/library/datetime.html#datetime.date>`_ object and `datetime.datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime>`_.

The start and end are inclusive. As an example: if an event is longer than one day it is still included if it takes place at ``a_date``.

.. code-block:: python

    >>> import datetime

    # save the query object for the calendar
    >>> query = recurring_ical_events.of(a_calendar)
    >>> len(query.at(2023))                      # a year - 2023 has 12 events happening
    12
    >>> len(query.at((2023,)))                   # a year
    12
    >>> len(query.at((2023, 1)))                 # January in 2023 - only one event is in January
    1
    >>> len(query.at((2023, 1, 1)))              # the 1st of January in 2023
    0
    >>> len(query.at("20230101"))                # the 1st of January in 2023
    0
    >>> len(query.at((2023, 1, 1, 0)))           # the first hour of the year 2023
    0
    >>> len(query.at((2023, 1, 1, 0, 0)))        # the first minute in 2023
    0
    >>> len(query.at(datetime.date(2023, 1, 1))) # the first day in 2023
    0

The resulting ``events`` are a list of `icalendar events <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Event>`_, see below.

``between(start, end)``
***********************

``between(start, end)`` returns all events happening between a start and an end time. Both arguments can be `datetime.datetime`_, `datetime.date`_, tuples of numbers passed as arguments to `datetime.datetime`_ or strings in the form of
``%Y%m%d`` (``yyyymmdd``) and ``%Y%m%dT%H%M%SZ`` (``yyyymmddThhmmssZ``).
Additionally, the ``end`` argument can be a ``datetime.timedelta`` to express that the end is relative to the ``start``.
For examples of arguments, see ``at(a_date)`` above.

.. code-block:: python

    >>> query = recurring_ical_events.of(a_calendar)

    # What happens in 2016, 2017 and 2018?
    >>> events = recurring_ical_events.of(a_calendar).between(2016, 2019)
    >>> len(events) # quite a lot is happening!
    39

The resulting ``events`` are in a list of `icalendar events`_, see below.

``after(earliest_end)``
***********************

You can retrieve events that happen after a time or date using ``after(earliest_end)``.
Events that are happening during the ``earliest_end`` are included in the iteration.

.. code-block:: python

    >>> earlierst_end = 2023
    >>> for i, event in enumerate(query.after(earlierst_end)):
    ...     print(f"{event['SUMMARY']} ends {event['DTEND'].dt}") # all dates printed are after January 1st 2023
    ...     if i > 10: break  # we might get endless events and a lot of them!
    Repair Café ends 2023-01-07 17:00:00+01:00
    Repair Café ends 2023-02-04 17:00:00+01:00
    Repair Café ends 2023-03-04 17:00:00+01:00
    Repair Café ends 2023-04-01 17:00:00+02:00
    Repair Café ends 2023-05-06 17:00:00+02:00
    Repair Café ends 2023-06-03 17:00:00+02:00
    Repair Café ends 2023-07-01 17:00:00+02:00
    Repair Café ends 2023-08-05 17:00:00+02:00
    Repair Café ends 2023-09-02 17:00:00+02:00
    Repair Café ends 2023-10-07 17:00:00+02:00
    Repair Café ends 2023-11-04 17:00:00+01:00
    Repair Café ends 2023-12-02 17:00:00+01:00


``all()``
*********

If you wish to iterate over all occurrences of the components, then you can use ``all()``.
Since a calendar can define a huge amount of recurring entries, this method generates them
and forgets them, reducing memory overhead.

This example shows the first event that takes place in the calendar:

.. code-block:: python

    >>> first_event = next(query.all()) # not all events are generated
    >>> print(f"The first event is {first_event['SUMMARY']}")
    The first event is Weihnachts Repair-Café

``count()``
***********

You can count occurrences of events and other components using ``count()``.

.. code-block:: python

    >>> number_of_TODOs = recurring_ical_events.of(a_calendar, components=["VTODO"]).count()
    >>> print(f"You have {number_of_TODOs} things to do!")
    You have 0 things to do!

    >>> number_of_journal_entries = recurring_ical_events.of(a_calendar, components=["VJOURNAL"]).count()
    >>> print(f"There are {number_of_journal_entries} journal entries in the calendar.")
    There are 0 journal entries in the calendar.

However, this can be very costly!


``events`` as list - ``at()`` and ``between()``
***********************************************

The result of both ``between(start, end)`` and ``at(a_date)`` is a list of `icalendar events`_.
By default, all attributes of the event with repetitions are copied, like ``UID`` and ``SUMMARY``.
However, these attributes may differ from the source event:

* ``DTSTART`` which is the start of the event instance. (always present)
* ``DTEND`` which is the end of the event instance. (always present)
* ``RDATE``, ``EXDATE``, ``RRULE`` are the rules to create event repetitions.
  They are **not** included in repeated events, see `Issue 23 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/23>`_.
  To change this, use ``of(calendar, keep_recurrence_attributes=True)``.

Generator - ``after()`` and ``all()``
*************************************

If the resulting components are ordered when ``after(earliest_end)`` or ``all()`` is used.
The result is an iterator that returns the events in order.

.. code-block:: python

    for event in recurring_ical_events.of(an_icalendar_object).after(datetime.datetime.now()):
        print(event["DTSTART"]) # The start is ordered

Pagination
**********

Pagination allows you to chop the resulting components into chunks of a certain size.

.. code-block: python

    # we get a calendar with 10 events and 2 events per page
    >>> ten_events = recurring_ical_events.example_calendar("event_10_times")
    >>> pages = recurring_ical_events.of(ten_events).paginate(2)

    # we can iterate over the pages with 2 events each
    >>> for i, last_page in enumerate(pages):
    ...     print(f"page: {i}")
    ...     for event in last_page:
    ...         print(f"->  {event.start}")
    ...     if i == 1: break
    page: 0
    ->  2020-01-13 07:45:00+01:00
    ->  2020-01-14 07:45:00+01:00
    page: 1
    ->  2020-01-15 07:45:00+01:00
    ->  2020-01-16 07:45:00+01:00

If you run a web service and you would like to continue pagination after a certain page,
this can be done, too. Just hand someone the ``next_page_id`` and continue from there on.

.. code-block: python

    # resume the same query from the next page
    >>> pages = recurring_ical_events.of(ten_events).paginate(2, next_page_id = last_page.next_page_id)
    >>> for i, last_page in enumerate(pages):
    ...     print(f"page: {i + 2}")
    ...     for event in last_page:
    ...         print(f"->  {event.start}")
    ...     if i == 1: break
    page: 2
    ->  2020-01-17 07:45:00+01:00
    ->  2020-01-18 07:45:00+01:00
    page: 3
    ->  2020-01-19 07:45:00+01:00
    ->  2020-01-20 07:45:00+01:00

The ``last_page.next_page_id`` is a string so that it can be used easily.
It is tested against malicious modification and can safely be passed from a third party source.

Additionally to the page size, you can also pass a ``start`` and an ``end`` to the pages so that
all components are visible within that time.

Different Components, not just Events
*************************************

By default the ``recurring_ical_events`` only selects events as the name already implies.
However, there are different `components <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Component>`_ available in a `calendar <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Calendar>`_.
You can select which components you like to have returned by passing ``components`` to the ``of`` function:

.. code-block:: python

    of(a_calendar, components=["VEVENT"])

Here is a template code for choosing the supported types of components:

.. code-block:: python

    >>> query_events = recurring_ical_events.of(a_calendar)
    >>> query_journals = recurring_ical_events.of(a_calendar, components=["VJOURNAL"])
    >>> query_todos = recurring_ical_events.of(a_calendar, components=["VTODO"])
    >>> query_all = recurring_ical_events.of(a_calendar, components=["VTODO", "VEVENT", "VJOURNAL"])

If a type of component is not listed here, it can be added.
Please create an issue for this in the source code repository.

For further customization, please refer to the section on how to extend the default functionality.

Alarms
******

Alarms are subcomponents of events and todos. They only make sense with an event or todo.
Thus the interface is slightly different.

Add ``VALARM`` as the component you would like:

.. code-block:: python

    >>> query_alarms = recurring_ical_events.of(a_calendar, components=["VALARM"])

In the following example, an event has an alarm one week before it starts.
The component returned is not a ``VALARM`` component but instead the ``VEVENT`` with only
one ``VALARM`` in it.

.. code-block:: python

    # read an .ics file with an event with an alarm
    >>> calendar_with_alarm = recurring_ical_events.example_calendar("alarm_1_week_before_event")
    >>> alarm_day = datetime.date(2024, 12, 2)

    # we get the event that has an alarm on that day
    >>> event = recurring_ical_events.of(calendar_with_alarm, components=["VALARM"]).at(alarm_day)[0]
    >>> len(event.alarms.times)
    1
    >>> alarm = event.alarms.times[0]

    # the alarm happens one week before the event
    >>> event.start - alarm.trigger
    datetime.timedelta(days=7)

In the following code, we query the same day for a ``VEVENT`` component and we find nothing.
The event happens a week later.

.. code-block:: python

    # No events on that day. There is only an alarm.
    >>> recurring_ical_events.of(calendar_with_alarm, components=["VEVENT"]).at(alarm_day)
    []

When querying events and todos, they keep their alarms and other subcompnents.
These alarm times can be outside of the dates requested.

In this example, we get an event and find that it has several alarms in it.

.. code-block:: python

    >>> event_day = alarm_day + datetime.timedelta(days=7)
    >>> event = recurring_ical_events.of(calendar_with_alarm, components=["VEVENT"]).at(event_day)[0]

    # The event a week later has more than one alarm.
    >>> len(event.walk("VALARM"))
    2

Speed
*****

If you use ``between()`` or ``at()``
several times, it is faster to re-use the object coming from ``of()``.

.. code-block:: python

    >>> query = recurring_ical_events.of(a_calendar)
    >>> events_of_day_1 = query.at((2019, 2, 1))
    >>> events_of_day_2 = query.at((2019, 2, 2))
    >>> events_of_day_3 = query.at((2019, 2, 3))

    # ... and so on

Skip bad formatted ical events
******************************

Some events may be badly formatted and therefore cannot be handled by ``recurring-ical-events``.
Passing ``skip_bad_series=True`` as ``of()`` argument will totally skip theses events.

.. code-block:: python

    # Create a calendar that contains broken events.
    >>> calendar_file = CALENDARS / "bad_rrule_missing_until_event.ics"
    >>> calendar_with_bad_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())

     # By default, broken events result in errors.
    >>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=False).count()
    Traceback (most recent call last):
      ...
    recurring_ical_events.errors.BadRuleStringFormat: UNTIL parameter is missing: FREQ=WEEKLY;BYDAY=TH;WKST=SU;UNTL=20191023

    # With skip_bad_series=True we skip the series that we cannot handle.
    >>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=True).count()
    0

Architecture
------------

.. image:: img/architecture.png
   :alt: Architecture Diagram showing the components interacting

Each icalendar **Calendar** can contain Events, Journal entries,
TODOs and others, called **Components**.
Those entries are grouped by their ``UID``.
Such a ``UID`` defines a **Series** of **Occurrences** that take place at
a given time.
Since each **Component** is different, the **ComponentAdapter** offers a unified
interface to interact with them.
The **Calendar** gets filtered and for each ``UID``,
a **Series** can use one or more **ComponentAdapters** to create 
**Occurrences** of what happens in a time span.
These **Occurrences** are used internally and convert to **Components** for further use.

Extending ``recurring-ical-events``
***********************************

All the functionality of ``recurring-ical-events`` can be extended and modified.
To understand where to extend, have a look at the `Architecture`_.

The first place for extending is the collection of components.
Components are collected into a ``Series``.
A series belongs together because all components have the same ``UID``.
In this example, we collect one VEVENT which matches a certain UID:

.. code-block:: python

    >>> from recurring_ical_events import SelectComponents, EventAdapter, Series
    >>> from icalendar.cal import Component
    >>> from typing import Sequence

    # create the calendar
    >>> calendar_file = CALENDARS / "machbar_16_feb_2019.ics"
    >>> machbar_calendar = icalendar.Calendar.from_ical(calendar_file.read_bytes())

    # Create a collector of components that searches for an event with a specific UID
    >>> class CollectOneUIDEvent(SelectComponents):
    ...     def __init__(self, uid:str) -> None:
    ...         self.uid = uid
    ...     def collect_series_from(self, source: Component, suppress_errors: tuple) -> Sequence[Series]:
    ...         components : list[Component] = []
    ...         for component in source.walk("VEVENT"):
    ...             if component.get("UID") == self.uid:
    ...                 components.append(EventAdapter(component))
    ...         return [Series(components)] if components else []

    # collect only one UID: 4mm2ak3in2j3pllqdk1ubtbp9p@google.com
    >>> one_uid = CollectOneUIDEvent("4mm2ak3in2j3pllqdk1ubtbp9p@google.com")
    >>> uid_query = recurring_ical_events.of(machbar_calendar, components=[one_uid])
    >>> uid_query.count()  # the event has no recurrence and thus there is only one
    1

Several ways of extending the functionality have been created to override internals.
These can be subclassed or composed.

Below, you can choose to collect all components. Subclasses can be created for the
``Series`` and the ``Occurrence``. 

.. code-block:: python

    >>> from recurring_ical_events import AllKnownComponents, Series, Occurrence

    # we create a calendar with one event
    >>> calendar_file = CALENDARS / "one_event.ics"
    >>> one_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())

    # You can override the Occurrence and Series classes for all computable components
    >>> select_all_known = AllKnownComponents(series=Series, occurrence=Occurrence)
    >>> select_all_known.names  # these are the supported types of components
    ['VALARM', 'VEVENT', 'VJOURNAL', 'VTODO']
    >>> query_all_known = recurring_ical_events.of(one_event, components=[select_all_known])

    # There should be exactly one event.
    >>> query_all_known.count()
    1

This example shows that the behavior for specific types of components can be extended.
Additional to the series, you can change the ``ComponentAdapter`` that provides
a unified interface for all the components with the same name (``VEVENT`` for example).

.. code-block:: python

    >>> from recurring_ical_events import ComponentsWithName, EventAdapter, JournalAdapter, TodoAdapter

    # You can also choose to select only specific subcomponents by their name.
    # The default arguments are added to show the extensibility.
    >>> select_events =   ComponentsWithName("VEVENT",   adapter=EventAdapter,   series=Series, occurrence=Occurrence)
    >>> select_todos =    ComponentsWithName("VTODO",    adapter=TodoAdapter,    series=Series, occurrence=Occurrence)
    >>> select_journals = ComponentsWithName("VJOURNAL", adapter=JournalAdapter, series=Series, occurrence=Occurrence)

    # There should be one event happening and nothing else
    >>> recurring_ical_events.of(one_event, components=[select_events]).count()
    1
    >>> recurring_ical_events.of(one_event, components=[select_todos]).count()
    0
    >>> recurring_ical_events.of(one_event, components=[select_journals]).count()
    0

So, if you would like to modify all events that are returned by the query,
you can do that subclassing the ``Occurrence`` class.


.. code-block:: python

    # This occurence changes adds a new attribute to the resulting events
    >>> class MyOccurrence(Occurrence):
    ...     """An occurrence that modifies the component."""
    ...     def as_component(self, keep_recurrence_attributes: bool) -> Component:
    ...         """Return a shallow copy of the source component and modify some attributes."""
    ...         component = super().as_component(keep_recurrence_attributes)
    ...         component["X-MY-ATTRIBUTE"] = "my occurrence"
    ...         return component
    >>> query = recurring_ical_events.of(one_event, components=[ComponentsWithName("VEVENT", occurrence=MyOccurrence)])
    >>> event = next(query.all())
    >>> event["X-MY-ATTRIBUTE"]
    'my occurrence'

This library allows extension of functionality during the selection of components to calculate using these classes:

* ``ComponentsWithName`` - for components of a certain name
* ``AllKnownComponents`` - for all components known
* ``SelectComponents`` - the interface to provide

You can further customize behaviour by subclassing these:

* ``ComponentAdapter`` such as ``EventAdapter``, ``JournalAdapter`` or ``TodoAdapter``.
* ``Series``
* ``Occurrence``
* ``CalendarQuery``

Version Fixing
**************

If you use this library in your code, you may want to make sure that
updates can be received but they do not break your code.
The version numbers are handeled this way: ``a.b.c`` example: ``0.1.12``

- ``c`` is changed for each minor bug fix.
- ``b`` is changed whenever new features are added.
- ``a`` is changed when the interface or major assumptions change that may break your code.

So, I recommend to version-fix this library to stay with the same ``a``
while ``b`` and ``c`` can change.

Development
-----------

Code style
**********

Please install `pre-commit <https://pre-commit.com/>`_ before git commit.  It will ensure that the code is formatted and linted as expected using `ruff <https://docs.astral.sh/ruff/>`_.

.. code-block:: shell

   pre-commit install


Testing
*******

This project's development is driven by tests.
Tests assure a consistent interface and less knowledge lost over time.
If you like to change the code, tests help that nothing breaks in the future.
They are required in that sense.
Example code and ics files can be transferred into tests and speed up fixing bugs.

You can view the tests in the `test folder
<https://github.com/niccokunzmann/python-recurring-ical-events/tree/master/test>`_.
If you have a calendar ICS file for which this library does not
generate the desired output, you can add it to the ``test/calendars``
folder and write tests for what you expect.
If you like, `open an issue <https://github.com/niccokunzmann/python-recurring-ical-events/issues>`_ first, e.g. to discuss the changes and
how to go about it.


To run the tests, we use ``tox``.
``tox`` tests all different Python versions which we want to  be compatible to.

.. code-block:: shell

   pip3 install tox

To run all the tests:

.. code-block:: shell

   tox

To run the tests in a specific Python version:

.. code-block:: shell

   tox -e py39



New Releases
------------

You can build the new release by running this command:

.. code-block:: shell

    tox -e build

To release new versions,

1. Edit the Changelog Section.
2. Create a commit and push it.
3. Wait for `GitHub Actions <https://github.com/niccokunzmann/python-recurring-ical-events/actions>`_ to finish the build.
4. Run

   .. code-block:: shell

       git tag v3.5.1
       git push origin v3.5.1

5. Notify the issues about their release.

Changelog
---------

- v3.5.1

  - Move to ``pyproject.toml`` format to include directory structure more easily. See `Issue 214 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/214>`_
  - Remove release 3.5.0 as it does not contain any source files.

- v3.5.0 - yanked

  - Restructure module into package with a file structure.
  - Add pagination, see `Issue 211 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/211>`_

- v3.4.1

  - Improve Alarm documentation

- v3.4.0

  - Add ``VALARM`` support: Calculate alarm times. See `Issue 186 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/186>`_

- v3.3.4

  - Allow ``x-wr-timezone`` 1.* and 2.* for this lib to remove dependency update problems.

- v3.3.3

  -  Fix: Events with DTSTART of type date have a duration of one day, see `Issue 179 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/179>`_

- v3.3.2

  - Update x-wr-timezone

- v3.3.1

  - Support RDATE with PERIOD value type where the end is a duration, see `PR 180 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/180>`_
  - Support modifying all events in the future (RECURRENCE-ID with RANGE=THISANDFUTURE), see `Issue 75 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/75>`_

- v3.3.0

  - Make tests work with ``icalendar`` version 5
  - Restructure README to be tested with ``doctest``
  - Remove ``DURATION`` from the result, see `Issue 139 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/139>`_
  - Document new way of extending the functionality, see `Issue 133 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/133>`_ and `PR 175 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/175>`_

- v3.2.0

  - Allow ``datetime.timedelta`` as second argument to ``between(absolute_time, datetime.timedelta())``

- v3.1.1

  - Fix: Remove duplication of modification with same sequence number, see `Issue 164 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/164>`_
  - Fix: EXDATE now excludes a modified instance for an event with higher ``SEQUENCE``, see `Issue <https://github.com/niccokunzmann/python-recurring-ical-events/issues/163>`_

- v3.1.0

  - Add ``count() -> int`` to count all occurrences within a calendar
  - Add ``all() -> Generator[icalendar.Component]`` to iterate over the whole calendar

- v3.0.0

  - Change the architecture and add a diagram
  - Add type hints, see `Issue 91 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/91>`_
  - Rename ``UnfoldableCalendar`` to ``CalendarQuery``
  - Rename ``of(skip_bad_events=None)`` to ``of(skip_bad_series=False)``
  - ``of(components=[...])`` now also takes ``ComponentAdapters``
  - Fix edit sequence problems, see `Issue 151 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/151>`_

- v2.2.3

  - Fix: Edits of whole event are now considering RDATE and EXDATE, see `Issue 148 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/148>`_

- v2.2.2

  - Test support for ``icalendar==6.*``
  - Remove Python 3.7 from tests and compatibility list
  - Remove pytz from requirements

- v2.2.1

  - Add support for multiple RRULE in events.

- v2.2.0

  - Add ``after()`` method to iterate over upcoming events.

- v2.1.3

  - Test and support Python 3.12.
  - Change SPDX license header.
  - Fix RRULE with negative COUNT, see `Issue 128 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/128>`_

- v2.1.2

  - Fix RRULE with EXDATE as DATE, see `PR 121 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/121>`__ by Jan Grasnick and `PR 122 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/122>`__.

- v2.1.1

  - Claim and test support for Python 3.11.
  - Support deleting events by setting RRULE UNTIL < DTSTART, see `Issue 117 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/117>`__.

- v2.1.0

  - Added support for PERIOD values in RDATE. See `Issue 113 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/113>`_.
  - Fixed ``icalendar>=5.0.9`` to support ``RDATE`` of type ``PERIOD`` with a time zone.
  - Fixed ``pytz>=2023.3`` to assure compatibility.

- v2.0.2

  - Fixed omitting last event of ``RRULE`` with ``UNTIL`` when using ``pytz``, the event starting in winter time and ending in summer time. See `Issue 107 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/107>`_.

- v2.0.1

  - Fixed crasher with duplicate RRULE. See `Pull Request 104 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/104>`_

- v2.0.0b

  - Only return ``VEVENT`` by default. Add ``of(... ,components=...)`` parameter to select which kinds of components should be returned. See `Issue 101 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/101>`_.
  - Remove ``beta`` indicator. This library works okay: Feature requests come in, not so much bug reports.

- v1.1.0b

  - Add repeated TODOs and Journals. See `Pull Request 100 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/100>`_ and `Issue 97 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/97>`_.

- v1.0.3b

  - Remove syntax anomalies in README.
  - Switch to GitHub actions because GitLab decided to remove support.

- v1.0.2b

  - Add support for ``X-WR-TIMEZONE`` calendars which contain events without an explicit time zone, see `Issue 86 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/86>`_.

- v1.0.1b

  - Add support for ``zoneinfo.ZoneInfo`` time zones, see `Issue 57 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/57>`_.
  - Migrate from Travis CI to Gitlab CI.
  - Add code coverage on Gitlab.

- v1.0.0b

  - Remove Python 2 support, see `Issue 64 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/64>`_.
  - Remove support for Python 3.5 and 3.6.
  - Note: These deprecated Python versions may still work. We just do not claim they do.
  - ``X-WR-TIMEZONE`` support, see `Issue 71 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/71>`_.

- v0.2.4b

  - Events with a duration of 0 seconds are correctly returned.
  - ``between()`` and ``at()`` take the same kind of arguments. These arguments are documented.

- v0.2.3b

  - ``between()`` and ``at()`` allow arguments with time zones now when calendar events do not have time zones, reported in `Issue 61 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/61>`_ and `Issue 52 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/52>`_.

- v0.2.2b

  - Check that ``at()`` does not return an event starting at the next day, see `Issue 44 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/44>`_.

- v0.2.1b

  - Check that recurring events are removed if they are modified to leave the requested time span, see `Issue 62 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/62>`_.

- v0.2.0b

  - Add ability to keep the recurrence attributes (RRULE, RDATE, EXDATE) on the event copies instead of stripping them. See `Pull Request 54 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/54>`_.

- v0.1.21b

  - Fix issue with repetitions over DST boundary. See `Issue 48 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/48>`_.

- v0.1.20b

  - Fix handling of modified recurrences with lower sequence number than their base event `Pull Request 45 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/45>`_

- v0.1.19b

  - Benchmark using `@mrx23dot <https://github.com/mrx23dot>`_'s script and speed up recurrence calculation by factor 4, see `Issue 42 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/42>`_.

- v0.1.18b

  - Handle `Issue 28 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/28>`__ so that EXDATEs match as expected.
  - Handle `Issue 27 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/27>`_ so that parsing some rrule UNTIL values does not crash.

- v0.1.17b

  - Handle `Issue 28 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/28>`__ where passed arguments lead to errors where it is expected to work.

- v0.1.16b

  - Events with an empty RRULE are handled like events without an RRULE.
  - Remove fixed dependency versions, see `Issue 14 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/14>`_

- v0.1.15b

  - Repeated events also include subcomponents. `Issue 6 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/6>`_

- v0.1.14b

  - Fix compatibility `issue 20 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/20>`_: EXDATEs of different time zones are now supported.

- v0.1.13b

  - Remove attributes RDATE, EXDATE, RRULE from repeated events `Issue 23`_
  - Use vDDDTypes instead of explicit date/datetime type `Pull Request 19 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/19>`_
  - Start Changelog

Libraries Used
--------------

- `python-dateutil <https://pypi.org/project/python-dateutil/>`_ - to compute the recurrences of events using ``rrule``
- `icalendar`_ - the library used to parse ICS files
- `pytz <https://pypi.org/project/pytz/>`_ - for timezones
- `x-wr-timezone <https://github.com/niccokunzmann/x-wr-timezone>`_ for handling the non-standard ``X-WR-TIMEZONE`` property.

Related Projects
----------------

- `icalevents <https://github.com/irgangla/icalevents>`_ - another library for roughly the same use-case
- `Open Web Calendar <https://github.com/niccokunzmann/open-web-calendar>`_ - a web calendar to embed into websites which uses this library
- `icspy <https://icspy.readthedocs.io/>`_ - to create your own calendar events
- `pyICSParser <https://pypi.org/project/pyICSParser/>`_ - parse icalendar files and return event times (`GitHub <https://github.com/oberron/pyICSParser>`__)
- `ics-query`_ - a **command line** impementation of ``recurring-ical-events``
- `icalendar-events-cli`_ - another **command line** impementation of ``recurring-ical-events``
- `caldav`_ - the python caldav client library
- `plann`_ - a **command line** caldav client

.. _`ics-query`: https://github.com/niccokunzmann/ics-query#readme
.. _`icalendar-events-cli`: https://github.com/waldbaer/icalendar-events-cli#readme
.. _`caldav`:  https://github.com/python-caldav/caldav
.. _`plann`: https://github.com/tobixen/plann

Media
-----

Nicco Kunzmann talked about this library at the
FOSSASIA 2022 Summit:

.. image:: https://niccokunzmann.github.io/ical-talk-fossasia-2022/youtube.png
   :target: https://youtu.be/8l3opDdg92I?t=10369
   :alt: Talk about this library at the FOSSASIA 2022 Summit

Research
--------

- `RFC 5545 <https://tools.ietf.org/html/rfc5545>`_
- `RFC 7986 <https://tools.ietf.org/html/rfc7986>`_ -- an update to RFC 5545. It does not change any properties useful for scheduling events.
- `Stackoverflow question this is created for <https://stackoverflow.com/questions/30913824/ical-library-to-iterate-recurring-events-with-specific-instances>`_
- `<https://github.com/oberron/annum>`_

  - `<https://stackoverflow.com/questions/28829261/python-ical-get-events-for-a-day-including-recurring-ones#28829401>`_

- `<https://stackoverflow.com/questions/20268204/ical-get-date-from-recurring-event-by-rrule-and-dtstart>`_
- `<https://github.com/collective/icalendar/issues/162>`_
- `<https://stackoverflow.com/questions/46471852/ical-parsing-reoccuring-events-in-python>`_
- RDATE `<https://stackoverflow.com/a/46709850/1320237>`_

  - `<https://tools.ietf.org/html/rfc5545#section-3.8.5.2>`_

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "recurring-ical-events",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Nicco Kunzmann <niccokunzmann@rambler.ru>",
    "keywords": "alarm, calendar, events, icalendar, ics, journal, rfc5545, scheduling, todo",
    "author": null,
    "author_email": "Nicco Kunzmann <niccokunzmann@rambler.ru>",
    "download_url": "https://files.pythonhosted.org/packages/4b/26/f000cabb98aeca1a84b84ad892495c163dd5607470debaf1f35fa03beb3d/recurring_ical_events-3.5.1.tar.gz",
    "platform": null,
    "description": "Recurring ICal events for Python\n================================\n\n.. image:: https://github.com/niccokunzmann/python-recurring-ical-events/actions/workflows/tests.yml/badge.svg\n   :target: https://github.com/niccokunzmann/python-recurring-ical-events/actions/workflows/tests.yml\n   :alt: GitHub CI build and test status\n.. image:: https://badge.fury.io/py/recurring-ical-events.svg\n   :target: https://pypi.python.org/pypi/recurring-ical-events\n   :alt: Python Package Version on Pypi\n.. image:: https://img.shields.io/pypi/dm/recurring-ical-events.svg\n   :target: https://pypi.org/project/recurring-ical-events/#files\n   :alt: Downloads from Pypi\n.. image:: https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective\n   :target: https://opencollective.com/open-web-calendar/\n   :alt: Support on Open Collective\n.. image:: https://img.shields.io/github/issues/niccokunzmann/python-recurring-ical-events?logo=github&label=issues%20seek%20funding&color=%230062ff\n   :target: https://polar.sh/niccokunzmann/python-recurring-ical-events\n   :alt: issues seek funding\n\n\n\nICal has some complexity to it:\nEvents, TODOs, Journal entries and Alarms can be repeated, removed from the feed and edited later on.\nThis tool takes care of these circumstances.\n\nLet's put our expertise together and build a tool that can solve this!\n\n.. image:: https://img.shields.io/badge/RFC_2445-deprecated-red\n   :target: https://datatracker.ietf.org/doc/html/rfc2445#section-4.8.5.2\n   :alt: RFC 2445 is deprecated\n.. image:: https://img.shields.io/badge/RFC_5545-supported-green\n   :target: https://datatracker.ietf.org/doc/html/rfc5545\n   :alt: RFC 5545 is supported\n.. image:: https://img.shields.io/badge/RFC_7529-todo-red\n   :target: https://github.com/niccokunzmann/python-recurring-ical-events/issues/142\n   :alt: RFC 7529 is not implemented\n.. image:: https://img.shields.io/badge/RFC_7953-todo-red\n   :target: https://github.com/niccokunzmann/python-recurring-ical-events/issues/143\n   :alt: RFC 7953 is not implemented\n\n* day light saving time (DONE)\n* recurring events (DONE)\n* recurring events with edits (DONE)\n* recurring events where events are omitted (DONE)\n* recurring events events where the edit took place later (DONE)\n* normal events (DONE)\n* recurrence of dates but not hours, minutes, and smaller (DONE)\n* endless recurrence (DONE)\n* ending recurrence (DONE)\n* events with start date and no end date (DONE)\n* events with start as date and start as datetime (DONE)\n* `RRULE <https://www.kanzaki.com/docs/ical/rrule.html>`_ (DONE)\n* events with multiple RRULE (DONE)\n* `RDATE <https://www.kanzaki.com/docs/ical/rdate.html>`_ (DONE)\n* `DURATION <https://www.kanzaki.com/docs/ical/duration.html>`_ (DONE)\n* `EXDATE <https://www.kanzaki.com/docs/ical/exdate.html>`_ (DONE)\n* `X-WR-TIMEZONE` compatibilty (DONE)\n* non-gregorian event repetitions (TODO)\n* RECURRENCE-ID with THISANDFUTURE - modify all future events (DONE)\n\nNot included:\n\n* EXRULE (deprecated), see `8.3.2.  Properties Registry\n  <https://tools.ietf.org/html/rfc5545#section-8.3.2>`_\n\nInstallation\n------------\n\nYou can install this package using ``pip``.\n\n.. code:: shell\n\n    pip install 'recurring-ical-events==3.*'\n\nOn Debian/Ubuntu, you use the package manager to install `python-recurring-ical-events <https://tracker.debian.org/pkg/python-recurring-ical-events>`_.\n\n.. code:: shell\n\n    sudo apt-get install python-recurring-ical-events\n\nIf you would like to use this functionality on the command line or in the shell, you can use\n`ics-query`_.\n\nSupport\n-------\n\n- `Support using GitHub Sponsors <https://github.com/sponsors/niccokunzmann>`_\n- `Fund specific issues using Polar <https://polar.sh/niccokunzmann/python-recurring-ical-events>`_\n- `Support using Open Collective <https://opencollective.com/open-web-calendar/>`_\n- `Support using thanks.dev <https://thanks.dev>`_\n\nWe accept donations to sustain our work, once or regular.\nConsider donating money to open-source as everyone benefits.\n\nUsage\n-----\n\nThe `icalendar <https://pypi.org/project/icalendar/>`_ module is responsible for parsing and converting calendars.\nThe `recurring_ical_events <https://pypi.org/project/recurring-ical-events/>`_ module uses such a `calendar`_ and creates all repetitions of its events within a time span.\n\nTo import this module, write\n\n.. code-block:: python\n\n    >>> import recurring_ical_events\n\nThere are several methods you can use to unfold repeating events, such as ``at(a_time)`` and ``between(a_start, an_end)``.\n\nExample\n-------\n\n.. code-block:: python\n\n    >>> import icalendar\n    >>> import recurring_ical_events\n    >>> from pathlib import Path\n\n    # read the calendar file and parse it\n    # CALENDARS = Path(\"to/your/calendar/directory\")\n    >>> calendar_file : Path = CALENDARS / \"fablab_cottbus.ics\"\n    >>> ical_string = calendar_file.read_bytes()\n    >>> print(ical_string[:28])\n    BEGIN:VCALENDAR\n    VERSION:2.0\n    >>> a_calendar = icalendar.Calendar.from_ical(ical_string)\n \n    # request the events in a specific interval\n    # start on the 1st of January 2017 0:00\n    >>> start_date = (2017, 1, 1)\n\n    # the event on the 1st of January 2018 is not included\n    >>> end_date =   (2018,  1, 1)\n    >>> events = recurring_ical_events.of(a_calendar).between(start_date, end_date)\n    >>> for event in events:\n    ...     start = event[\"DTSTART\"].dt\n    ...     summary = event[\"SUMMARY\"]\n    ...     print(f\"start {start} summary {summary}\")\n    start 2017-03-11 17:00:00+01:00 summary Vereinssitzung\n    start 2017-06-10 10:00:00+02:00 summary Repair und Recycling Caf\u00e9\n    start 2017-06-11 16:30:00+02:00 summary Brandenburger Maker-Treffen\n    start 2017-07-05 17:45:00+02:00 summary Der Computer-Treff f\u00e4llt aus\n    start 2017-07-29 14:00:00+02:00 summary Sommerfest\n    start 2017-10-19 16:00:00+02:00 summary 3D-Modelle programmieren mit OpenSCAD\n    start 2017-10-20 16:00:00+02:00 summary Programmier dir deine eigene Crypto-W\u00e4hrung\n    start 2017-10-21 13:00:00+02:00 summary Programmiere deine eigene Wetterstation\n    start 2017-10-22 13:00:00+02:00 summary Luftqualit\u00e4t: Ein Workshop zum selber messen (Einsteiger)\n    start 2017-10-22 13:00:00+02:00 summary Websites selbst programmieren\n\n\n``at(a_date)``\n**************\n\nYou can get all events which take place at ``a_date``.\nA date can be a year, e.g. ``2023``, a month of a year e.g. January in 2023 ``(2023, 1)``, a day of a certain month e.g. ``(2023, 1, 1)``, an hour e.g. ``(2023, 1, 1, 0)``, a minute e.g. ``(2023, 1, 1, 0, 0)``, or second as well as a `datetime.date <https://docs.python.org/3/library/datetime.html#datetime.date>`_ object and `datetime.datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime>`_.\n\nThe start and end are inclusive. As an example: if an event is longer than one day it is still included if it takes place at ``a_date``.\n\n.. code-block:: python\n\n    >>> import datetime\n\n    # save the query object for the calendar\n    >>> query = recurring_ical_events.of(a_calendar)\n    >>> len(query.at(2023))                      # a year - 2023 has 12 events happening\n    12\n    >>> len(query.at((2023,)))                   # a year\n    12\n    >>> len(query.at((2023, 1)))                 # January in 2023 - only one event is in January\n    1\n    >>> len(query.at((2023, 1, 1)))              # the 1st of January in 2023\n    0\n    >>> len(query.at(\"20230101\"))                # the 1st of January in 2023\n    0\n    >>> len(query.at((2023, 1, 1, 0)))           # the first hour of the year 2023\n    0\n    >>> len(query.at((2023, 1, 1, 0, 0)))        # the first minute in 2023\n    0\n    >>> len(query.at(datetime.date(2023, 1, 1))) # the first day in 2023\n    0\n\nThe resulting ``events`` are a list of `icalendar events <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Event>`_, see below.\n\n``between(start, end)``\n***********************\n\n``between(start, end)`` returns all events happening between a start and an end time. Both arguments can be `datetime.datetime`_, `datetime.date`_, tuples of numbers passed as arguments to `datetime.datetime`_ or strings in the form of\n``%Y%m%d`` (``yyyymmdd``) and ``%Y%m%dT%H%M%SZ`` (``yyyymmddThhmmssZ``).\nAdditionally, the ``end`` argument can be a ``datetime.timedelta`` to express that the end is relative to the ``start``.\nFor examples of arguments, see ``at(a_date)`` above.\n\n.. code-block:: python\n\n    >>> query = recurring_ical_events.of(a_calendar)\n\n    # What happens in 2016, 2017 and 2018?\n    >>> events = recurring_ical_events.of(a_calendar).between(2016, 2019)\n    >>> len(events) # quite a lot is happening!\n    39\n\nThe resulting ``events`` are in a list of `icalendar events`_, see below.\n\n``after(earliest_end)``\n***********************\n\nYou can retrieve events that happen after a time or date using ``after(earliest_end)``.\nEvents that are happening during the ``earliest_end`` are included in the iteration.\n\n.. code-block:: python\n\n    >>> earlierst_end = 2023\n    >>> for i, event in enumerate(query.after(earlierst_end)):\n    ...     print(f\"{event['SUMMARY']} ends {event['DTEND'].dt}\") # all dates printed are after January 1st 2023\n    ...     if i > 10: break  # we might get endless events and a lot of them!\n    Repair Caf\u00e9 ends 2023-01-07 17:00:00+01:00\n    Repair Caf\u00e9 ends 2023-02-04 17:00:00+01:00\n    Repair Caf\u00e9 ends 2023-03-04 17:00:00+01:00\n    Repair Caf\u00e9 ends 2023-04-01 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-05-06 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-06-03 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-07-01 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-08-05 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-09-02 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-10-07 17:00:00+02:00\n    Repair Caf\u00e9 ends 2023-11-04 17:00:00+01:00\n    Repair Caf\u00e9 ends 2023-12-02 17:00:00+01:00\n\n\n``all()``\n*********\n\nIf you wish to iterate over all occurrences of the components, then you can use ``all()``.\nSince a calendar can define a huge amount of recurring entries, this method generates them\nand forgets them, reducing memory overhead.\n\nThis example shows the first event that takes place in the calendar:\n\n.. code-block:: python\n\n    >>> first_event = next(query.all()) # not all events are generated\n    >>> print(f\"The first event is {first_event['SUMMARY']}\")\n    The first event is Weihnachts Repair-Caf\u00e9\n\n``count()``\n***********\n\nYou can count occurrences of events and other components using ``count()``.\n\n.. code-block:: python\n\n    >>> number_of_TODOs = recurring_ical_events.of(a_calendar, components=[\"VTODO\"]).count()\n    >>> print(f\"You have {number_of_TODOs} things to do!\")\n    You have 0 things to do!\n\n    >>> number_of_journal_entries = recurring_ical_events.of(a_calendar, components=[\"VJOURNAL\"]).count()\n    >>> print(f\"There are {number_of_journal_entries} journal entries in the calendar.\")\n    There are 0 journal entries in the calendar.\n\nHowever, this can be very costly!\n\n\n``events`` as list - ``at()`` and ``between()``\n***********************************************\n\nThe result of both ``between(start, end)`` and ``at(a_date)`` is a list of `icalendar events`_.\nBy default, all attributes of the event with repetitions are copied, like ``UID`` and ``SUMMARY``.\nHowever, these attributes may differ from the source event:\n\n* ``DTSTART`` which is the start of the event instance. (always present)\n* ``DTEND`` which is the end of the event instance. (always present)\n* ``RDATE``, ``EXDATE``, ``RRULE`` are the rules to create event repetitions.\n  They are **not** included in repeated events, see `Issue 23 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/23>`_.\n  To change this, use ``of(calendar, keep_recurrence_attributes=True)``.\n\nGenerator - ``after()`` and ``all()``\n*************************************\n\nIf the resulting components are ordered when ``after(earliest_end)`` or ``all()`` is used.\nThe result is an iterator that returns the events in order.\n\n.. code-block:: python\n\n    for event in recurring_ical_events.of(an_icalendar_object).after(datetime.datetime.now()):\n        print(event[\"DTSTART\"]) # The start is ordered\n\nPagination\n**********\n\nPagination allows you to chop the resulting components into chunks of a certain size.\n\n.. code-block: python\n\n    # we get a calendar with 10 events and 2 events per page\n    >>> ten_events = recurring_ical_events.example_calendar(\"event_10_times\")\n    >>> pages = recurring_ical_events.of(ten_events).paginate(2)\n\n    # we can iterate over the pages with 2 events each\n    >>> for i, last_page in enumerate(pages):\n    ...     print(f\"page: {i}\")\n    ...     for event in last_page:\n    ...         print(f\"->  {event.start}\")\n    ...     if i == 1: break\n    page: 0\n    ->  2020-01-13 07:45:00+01:00\n    ->  2020-01-14 07:45:00+01:00\n    page: 1\n    ->  2020-01-15 07:45:00+01:00\n    ->  2020-01-16 07:45:00+01:00\n\nIf you run a web service and you would like to continue pagination after a certain page,\nthis can be done, too. Just hand someone the ``next_page_id`` and continue from there on.\n\n.. code-block: python\n\n    # resume the same query from the next page\n    >>> pages = recurring_ical_events.of(ten_events).paginate(2, next_page_id = last_page.next_page_id)\n    >>> for i, last_page in enumerate(pages):\n    ...     print(f\"page: {i + 2}\")\n    ...     for event in last_page:\n    ...         print(f\"->  {event.start}\")\n    ...     if i == 1: break\n    page: 2\n    ->  2020-01-17 07:45:00+01:00\n    ->  2020-01-18 07:45:00+01:00\n    page: 3\n    ->  2020-01-19 07:45:00+01:00\n    ->  2020-01-20 07:45:00+01:00\n\nThe ``last_page.next_page_id`` is a string so that it can be used easily.\nIt is tested against malicious modification and can safely be passed from a third party source.\n\nAdditionally to the page size, you can also pass a ``start`` and an ``end`` to the pages so that\nall components are visible within that time.\n\nDifferent Components, not just Events\n*************************************\n\nBy default the ``recurring_ical_events`` only selects events as the name already implies.\nHowever, there are different `components <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Component>`_ available in a `calendar <https://icalendar.readthedocs.io/en/latest/api.html#icalendar.cal.Calendar>`_.\nYou can select which components you like to have returned by passing ``components`` to the ``of`` function:\n\n.. code-block:: python\n\n    of(a_calendar, components=[\"VEVENT\"])\n\nHere is a template code for choosing the supported types of components:\n\n.. code-block:: python\n\n    >>> query_events = recurring_ical_events.of(a_calendar)\n    >>> query_journals = recurring_ical_events.of(a_calendar, components=[\"VJOURNAL\"])\n    >>> query_todos = recurring_ical_events.of(a_calendar, components=[\"VTODO\"])\n    >>> query_all = recurring_ical_events.of(a_calendar, components=[\"VTODO\", \"VEVENT\", \"VJOURNAL\"])\n\nIf a type of component is not listed here, it can be added.\nPlease create an issue for this in the source code repository.\n\nFor further customization, please refer to the section on how to extend the default functionality.\n\nAlarms\n******\n\nAlarms are subcomponents of events and todos. They only make sense with an event or todo.\nThus the interface is slightly different.\n\nAdd ``VALARM`` as the component you would like:\n\n.. code-block:: python\n\n    >>> query_alarms = recurring_ical_events.of(a_calendar, components=[\"VALARM\"])\n\nIn the following example, an event has an alarm one week before it starts.\nThe component returned is not a ``VALARM`` component but instead the ``VEVENT`` with only\none ``VALARM`` in it.\n\n.. code-block:: python\n\n    # read an .ics file with an event with an alarm\n    >>> calendar_with_alarm = recurring_ical_events.example_calendar(\"alarm_1_week_before_event\")\n    >>> alarm_day = datetime.date(2024, 12, 2)\n\n    # we get the event that has an alarm on that day\n    >>> event = recurring_ical_events.of(calendar_with_alarm, components=[\"VALARM\"]).at(alarm_day)[0]\n    >>> len(event.alarms.times)\n    1\n    >>> alarm = event.alarms.times[0]\n\n    # the alarm happens one week before the event\n    >>> event.start - alarm.trigger\n    datetime.timedelta(days=7)\n\nIn the following code, we query the same day for a ``VEVENT`` component and we find nothing.\nThe event happens a week later.\n\n.. code-block:: python\n\n    # No events on that day. There is only an alarm.\n    >>> recurring_ical_events.of(calendar_with_alarm, components=[\"VEVENT\"]).at(alarm_day)\n    []\n\nWhen querying events and todos, they keep their alarms and other subcompnents.\nThese alarm times can be outside of the dates requested.\n\nIn this example, we get an event and find that it has several alarms in it.\n\n.. code-block:: python\n\n    >>> event_day = alarm_day + datetime.timedelta(days=7)\n    >>> event = recurring_ical_events.of(calendar_with_alarm, components=[\"VEVENT\"]).at(event_day)[0]\n\n    # The event a week later has more than one alarm.\n    >>> len(event.walk(\"VALARM\"))\n    2\n\nSpeed\n*****\n\nIf you use ``between()`` or ``at()``\nseveral times, it is faster to re-use the object coming from ``of()``.\n\n.. code-block:: python\n\n    >>> query = recurring_ical_events.of(a_calendar)\n    >>> events_of_day_1 = query.at((2019, 2, 1))\n    >>> events_of_day_2 = query.at((2019, 2, 2))\n    >>> events_of_day_3 = query.at((2019, 2, 3))\n\n    # ... and so on\n\nSkip bad formatted ical events\n******************************\n\nSome events may be badly formatted and therefore cannot be handled by ``recurring-ical-events``.\nPassing ``skip_bad_series=True`` as ``of()`` argument will totally skip theses events.\n\n.. code-block:: python\n\n    # Create a calendar that contains broken events.\n    >>> calendar_file = CALENDARS / \"bad_rrule_missing_until_event.ics\"\n    >>> calendar_with_bad_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())\n\n     # By default, broken events result in errors.\n    >>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=False).count()\n    Traceback (most recent call last):\n      ...\n    recurring_ical_events.errors.BadRuleStringFormat: UNTIL parameter is missing: FREQ=WEEKLY;BYDAY=TH;WKST=SU;UNTL=20191023\n\n    # With skip_bad_series=True we skip the series that we cannot handle.\n    >>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=True).count()\n    0\n\nArchitecture\n------------\n\n.. image:: img/architecture.png\n   :alt: Architecture Diagram showing the components interacting\n\nEach icalendar **Calendar** can contain Events, Journal entries,\nTODOs and others, called **Components**.\nThose entries are grouped by their ``UID``.\nSuch a ``UID`` defines a **Series** of **Occurrences** that take place at\na given time.\nSince each **Component** is different, the **ComponentAdapter** offers a unified\ninterface to interact with them.\nThe **Calendar** gets filtered and for each ``UID``,\na **Series** can use one or more **ComponentAdapters** to create \n**Occurrences** of what happens in a time span.\nThese **Occurrences** are used internally and convert to **Components** for further use.\n\nExtending ``recurring-ical-events``\n***********************************\n\nAll the functionality of ``recurring-ical-events`` can be extended and modified.\nTo understand where to extend, have a look at the `Architecture`_.\n\nThe first place for extending is the collection of components.\nComponents are collected into a ``Series``.\nA series belongs together because all components have the same ``UID``.\nIn this example, we collect one VEVENT which matches a certain UID:\n\n.. code-block:: python\n\n    >>> from recurring_ical_events import SelectComponents, EventAdapter, Series\n    >>> from icalendar.cal import Component\n    >>> from typing import Sequence\n\n    # create the calendar\n    >>> calendar_file = CALENDARS / \"machbar_16_feb_2019.ics\"\n    >>> machbar_calendar = icalendar.Calendar.from_ical(calendar_file.read_bytes())\n\n    # Create a collector of components that searches for an event with a specific UID\n    >>> class CollectOneUIDEvent(SelectComponents):\n    ...     def __init__(self, uid:str) -> None:\n    ...         self.uid = uid\n    ...     def collect_series_from(self, source: Component, suppress_errors: tuple) -> Sequence[Series]:\n    ...         components : list[Component] = []\n    ...         for component in source.walk(\"VEVENT\"):\n    ...             if component.get(\"UID\") == self.uid:\n    ...                 components.append(EventAdapter(component))\n    ...         return [Series(components)] if components else []\n\n    # collect only one UID: 4mm2ak3in2j3pllqdk1ubtbp9p@google.com\n    >>> one_uid = CollectOneUIDEvent(\"4mm2ak3in2j3pllqdk1ubtbp9p@google.com\")\n    >>> uid_query = recurring_ical_events.of(machbar_calendar, components=[one_uid])\n    >>> uid_query.count()  # the event has no recurrence and thus there is only one\n    1\n\nSeveral ways of extending the functionality have been created to override internals.\nThese can be subclassed or composed.\n\nBelow, you can choose to collect all components. Subclasses can be created for the\n``Series`` and the ``Occurrence``. \n\n.. code-block:: python\n\n    >>> from recurring_ical_events import AllKnownComponents, Series, Occurrence\n\n    # we create a calendar with one event\n    >>> calendar_file = CALENDARS / \"one_event.ics\"\n    >>> one_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())\n\n    # You can override the Occurrence and Series classes for all computable components\n    >>> select_all_known = AllKnownComponents(series=Series, occurrence=Occurrence)\n    >>> select_all_known.names  # these are the supported types of components\n    ['VALARM', 'VEVENT', 'VJOURNAL', 'VTODO']\n    >>> query_all_known = recurring_ical_events.of(one_event, components=[select_all_known])\n\n    # There should be exactly one event.\n    >>> query_all_known.count()\n    1\n\nThis example shows that the behavior for specific types of components can be extended.\nAdditional to the series, you can change the ``ComponentAdapter`` that provides\na unified interface for all the components with the same name (``VEVENT`` for example).\n\n.. code-block:: python\n\n    >>> from recurring_ical_events import ComponentsWithName, EventAdapter, JournalAdapter, TodoAdapter\n\n    # You can also choose to select only specific subcomponents by their name.\n    # The default arguments are added to show the extensibility.\n    >>> select_events =   ComponentsWithName(\"VEVENT\",   adapter=EventAdapter,   series=Series, occurrence=Occurrence)\n    >>> select_todos =    ComponentsWithName(\"VTODO\",    adapter=TodoAdapter,    series=Series, occurrence=Occurrence)\n    >>> select_journals = ComponentsWithName(\"VJOURNAL\", adapter=JournalAdapter, series=Series, occurrence=Occurrence)\n\n    # There should be one event happening and nothing else\n    >>> recurring_ical_events.of(one_event, components=[select_events]).count()\n    1\n    >>> recurring_ical_events.of(one_event, components=[select_todos]).count()\n    0\n    >>> recurring_ical_events.of(one_event, components=[select_journals]).count()\n    0\n\nSo, if you would like to modify all events that are returned by the query,\nyou can do that subclassing the ``Occurrence`` class.\n\n\n.. code-block:: python\n\n    # This occurence changes adds a new attribute to the resulting events\n    >>> class MyOccurrence(Occurrence):\n    ...     \"\"\"An occurrence that modifies the component.\"\"\"\n    ...     def as_component(self, keep_recurrence_attributes: bool) -> Component:\n    ...         \"\"\"Return a shallow copy of the source component and modify some attributes.\"\"\"\n    ...         component = super().as_component(keep_recurrence_attributes)\n    ...         component[\"X-MY-ATTRIBUTE\"] = \"my occurrence\"\n    ...         return component\n    >>> query = recurring_ical_events.of(one_event, components=[ComponentsWithName(\"VEVENT\", occurrence=MyOccurrence)])\n    >>> event = next(query.all())\n    >>> event[\"X-MY-ATTRIBUTE\"]\n    'my occurrence'\n\nThis library allows extension of functionality during the selection of components to calculate using these classes:\n\n* ``ComponentsWithName`` - for components of a certain name\n* ``AllKnownComponents`` - for all components known\n* ``SelectComponents`` - the interface to provide\n\nYou can further customize behaviour by subclassing these:\n\n* ``ComponentAdapter`` such as ``EventAdapter``, ``JournalAdapter`` or ``TodoAdapter``.\n* ``Series``\n* ``Occurrence``\n* ``CalendarQuery``\n\nVersion Fixing\n**************\n\nIf you use this library in your code, you may want to make sure that\nupdates can be received but they do not break your code.\nThe version numbers are handeled this way: ``a.b.c`` example: ``0.1.12``\n\n- ``c`` is changed for each minor bug fix.\n- ``b`` is changed whenever new features are added.\n- ``a`` is changed when the interface or major assumptions change that may break your code.\n\nSo, I recommend to version-fix this library to stay with the same ``a``\nwhile ``b`` and ``c`` can change.\n\nDevelopment\n-----------\n\nCode style\n**********\n\nPlease install `pre-commit <https://pre-commit.com/>`_ before git commit.  It will ensure that the code is formatted and linted as expected using `ruff <https://docs.astral.sh/ruff/>`_.\n\n.. code-block:: shell\n\n   pre-commit install\n\n\nTesting\n*******\n\nThis project's development is driven by tests.\nTests assure a consistent interface and less knowledge lost over time.\nIf you like to change the code, tests help that nothing breaks in the future.\nThey are required in that sense.\nExample code and ics files can be transferred into tests and speed up fixing bugs.\n\nYou can view the tests in the `test folder\n<https://github.com/niccokunzmann/python-recurring-ical-events/tree/master/test>`_.\nIf you have a calendar ICS file for which this library does not\ngenerate the desired output, you can add it to the ``test/calendars``\nfolder and write tests for what you expect.\nIf you like, `open an issue <https://github.com/niccokunzmann/python-recurring-ical-events/issues>`_ first, e.g. to discuss the changes and\nhow to go about it.\n\n\nTo run the tests, we use ``tox``.\n``tox`` tests all different Python versions which we want to  be compatible to.\n\n.. code-block:: shell\n\n   pip3 install tox\n\nTo run all the tests:\n\n.. code-block:: shell\n\n   tox\n\nTo run the tests in a specific Python version:\n\n.. code-block:: shell\n\n   tox -e py39\n\n\n\nNew Releases\n------------\n\nYou can build the new release by running this command:\n\n.. code-block:: shell\n\n    tox -e build\n\nTo release new versions,\n\n1. Edit the Changelog Section.\n2. Create a commit and push it.\n3. Wait for `GitHub Actions <https://github.com/niccokunzmann/python-recurring-ical-events/actions>`_ to finish the build.\n4. Run\n\n   .. code-block:: shell\n\n       git tag v3.5.1\n       git push origin v3.5.1\n\n5. Notify the issues about their release.\n\nChangelog\n---------\n\n- v3.5.1\n\n  - Move to ``pyproject.toml`` format to include directory structure more easily. See `Issue 214 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/214>`_\n  - Remove release 3.5.0 as it does not contain any source files.\n\n- v3.5.0 - yanked\n\n  - Restructure module into package with a file structure.\n  - Add pagination, see `Issue 211 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/211>`_\n\n- v3.4.1\n\n  - Improve Alarm documentation\n\n- v3.4.0\n\n  - Add ``VALARM`` support: Calculate alarm times. See `Issue 186 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/186>`_\n\n- v3.3.4\n\n  - Allow ``x-wr-timezone`` 1.* and 2.* for this lib to remove dependency update problems.\n\n- v3.3.3\n\n  -  Fix: Events with DTSTART of type date have a duration of one day, see `Issue 179 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/179>`_\n\n- v3.3.2\n\n  - Update x-wr-timezone\n\n- v3.3.1\n\n  - Support RDATE with PERIOD value type where the end is a duration, see `PR 180 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/180>`_\n  - Support modifying all events in the future (RECURRENCE-ID with RANGE=THISANDFUTURE), see `Issue 75 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/75>`_\n\n- v3.3.0\n\n  - Make tests work with ``icalendar`` version 5\n  - Restructure README to be tested with ``doctest``\n  - Remove ``DURATION`` from the result, see `Issue 139 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/139>`_\n  - Document new way of extending the functionality, see `Issue 133 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/133>`_ and `PR 175 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/175>`_\n\n- v3.2.0\n\n  - Allow ``datetime.timedelta`` as second argument to ``between(absolute_time, datetime.timedelta())``\n\n- v3.1.1\n\n  - Fix: Remove duplication of modification with same sequence number, see `Issue 164 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/164>`_\n  - Fix: EXDATE now excludes a modified instance for an event with higher ``SEQUENCE``, see `Issue <https://github.com/niccokunzmann/python-recurring-ical-events/issues/163>`_\n\n- v3.1.0\n\n  - Add ``count() -> int`` to count all occurrences within a calendar\n  - Add ``all() -> Generator[icalendar.Component]`` to iterate over the whole calendar\n\n- v3.0.0\n\n  - Change the architecture and add a diagram\n  - Add type hints, see `Issue 91 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/91>`_\n  - Rename ``UnfoldableCalendar`` to ``CalendarQuery``\n  - Rename ``of(skip_bad_events=None)`` to ``of(skip_bad_series=False)``\n  - ``of(components=[...])`` now also takes ``ComponentAdapters``\n  - Fix edit sequence problems, see `Issue 151 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/151>`_\n\n- v2.2.3\n\n  - Fix: Edits of whole event are now considering RDATE and EXDATE, see `Issue 148 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/148>`_\n\n- v2.2.2\n\n  - Test support for ``icalendar==6.*``\n  - Remove Python 3.7 from tests and compatibility list\n  - Remove pytz from requirements\n\n- v2.2.1\n\n  - Add support for multiple RRULE in events.\n\n- v2.2.0\n\n  - Add ``after()`` method to iterate over upcoming events.\n\n- v2.1.3\n\n  - Test and support Python 3.12.\n  - Change SPDX license header.\n  - Fix RRULE with negative COUNT, see `Issue 128 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/128>`_\n\n- v2.1.2\n\n  - Fix RRULE with EXDATE as DATE, see `PR 121 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/121>`__ by Jan Grasnick and `PR 122 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/122>`__.\n\n- v2.1.1\n\n  - Claim and test support for Python 3.11.\n  - Support deleting events by setting RRULE UNTIL < DTSTART, see `Issue 117 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/117>`__.\n\n- v2.1.0\n\n  - Added support for PERIOD values in RDATE. See `Issue 113 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/113>`_.\n  - Fixed ``icalendar>=5.0.9`` to support ``RDATE`` of type ``PERIOD`` with a time zone.\n  - Fixed ``pytz>=2023.3`` to assure compatibility.\n\n- v2.0.2\n\n  - Fixed omitting last event of ``RRULE`` with ``UNTIL`` when using ``pytz``, the event starting in winter time and ending in summer time. See `Issue 107 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/107>`_.\n\n- v2.0.1\n\n  - Fixed crasher with duplicate RRULE. See `Pull Request 104 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/104>`_\n\n- v2.0.0b\n\n  - Only return ``VEVENT`` by default. Add ``of(... ,components=...)`` parameter to select which kinds of components should be returned. See `Issue 101 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/101>`_.\n  - Remove ``beta`` indicator. This library works okay: Feature requests come in, not so much bug reports.\n\n- v1.1.0b\n\n  - Add repeated TODOs and Journals. See `Pull Request 100 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/100>`_ and `Issue 97 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/97>`_.\n\n- v1.0.3b\n\n  - Remove syntax anomalies in README.\n  - Switch to GitHub actions because GitLab decided to remove support.\n\n- v1.0.2b\n\n  - Add support for ``X-WR-TIMEZONE`` calendars which contain events without an explicit time zone, see `Issue 86 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/86>`_.\n\n- v1.0.1b\n\n  - Add support for ``zoneinfo.ZoneInfo`` time zones, see `Issue 57 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/57>`_.\n  - Migrate from Travis CI to Gitlab CI.\n  - Add code coverage on Gitlab.\n\n- v1.0.0b\n\n  - Remove Python 2 support, see `Issue 64 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/64>`_.\n  - Remove support for Python 3.5 and 3.6.\n  - Note: These deprecated Python versions may still work. We just do not claim they do.\n  - ``X-WR-TIMEZONE`` support, see `Issue 71 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/71>`_.\n\n- v0.2.4b\n\n  - Events with a duration of 0 seconds are correctly returned.\n  - ``between()`` and ``at()`` take the same kind of arguments. These arguments are documented.\n\n- v0.2.3b\n\n  - ``between()`` and ``at()`` allow arguments with time zones now when calendar events do not have time zones, reported in `Issue 61 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/61>`_ and `Issue 52 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/52>`_.\n\n- v0.2.2b\n\n  - Check that ``at()`` does not return an event starting at the next day, see `Issue 44 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/44>`_.\n\n- v0.2.1b\n\n  - Check that recurring events are removed if they are modified to leave the requested time span, see `Issue 62 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/62>`_.\n\n- v0.2.0b\n\n  - Add ability to keep the recurrence attributes (RRULE, RDATE, EXDATE) on the event copies instead of stripping them. See `Pull Request 54 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/54>`_.\n\n- v0.1.21b\n\n  - Fix issue with repetitions over DST boundary. See `Issue 48 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/48>`_.\n\n- v0.1.20b\n\n  - Fix handling of modified recurrences with lower sequence number than their base event `Pull Request 45 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/45>`_\n\n- v0.1.19b\n\n  - Benchmark using `@mrx23dot <https://github.com/mrx23dot>`_'s script and speed up recurrence calculation by factor 4, see `Issue 42 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/42>`_.\n\n- v0.1.18b\n\n  - Handle `Issue 28 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/28>`__ so that EXDATEs match as expected.\n  - Handle `Issue 27 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/27>`_ so that parsing some rrule UNTIL values does not crash.\n\n- v0.1.17b\n\n  - Handle `Issue 28 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/28>`__ where passed arguments lead to errors where it is expected to work.\n\n- v0.1.16b\n\n  - Events with an empty RRULE are handled like events without an RRULE.\n  - Remove fixed dependency versions, see `Issue 14 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/14>`_\n\n- v0.1.15b\n\n  - Repeated events also include subcomponents. `Issue 6 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/6>`_\n\n- v0.1.14b\n\n  - Fix compatibility `issue 20 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/20>`_: EXDATEs of different time zones are now supported.\n\n- v0.1.13b\n\n  - Remove attributes RDATE, EXDATE, RRULE from repeated events `Issue 23`_\n  - Use vDDDTypes instead of explicit date/datetime type `Pull Request 19 <https://github.com/niccokunzmann/python-recurring-ical-events/pull/19>`_\n  - Start Changelog\n\nLibraries Used\n--------------\n\n- `python-dateutil <https://pypi.org/project/python-dateutil/>`_ - to compute the recurrences of events using ``rrule``\n- `icalendar`_ - the library used to parse ICS files\n- `pytz <https://pypi.org/project/pytz/>`_ - for timezones\n- `x-wr-timezone <https://github.com/niccokunzmann/x-wr-timezone>`_ for handling the non-standard ``X-WR-TIMEZONE`` property.\n\nRelated Projects\n----------------\n\n- `icalevents <https://github.com/irgangla/icalevents>`_ - another library for roughly the same use-case\n- `Open Web Calendar <https://github.com/niccokunzmann/open-web-calendar>`_ - a web calendar to embed into websites which uses this library\n- `icspy <https://icspy.readthedocs.io/>`_ - to create your own calendar events\n- `pyICSParser <https://pypi.org/project/pyICSParser/>`_ - parse icalendar files and return event times (`GitHub <https://github.com/oberron/pyICSParser>`__)\n- `ics-query`_ - a **command line** impementation of ``recurring-ical-events``\n- `icalendar-events-cli`_ - another **command line** impementation of ``recurring-ical-events``\n- `caldav`_ - the python caldav client library\n- `plann`_ - a **command line** caldav client\n\n.. _`ics-query`: https://github.com/niccokunzmann/ics-query#readme\n.. _`icalendar-events-cli`: https://github.com/waldbaer/icalendar-events-cli#readme\n.. _`caldav`:  https://github.com/python-caldav/caldav\n.. _`plann`: https://github.com/tobixen/plann\n\nMedia\n-----\n\nNicco Kunzmann talked about this library at the\nFOSSASIA 2022 Summit:\n\n.. image:: https://niccokunzmann.github.io/ical-talk-fossasia-2022/youtube.png\n   :target: https://youtu.be/8l3opDdg92I?t=10369\n   :alt: Talk about this library at the FOSSASIA 2022 Summit\n\nResearch\n--------\n\n- `RFC 5545 <https://tools.ietf.org/html/rfc5545>`_\n- `RFC 7986 <https://tools.ietf.org/html/rfc7986>`_ -- an update to RFC 5545. It does not change any properties useful for scheduling events.\n- `Stackoverflow question this is created for <https://stackoverflow.com/questions/30913824/ical-library-to-iterate-recurring-events-with-specific-instances>`_\n- `<https://github.com/oberron/annum>`_\n\n  - `<https://stackoverflow.com/questions/28829261/python-ical-get-events-for-a-day-including-recurring-ones#28829401>`_\n\n- `<https://stackoverflow.com/questions/20268204/ical-get-date-from-recurring-event-by-rrule-and-dtstart>`_\n- `<https://github.com/collective/icalendar/issues/162>`_\n- `<https://stackoverflow.com/questions/46471852/ical-parsing-reoccuring-events-in-python>`_\n- RDATE `<https://stackoverflow.com/a/46709850/1320237>`_\n\n  - `<https://tools.ietf.org/html/rfc5545#section-3.8.5.2>`_\n",
    "bugtrack_url": null,
    "license": "GNU LESSER GENERAL PUBLIC LICENSE\n                               Version 3, 29 June 2007\n        \n         Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>\n         Everyone is permitted to copy and distribute verbatim copies\n         of this license document, but changing it is not allowed.\n        \n        \n          This version of the GNU Lesser General Public License incorporates\n        the terms and conditions of version 3 of the GNU General Public\n        License, supplemented by the additional permissions listed below.\n        \n          0. Additional Definitions.\n        \n          As used herein, \"this License\" refers to version 3 of the GNU Lesser\n        General Public License, and the \"GNU GPL\" refers to version 3 of the GNU\n        General Public License.\n        \n          \"The Library\" refers to a covered work governed by this License,\n        other than an Application or a Combined Work as defined below.\n        \n          An \"Application\" is any work that makes use of an interface provided\n        by the Library, but which is not otherwise based on the Library.\n        Defining a subclass of a class defined by the Library is deemed a mode\n        of using an interface provided by the Library.\n        \n          A \"Combined Work\" is a work produced by combining or linking an\n        Application with the Library.  The particular version of the Library\n        with which the Combined Work was made is also called the \"Linked\n        Version\".\n        \n          The \"Minimal Corresponding Source\" for a Combined Work means the\n        Corresponding Source for the Combined Work, excluding any source code\n        for portions of the Combined Work that, considered in isolation, are\n        based on the Application, and not on the Linked Version.\n        \n          The \"Corresponding Application Code\" for a Combined Work means the\n        object code and/or source code for the Application, including any data\n        and utility programs needed for reproducing the Combined Work from the\n        Application, but excluding the System Libraries of the Combined Work.\n        \n          1. Exception to Section 3 of the GNU GPL.\n        \n          You may convey a covered work under sections 3 and 4 of this License\n        without being bound by section 3 of the GNU GPL.\n        \n          2. Conveying Modified Versions.\n        \n          If you modify a copy of the Library, and, in your modifications, a\n        facility refers to a function or data to be supplied by an Application\n        that uses the facility (other than as an argument passed when the\n        facility is invoked), then you may convey a copy of the modified\n        version:\n        \n           a) under this License, provided that you make a good faith effort to\n           ensure that, in the event an Application does not supply the\n           function or data, the facility still operates, and performs\n           whatever part of its purpose remains meaningful, or\n        \n           b) under the GNU GPL, with none of the additional permissions of\n           this License applicable to that copy.\n        \n          3. Object Code Incorporating Material from Library Header Files.\n        \n          The object code form of an Application may incorporate material from\n        a header file that is part of the Library.  You may convey such object\n        code under terms of your choice, provided that, if the incorporated\n        material is not limited to numerical parameters, data structure\n        layouts and accessors, or small macros, inline functions and templates\n        (ten or fewer lines in length), you do both of the following:\n        \n           a) Give prominent notice with each copy of the object code that the\n           Library is used in it and that the Library and its use are\n           covered by this License.\n        \n           b) Accompany the object code with a copy of the GNU GPL and this license\n           document.\n        \n          4. Combined Works.\n        \n          You may convey a Combined Work under terms of your choice that,\n        taken together, effectively do not restrict modification of the\n        portions of the Library contained in the Combined Work and reverse\n        engineering for debugging such modifications, if you also do each of\n        the following:\n        \n           a) Give prominent notice with each copy of the Combined Work that\n           the Library is used in it and that the Library and its use are\n           covered by this License.\n        \n           b) Accompany the Combined Work with a copy of the GNU GPL and this license\n           document.\n        \n           c) For a Combined Work that displays copyright notices during\n           execution, include the copyright notice for the Library among\n           these notices, as well as a reference directing the user to the\n           copies of the GNU GPL and this license document.\n        \n           d) Do one of the following:\n        \n               0) Convey the Minimal Corresponding Source under the terms of this\n               License, and the Corresponding Application Code in a form\n               suitable for, and under terms that permit, the user to\n               recombine or relink the Application with a modified version of\n               the Linked Version to produce a modified Combined Work, in the\n               manner specified by section 6 of the GNU GPL for conveying\n               Corresponding Source.\n        \n               1) Use a suitable shared library mechanism for linking with the\n               Library.  A suitable mechanism is one that (a) uses at run time\n               a copy of the Library already present on the user's computer\n               system, and (b) will operate properly with a modified version\n               of the Library that is interface-compatible with the Linked\n               Version.\n        \n           e) Provide Installation Information, but only if you would otherwise\n           be required to provide such information under section 6 of the\n           GNU GPL, and only to the extent that such information is\n           necessary to install and execute a modified version of the\n           Combined Work produced by recombining or relinking the\n           Application with a modified version of the Linked Version. (If\n           you use option 4d0, the Installation Information must accompany\n           the Minimal Corresponding Source and Corresponding Application\n           Code. If you use option 4d1, you must provide the Installation\n           Information in the manner specified by section 6 of the GNU GPL\n           for conveying Corresponding Source.)\n        \n          5. Combined Libraries.\n        \n          You may place library facilities that are a work based on the\n        Library side by side in a single library together with other library\n        facilities that are not Applications and are not covered by this\n        License, and convey such a combined library under terms of your\n        choice, if you do both of the following:\n        \n           a) Accompany the combined library with a copy of the same work based\n           on the Library, uncombined with any other library facilities,\n           conveyed under the terms of this License.\n        \n           b) Give prominent notice with the combined library that part of it\n           is a work based on the Library, and explaining where to find the\n           accompanying uncombined form of the same work.\n        \n          6. Revised Versions of the GNU Lesser General Public License.\n        \n          The Free Software Foundation may publish revised and/or new versions\n        of the GNU Lesser General Public License from time to time. Such new\n        versions will be similar in spirit to the present version, but may\n        differ in detail to address new problems or concerns.\n        \n          Each version is given a distinguishing version number. If the\n        Library as you received it specifies that a certain numbered version\n        of the GNU Lesser General Public License \"or any later version\"\n        applies to it, you have the option of following the terms and\n        conditions either of that published version or of any later version\n        published by the Free Software Foundation. If the Library as you\n        received it does not specify a version number of the GNU Lesser\n        General Public License, you may choose any version of the GNU Lesser\n        General Public License ever published by the Free Software Foundation.\n        \n          If the Library as you received it specifies that a proxy can decide\n        whether future versions of the GNU Lesser General Public License shall\n        apply, that proxy's public statement of acceptance of any version is\n        permanent authorization for you to choose that version for the\n        Library.",
    "summary": "Calculate recurrence times of events, todos, alarms and journals based on icalendar RFC5545.",
    "version": "3.5.1",
    "project_urls": {
        "Changelog": "https://github.com/niccokunzmann/python-recurring-ical-events?tab=readme-ov-file#changelog",
        "Documentation": "https://github.com/niccokunzmann/python-recurring-ical-events",
        "Homepage": "https://github.com/niccokunzmann/python-recurring-ical-events",
        "Issues": "https://github.com/niccokunzmann/python-recurring-ical-events/issues",
        "Repository": "https://github.com/niccokunzmann/python-recurring-ical-events",
        "source_archive": "https://github.com/niccokunzmann/python-recurring-ical-events/archive/08725beb39aaf0439ed0318310b5f2c0d626d16e.zip"
    },
    "split_keywords": [
        "alarm",
        " calendar",
        " events",
        " icalendar",
        " ics",
        " journal",
        " rfc5545",
        " scheduling",
        " todo"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "97a9c056eca5d4ec396f8c25fbd6fe905728d527a7723d37ac1e40c81356ed6e",
                "md5": "5bac36cce58d31cc980caeae5f73c587",
                "sha256": "563838cb9e6679ab9a2d471dde1c1af0f8f81bd64c5d6af6efd19dc6025765d7"
            },
            "downloads": -1,
            "filename": "recurring_ical_events-3.5.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5bac36cce58d31cc980caeae5f73c587",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 239806,
            "upload_time": "2025-02-12T19:53:22",
            "upload_time_iso_8601": "2025-02-12T19:53:22.146522Z",
            "url": "https://files.pythonhosted.org/packages/97/a9/c056eca5d4ec396f8c25fbd6fe905728d527a7723d37ac1e40c81356ed6e/recurring_ical_events-3.5.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4b26f000cabb98aeca1a84b84ad892495c163dd5607470debaf1f35fa03beb3d",
                "md5": "7460305000f64eabdbc56d1ba7f54ebe",
                "sha256": "a5b61918a14dc842d23b4929bcd99123aaeaae296f99b3adb0fec6f405bc53f4"
            },
            "downloads": -1,
            "filename": "recurring_ical_events-3.5.1.tar.gz",
            "has_sig": false,
            "md5_digest": "7460305000f64eabdbc56d1ba7f54ebe",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 602738,
            "upload_time": "2025-02-12T19:53:25",
            "upload_time_iso_8601": "2025-02-12T19:53:25.458612Z",
            "url": "https://files.pythonhosted.org/packages/4b/26/f000cabb98aeca1a84b84ad892495c163dd5607470debaf1f35fa03beb3d/recurring_ical_events-3.5.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-12 19:53:25",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "niccokunzmann",
    "github_project": "python-recurring-ical-events?tab=readme-ov-file#changelog",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "click",
            "specs": [
                [
                    "==",
                    "8.1.8"
                ]
            ]
        },
        {
            "name": "icalendar",
            "specs": [
                [
                    "==",
                    "6.1.1"
                ]
            ]
        },
        {
            "name": "python-dateutil",
            "specs": [
                [
                    "==",
                    "2.9.0.post0"
                ]
            ]
        },
        {
            "name": "six",
            "specs": [
                [
                    "==",
                    "1.17.0"
                ]
            ]
        },
        {
            "name": "tzdata",
            "specs": [
                [
                    "==",
                    "2025.1"
                ]
            ]
        },
        {
            "name": "x-wr-timezone",
            "specs": [
                [
                    "==",
                    "2.0.1"
                ]
            ]
        }
    ],
    "tox": true,
    "lcname": "recurring-ical-events"
}
None
Elapsed time: 4.33973s