how to deal with deprecating API functionality in python module?

[Ben Finney]

Chris Angelico <rosuav at gmail.com> writes:

> 1) Keep deprecated APIs around for as long as you can, even if they're
> implemented messily on top of your current API.
>
> 2) Design your API with future-proofing in mind.

2.1) Have a generous deprecation schedule, and go to significant lengths
to ensure all developers using your library are aware of the schedule.
The PEP 4 <URL:http://www.python.org/dev/peps/pep-0004/> procedure for
deprecating Python standard library modules is a good example.

2.2) The schedule needs to spread over several versions; allow the
impending removal of the feature to be preceded by staged deprecation.
Use warnings (especially DeprecationWarning) to increase awareness of
the removal, and to gradually increase the effort needed to continue
using the feature anyway as its removal gets closer.

-- 
 \          “That's all very good in practice, but how does it work in |
  `\                                             *theory*?” —anonymous |
_o__)                                                                  |
Ben Finney