Roadmap 2025/2026

[tobixen]

Note: Roadmap updates in #599

Python CalDAV Client Library - Roadmap

Hopefully I will have some time to work on the Python CalDAV library in the upcoming months. I'm now trying to make this "super issue" to prioritize the outstanding work, throw some estimates on the work tasks and break down the projects.

Summary first

Estimated outstanding work:

• Close outstanding pull requests - 12h
• Outstanding issues slated for v1.5 - 8h
• Outstanding issues slated for v1.6 - 12h
• Documentation work - 20h
• Server checker and server compatibility hints project - 28h
• Outstanding issues slated for v2.0 - 23h
• New interface + asyncio projects - 50h
• Outstanding issues slated for v3.0 - 12h
• Maintain and expand the test server list - 8h
• JMAP project - 40h

I do believe I can manage to contribute somewhere between 5 and 30 hours per month to the caldav project over the upcoming year. That's between 60 and 360 hours. In the very best scenario it will be possible to get everything above done. Most likely something has to go out, most likely many outstanding issues slated for v1.5 will be procrastinated, same with the JMAP project and quite some of the v2.0-issues.

This being open source, I'm not doing everything alone, there is a steady stream of contributions from other contributors ticking in - but most of those contributions are related to new issues - unknown bugs and features I haven't thought about. Generally community contributions improve the overall quality of the project, but contributes negatively to the roadmap progress. Most reported issues comes iwthout pull-requests, even when there are pull-requests it takes some time to do QA on the contributions, add missing test code, documentation and changelog entries.

Funding

This aggressive roadmap was made possible due tofunding through NGI Zero Core, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program, as a part of the OpenWebCalendar project. Learn more at the NLnet project page.

The higher goals

For all work that is done, it's important to consider if it's bringing the project in the right direction or not, defined as such:

• The library should offer high-level easy-to-use methods for doing interaction with CalDAV servers (but it should also offer lower-level methods).
• The library should just work - with a bare minimum of configuration (but it should also be possible to do advanced configuration).
• The high-level methods should be accessible for people who know nothing about the CalDAV standard nor the iCalendar standard (while the low-level methods should give power-users unlimited possibilities).
• The CalDAV standard is currently the only widely adopted standard for calendar access, though it's not a very good standard - when newer standards are evolving, the scope for the library may change.
• The library should work consistently towards different server implementations

Outstanding pull requests

It's important to get done with some pull requests - many of them is work that I've started on and got partly or mostly done, but I never had time to complete it. Some of it may be considered "low hanging fruit" as most or parts of the work is already done.

• Support for alarms - several users have requested better support for alarms. Work has been done to make high-level interface for creating events with alarms and searching for events based on alarms, but the functional tests were procrastinated as the test servers didn't support alarms. Functionality for "find the next upcoming alarms" is also missing. Estimate: 4h
• Relationship validation - While the RFCs says nothing about it, I believe it's good practice to have a two-way linking in the RELATED-TO-property (if a "child" is pointing to a "parent", the "parent" should point back to the child). The pull request should allow going through all events in the calendar and verify that no such links are missing, as well as fix missing links. Estimate: 3h
• Repairing the Readthedocs sync - https://caldav.readthedocs.io/en/latest/ is stuck on 1.3.6, while the latest release is 1.4, I need to figure out what's the problem here, fix it and verify that things are working. Estimate: 2h.
• Compatibility workaround: Accept XML content from calendar server even if it's marked up with content-type text/plain. Estimate: 1h
• Server checker - this is part of the "server compatibility hints"-project, more information below.
• Code cleanup - Estimate: 2h

Outstanding issues not related to the projects

I try to prioritize the issues in the github tracker by using the "milestone" concept. The milestones correspond to some future release. It's a very optimistic estimate on what release the issue will be fixed in, so in the end I freqeuently push the milestone target.

1.5 milestone

