I've already deprecated some parts of the API, and the long-term plan is to give the API a full overhaul.
Policy is that stuff that is marked as deprecated (i.e. in docstring) in one version series (i.e. 0.x) will remain available for one major release (1.x) and removed in the next (2.0) - and it's intended that a major release will be maintained at least for three years.
Whenever someone hits legacy API, warnings will be logged. I'm considering to increase the logging level, starting with WARNING and gradually increasing to CRITICAL when the removal of the legacy API is imminent.
However, this may cause a lot of noise in various logs - so we need a framework for muting it as well as a framework for rate-limiting (or ensuring that each warning is printed once and only once). It would also be useful to print a stack trace.
So in caldav/lib/error.py it's needed with a new function for logging a legacy warning. It should receive a message and a logging level (or possibly just the name of the function, and the rest can be stored internally in error.py). It should honor some environment variable that specifies how heavy the logging should be. By default it should log every unique message only once.
There are currently two deprecated methods, and both can be found by grepping for "DEPRECATION" ... and also one deprecated parameter, can also be found by grepping for DEPRECATED. There are also some new potentially unstable methods marked up that they may become DEPRECATED on short notice and may disappear in 2.0.
I've already deprecated some parts of the API, and the long-term plan is to give the API a full overhaul.
Policy is that stuff that is marked as deprecated (i.e. in docstring) in one version series (i.e. 0.x) will remain available for one major release (1.x) and removed in the next (2.0) - and it's intended that a major release will be maintained at least for three years.
Whenever someone hits legacy API, warnings will be logged. I'm considering to increase the logging level, starting with WARNING and gradually increasing to CRITICAL when the removal of the legacy API is imminent.
However, this may cause a lot of noise in various logs - so we need a framework for muting it as well as a framework for rate-limiting (or ensuring that each warning is printed once and only once). It would also be useful to print a stack trace.
So in
caldav/lib/error.pyit's needed with a new function for logging a legacy warning. It should receive a message and a logging level (or possibly just the name of the function, and the rest can be stored internally inerror.py). It should honor some environment variable that specifies how heavy the logging should be. By default it should log every unique message only once.There are currently two deprecated methods, and both can be found by grepping for "DEPRECATION" ... and also one deprecated parameter, can also be found by grepping for DEPRECATED. There are also some new potentially unstable methods marked up that they may become DEPRECATED on short notice and may disappear in 2.0.