docs: add async tutorial

Add docs/source/async_tutorial.rst, a step-by-step async tutorial that
mirrors the existing sync tutorial.rst.  Covers the same topics (creating
calendars, accessing calendars, creating events, searching, investigating
events, modifying events, tasks) plus a "Parallel Operations" section
demonstrating asyncio.gather().

Also update tutorial.rst to link to the new async tutorial instead of
saying "will come soon", and add async_tutorial to the docs index.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tobixen

docs/source/async_tutorial.rst

@@ -0,0 +1,380 @@
+==============
+Async Tutorial
+==============
+
+This tutorial covers async usage of the Python CalDAV client library.
+It mirrors :doc:`tutorial`, but uses the ``caldav.aio`` module.  This
+tutorial assumes you've already browsed through the sync tutorial.
+
+Copy code examples into a Python file and run them with ``python``.  Do not
+name your file ``caldav.py`` or ``calendar.py``, as this may break imports.
+
+All examples run inside an ``async def`` function launched via
+``asyncio.run()``.  You are encouraged to add a ``breakpoint()`` inside the
+``async with`` blocks to inspect return objects.
+
+Go through the tutorial twice, first against a Xandikos test server, and then
+against a server of your own choice.
+
+Configuration
+-------------
+
+The same applies here as in the sync tutorial, use ``export PYTHON_CALDAV_USE_TEST_SERVER=1`` and install Xandikos and the instructions below will give you a test server.  Unset ``PYTHON_CALDAV_USE_TEST_SERVER`` and edit ``~/.config/caldav/calendar.conf`` or adjust the environment variables to test with a real server.
+
+Creating Calendars
+------------------
+
+The async API lives in ``caldav.aio``.  Obtain a client by awaiting
+:func:`~caldav.aio.get_async_davclient`, then use it as an async context
+manager.  When the ``async with`` block exits the HTTP session is closed.
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        client = await aio.get_async_davclient()
+        async with client:
+            my_principal = await client.get_principal()
+            my_new_calendar = await my_principal.make_calendar(name="Teest calendar")
+            ## Enable the debug breakpoint to investigate the calendar object
+            #breakpoint()
+            await my_new_calendar.delete()
+
+    asyncio.run(main())
+
+The delete step is unimportant when running towards an ephemeral test server.
+
+The async version probes the server with an OPTIONS request by default (``probe=True``).  It may and may not cause an immediate failure on wrong credentials, depending on the server setup.  Feel free to play with it.  This code will never fail:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        ## Invalid domain, invalid password ...
+        ## ... this probably ought to raise an error?
+        client = await aio.get_async_davclient(
+            username='alice',
+            password='hunter2',
+            url='https://calendar.example.com/dav/',
+            probe=False)
+        async with client:
+            ...
+
+    asyncio.run(main())
+
+Accessing Calendars
+-------------------
+
+Use :func:`aio.get_calendars` to list all calendars in one call.  Like the
+sync version it returns a collection that can be used as an async context
+manager — the HTTP session is terminated on exit:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        async with await aio.get_calendars() as calendars:
+            for calendar in calendars:
+                print(f"Calendar \"{await calendar.get_display_name()}\" has URL {calendar.url}")
+
+    asyncio.run(main())
+
+:func:`aio.get_calendar` is the async counterpart of :func:`caldav.get_calendar`
+and is the **recommended starting point** for most code:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        async with await aio.get_calendar() as calendar:
+            print(f"Calendar \"{await calendar.get_display_name()}\" has URL {calendar.url}")
+            ## You may add a debugger breakpoint and investigate the object
+            #breakpoint()
+
+    asyncio.run(main())
+
+The calendar has a ``.client`` property which gives the client.
+
+Creating Events
+---------------
+
+From the :class:`~caldav.collection.Calendar` object, use
+:meth:`~caldav.collection.Calendar.add_event` to create an event:
+
+.. code-block:: python
+
+    import asyncio
+    import datetime
+    from caldav import aio
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            ## Add a may 17 event
+            may17 = await cal.add_event(
+                dtstart=datetime.datetime(2020,5,17,8),
+                dtend=datetime.datetime(2020,5,18,1),
+                uid="may17",
+                summary="Do the needful",
+                rrule={'FREQ': 'YEARLY'})
+            ## You may want to inspect the event
+            #breakpoint()
+
+    asyncio.run(main())
+
+You have icalendar code and want to put it into the calendar?  Easy!
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            may17 = await cal.add_event("""BEGIN:VCALENDAR
+    VERSION:2.0
+    PRODID:-//Example Corp.//CalDAV Client//EN
+    BEGIN:VEVENT
+    UID:20200516T060000Z-123401@example.com
+    DTSTAMP:20200516T060000Z
+    DTSTART:20200517T060000Z
+    DTEND:20200517T230000Z
+    RRULE:FREQ=YEARLY
+    SUMMARY:Do the needful
+    END:VEVENT
+    END:VCALENDAR
+    """)
+            #breakpoint()
+
+    asyncio.run(main())
+
+
+Searching
+---------
+
+The search API is identical to the sync version; just add ``await``:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+    from datetime import datetime, date
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            await cal.add_event(
+                dtstart=datetime(2023,5,17,8),
+                dtend=datetime(2023,5,18,1),
+                uid="may17",
+                summary="Do the needful",
+                rrule={'FREQ': 'YEARLY'})
+
+            my_events = await cal.search(
+                event=True,
+                start=date(2026,5,1),
+                end=date(2026,6,1),
+                expand=True)
+
+            print(my_events[0].data)
+            #breakpoint()
+
+    asyncio.run(main())
+
+The ``expand``, ``event``, and other parameters work exactly as in the sync
+API.  See the sync tutorial for a full explanation of the search options.
+
+Investigating Events
+--------------------
+
+Use ``.data`` for raw icalendar data, or
+:meth:`~caldav.calendarobjectresource.CalendarObjectResource.get_icalendar_component`
+for convenient property access:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+    from datetime import datetime, date
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            await cal.add_event(
+                dtstart=datetime(2023,5,17,8),
+                dtend=datetime(2023,5,18,1),
+                uid="may17",
+                summary="Do the needful",
+                rrule={'FREQ': 'YEARLY'})
+
+            my_events = await cal.search(
+                event=True,
+                start=date(2026,5,1),
+                end=date(2026,6,1),
+                expand=True)
+
+            print(my_events[0].get_icalendar_component()['summary'])
+            print(my_events[0].get_icalendar_component().duration)
+            #breakpoint()
+
+    asyncio.run(main())
+
+The caveat about recurring events from the sync tutorial applies here too:
+``get_icalendar_component()`` is safe after an expanded search.
+
+Modifying Events
+----------------
+
+Replace the raw ``data`` string:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+    from datetime import date
+    import datetime
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            await cal.add_event(
+                dtstart=datetime.datetime(2023,5,17,8),
+                dtend=datetime.datetime(2023,5,18,1),
+                uid="may17",
+                summary="Do the needful",
+                rrule={'FREQ': 'YEARLY'})
+
+            my_events = await cal.search(
+                event=True,
+                start=date(2026,5,1),
+                end=date(2026,6,1),
+                expand=True)
+
+            my_events[0].data = my_events[0].data.replace("Do the needful", "Have fun!")
+            await my_events[0].save()
+            #breakpoint()
+
+    asyncio.run(main())
+
+Best practice is to use
+:meth:`~caldav.calendarobjectresource.CalendarObjectResource.edit_icalendar_component`:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+    from datetime import date
+    import datetime
+
+    async def main():
+        async with await aio.get_calendar() as cal:
+            await cal.add_event(
+                dtstart=datetime.datetime(2023,5,17,8),
+                dtend=datetime.datetime(2023,5,18,1),
+                uid="may17",
+                summary="Do the needful",
+                rrule={'FREQ': 'YEARLY'})
+
+            my_events = await cal.search(
+                event=True,
+                start=date(2026,5,1),
+                end=date(2026,6,1),
+                expand=True)
+
+            ## Edit the summary using the "borrowing pattern":
+            with my_events[0].edit_icalendar_component() as event_ical:
+                ## "component" is always safe after an expanded search
+                event_ical['summary'] = "Norwegian national day celebrations"
+            await my_events[0].save()
+
+            ## Let's take out the event again:
+            may17 = await cal.get_event_by_uid('may17')
+
+            ## Inspect may17 in a debug breakpoint
+            #breakpoint()
+
+    asyncio.run(main())
+
+Note that ``edit_icalendar_component()`` is a plain (synchronous) context
+manager — no ``await`` or ``async with`` needed there.
+
+Tasks
+-----
+
+Tasks work just like events, with ``await`` added:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+    from datetime import date
+
+    async def main():
+        client = await aio.get_async_davclient()
+        async with client:
+            my_principal = await client.get_principal()
+            ## This can be read as "create me a tasklist"
+            cal = await my_principal.make_calendar(
+                name="Test tasklist", supported_calendar_component_set=['VTODO'])
+            ## ... but for most servers it's an ordinary calendar!
+            await cal.add_todo(
+                summary="prepare for the Norwegian national day", due=date(2025,5,16))
+
+            my_tasks = await cal.search(todo=True)
+            assert len(my_tasks) == 1
+            await my_tasks[0].complete()
+            my_tasks = await cal.search(todo=True)
+            assert len(my_tasks) == 0
+            my_tasks = await cal.search(todo=True, include_completed=True)
+            assert my_tasks
+
+    asyncio.run(main())
+
+The :meth:`~caldav.calendarobjectresource.Todo.complete` method is awaitable in
+async mode.  See the sync tutorial for a note on tasklist vs calendar support
+differences between servers.
+
+Parallel Operations
+-------------------
+
+The main benefit of the async API is the ability to run multiple I/O operations
+*concurrently* using :func:`asyncio.gather`.  The following example fetches
+events from all calendars at the same time, instead of one by one:
+
+.. code-block:: python
+
+    import asyncio
+    from caldav import aio
+
+    async def main():
+        async with await aio.get_calendars() as calendars:
+            ## Kick off all searches in parallel, then collect the results
+            results = await asyncio.gather(
+                *[cal.search(event=True) for cal in calendars])
+
+            for cal, events in zip(calendars, results):
+                print(f"{await cal.get_display_name()}: {len(events)} event(s)")
+
+    asyncio.run(main())
+
+``asyncio.gather`` runs all the coroutines concurrently.  For a single server
+the speed gain is modest (one connection), but when talking to multiple servers
+or doing many independent fetches the difference can be significant.
+
+Further Reading
+---------------
+
+See the :ref:`examples:examples` folder for more code, including
+`async examples <https://github.com/python-caldav/caldav/blob/master/examples/async_usage_examples.py>`_
+and `sync examples <https://github.com/python-caldav/caldav/blob/master/examples/basic_usage_examples.py>`_
+for comparison.
+
+See :doc:`async` for the async API reference, including a migration guide from
+the sync API.
+
+The `integration tests <https://github.com/python-caldav/caldav/blob/master/tests/test_async_integration.py>`_
+cover most async features.

docs/source/index.rst

@@ -20,6 +20,7 @@ Contents
    about
    v3-migration
    tutorial
+   async_tutorial
    configfile
    async
    jmap

docs/source/tutorial.rst

@@ -11,8 +11,8 @@ imports.
 Go through the tutorial twice, first against a Xandikos test server,
 and then against a server of your own choice.
 
-This tutorial only covers the sync API.  The async API is quite
-similar.  A tutorial on the async API will come soon.
+This tutorial only covers the sync API.  See :doc:`async_tutorial` for the
+async equivalent.
 
 Ad-hoc Configuration
 --------------------