• authentication header is case sensitive. #458 - case sensitivity in http headers - Estimate: 1h
• Look into declarative configuration #262 - look once more into setup.py vs pyproject.toml etc - Estimate: 2h
• calendar.search(journal=True) should work #237 - search for journals - Estimate: 1h
• Test code for multiget; date_search to optionally do a multiget #115 - multiget - Estimate: 1h
• CalDAV-Error due to a location #151 - Some Apple problems - Estimate: 1h
• .netrc should not be honored if username and password is given to the client #206 - trouble with .netrc - Estimate: 1h
• caldav + homeassistant + gmx -> "path handling problem" #309 - trouble with GMX - Estimate: 2h
• Warning server path handling problem using Nextcloud #330 - another path handling problem - Estimate: 1h

New "bonus issues" not included in the original roadmap:

• Robur issue with testCreateOverwriteDeleteEvent #491 - Robur issues encountered while verifying the 1.5-release
• NotImplementedError: The server does not provide any of the currently supported authentication methods: basic, digest, bearer #479 - Logging into a server with an empty password should work
• Unable to fetch recurring todos from Nextcloud server 31.0.5 #495 - problems with recurring tasks
• radicale tests, another attempt on fixup #480 - reenabling functional tests towards internal radicale server
• Refactor - split objects.py into smaller files #483 - code refactoring
• Refactor compatibility issues #484 - preparations for the server checker project
• Pre-release v1.5 fixes #492 - various pre-release 1.5 fixes (resolving issues with broken functional tests towards some of my testing servers, CHANGELOG, etc)
• Adding a Code of Conduct #494 - adding a Code of Conduct

1.6 milestone

Those items were originally included in the 1.5-milestone. I expected it would take me too long time to get through this list, hence I procrastinated those and released 1.5. In the end it took me less time than expected, and 1.6 was released just some few days after 1.5.

• Scheduling support (RFC6638) #125 - RFC6638 support - Estimate: 4h
• Exception thrown in tentatively_accept_invite() #163 - Exception thrown in tentatively_accept_invite - Estimate: 2h
• set_dtend is missing #356 - a missing method - Estimate: 2h
• Edit a single occurence of a recurrent event #379 - Edit a single occurence of a recurrent event - Estimate: 2h
• Verify that there are no internal dependencies on vobject #476 - Verify that there are no internal dependencies on vobject - Estimate: 1h
• Assertion Error with Fastmail #478 - problem with Fastmail - Estimate: 1h

2.0 milestone

• How are proxy variables handled? #462 - better support for proxying, better tests, better doc - Estimate: 3h
• Increase test coverage #93 - increase test coverage, again - Estimate: 4h
• Tests - should be easier to run them towards private calendar servers #99 - documentation and refactoring of test runs - Estimate: 1h
• Clean up CalendarObjectResource._create #96 - refactoring - Estimate: 2h
• Search for calendars owned by other principals #131 - cross-principal calendar search - Estimate: 4h
• set_relation reltype can be ignored because of type(uid)==icalendar.vText #334 - some missing test code - Estimate: 1h
• 507 error during collection sync #340 - google compatibility - Estimate: 2h - procrasting this as I will be working with Google calendar server on a later stage
• test_create_ical can be flaky on Python 3.12 #380 - intermedient test problem - Estimate: 1h
• Recurrence instances gets stripped when doing cal.object_by_uid(uid,comp_class=caldav.Event) #397 - Recurrence instances gets stripped when doing cal.object_by_uid(uid,comp_class=caldav.Event) - Estimate: 2h
• Test fails against radicale #439 - Test fails against radicale - Estimate: 2h
• Shred the vobject-dependency #477 - Deprecation warnings on vobject - Estimate: 1h

3.0 milestone

• Server says "Forbidden" when creating event with timezone #372 - timezones problem - Estimate: 5h
• Improvements, test code and documentation needed for editing and selecting recurrence instances #398 - look more into recurrences - Estimate: 5h
• Problem with accept invite in calendar #399 - problems with accept_invite at some servers - Estimate: 2h
• 507 error during collection sync #340 - some Google compatibility problem

Later

• How to handle deletion of a recurrence? #35
• Collission avoidance #152
• Support RFC 7953 Availability #425
• Depend on deprecated vobject #420

