Internet Calendaring and Scheduling (iCalendar) for Python
 
 
Go to file
Bob Florian c1527336df
Update about.rst
updated about.rst to include details that the repo is not obsolete and  still compliant with RFC5545
2023-09-15 11:19:28 -05:00
.github Add keys for caching 2023-08-30 07:48:55 +01:00
docs Update about.rst 2023-09-15 11:19:28 -05:00
src/icalendar Merge pull request #547 from niccokunzmann/issue-152 2023-09-06 19:54:04 +02:00
.gitignore ignore venv folder 2022-08-22 13:42:32 +01:00
.readthedocs.yml Update readthedocs config 2023-08-30 08:40:09 +01:00
CHANGES.rst Merge pull request #547 from niccokunzmann/issue-152 2023-09-06 19:54:04 +02:00
CONTRIBUTING.rst update links (#378) 2022-08-17 00:31:15 +03:00
LICENSE.rst
MANIFEST.in
README.rst Add documentation about parsing 2023-08-30 17:33:21 +01:00
bootstrap.py update links (#378) 2022-08-17 00:31:15 +03:00
buildout.cfg
requirements_docs.txt Revert "fix Sphinx build" 2022-09-26 17:34:52 +01:00
setup.cfg Do not create a universal wheel for the release. 2022-10-19 09:29:58 +02:00
setup.py use find_namespace_packages() to fix installing data subdirs 2022-10-18 07:53:14 +02:00
tox.ini No longer run the plone.app.event tests. 2023-08-28 11:57:08 +02:00

README.rst

==========================================================
Internet Calendaring and Scheduling (iCalendar) for Python
==========================================================

The `icalendar`_ package is a `RFC 5545`_ compatible parser/generator for iCalendar
files.

----

:Homepage: https://icalendar.readthedocs.io
:Code: https://github.com/collective/icalendar
:Mailing list: https://github.com/collective/icalendar/issues
:Dependencies: `python-dateutil`_ and `pytz`_.
:Compatible with: Python 2.7 and 3.4+
:License: `BSD`_

----

.. image:: https://badge.fury.io/py/icalendar.svg
   :target: https://pypi.org/project/icalendar/
   :alt: Python Package Version on PyPI

.. image:: https://img.shields.io/pypi/dm/icalendar.svg
   :target: https://pypi.org/project/icalendar/#files
   :alt: Downloads from PyPI

.. image:: https://img.shields.io/github/actions/workflow/status/collective/icalendar/tests.yml?branch=master&label=master&logo=github
    :target: https://github.com/collective/icalendar/actions/workflows/tests.yml?query=branch%3Amaster
    :alt: GitHub Actions build status for master

.. image:: https://img.shields.io/github/actions/workflow/status/collective/icalendar/tests.yml?branch=4.x&label=4.x&logo=github
    :target: https://github.com/collective/icalendar/actions/workflows/tests.yml?query=branch%3A4.x++
    :alt: GitHub Actions build status for 4.x

.. image:: https://readthedocs.org/projects/icalendar/badge/?version=latest
    :target: https://icalendar.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. _`icalendar`: https://pypi.org/project/icalendar/
.. _`RFC 5545`: https://www.ietf.org/rfc/rfc5545.txt
.. _`python-dateutil`: https://github.com/dateutil/dateutil/
.. _`pytz`: https://pypi.org/project/pytz/
.. _`BSD`: https://github.com/collective/icalendar/issues/2

Quick Guide
-----------

To **install** the package, run::

    pip install icalendar

You can open an ``.ics`` file and see all the events::

  >>> import icalendar
  >>> path_to_ics_file = "src/icalendar/tests/calendars/example.ics"
  >>> with open(path_to_ics_file) as f:
  ...     calendar = icalendar.Calendar.from_ical(f.read())
  >>> for event in calendar.walk('VEVENT'):
  ...     print(event.get("SUMMARY"))
  New Year's Day
  Orthodox Christmas
  International Women's Day

Using this package, you can also create calendars from scratch or edit existing ones.

Versions and Compatibility
--------------------------

``icalendar`` is a critical project used by many. It has been there for a long time and maintaining
long-term compatibility with projects conflicts partially with providing and using the features that
the latest Python versions bring.

Since we pour more `effort into maintaining and developing icalendar <https://github.com/collective/icalendar/discussions/360>`__,
we split the project into two:

- `Branch 4.x <https://github.com/collective/icalendar/tree/4.x>`__ with maximum compatibility to Python versions ``2.7`` and ``3.4+``, ``PyPy2`` and ``PyPy3``.
- `Branch master <https://github.com/collective/icalendar/>`__ with the compatibility to Python versions ``3.7+`` and ``PyPy3``.

We expect the ``master`` branch with versions ``5+`` receive the latest updates and features,
and the ``4.x`` branch the subset of security and bug fixes only.
We recommend migrating to later Python versions and also providing feedback if you depend on the ``4.x`` features.

Related projects
================

* `icalevents <https://github.com/irgangla/icalevents>`_. It is built on top of icalendar and allows you to query iCal files and get the events happening on specific dates. It manages recurrent events as well.
* `recurring-ical-events <https://pypi.org/project/recurring-ical-events/>`_. Library to query an ``ICalendar`` object for events happening at a certain date or within a certain time.
* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library to make ``ICalendar`` objects and files using the non-standard ``X-WR-TIMEZONE`` compliant with the standard (RFC 5545).