API changes in version 3.0?

[tobixen]

Creating a new issue to keep track of changes to be considered for upcoming major-releases. This top entry will be edited to reflect all significant changes planned. last update: 2025-12-05. (Perhaps it's about time to close this issue and make a new one? Perhaps the "GitHub Issue" model is not the best way of discussing API-changes?)

Backward compatibility plan

Generally, anything that is not deprecated in major verson (x-1) should still work in version x.

The plan is to introduce async support in 3.x. Async usage of the library will require changes in the user pattern - so it's the perfect timing for doing API-changes. The old sync way of doing things will be left unchanged, though some stuff deprecated in 2.x will be removed from 3.x.

In 2.0 a new function davclient.get_davclient was introduced. While the details may be discussed, my proposal is that the public usage of the API (as documented in the documentation and examples and docstrings) should always start with this method, never use any class constructors directly (exceptions may apply, like classes from the lib directory), everything should be available by utilizing method calls, starting with the DAVClient object returned from the get_davclient function.

API Changes

Everything should be looked through, all publicly available methods and classes should be reviewed. Only the methods that are useful for real-world use-case-scenarios should be included in the async API.

Some thoughts:

• We should (probably?) consistently use verbs for methods (like principal.get_calendar() rather than principal.calendar())
• Some places we use properties instead of methods. It should be well though through, when does it makes sense to use properties, and when does it make sense to use methods? At least usage of a property should (probably?( never cause any communication with the caldav server?
• There are calendars and calendar-like systems out there that doesn't support CalDAV. I'm also planning to make support for JMAP. I do have some long-term plans to perhaps make a separate "Python Calendar Client" library that would support various servers and not only CalDAV servers. This is something that should be kept in mind. Moving an application (like my plann utility) from the CalDAV library to the Calendar Client library should be trivial. Methods should contain as few caldav-specific parameters as possible. Perhaps the part of the API that is CalDAV-specific or DAV-specific should have names prefixed with caldav_ or dav_`?

[tobixen]

SEMVER states ...

If your software is being used in production, it should probably already be 1.0.0.
If you have a stable API on which users have come to depend, you should be 1.0.0.
If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

All three points apply, hence a 1.0-release is way overdue.

New tentative road map:

• There won't be any 0.12. There will be a 1.0.0.
• 1.0.0 will be fully backward-compatible with 0.11.
• Already in 0.11, I've marked up some stuff as DEPRECATED. This stuff will be abandoned as of a future 2.0.0-release (or perhaps 3.0.0 for important things like date_search )
• We will gradually think of what is sub-optimal with the API while working on the 1.x-series and perhaps make a new and better API available prior to a future 2.0.0-release.
• I will think out (or check out what others are using) some framework to warn when library users are using some deprecated API.

@cyrilrbt do you have any opinions?

[cyrilrbt]

It's always been my intention to align with semver so let's go for it!
This is a good idea, and it will be useful for future releases, go for it :)