docs: update docs/source for v3.0 API

tobixen · claude · tobixen · commit 5e48678e1f82 · 2026-03-07T21:25:29.000+01:00
- tutorial.rst: fix config file path (caldav.conf→calendar.conf), fix
  format (INI→YAML with caldav_ key prefix), use get_principal() instead
  of deprecated principal()
- async.rst: replace all uses of deprecated client.principal() with
  client.get_principal()
- about.rst: update backward-compat section for v3.0 release, fix Python
  minimum version (3.9→3.10), modernise test command (setup.py→pytest)
- configfile.rst: note get_calendar/get_calendars now exist; update
  calendar parameters section (no longer unimplemented)
- performance.rst: update niquests reference from "2.x" to "v3.x default"
- jmap.rst: fix typo "jap support" → "JMAP support"

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/source/about.rst b/docs/source/about.rst
@@ -32,28 +32,34 @@ icalendar data.
 Backward compatibility support
 ==============================
 
-The 1.x version series is intended to be maintained at least until
-2026-01.
+If you stumble upon problems and cannot easily resolve them, feel free
+to get in touch, i.e. by the issue tracker.
 
-The 2.x version series (not released as of 2025-06-01) is supposed to
-be fully backwards-compatible with version 1.x, and is intended to be
-maintained at least until 2027.
+The 1.x version series is not maintained anymore.
 
-2.0 sheds compatibility with python 3.7 and python 3.8, and one
-obscure deprecated method has been ripped out.
+If serious problems are found with v2.2.6 during 2026, v2.2.7 will be
+released.
 
-API that is marked as deprecated 2.x will most likely be removed in version 3.0
-If you have any suggestions on API-changes, please
-comment on https://github.com/python-caldav/caldav/issues/92
+The 3.x version series (released 2026-03) is almost
+backwards-compatible with version 2.x.  Python 3.10+ is required
+(Python 3.8 and 3.9 are no longer supported).  The
+``caldav/objects.py`` backward-compatibility shim has been removed;
+any code doing ``from caldav.objects import <something>`` must be
+updated to import directly from ``caldav``.  The wildcard import has
+also been removed, so if you were doing weird imports from ``caldav``,
+things may break.
 
-Warnings will be issued when using legacy interface.
+API deprecated with a warning in 2.x may be removed in a future 4.0 release.
+API deprecated without a warning in 2.x will get a deprecation warning in 4.0.
 
+If you have any suggestions on API-changes, please
+comment on https://github.com/python-caldav/caldav/issues/92
 
 Python compatibility notice
 ===========================
 
 Most of the code is regularly tested towards different versions of
-Python, the oldest being Python 3.9.
+Python, the oldest being Python 3.10 (as of v3.0).
 
 Support for Python2 was officially not supported starting from caldav
 version 1.0.
@@ -256,11 +262,12 @@ CalDAV URLs can be quite confusing, some software requires the URL to the calend
 Unit testing
 ============
 
-To start the tests code, install everything from the setup.tests_requires list and run:
+To run the tests, install the test dependencies and use pytest:
 
 .. code-block:: bash
 
-  $ python setup.py test
+  $ pip install -e ".[test]"
+  $ pytest
 
 tox should also work:
 
diff --git a/docs/source/async.rst b/docs/source/async.rst
@@ -21,7 +21,7 @@ The async API is available through the ``caldav.aio`` module:
 
     async def main():
         async with aio.get_async_davclient() as client:
-            principal = await client.principal()
+            principal = await client.get_principal()
             calendars = await principal.get_calendars()
             for cal in calendars:
                 print(f"Calendar: {cal.name}")
@@ -73,7 +73,7 @@ Example: Working with Calendars
 
     async def calendar_demo():
         async with aio.get_async_davclient() as client:
