==========================================================
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
:Community Discussions: https://github.com/collective/icalendar/discussions
:Issue Tracker: https://github.com/collective/icalendar/issues
:Code: https://github.com/collective/icalendar
:Dependencies: `python-dateutil`_ and `tzdata`_.
: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/pyversions/icalendar
:target: https://pypi.org/project/icalendar/
:alt: PyPI - Python Version
.. 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=main&label=main&logo=github
:target: https://github.com/collective/icalendar/actions/workflows/tests.yml?query=branch%3Amain
:alt: GitHub Actions build status for main
.. image:: https://readthedocs.org/projects/icalendar/badge/?version=latest
:target: https://icalendar.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://coveralls.io/repos/github/collective/icalendar/badge.svg
:target: https://coveralls.io/github/collective/icalendar
:alt: Test Coverage
.. _`icalendar`: https://pypi.org/project/icalendar/
.. _`python-dateutil`: https://github.com/dateutil/dateutil/
.. _`tzdata`: https://pypi.org/project/tzdata/
.. _`BSD`: https://github.com/collective/icalendar/issues/2
Quick start guide
=================
``icalendar`` enables you to **create**, **inspect** and **modify**
calendaring information with Python.
To **install** the package, run::
pip install icalendar
Inspect Files
-------------
You can open an ``.ics`` file and see all the events:
.. code:: python
>>> import icalendar
>>> from pathlib import Path
>>> ics_path = Path("src/icalendar/tests/calendars/example.ics")
>>> calendar = icalendar.Calendar.from_ical(ics_path.read_bytes())
>>> for event in calendar.events:
... print(event.get("SUMMARY"))
New Year's Day
Orthodox Christmas
International Women's Day
Modify Content
--------------
Such a calendar can then be edited and saved again.
.. code:: python
>>> calendar.calendar_name = "My Modified Calendar" # modify
>>> print(calendar.to_ical()[:121]) # save modification
BEGIN:VCALENDAR
VERSION:2.0
PRODID:collective/icalendar
CALSCALE:GREGORIAN
METHOD:PUBLISH
NAME:My Modified Calendar
Create Events, TODOs, Journals, Alarms, ...
-------------------------------------------
``icalendar`` supports the creation and parsing of all kinds of objects
in the iCalendar (:rfc:`5545`) standard.
.. code:: python
>>> icalendar.Event() # events
VEVENT({})
>>> icalendar.FreeBusy() # free/busy times
VFREEBUSY({})
>>> icalendar.Todo() # Todo list entries
VTODO({})
>>> icalendar.Alarm() # Alarms e.g. for events
VALARM({})
>>> icalendar.Journal() # Journal entries
VJOURNAL({})
Have a look at `more examples
<https://icalendar.readthedocs.io/en/latest/usage.html>`_.
Use timezones of your choice
----------------------------
With ``icalendar``, you can localize your events to take place in different
timezones.
``zoneinfo``, ``dateutil.tz`` and ``pytz`` are compatible with ``icalendar``.
This example creates an event that uses all of the timezone implementations
with the same result:
.. code:: python
>>> import pytz, zoneinfo, dateutil.tz # timezone libraries
>>> import datetime, icalendar
>>> e = icalendar.Event()
>>> tz = dateutil.tz.tzstr("Europe/London")
>>> e["X-DT-DATEUTIL"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = pytz.timezone("Europe/London")
>>> e["X-DT-USE-PYTZ"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = zoneinfo.ZoneInfo("Europe/London")
>>> e["X-DT-ZONEINFO"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> print(e.to_ical()) # the libraries yield the same result
BEGIN:VEVENT
X-DT-DATEUTIL;TZID=Europe/London:20240619T100100
X-DT-USE-PYTZ;TZID=Europe/London:20240619T100100
X-DT-ZONEINFO;TZID=Europe/London:20240619T100100
END:VEVENT
Version 6 with zoneinfo
-----------------------
Version 6 of ``icalendar`` switches the timezone implementation to ``zoneinfo``.
This only affects you if you parse ``icalendar`` objects with ``from_ical()``.
The functionality is extended and is tested since 6.0.0 with both timezone
implementations ``pytz`` and ``zoneinfo``.
By default and since 6.0.0, ``zoneinfo`` timezones are created.
.. code:: python
>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
ZoneInfo(key='Europe/Vienna')
If you would like to continue to receive ``pytz`` timezones in parse results,
you can receive all the latest updates, and switch back to earlier behavior:
.. code:: python
>>> icalendar.use_pytz()
>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
<DstTzInfo 'Europe/Vienna' CET+1:00:00 STD>
Version 6 is on `branch main <https://github.com/collective/icalendar/>`_.
It is compatible with Python versions 3.8 - 3.13, and PyPy3.
We expect the ``main`` branch with versions ``6+`` to receive the latest updates and 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.Calendar`` object for events and other components happening at a certain date or within a certain time.
* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library and command line tool to make ``icalendar.Calendar`` objects and files from Google Calendar (using the non-standard ``X-WR-TIMEZONE`` property) compliant with the standard (:rfc:`5545`).
* `ics-query <http://pypi.org/project/ics-query>`_. Command line tool to query iCalendar files for occurrences of events and other components.
* `icalendar-compatibility <https://icalendar-compatibility.readthedocs.io/en/latest/>`_ - access to event data compatible with RFC5545 and different implementations
Further Reading
===============
You can find out more about this project:
* `Contributing`_
* `Changelog`_
* `License`_
.. _`Contributing`: https://icalendar.readthedocs.io/en/latest/contributing.html
.. _`Changelog`: https://icalendar.readthedocs.io/en/latest/changelog.html
.. _`License`: https://icalendar.readthedocs.io/en/latest/license.html
Raw data
{
"_id": null,
"home_page": null,
"name": "icalendar",
"maintainer": "Christian Geier",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Nicco Kunzmann <niccokunzmann@rambler.ru>, Jaca <vitouejj@gmail.com>",
"keywords": "calendar, calendaring, event, ical, icalendar, journal, recurring, rfc5545, todo",
"author": null,
"author_email": "Plone Foundation <plone-developers@lists.sourceforge.net>",
"download_url": "https://files.pythonhosted.org/packages/5d/70/458092b3e7c15783423fe64d07e63ea3311a597e723be6a1060513e3db93/icalendar-6.3.2.tar.gz",
"platform": null,
"description": "==========================================================\nInternet Calendaring and Scheduling (iCalendar) for Python\n==========================================================\n\nThe `icalendar`_ package is a :rfc:`5545` compatible parser/generator for iCalendar\nfiles.\n\n----\n\n:Homepage: https://icalendar.readthedocs.io\n:Community Discussions: https://github.com/collective/icalendar/discussions\n:Issue Tracker: https://github.com/collective/icalendar/issues\n:Code: https://github.com/collective/icalendar\n:Dependencies: `python-dateutil`_ and `tzdata`_.\n:License: `BSD`_\n\n----\n\n.. image:: https://badge.fury.io/py/icalendar.svg\n :target: https://pypi.org/project/icalendar/\n :alt: Python Package Version on PyPI\n\n.. image:: https://img.shields.io/pypi/pyversions/icalendar\n :target: https://pypi.org/project/icalendar/\n :alt: PyPI - Python Version\n\n.. image:: https://img.shields.io/pypi/dm/icalendar.svg\n :target: https://pypi.org/project/icalendar/#files\n :alt: Downloads from PyPI\n\n.. image:: https://img.shields.io/github/actions/workflow/status/collective/icalendar/tests.yml?branch=main&label=main&logo=github\n :target: https://github.com/collective/icalendar/actions/workflows/tests.yml?query=branch%3Amain\n :alt: GitHub Actions build status for main\n\n.. image:: https://readthedocs.org/projects/icalendar/badge/?version=latest\n :target: https://icalendar.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://coveralls.io/repos/github/collective/icalendar/badge.svg\n :target: https://coveralls.io/github/collective/icalendar\n :alt: Test Coverage\n\n\n.. _`icalendar`: https://pypi.org/project/icalendar/\n.. _`python-dateutil`: https://github.com/dateutil/dateutil/\n.. _`tzdata`: https://pypi.org/project/tzdata/\n.. _`BSD`: https://github.com/collective/icalendar/issues/2\n\nQuick start guide\n=================\n\n``icalendar`` enables you to **create**, **inspect** and **modify**\ncalendaring information with Python.\n\nTo **install** the package, run::\n\n pip install icalendar\n\n\nInspect Files\n-------------\n\nYou can open an ``.ics`` file and see all the events:\n\n.. code:: python\n\n >>> import icalendar\n >>> from pathlib import Path\n >>> ics_path = Path(\"src/icalendar/tests/calendars/example.ics\")\n >>> calendar = icalendar.Calendar.from_ical(ics_path.read_bytes())\n >>> for event in calendar.events:\n ... print(event.get(\"SUMMARY\"))\n New Year's Day\n Orthodox Christmas\n International Women's Day\n\nModify Content\n--------------\n\nSuch a calendar can then be edited and saved again.\n\n.. code:: python\n\n >>> calendar.calendar_name = \"My Modified Calendar\" # modify\n >>> print(calendar.to_ical()[:121]) # save modification\n BEGIN:VCALENDAR\n VERSION:2.0\n PRODID:collective/icalendar\n CALSCALE:GREGORIAN\n METHOD:PUBLISH\n NAME:My Modified Calendar\n\n\nCreate Events, TODOs, Journals, Alarms, ...\n-------------------------------------------\n\n``icalendar`` supports the creation and parsing of all kinds of objects\nin the iCalendar (:rfc:`5545`) standard.\n\n.. code:: python\n\n >>> icalendar.Event() # events\n VEVENT({})\n >>> icalendar.FreeBusy() # free/busy times\n VFREEBUSY({})\n >>> icalendar.Todo() # Todo list entries\n VTODO({})\n >>> icalendar.Alarm() # Alarms e.g. for events\n VALARM({})\n >>> icalendar.Journal() # Journal entries\n VJOURNAL({})\n\n\nHave a look at `more examples\n<https://icalendar.readthedocs.io/en/latest/usage.html>`_.\n\nUse timezones of your choice\n----------------------------\n\nWith ``icalendar``, you can localize your events to take place in different\ntimezones.\n``zoneinfo``, ``dateutil.tz`` and ``pytz`` are compatible with ``icalendar``.\nThis example creates an event that uses all of the timezone implementations\nwith the same result:\n\n.. code:: python\n\n >>> import pytz, zoneinfo, dateutil.tz # timezone libraries\n >>> import datetime, icalendar\n >>> e = icalendar.Event()\n >>> tz = dateutil.tz.tzstr(\"Europe/London\")\n >>> e[\"X-DT-DATEUTIL\"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))\n >>> tz = pytz.timezone(\"Europe/London\")\n >>> e[\"X-DT-USE-PYTZ\"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))\n >>> tz = zoneinfo.ZoneInfo(\"Europe/London\")\n >>> e[\"X-DT-ZONEINFO\"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))\n >>> print(e.to_ical()) # the libraries yield the same result\n BEGIN:VEVENT\n X-DT-DATEUTIL;TZID=Europe/London:20240619T100100\n X-DT-USE-PYTZ;TZID=Europe/London:20240619T100100\n X-DT-ZONEINFO;TZID=Europe/London:20240619T100100\n END:VEVENT\n\nVersion 6 with zoneinfo\n-----------------------\n\nVersion 6 of ``icalendar`` switches the timezone implementation to ``zoneinfo``.\nThis only affects you if you parse ``icalendar`` objects with ``from_ical()``.\nThe functionality is extended and is tested since 6.0.0 with both timezone\nimplementations ``pytz`` and ``zoneinfo``.\n\nBy default and since 6.0.0, ``zoneinfo`` timezones are created.\n\n.. code:: python\n\n >>> dt = icalendar.Calendar.example(\"timezoned\").events[0].start\n >>> dt.tzinfo\n ZoneInfo(key='Europe/Vienna')\n\nIf you would like to continue to receive ``pytz`` timezones in parse results,\nyou can receive all the latest updates, and switch back to earlier behavior:\n\n.. code:: python\n\n >>> icalendar.use_pytz()\n >>> dt = icalendar.Calendar.example(\"timezoned\").events[0].start\n >>> dt.tzinfo\n <DstTzInfo 'Europe/Vienna' CET+1:00:00 STD>\n\nVersion 6 is on `branch main <https://github.com/collective/icalendar/>`_.\nIt is compatible with Python versions 3.8 - 3.13, and PyPy3.\nWe expect the ``main`` branch with versions ``6+`` to receive the latest updates and features.\n\nRelated projects\n================\n\n* `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.\n* `recurring-ical-events <https://pypi.org/project/recurring-ical-events/>`_. Library to query an ``icalendar.Calendar`` object for events and other components happening at a certain date or within a certain time.\n* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library and command line tool to make ``icalendar.Calendar`` objects and files from Google Calendar (using the non-standard ``X-WR-TIMEZONE`` property) compliant with the standard (:rfc:`5545`).\n* `ics-query <http://pypi.org/project/ics-query>`_. Command line tool to query iCalendar files for occurrences of events and other components.\n* `icalendar-compatibility <https://icalendar-compatibility.readthedocs.io/en/latest/>`_ - access to event data compatible with RFC5545 and different implementations\n\nFurther Reading\n===============\n\nYou can find out more about this project:\n\n* `Contributing`_\n* `Changelog`_\n* `License`_\n\n.. _`Contributing`: https://icalendar.readthedocs.io/en/latest/contributing.html\n.. _`Changelog`: https://icalendar.readthedocs.io/en/latest/changelog.html\n.. _`License`: https://icalendar.readthedocs.io/en/latest/license.html\n",
"bugtrack_url": null,
"license": null,
"summary": "iCalendar parser/generator",
"version": "6.3.2",
"project_urls": {
"Changelog": "https://icalendar.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://icalendar.readthedocs.io/",
"Homepage": "https://icalendar.readthedocs.io/",
"Issues": "https://github.com/collective/icalendar/issues",
"Repository": "https://github.com/collective/icalendar/",
"source_archive": "https://github.com/collective/icalendar/archive/2f0683a03c1d2182a04ae35a1fcbaad59672888d.zip"
},
"split_keywords": [
"calendar",
" calendaring",
" event",
" ical",
" icalendar",
" journal",
" recurring",
" rfc5545",
" todo"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06ee2ff96bb5bd88fe03ab90aedf5180f96dc0f3ae4648ca264b473055bcaaff",
"md5": "205e4d6b62b2f65f821879d573677a50",
"sha256": "d400e9c9bb8c025e5a3c77c236941bb690494be52528a0b43cc7e8b7c9505064"
},
"downloads": -1,
"filename": "icalendar-6.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "205e4d6b62b2f65f821879d573677a50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 242403,
"upload_time": "2025-11-05T12:49:30",
"upload_time_iso_8601": "2025-11-05T12:49:30.691549Z",
"url": "https://files.pythonhosted.org/packages/06/ee/2ff96bb5bd88fe03ab90aedf5180f96dc0f3ae4648ca264b473055bcaaff/icalendar-6.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5d70458092b3e7c15783423fe64d07e63ea3311a597e723be6a1060513e3db93",
"md5": "75eec6a59ade0678257717594e3c861a",
"sha256": "e0c10ecbfcebe958d33af7d491f6e6b7580d11d475f2eeb29532d0424f9110a1"
},
"downloads": -1,
"filename": "icalendar-6.3.2.tar.gz",
"has_sig": false,
"md5_digest": "75eec6a59ade0678257717594e3c861a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 178422,
"upload_time": "2025-11-05T12:49:32",
"upload_time_iso_8601": "2025-11-05T12:49:32.286487Z",
"url": "https://files.pythonhosted.org/packages/5d/70/458092b3e7c15783423fe64d07e63ea3311a597e723be6a1060513e3db93/icalendar-6.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 12:49:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "collective",
"github_project": "icalendar",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "icalendar"
}
JSON
