This is an iCalendar rfc 5545 implementation in python. The goal of this
project is to offer a calendar library with the relevant and practical
features needed for building a calendar application (e.g. recurring
events).
ical's main focus is on simplicity, and the internal implementation
is based on existing parsing libraries, where possible, making it
easy to support as much as possible of rfc5545. It is not a goal to
support everything exhaustively, however, the simplicity of the
implementation makes it easy to do so.
See [documentation](https://allenporter.github.io/ical/) for full quickstart and API reference.
# Quickstart
The example below creates a Calendar, then adds an all day event to
the calendar, then iterates over all events on the calendar.
```python
from datetime import date
from ical.calendar import Calendar
from ical.event import Event
calendar = Calendar()
calendar.events.append(
Event(summary="Event summary", start=date(2022, 7, 3), end=date(2022, 7, 4)),
)
for event in calendar.timeline:
print(event.summary)
```
# Reading ics files
This example parses an .ics file from disk and creates a `ical.calendar.Calendar` object, then
prints out the events in order:
```python
from pathlib import Path
from ical.calendar_stream import IcsCalendarStream
from ical.exceptions import CalendarParseError
filename = Path("example/calendar.ics")
with filename.open() as ics_file:
try:
calendar = IcsCalendarStream.calendar_from_ics(ics_file.read())
except CalendarParseError as err:
print(f"Failed to parse ics file '{str(filename)}': {err}")
else:
print([event.summary for event in calendar.timeline])
```
# Writing ics files
This example writes a calendar object to an ics output file:
```python
from pathlib import Path
from ical.calendar_stream import IcsCalendarStream
filename = Path("example/output.ics")
with filename.open() as ics_file:
ics_file.write(IcsCalendarStream.calendar_to_ics(calendar))
```
# Application-level APIs
The above APIs are used for lower level interaction with calendar components,
however applications require a higher level interface to manage some of the
underlying complexity. The `ical.store` library is used to manage state at a higher
level (e.g. ensuring timezones are created properly) or handling edits to
recurring events.
# Recurring events
A calendar event may be recurring (e.g. weekly, monthly, etc). Recurring events
are represented in a `ical.calendar.Calendar` with a single `ical.event.Event` object, however
when observed through a `ical.timeline.Timeline` will be expanded based on the recurrence rule.
See the `rrule`, `rdate`, and `exdate` fields on the `ical.event.Event` for more details.
# Related Work
There are other python rfc5545 implementations that are more mature, and having
been around for many years, are still active, and served as reference
implementations for this project:
- Ics.py - [github](https://github.com/ics-py/ics-py) [docs](https://icspy.readthedocs.io/en/stable/) - Since 2013
- icalendar [github](https://github.com/collective/icalendar) [docs](https://icalendar.readthedocs.io/) - Since 2005
Raw data
{
"_id": null,
"home_page": "https://github.com/allenporter/ical",
"name": "ical",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Allen Porter",
"author_email": "allen.porter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1a/81/1863ef2e43de9aeee7d57eaef1c3f7c0d188ed9f466a0062ce47757952d3/ical-8.2.0.tar.gz",
"platform": null,
"description": "This is an iCalendar rfc 5545 implementation in python. The goal of this\nproject is to offer a calendar library with the relevant and practical\nfeatures needed for building a calendar application (e.g. recurring\nevents).\n\nical's main focus is on simplicity, and the internal implementation\nis based on existing parsing libraries, where possible, making it\neasy to support as much as possible of rfc5545. It is not a goal to\nsupport everything exhaustively, however, the simplicity of the\nimplementation makes it easy to do so.\n\nSee [documentation](https://allenporter.github.io/ical/) for full quickstart and API reference.\n\n# Quickstart\n\nThe example below creates a Calendar, then adds an all day event to\nthe calendar, then iterates over all events on the calendar.\n\n```python\nfrom datetime import date\n\nfrom ical.calendar import Calendar\nfrom ical.event import Event\n\ncalendar = Calendar()\ncalendar.events.append(\n Event(summary=\"Event summary\", start=date(2022, 7, 3), end=date(2022, 7, 4)),\n)\nfor event in calendar.timeline:\n print(event.summary)\n```\n\n# Reading ics files\n\nThis example parses an .ics file from disk and creates a `ical.calendar.Calendar` object, then\nprints out the events in order:\n\n```python\nfrom pathlib import Path\nfrom ical.calendar_stream import IcsCalendarStream\nfrom ical.exceptions import CalendarParseError\n\nfilename = Path(\"example/calendar.ics\")\nwith filename.open() as ics_file:\n try:\n calendar = IcsCalendarStream.calendar_from_ics(ics_file.read())\n except CalendarParseError as err:\n print(f\"Failed to parse ics file '{str(filename)}': {err}\")\n else:\n print([event.summary for event in calendar.timeline])\n```\n\n# Writing ics files\n\nThis example writes a calendar object to an ics output file:\n\n```python\nfrom pathlib import Path\nfrom ical.calendar_stream import IcsCalendarStream\n\nfilename = Path(\"example/output.ics\")\nwith filename.open() as ics_file:\n ics_file.write(IcsCalendarStream.calendar_to_ics(calendar))\n```\n\n# Application-level APIs\n\nThe above APIs are used for lower level interaction with calendar components,\nhowever applications require a higher level interface to manage some of the\nunderlying complexity. The `ical.store` library is used to manage state at a higher\nlevel (e.g. ensuring timezones are created properly) or handling edits to\nrecurring events.\n\n# Recurring events\n\nA calendar event may be recurring (e.g. weekly, monthly, etc). Recurring events\nare represented in a `ical.calendar.Calendar` with a single `ical.event.Event` object, however\nwhen observed through a `ical.timeline.Timeline` will be expanded based on the recurrence rule.\nSee the `rrule`, `rdate`, and `exdate` fields on the `ical.event.Event` for more details.\n\n# Related Work\n\nThere are other python rfc5545 implementations that are more mature, and having\nbeen around for many years, are still active, and served as reference\nimplementations for this project:\n - Ics.py - [github](https://github.com/ics-py/ics-py) [docs](https://icspy.readthedocs.io/en/stable/) - Since 2013\n - icalendar [github](https://github.com/collective/icalendar) [docs](https://icalendar.readthedocs.io/) - Since 2005\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python iCalendar implementation (rfc 2445)",
"version": "8.2.0",
"project_urls": {
"Homepage": "https://github.com/allenporter/ical"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "21f6f70bf5be07f25fc9b10f25aef772586b3cf1449ce94900c097995a50fcba",
"md5": "d10eede027cc78d229bef5869fac94c5",
"sha256": "f35d7b80dc88f437dca94d19ae3f7cd99b3cc1118a44779a58481697240aa11d"
},
"downloads": -1,
"filename": "ical-8.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d10eede027cc78d229bef5869fac94c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 115336,
"upload_time": "2024-09-12T05:00:00",
"upload_time_iso_8601": "2024-09-12T05:00:00.312363Z",
"url": "https://files.pythonhosted.org/packages/21/f6/f70bf5be07f25fc9b10f25aef772586b3cf1449ce94900c097995a50fcba/ical-8.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a811863ef2e43de9aeee7d57eaef1c3f7c0d188ed9f466a0062ce47757952d3",
"md5": "85d6d3b2da153da9995186a7f97d527b",
"sha256": "fb65ab62a0dc38fb8fb1a1fce3912ea505873c352b51d5206e3e1253b8416cb8"
},
"downloads": -1,
"filename": "ical-8.2.0.tar.gz",
"has_sig": false,
"md5_digest": "85d6d3b2da153da9995186a7f97d527b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 114331,
"upload_time": "2024-09-12T05:00:01",
"upload_time_iso_8601": "2024-09-12T05:00:01.954765Z",
"url": "https://files.pythonhosted.org/packages/1a/81/1863ef2e43de9aeee7d57eaef1c3f7c0d188ed9f466a0062ce47757952d3/ical-8.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 05:00:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenporter",
"github_project": "ical",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ical"
}
JSON