Documentation work

The documentation is not much good nor intuitive for new users. People are encouraged to check some example code inside the repository, but this example code is not tested regularly. The code should be embedded in the documentation and executed by the test suite.

Original plan:

• Make a way to embed code in the documentation and have it executed by functional tests. Estimate: 2h
• Move the existing example code into documentation and improve it (I changed my mind. Example doc has been brushed up a bit, some of it is now covered by unit tests, and it's listed and commented in the documentation) Estimate: 3h
• Look through the documentation, reorganize it, write more and better doc. Estimate: 6h
• Look through all the outstanding documentation issues. Estimate: 3h
• Update the documentation again, after fixing all other issues mentioned here. Estimate: 4h

Revised plan:

• Consider Dietaxis
  • Make a tutorial
  • Make some how-tos - procrastinated and split out into a new issue Documentation howtos #513
  • Make a reference
  • Make some explanations
• Consider manuel
  • Set up tests
• Consider https://pydata-sphinx-theme.readthedocs.io/en/stable/
• Consider making things slightly similar to how things are done at the iCalendar doc
• Consider what to do with the examples. As a bare minimum, they have to be executed by the test framework
• Look through the documentation again and see if there are any improval points

Related issues and pull requests

• Finding caldav parameters through config files, environmental variables or others #485
• Tests - should improve readability #100
• Support for bearer authentication #119
• Documentation for each server/cloud provider #120
• The new event.icalendar_component property needs doc and example code #239
• Possible arguments to calendar.save_event() and calendar.search() is poorly documented #253
• QA on the basic_usage_examples.py needed #256
• Basic example code - improve the code dealing with tasks #269
• Google calendar - make authentication simpler and document it #311

Project: Server compatibility hints

There is a jungle of calendar servers out there, the RFCs are sometimes ambiguous, and quite a lot in the RFCs is optional to implement. Ideally, a python program using the caldav library should behave the same even if the calendar servers behaves differently - for instance, if the calendar server does not support search, the search operation may work by downloading the whole calendar and do a client-side search. A side-project (and requisite) here is a server-checker script that may run various tests towards a calendar server to check for compatibility issues. The server checker script is partially done, but got derailed due to lack of time.

Subtasks

• The current "quick list" is a mess and needs to be cleanded up and reorganized. After doing that, the functional tests and the server checker script must be rewritten to comply with the new list. Estimate: 5h
• The server checker script needs to be refactored - currently it's only possible to run all checks or nothing, it should be possible to check one quirk without running the full test suite. This is slightly non-trivial as the current script sometimes needs data from one quirk test run before it can run another quirk test. Estimate: 6h
• The server configuration for caldav should be improved
  • In "auto-mode" (default) the client should do a quick effort on figuring out compatibility quirks, guessing the correct URL, etc. Estimate: 2h
  • In "probe-mode", the client should do extensive probing to figure out of things. Estimate: 2h
  • In "manual" mode, the client should assume the configuration it gets is correct.
  • It should accept a parameter telling it what kind of server is in use ... i.e. server_impementation=nextcloud and it would know that all nextcloud-quirks should be applied. It's complicated as version numbers also has to be taken into consideration. Alternatively, it should be possible to pass a complete quirk-list. Estimate: 3h
  • It should be possible to configure some few other things. Estimate: 1h
    • Is it allowed to download the full calendar i.e. to do a client text search?
    • If an operation is known to fail due to the quirk-list, should the server raise an error, or should it try anyway?
    • Should we do work-arounds to ensure consistency across different calendar servers? (this may break consistency towards elder versions of the library)
    • ... probably more options as well ..
  • Now that we have a quirk-list, it should be utilized:
    • Try to identify all the points in the code where we should do differently dependent on the quirk list and configuration. Estimate: 3h
    • Try to mitigate as many of the quirks as possible, and raise errors when the server does not support the operation. Estimate: 6h

Related issues and pull requests

• Server checker #451
• Try out paths to find caldav base URL #463
• Server compatibility hints #402
• Support for rfc6764 - find CalDAV URL through DNS lookup #102
• Make workarounds for servers that does not support sync_token properly #183
• Nextcloud objects with SyncToken - Teapot status code for deleted events #203
• calendar.search-method with timestamp filters yielding too much #351
• Some server needs explicit event or task when doing search #401

Project: New interface

The current interface has grown organically and without much thought. Method names are inconsistent, the workflow is inconsistent, in some places a property is in use while other places a method is in use. The library was also made back when "Python 3k" was a long-in-the-future project, and while async operation meant one would have to understand the twisted "Twisted" framework. I think it may be useful to think through things and make a new application interface from scratch. I deem backward compatibility high, so the new and old application interface will live side by side (but eventually with deprecation warnings) for a while. This involves quite a lot of thinking and documentation, some refactoring of current code, but should not involve duplicating code nor "writing things from scratch".

This should be done a bit in lockstep with the asyncio project. One idea may be to create the new interface for async usage and leave the old interface for sync usage. The estimate is set low because much of the actual work is done in the asyncio project.

Estimate: 10h

Related issues and pull requests

• API changes in version 3.0? #92
• DAVObject.name should probably go away #128
• Some servers may not support current-user-principal #180
• Create an CalendarObjectResource.icalendar_component property #232
• Framework for logging legacy warnings (particularly date_search) #240

Project: asyncio

Modern Python applications should work asynchronously.

I haven't thought much about how to achieve this - but I give a very rough estimate that it will take me one working week to figure it out and implement it.

Estimate: 40h

Related issues and pull requests

• need support asyncio #342
• use niquests #455
• Replace requests with niquests or httpx? #457

Project: JMAP

JMAP is a new email protocol intended to replace IMAP - at FOSSDEM 2025 it appeared that both server developers and client developers found it superior compared to IMAP. The JMAP protocol also supports the exchange of calendaring data.

I think it would be nice with a library where the high-level methods would work seamlessly for the end user no matter if the CalDAV protocol or the JMAP protocol is used. The first step of this project would be to investigate if this is at all possible - if not, we may need to make changes to the high-level API.

Supporting JMAP may not be intuitive considering the naming of the library, but it may be important for future-proofing the library.

It's prerequisite to find calendar servers supporting JMAP for testing.

Related issues and pull requests

• implement support for JMAP protocol #424

Estimate: 40h

Increase the list of test servers

This involves signing up at different cloud providers, begging for test accounts from people who are running calendar servers, setting up my own self-hosted servers, etc. Trying to keep an overview at #45 and in my own private config file.

Estimate: 8h

[stevepiercy]

@tobixen here's a collection of links from our discussion.

• https://github.com/plone/plone.api - Uses manuel to test documentation examples in your narrative documentation, ensuring they actually do what you expect. See the plone.api documentation for how to Add a function to an existing module.
• https://github.com/plone/plone.restapi/ - Uses https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/ and https://sphinxcontrib-httpexample.readthedocs.io/en/latest/ to generate examples of HTTP requests and responses using various libraries. Example: https://6.docs.plone.org/plone.restapi/docs/source/endpoints/addons.html. How to Generate documentation examples.
• Diátaxis a framework to guide you to organize your thoughts and documentation. The author leads the documentation team at Canonical, which releases Ubuntu, and has adopted by the core Python team and other Python communities. Plone is also moving toward this framework.
• Triple D: Documentation Driven Development - A Panel Discussion - a demonstration video of a batteries-included documentation scaffold generator using Cookieplone.
• PyData Sphinx Theme - A clean and well-structured Sphinx theme that is mobile-first and comes with accessibility features.
• Bonus: Plone uses MyST syntax, which combines the richness of reStructuredText with the ease of Markdown. I find it helps me stay in the flow of authoring documentation.

I'm happy to help out with documentation. Please let me know. Thank you!

[tobixen]

41 hours spent on the caldav library since 1.6 was released, and I'm probably three-four working hours away from releasing 2.0. That's a relatively good estimate.

[tobixen]

Marking this "meta issue" as closed, as most of the work is done and the remaining work is pushed to #599