how to deal with deprecating API functionality in python module?

[Chris Angelico]

On Thu, Nov 21, 2013 at 11:02 AM, Chris Friesen
<chris.friesen at windriver.com> wrote:
> I'm pretty new to python, I'm trying to figure out how a python module is
> supposed to make non-backwards-compatible changes without blowing up the
> applications that use it.

First and foremost, the best way to break backward compatibility is to
not do so! Which means:

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.

3) Batch up all the compatibility-breaks into one big change.

Then, since #3 will be such a rare operation, you can just put it into
the file name. There's an "sqlite3" package which works with, well,
SQLite v3, I guess, and it's not compatible with version 2 which (I
think) was called just "sqlite". Ideally, you should be able to do
this seldom enough that your users won't have more than two "current
versions" to deal with at any given time (unless they're supporting
both RHEL and Ubuntu, in which case their tolerance for pain is to be
admired!).

You might be able to do some weird package magic so your users type:

import foo.v1  # Get the old API
import foo.v2  # Get the new API - will throw if you do both

But I'm not sure how you'd go about doing this cleanly, given that
it'd need to change which symbols get imported as "foo.bar" etc. At
best, you could certainly do:

import foo1 as foo # Get the old API
import foo2 as foo # Get the new API

which is pretty much how a lot of Py2/Py3 compatibility code works.
But again, you want to do this as rarely as possible.

Of course, backward-compatible API changes (new APIs and such) can
easily be signalled with a version tuple, as Ben mentioned. Two apps
can demand different minimums and be satisfied by the same current
version. That's the easy bit!

ChrisA