Playground/new async api design

.github/workflows/linkcheck.yml

@@ -0,0 +1,18 @@
+name: Link check
+
+on: [push, pull_request]
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Check links with Lychee
+      uses: lycheeverse/lychee-action@v2
+      with:
+        fail: true
+        args: >-
+          --timeout 10
+          --max-retries 2
+          '**/*.md'
+          '**/*.rst'

.github/workflows/tests.yaml

@@ -144,7 +144,7 @@ jobs:
           docker exec ${{ job.services.nextcloud.id }} php occ app:disable password_policy || true
 
           # Create test user
-          docker exec -e OC_PASS="TestPassword123!" ${{ job.services.nextcloud.id }} php occ user:add --password-from-env --display-name="Test User" testuser || echo "User may already exist"
+          docker exec -e OC_PASS="testpass" ${{ job.services.nextcloud.id }} php occ user:add --password-from-env --display-name="Test User" testuser || echo "User may already exist"
 
           # Enable calendar and contacts apps
           docker exec ${{ job.services.nextcloud.id }} php occ app:enable calendar || true
@@ -313,3 +313,39 @@ jobs:
           key: pre-commit|${{ hashFiles('.pre-commit-config.yaml') }}
       - run: pip install tox
       - run: tox -e style
+  deptry:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip|${{ hashFiles('setup.py') }}|${{ hashFiles('tox.ini') }}
+      - run: pip install tox
+      - run: tox -e deptry
+  async-niquests:
+    # Test that async code works with niquests when httpx is not installed
+    name: async (niquests fallback)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies without httpx
+        run: |
+          pip install --editable .[test]
+          pip uninstall -y httpx
+      - name: Verify niquests is used
+        run: |
+          python -c "
+          from caldav.async_davclient import _USE_HTTPX, _USE_NIQUESTS
+          assert not _USE_HTTPX, 'httpx should not be available'
+          assert _USE_NIQUESTS, 'niquests should be used'
+          print('✓ Using niquests for async HTTP')
+          "
+      - name: Run async tests with niquests
+        run: pytest tests/test_async_davclient.py -v

.lycheeignore

@@ -0,0 +1,20 @@
+# Example domains that don't resolve
+https?://your\.server\.example\.com/.*
+https?://.*\.example\.com/.*
+
+# Localhost URLs for test servers (not accessible in CI)
+http://localhost:\d+/.*
+
+# CalDAV endpoints that require authentication (401/403 expected)
+https://caldav\.fastmail\.com/.*
+https://caldav\.gmx\.net/.*
+https://caldav\.icloud\.com/.*
+https://p\d+-caldav\.icloud\.com/.*
+https://posteo\.de:\d+/.*
+https://purelymail\.com/.*
+https://webmail\.all-inkl\.com/.*
+https://www\.google\.com/calendar/dav/.*
+https://caldav-jp\.larksuite\.com/.*
+
+# Apple namespace URL (returns 404 but is a valid XML namespace reference)
+http://apple\.com/ns/ical/

.pre-commit-config.yaml

@@ -14,3 +14,9 @@ repos:
       - id: check-byte-order-marker
       - id: trailing-whitespace
       - id: end-of-file-fixer
+  - repo: https://github.com/lycheeverse/lychee
+    rev: lychee-v0.22.0
+    hooks:
+      - id: lychee-docker
+        args: ["--no-progress", "--timeout", "10"]
+        types: [markdown, rst]

AI_POLICY.md → AI-POLICY.md

