diff --git a/CHANGES.rst b/CHANGES.rst index 8c7f5d2c..b6d8ce4a 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -8,6 +8,7 @@ Minor changes: - Update build configuration to build readthedocs. #538 - No longer run the ``plone.app.event`` tests. +- Add documentation on how to parse ``.ics`` files. #152 - Move pip caching into Python setup action. Breaking changes: diff --git a/README.rst b/README.rst index dc397939..0ae54fdf 100644 --- a/README.rst +++ b/README.rst @@ -42,6 +42,27 @@ files. .. _`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 -------------------------- diff --git a/docs/usage.rst b/docs/usage.rst index 2ae83c30..7d7aa0c5 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -342,5 +342,5 @@ Print out the calendar:: More documentation ================== -Have a look at the tests of this package to get more examples. +Have a look at the `tests `__ of this package to get more examples. All modules and classes docstrings, which document how they work. diff --git a/src/icalendar/tests/calendars/example.ics b/src/icalendar/tests/calendars/example.ics new file mode 100644 index 00000000..a01c8f42 --- /dev/null +++ b/src/icalendar/tests/calendars/example.ics @@ -0,0 +1,40 @@ +BEGIN:VCALENDAR +VERSION:2.0 +PRODID:collective/icalendar +CALSCALE:GREGORIAN +METHOD:PUBLISH +X-WR-CALNAME:Holidays +X-WR-TIMEZONE:Etc/GMT +BEGIN:VEVENT +SUMMARY:New Year's Day +DTSTART:20220101 +DTEND:20220101 +DESCRIPTION:Happy New Year! +UID:636a0cc1dbd5a1667894465@icalendar +DTSTAMP:20221108T080105Z +STATUS:CONFIRMED +TRANSP:TRANSPARENT +SEQUENCE:0 +END:VEVENT +BEGIN:VEVENT +SUMMARY:Orthodox Christmas +DTSTART:20220107 +DTEND:20220107 +LOCATION:Russia +DESCRIPTION:It is Christmas again! +UID:636a0cc1dbfd91667894465@icalendar +STATUS:CONFIRMED +TRANSP:TRANSPARENT +SEQUENCE:0 +END:VEVENT +BEGIN:VEVENT +SUMMARY:International Women's Day +DTSTART:20220308 +DTEND:20220308 +DESCRIPTION:May the feminine be honoured! +UID:636a0cc1dc0f11667894465@icalendar +STATUS:CONFIRMED +TRANSP:TRANSPARENT +SEQUENCE:0 +END:VEVENT +END:VCALENDAR \ No newline at end of file