-            principal = await client.principal()
+            principal = await client.get_principal()
 
             # Create a new calendar
             my_calendar = await principal.make_calendar(
@@ -113,7 +113,7 @@ concurrently:
 
     async def fetch_all_events():
         async with aio.get_async_davclient() as client:
-            principal = await client.principal()
+            principal = await client.get_principal()
             calendars = await principal.get_calendars()
 
             # Fetch events from all calendars in parallel
@@ -158,12 +158,12 @@ The async API closely mirrors the sync API. Here are the key differences:
    .. code-block:: python
 
        # Sync
-       principal = client.principal()
+       principal = client.get_principal()
        calendars = principal.get_calendars()
        events = calendar.get_events()
 
        # Async
-       principal = await client.principal()
+       principal = await client.get_principal()
        calendars = await principal.get_calendars()
        events = await calendar.get_events()
 
@@ -187,7 +187,7 @@ All methods that perform I/O are ``async`` and must be awaited:
 
 **AsyncDAVClient:**
 
-* ``await client.principal()`` - Get the principal
+* ``await client.get_principal()`` - Get the principal
 * ``client.calendar(url=...)`` - Get a calendar by URL (no await, no I/O)
 
 **AsyncPrincipal:**
diff --git a/docs/source/configfile.rst b/docs/source/configfile.rst
@@ -3,7 +3,7 @@ Config file format
 ==================
 
 
-The :class:`davclient.get_davclient` method (and perhaps in 2.1, also ``davclient.get_calendar``) can read from a config file.  It will look for it in the following locations:
+The :func:`caldav.get_davclient`, :func:`caldav.get_calendar`, and :func:`caldav.get_calendars` functions can read from a config file.  It will look for it in the following locations:
 
 * ``$HOME/.config/caldav/calendar.conf``
 * ``$HOME/.config/caldav/calendar.yaml``
@@ -13,7 +13,7 @@ The :class:`davclient.get_davclient` method (and perhaps in 2.1, also ``davclien
 
 The config file has to be valid json or yaml (support for toml and Apple pkl may be considered).
 
-The config file is expected to be divided in sections, where each section can describe locations and credentials to a CalDAV server, a CalDAV calendar or a collection of calendars/servers.  As of version 2.0, only the first is supported.
+The config file is expected to be divided in sections, where each section can describe locations and credentials to a CalDAV server, a CalDAV calendar or a collection of calendars/servers.
 
 A config section can be given either through parameters to :func:`caldav.get_davclient` or by enviornment variable ``CALDAV_CONFIG_SECTION``.  If no section is given, the ``default`` section is used.
 
@@ -25,9 +25,8 @@ The section should contain configuration keys and values.  All configuration key
 Calendar parameters
 ===================
 
-Not implemented yet.
-
-Probably in version 2.1 or version 2.2, ``calendar_name``, ``calendar_id`` and ``calendar_url`` can be used to specify a calendar.
+The :func:`caldav.get_calendar` and :func:`caldav.get_calendars` functions accept
+``calendar_name`` and ``calendar_url`` parameters to select a specific calendar.
 
 Inheritance and collections
 ===========================
diff --git a/docs/source/jmap.rst b/docs/source/jmap.rst
@@ -2,7 +2,7 @@
 JMAP
 ====
 
-**The jap support in v3.0 is experimental, the API may change in v3.1 of the library**
+**The JMAP support in v3.0 is experimental, the API may change in v3.1 of the library**
 
 The caldav library includes a JMAP client for servers that speak
 `RFC 8620 <https://www.rfc-editor.org/rfc/rfc8620>`_ (JMAP Core) and
diff --git a/docs/source/performance.rst b/docs/source/performance.rst
@@ -2,11 +2,11 @@
 Performance
 ===========
 
-The current maintainer of the CalDAV library was born in an age where memory and CPU was limited resources.  CPU and memory comes cheaply today (read https://www.aardvark.co.nz/daily/2025/0611.shtml to see what I mean).  The CalDAV and iCalendar protocols weren't really written for lean computing in the first place.  If you need something that can run around on what used to be a bleeding edge supercomputer, you probably need to scrap those standards and write your own optimized calendaring standard and your own server and client for it - and this probably has to be done in C, not in Python.
+The current maintainer of the CalDAV library was born in an age where memory and CPU was limited resources.  CPU and memory comes cheaply today (read https://www.aardvark.co.nz/daily/2025/0611.shtml to see what I mean).  The CalDAV and iCalendar protocols weren't really written for lean computing in the first place.  If you need something that can run around on what used to be a bleeding edge supercomputer some decades ago, you probably need to scrap those standards and write your own optimized calendaring standard and your own server and client for it - and this probably has to be done in C, not in Python.
 
 Still, sometimes all the extra bloat I've added to the CalDAV library makes me cringe a bit.  If you have issues with performance, please reach out (see the :ref:`contact:contact` document).
 
 Some thoughts:
 
-* While CPU and memory comes cheaply today, latency is often a problem.  Creating server requests and particularly initiating TCP connections are typically costly.  There are a number of places in the code where it may be possible to reduce the number of requests.  As of 2.x, consider reading the top of the CHANGELOG - utilizing the niquests rather than requests library may possibly make the server communication more snappy.
+* While CPU and memory comes cheaply today, latency is often a problem.  Creating server requests and particularly initiating TCP connections are typically costly.  There are a number of places in the code where it may be possible to reduce the number of requests.  As of v3.x, **niquests** is used by default for HTTP communication, bringing HTTP/2 and HTTP/3 support, this should make things more snappy.  See the :doc:`http-libraries` document for details.  It's also possible to enable multiplexing by enabling `http.multiplexing` in the server `features` setting.  (it's disabled by default because a handful of servers out there can't handle the authentication if multiplexing is enabled)
 * In the early days almost all the necessary handling of icalendar data was done by accessing it as ``event.data``.  This may be the most efficient - but the ``vobject`` was also utilized.  Due to popular demand, plus the fact that ``vobject`` was not mainained for a while, ``icalendar`` took over.  I can imagine it does takes some CPU to convert the data between ical strings and instances.  This is done every time the data is accessed in a different format.  For performance reasons, I was initially not very happy to use the icalendar library for doing simple things like fetching the UID from an event - but I've come to think that this is necessary.  Now the problem is that every here and there there may still be some old code accessing ``event.data`` rather than ``event.icalendar_instance``.  This probably causes the burning of quite a lot of CPU cycles!
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
@@ -23,15 +23,16 @@ Real Configuration
 ------------------
 
 The recommended way to configure caldav is through a config file or
-environment variables. Create ``~/.config/caldav/caldav.conf``:
+environment variables. Create ``~/.config/caldav/calendar.conf``:
 
-.. code-block:: ini
+.. code-block:: yaml
 
-    # ~/.config/caldav/caldav.conf
-    [default]
-    url = https://caldav.example.com/
-    username = alice
-    password = secret
+    # ~/.config/caldav/calendar.conf
+    ---
+    default:
+        caldav_url: https://caldav.example.com/
+        caldav_username: alice
+        caldav_password: secret
 
 Or set environment variables:
 
@@ -62,7 +63,7 @@ Use :func:`caldav.get_calendars` to get all calendars or filter by name:
 
     # First create a calendar to work with
     with get_davclient() as client:
-        my_principal = client.principal()
+        my_principal = client.get_principal()
         my_principal.make_calendar(name="Work")
 
     # Get all calendars
