From 1c41de7904d443090e265f1a275e58bf45dc24a6 Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 08:54:41 +0100 Subject: [PATCH 1/8] Fix formatting issues in tutorial documentation If an inline literal like "``foo``" is too long to fit on screen, and it doesn't contain spaces, it won't include line-breaks, and for example on mobile this will extend past the right edge of the screen, allowing horizontal scrolling which is not wanted on mobile. Hence adding more spaces allows for more chances to break the literal, decreasing the chance this happens. --- docs/source/tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index d02002d1..8e603dbd 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -23,7 +23,7 @@ When you've run the tutorial as intended, I recommend going through the examples * Set the environment variables ``CALDAV_URL``, ``CALDAV_USER`` and ``CALDAV_PASSWORD`` to point to your personal calendar server. * Be aware that different calendar servers may behave differently. For instance, not all of them allows you to create a calendar. Some are even read-only. -* You will need to revert all changes done. The code examples below does not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ```my_new_calendar.delete()``` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're adviced to have a local backup of your calendars. I'll probably write a HOWTO on that one day. +* You will need to revert all changes done. The code examples below does not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're adviced to have a local backup of your calendars. I'll probably write a HOWTO on that one day. * Usage of a context manager is considered best practice, but not really needed - you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. Quick Start: Getting Calendars Directly @@ -94,7 +94,7 @@ function, go from there to get a Caveat: Things will break if password/url/username is wrong, but perhaps not where you expect it to. To test, you may try out -``get_davclient(username='alice', password='hunter2',url='https://calendar.example.com/dav/')``. +``get_davclient(username='alice', password='hunter2', url='https://calendar.example.com/dav/')``. The ``calendar``-method above gives one calendar - if you have more calendars, it will give you the first one it can find - which may not From 46c5a1a946c8f8991ef1860c23e50b00e0355cb1 Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:13:51 +0100 Subject: [PATCH 2/8] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/source/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 8e603dbd..71ff53ff 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -23,7 +23,7 @@ When you've run the tutorial as intended, I recommend going through the examples * Set the environment variables ``CALDAV_URL``, ``CALDAV_USER`` and ``CALDAV_PASSWORD`` to point to your personal calendar server. * Be aware that different calendar servers may behave differently. For instance, not all of them allows you to create a calendar. Some are even read-only. -* You will need to revert all changes done. The code examples below does not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're adviced to have a local backup of your calendars. I'll probably write a HOWTO on that one day. +* You will need to revert all changes done. The code examples below does not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. * Usage of a context manager is considered best practice, but not really needed - you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. Quick Start: Getting Calendars Directly From 043ad704af81baf0c5f6db23532b542b0939b442 Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:15:42 +0100 Subject: [PATCH 3/8] gr --- docs/source/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 71ff53ff..96417951 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -23,7 +23,7 @@ When you've run the tutorial as intended, I recommend going through the examples * Set the environment variables ``CALDAV_URL``, ``CALDAV_USER`` and ``CALDAV_PASSWORD`` to point to your personal calendar server. * Be aware that different calendar servers may behave differently. For instance, not all of them allows you to create a calendar. Some are even read-only. -* You will need to revert all changes done. The code examples below does not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. +* You will need to revert all changes done. The code examples below do not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. * Usage of a context manager is considered best practice, but not really needed - you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. Quick Start: Getting Calendars Directly From 43a827dfcddbd4c026cfcd93710fd6b046156a1e Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 09:45:17 +0100 Subject: [PATCH 4/8] use actual em-dash --- docs/source/tutorial.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 96417951..e64bf677 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -24,7 +24,7 @@ When you've run the tutorial as intended, I recommend going through the examples * Set the environment variables ``CALDAV_URL``, ``CALDAV_USER`` and ``CALDAV_PASSWORD`` to point to your personal calendar server. * Be aware that different calendar servers may behave differently. For instance, not all of them allows you to create a calendar. Some are even read-only. * You will need to revert all changes done. The code examples below do not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. -* Usage of a context manager is considered best practice, but not really needed - you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. +* Usage of a context manager is considered best practice, but not really needed – you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. Quick Start: Getting Calendars Directly --------------------------------------- @@ -96,10 +96,10 @@ Caveat: Things will break if password/url/username is wrong, but perhaps not where you expect it to. To test, you may try out ``get_davclient(username='alice', password='hunter2', url='https://calendar.example.com/dav/')``. -The ``calendar``-method above gives one calendar - if you have more -calendars, it will give you the first one it can find - which may not +The ``calendar``-method above gives one calendar – if you have more +calendars, it will give you the first one it can find – which may not be the correct one. To filter there are parameters ``name`` and -``cal_id`` - I recommend testing them: +``cal_id`` – I recommend testing them: .. code-block:: python @@ -125,7 +125,7 @@ to go through the principal object. Note that in the example above, no communication is done. If the URL is wrong, you will only know it when trying to save or get objects from the server! -For servers that supports it, it may be useful to create a dedicated test calendar - that way you can test freely without risking to mess up your calendar events. Let's populate it with an event while we're at it: +For servers that supports it, it may be useful to create a dedicated test calendar – that way you can test freely without risking to mess up your calendar events. Let's populate it with an event while we're at it: .. code-block:: python @@ -165,7 +165,7 @@ You have icalendar code and want to put it into the calendar? Easy! END:VCALENDAR """) -The best way of getting information out from the calendar is to use the search. Currently most of the logic is done on the server side - and the different calendar servers tends to give different results given the same data and search query. In future versions of the CalDAV library the intention is to do more workarounds and logic on the client side, allowing for more consistent results across different servers. +The best way of getting information out from the calendar is to use the search. Currently most of the logic is done on the server side – and the different calendar servers tends to give different results given the same data and search query. In future versions of the CalDAV library the intention is to do more workarounds and logic on the client side, allowing for more consistent results across different servers. .. code-block:: python @@ -193,11 +193,11 @@ The best way of getting information out from the calendar is to use the search. ``expand`` matters for recurring events and tasks, instead of getting returned the original event (with ``DTSTART`` set in 2023 and an ``RRULE`` set) it will return the *recurrence* for year 2026. Or, rather, a list of recurrences if there are more of them in the search interval. -``event`` causes the search to only return events. There are three kind of objects that can be saved to a calendar (but not all servers support all three) - events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalenderObjectResource objects such as an event, but it could also be a task or a journal" - and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. +``event`` causes the search to only return events. There are three kind of objects that can be saved to a calendar (but not all servers support all three) – events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalenderObjectResource objects such as an event, but it could also be a task or a journal" – and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. -Without ``event=True`` explicitly set, all kind of objects *should* be returned. Unfortunately many servers returns nothing - so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. +Without ``event=True`` explicitly set, all kind of objects *should* be returned. Unfortunately many servers returns nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. -The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` - for tasks and jornals there are similar classes Todo and Journal. +The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` – for tasks and jornals there are similar classes Todo and Journal. The ``data`` property delivers the icalendar data as a string. It can be modified: @@ -268,7 +268,7 @@ The ``event.component`` property gives easy access to the How to do operations on components in the icalendar library is outside the scope of this tutorial. -Usually tasks and journals can be applied directly to the same calendar as the events - but some implementations (notably Zimbra) has "task lists" and "calendars" as distinct entities. To create a task list, there is a parameter ``supported_calendar_component_set`` that can be set to ``['VTODO']``. Here is a quick example that features a task: +Usually tasks and journals can be applied directly to the same calendar as the events – but some implementations (notably Zimbra) has "task lists" and "calendars" as distinct entities. To create a task list, there is a parameter ``supported_calendar_component_set`` that can be set to ``['VTODO']``. Here is a quick example that features a task: .. code-block:: python From 11993d3a54a64e6df88a11f643d8ab3556037d48 Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 10:00:56 +0100 Subject: [PATCH 5/8] gr --- docs/source/tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index e64bf677..a78deed0 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -193,9 +193,9 @@ The best way of getting information out from the calendar is to use the search. ``expand`` matters for recurring events and tasks, instead of getting returned the original event (with ``DTSTART`` set in 2023 and an ``RRULE`` set) it will return the *recurrence* for year 2026. Or, rather, a list of recurrences if there are more of them in the search interval. -``event`` causes the search to only return events. There are three kind of objects that can be saved to a calendar (but not all servers support all three) – events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalenderObjectResource objects such as an event, but it could also be a task or a journal" – and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. +``event`` causes the search to only return events. There are three kinds of objects that can be saved to a calendar (but not all servers support all three) – events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalenderObjectResource objects such as an event, but it could also be a task or a journal" – and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. -Without ``event=True`` explicitly set, all kind of objects *should* be returned. Unfortunately many servers returns nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. +Without ``event=True`` explicitly set, all kinds of objects *should* be returned. Unfortunately many servers returns nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` – for tasks and jornals there are similar classes Todo and Journal. From 37a9c92914bb8d491b1cc0ce8e9a3cfb5f106bd8 Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 10:04:13 +0100 Subject: [PATCH 6/8] Apply grammar suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/source/tutorial.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index a78deed0..2f2c90c2 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -125,7 +125,7 @@ to go through the principal object. Note that in the example above, no communication is done. If the URL is wrong, you will only know it when trying to save or get objects from the server! -For servers that supports it, it may be useful to create a dedicated test calendar – that way you can test freely without risking to mess up your calendar events. Let's populate it with an event while we're at it: +For servers that support it, it may be useful to create a dedicated test calendar – that way you can test freely without risking to mess up your calendar events. Let's populate it with an event while we're at it: .. code-block:: python @@ -165,7 +165,7 @@ You have icalendar code and want to put it into the calendar? Easy! END:VCALENDAR """) -The best way of getting information out from the calendar is to use the search. Currently most of the logic is done on the server side – and the different calendar servers tends to give different results given the same data and search query. In future versions of the CalDAV library the intention is to do more workarounds and logic on the client side, allowing for more consistent results across different servers. +The best way of getting information out from the calendar is to use the search. Currently most of the logic is done on the server side – and the different calendar servers tend to give different results given the same data and search query. In future versions of the CalDAV library the intention is to do more workarounds and logic on the client side, allowing for more consistent results across different servers. .. code-block:: python @@ -197,7 +197,7 @@ The best way of getting information out from the calendar is to use the search. Without ``event=True`` explicitly set, all kinds of objects *should* be returned. Unfortunately many servers returns nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. -The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` – for tasks and jornals there are similar classes Todo and Journal. +The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` – for tasks and journals there are similar classes Todo and Journal. The ``data`` property delivers the icalendar data as a string. It can be modified: @@ -268,7 +268,7 @@ The ``event.component`` property gives easy access to the How to do operations on components in the icalendar library is outside the scope of this tutorial. -Usually tasks and journals can be applied directly to the same calendar as the events – but some implementations (notably Zimbra) has "task lists" and "calendars" as distinct entities. To create a task list, there is a parameter ``supported_calendar_component_set`` that can be set to ``['VTODO']``. Here is a quick example that features a task: +Usually tasks and journals can be applied directly to the same calendar as the events – but some implementations (notably Zimbra) have "task lists" and "calendars" as distinct entities. To create a task list, there is a parameter ``supported_calendar_component_set`` that can be set to ``['VTODO']``. Here is a quick example that features a task: .. code-block:: python From 5faa6b90e5377112290f77891386317142c29d9a Mon Sep 17 00:00:00 2001 From: joshinils <34302971+joshinils@users.noreply.github.com> Date: Sun, 8 Feb 2026 10:08:14 +0100 Subject: [PATCH 7/8] fix suggested grammar changes by copilot review --- docs/source/tutorial.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 2f2c90c2..c0e742bb 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -193,9 +193,9 @@ The best way of getting information out from the calendar is to use the search. ``expand`` matters for recurring events and tasks, instead of getting returned the original event (with ``DTSTART`` set in 2023 and an ``RRULE`` set) it will return the *recurrence* for year 2026. Or, rather, a list of recurrences if there are more of them in the search interval. -``event`` causes the search to only return events. There are three kinds of objects that can be saved to a calendar (but not all servers support all three) – events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalenderObjectResource objects such as an event, but it could also be a task or a journal" – and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. +``event`` causes the search to only return events. There are three kinds of objects that can be saved to a calendar (but not all servers support all three) – events, journals and tasks (``VEVENT``, ``VJOURNAL`` and ``VTODO``). This is called Calendar Object Resources in the RFC. Now that's quite a mouthful! To ease things, the word "event" is simply used in documentation and communication. So when reading "event", be aware that it actually means "a CalendarObjectResource objects such as an event, but it could also be a task or a journal" – and if you contribute code, remember to use ``CalendarObjectResource`` rather than ``Event``. -Without ``event=True`` explicitly set, all kinds of objects *should* be returned. Unfortunately many servers returns nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. +Without ``event=True`` explicitly set, all kinds of objects *should* be returned. Unfortunately many servers return nothing – so as of 2.0, it's important to always specify if you want events, tasks or journals. In future versions of CalDAV there will be workarounds for this so ``event=True`` can be safely skipped, regardless what server is used. The return type is a list of objects of the type :class:`caldav.calendarobjectresource.Event` – for tasks and journals there are similar classes Todo and Journal. From 763994118a9c4d13399426db98f9caf9717117cf Mon Sep 17 00:00:00 2001 From: Tobias Brox Date: Sun, 8 Feb 2026 12:19:33 +0100 Subject: [PATCH 8/8] Update docs/source/tutorial.rst Co-authored-by: joshinils <34302971+joshinils@users.noreply.github.com> --- docs/source/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index c0e742bb..fa1dc442 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -23,7 +23,7 @@ When you've run the tutorial as intended, I recommend going through the examples * Set the environment variables ``CALDAV_URL``, ``CALDAV_USER`` and ``CALDAV_PASSWORD`` to point to your personal calendar server. * Be aware that different calendar servers may behave differently. For instance, not all of them allows you to create a calendar. Some are even read-only. -* You will need to revert all changes done. The code examples below do not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also has a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. +* You will need to revert all changes done. The code examples below do not do any cleanup. If your calendar server supports creating and deleting calendars, then it should be easy enough: ``my_new_calendar.delete()`` inside the with-block. Events also have a ``.delete()``-method. Beware that there is no ``undo``. You're advised to have a local backup of your calendars. I'll probably write a HOWTO on that one day. * Usage of a context manager is considered best practice, but not really needed – you may skip the with-statement and write just ``client = get_davclient()``. This will make it easier to test code from the python shell. Quick Start: Getting Calendars Directly