API changes in version 2.0 and 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.

Version 1, 2, 3, ...

Version 1.0 was released mostly because a 1.0-release was "long overdue". Some few things were deprecated, and Python 2 was officially not supported anymore.

Version 2.0 will be released to unsupport python 3.7 (and possibly python 3.8). Some thoughts should be made on weather we'd like to deprecate older parts of the API while doing so. Things that are already deprecated should be gutted away.

I've long had an idea to do a major rewrite of the API, possibly that will be done in 3.0.

Backward compatibility plan

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

I'm considering a major overhaul of the API, assumed to happen in version 3.0. My suggestion is that the proper usage of 3.0 is to start with something like this:

from caldav import CalDAVClient
client = CalDAVClient(**connection_arguments)
principal = client.get_principal()

and then everything should be doable starting with the objects client or principal. In version 3.0, caldav/caldav/__init__.py will be trimmed to only reveal the CalDAVClient. All operations starting with CalDAVClient will results in objects/classes supporting the 2.0-API. For the classes where the API is changed, we'll create a new class with a class name ending with "NG" (new generation), inheritate the old class, and do the needed changes. In version 4.0 we'll refactor and remove the NG-cruft.

In 3.0, DAVClient will be a class for backward-compatibility with version 2.x. In version 4.0 we should consider to split out DAV-support to a separate davclient-module.

API Changes

• some_obj.instance is deprecated in v1.0, new methods some_obj.icalendar_instance and some_obj.vobject_instance (as well as some_obj.icalendar_component). Will be dropped in v2.0
• In v2.0, client side expansion of recurring events/tasks will be the default, with optional server-side expansion in the search method
• Think through properties vs methods, and be more consistent. Use verbs for all methods? Like principal.get_calendar(), client.get_principal(), etc. Properties should probably never cause any communication towards the calendar server. Access of properties should probably never cause side effects (the current instance and data properties may have side effects).

[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 :)

[tobixen]

It may be needed with a 2.0-release relatively soon due to pull request #437.