@@ -63,11 +63,10 @@ experiences is that the AI performs best when being "supervised" and
   <noreply@anthropic.com>` when it's doing commits, that's also OK.
 
 * **YOU** should be ready to follow up and respond to feedback and
-  questions on the contribution.  If all you do is to relay it to the
-  AI and relaying the AI output back to the pull request, then
-  you're not adding value to the project and you're not transparent
-  and honest.  You should at least do a quick QA on the AI-answer and
-  acknowledge that it was generated by the AI.
+  questions on the contribution.  If you're letting the AI do this for
+  you, then you're neither honest nor adding value to the project.
+  You should at least do a quick QA on the AI-answer and acknowledge
+  that it was generated by the AI.
 
 * The Contributors Guidelines aren't strongly enforced on this project
   as of 2025-12, and I can hardly see cases where the AI would break

CHANGELOG.md

@@ -16,6 +16,13 @@ Changelogs prior to v1.2 is pruned, but available in the v1.2 release
 
 This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), though some earlier releases may be incompatible with the SemVer standard.
 
+## [Unreleased]
+
+### Added
+
+* Added deptry for dependency verification in CI
+* Added python-dateutil and PyYAML as explicit dependencies (were transitive)
+
 ## [2.2.3] - [2025-12-06]
 
 ### Fixed
@@ -440,7 +447,7 @@ Since the roadmap was made, the maintainer has spent 39 hours working on the Cal
 * Search method has some logic handling non-conformant servers (loading data from the server if the search response didn't include the icalendar data, ignoring trash from the Google server when it returns data without a VTODO/VEVENT/VJOURNAL component), but it was inside an if-statement and applied only if Expanded-flag was set to True.  Moved the logic out of the if, so it always applies.
 * Revisited a problem that Google sometimes delivers junk when doing searches - credits to github user @zhwei in https://github.com/python-caldav/caldav/pull/366
 * There were some compatibility-logic loading objects if the server does not deliver icalendar data (as it's suppsoed to do according to the RFC), but only if passing the `expand`-flag to the `search`-method.  Fixed that it loads regardless of weather `expand` is set or not.  Also in https://github.com/python-caldav/caldav/pull/366
-* Tests - lots of work getting as much test code as possible to pass on different servers, and now testing also for Python 3.12 - ref https://github.com/python-caldav/caldav/pull/368 https://github.com/python-caldav/caldav/issues/360 https://github.com/python-caldav/caldav/pull/447 https://github.com/python-caldav/caldav/pull/369 https://github.com/python-caldav/caldav/pull/370  https://github.com/python-caldav/caldav/pull/441 https://github.com/python-caldav/caldav/pull/443a
+* Tests - lots of work getting as much test code as possible to pass on different servers, and now testing also for Python 3.12 - ref https://github.com/python-caldav/caldav/pull/368 https://github.com/python-caldav/caldav/issues/360 https://github.com/python-caldav/caldav/pull/447 https://github.com/python-caldav/caldav/pull/369 https://github.com/python-caldav/caldav/pull/370  https://github.com/python-caldav/caldav/pull/441 https://github.com/python-caldav/caldav/pull/443
 * The vcal fixup method was converting implicit dates into timestamps in the COMPLETED property, as it should be a timestamp according to the RFC - however, the regexp failed on explicit dates.  Now it will take explicit dates too.  https://github.com/python-caldav/caldav/pull/387
 * Code cleanups and modernizing the code - https://github.com/python-caldav/caldav/pull/404 https://github.com/python-caldav/caldav/pull/405 https://github.com/python-caldav/caldav/pull/406 https://github.com/python-caldav/caldav/pull/407 https://github.com/python-caldav/caldav/pull/408 https://github.com/python-caldav/caldav/pull/409 https://github.com/python-caldav/caldav/pull/412 https://github.com/python-caldav/caldav/pull/414 https://github.com/python-caldav/caldav/pull/415 https://github.com/python-caldav/caldav/pull/418 https://github.com/python-caldav/caldav/pull/419 https://github.com/python-caldav/caldav/pull/417 https://github.com/python-caldav/caldav/pull/421 https://github.com/python-caldav/caldav/pull/423 https://github.com/python-caldav/caldav/pull/430 https://github.com/python-caldav/caldav/pull/431 https://github.com/python-caldav/caldav/pull/440 https://github.com/python-caldav/caldav/pull/365
 * Doc - improved examples, https://github.com/python-caldav/caldav/pull/427

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Contributions are mostly welcome.  If the length of this text scares you, then I
 
 ## Usage of AI and other tools
 
-A separate [AI POLICY](AI_POLICY.md) has been made.  The gist of it, be transparent and inform if your contribution was a result of clever tool usage and/or AI-usage, don't submit code if you don't understand the code yourself, and you are supposed to contribute value to the project.  If you're too lazy to read the AI Policy, then at least have a chat with the AI to work out if your contribution is within the policy or not.
+A separate [AI POLICY](AI-POLICY.md) has been made.  The gist of it, be transparent and inform if your contribution was a result of clever tool usage and/or AI-usage, don't submit code if you don't understand the code yourself, and you are supposed to contribute value to the project.  If you're too lazy to read the AI Policy, then at least have a chat with the AI to work out if your contribution is within the policy or not.
 
 ## GitHub
 

README.md

@@ -7,9 +7,40 @@ Features:
  * create, modify calendar
  * create, update and delete event
  * search events by dates
+ * async support via `caldav.aio` module
  * etc.
 
-The documentation was freshed up a bit as of version 2.0, and is available at https://caldav.readthedocs.io/
+## Quick Start
+
+```python
+from caldav import get_davclient
+
+with get_davclient() as client:
+    principal = client.principal()
+    calendars = principal.calendars()
+    for cal in calendars:
+        print(f"Calendar: {cal.name}")
+```
+
+## Async API
+
+For async/await support, use the `caldav.aio` module:
+
+```python
+import asyncio
+from caldav import aio
+
+async def main():
+    async with aio.get_async_davclient() as client:
+        principal = await client.principal()
+        calendars = await principal.calendars()
+        for cal in calendars:
+            print(f"Calendar: {cal.name}")
+
+asyncio.run(main())
+```
+
+The documentation was updated as of version 2.0, and is available at https://caldav.readthedocs.io/
 
 The package is published at [Pypi](https://pypi.org/project/caldav)
 

caldav/__init__.py

@@ -10,7 +10,7 @@
     warnings.warn(
         "You need to install the `build` package and do a `python -m build` to get caldav.__version__ set correctly"
     )
-from .davclient import DAVClient
+from .davclient import DAVClient, get_davclient
 from .search import CalDAVSearcher
 
 ## TODO: this should go away in some future version of the library.
@@ -29,4 +29,4 @@ def emit(self, record) -> None:
 
 log.addHandler(NullHandler())
 
-__all__ = ["__version__", "DAVClient"]
+__all__ = ["__version__", "DAVClient", "get_davclient"]

caldav/aio.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+"""
+Async-first CalDAV API.
+
+This module provides async versions of the CalDAV client and objects.
+Use this for new async code:
+
+    from caldav import aio
+
+    async with aio.AsyncDAVClient(url=..., username=..., password=...) as client:
+        principal = await client.get_principal()
+        calendars = await principal.calendars()
+        for cal in calendars:
+            events = await cal.events()
+
+For backward-compatible sync code, continue using:
+
+    from caldav import DAVClient
+
+Note: As of the Sans-I/O refactoring (Phase 9), the domain objects (Calendar,
+Principal, Event, etc.) are now dual-mode - they work with both sync and async
+clients. When used with AsyncDAVClient, methods like calendars(), events(), etc.
+return coroutines that must be awaited.
+
+The Async* aliases are kept for backward compatibility but now point to the
+unified dual-mode classes.
+"""
+# Import the async client (this is truly async)
+from caldav.async_davclient import AsyncDAVClient
+from caldav.async_davclient import AsyncDAVResponse
+from caldav.async_davclient import get_davclient as get_async_davclient
+from caldav.calendarobjectresource import CalendarObjectResource
+from caldav.calendarobjectresource import Event
+from caldav.calendarobjectresource import FreeBusy
+from caldav.calendarobjectresource import Journal
+from caldav.calendarobjectresource import Todo
+from caldav.collection import Calendar
+from caldav.collection import CalendarSet
+from caldav.collection import Principal
+from caldav.collection import ScheduleInbox
+from caldav.collection import ScheduleMailbox
+from caldav.collection import ScheduleOutbox
+from caldav.davobject import DAVObject
+
+# Import unified dual-mode domain classes
+
+# Create aliases for backward compatibility with code using Async* names
+AsyncDAVObject = DAVObject
+AsyncCalendarObjectResource = CalendarObjectResource
+AsyncEvent = Event
+AsyncTodo = Todo
+AsyncJournal = Journal
+AsyncFreeBusy = FreeBusy
+AsyncCalendar = Calendar
+AsyncCalendarSet = CalendarSet
+AsyncPrincipal = Principal
+AsyncScheduleMailbox = ScheduleMailbox
+AsyncScheduleInbox = ScheduleInbox
+AsyncScheduleOutbox = ScheduleOutbox
+
+__all__ = [
+    # Client
+    "AsyncDAVClient",
+    "AsyncDAVResponse",
+    "get_async_davclient",
+    # Base objects (unified dual-mode)
+    "DAVObject",
+    "CalendarObjectResource",
+    # Calendar object types (unified dual-mode)
+    "Event",
+    "Todo",
+    "Journal",
+    "FreeBusy",
+    # Collections (unified dual-mode)
+    "Calendar",
+    "CalendarSet",
+    "Principal",
+    # Scheduling (RFC6638)
+    "ScheduleMailbox",
+    "ScheduleInbox",
+    "ScheduleOutbox",
+    # Legacy aliases for backward compatibility
+    "AsyncDAVObject",
+    "AsyncCalendarObjectResource",
+    "AsyncEvent",
+    "AsyncTodo",
+    "AsyncJournal",
+    "AsyncFreeBusy",
+    "AsyncCalendar",
+    "AsyncCalendarSet",
+    "AsyncPrincipal",
+    "AsyncScheduleMailbox",
+    "AsyncScheduleInbox",
+    "AsyncScheduleOutbox",
+]