Path: csiph.com!newsfeed.hal-mli.net!feeder3.hal-mli.net!newsfeed.hal-mli.net!feeder1.hal-mli.net!newsfeed.xs4all.nl!newsfeed1.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.000
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'warnings': 0.04; 'api.': 0.05; '(especially': 0.07; 'practice,': 0.07; 'apis': 0.09; 'deprecated': 0.09; 'generous': 0.09; 'pep': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'schedule,': 0.09; 'subject:module': 0.09; 'subject:skip:f 10': 0.09; 'api': 0.11; 'python': 0.11; 'anyway': 0.14; 'deprecation': 0.16; 'finney': 0.16; 'lengths': 0.16; 'preceded': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'removal,': 0.16; 'subject:API': 0.16; 'url:peps': 0.16; 'subject:python': 0.16; 'library': 0.18; 'spread': 0.22; 'header :User-Agent:1': 0.23; 'example.': 0.24; 'mind.': 0.24; 'url:dev': 0.24; 'developers': 0.25; 'gets': 0.27; 'header:X-Complaints- To:1': 0.27; 'chris': 0.29; 'feature': 0.29; 'writes:': 0.31; 'url:python': 0.33; 'implemented': 0.33; 'subject:with': 0.35; 'but': 0.35; 'subject:?': 0.36; 'url:org': 0.36; 'effort': 0.37; 'ben': 0.38; 'needed': 0.38; 'to:addr:python-list': 0.38; 'does': 0.39; 'to:addr:python.org': 0.39; 'received:org': 0.40; 'how': 0.40; 'ensure': 0.60; 'even': 0.60; 'removal': 0.74; 'increase': 0.74; 'closer.': 0.91
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Ben Finney <ben+python@benfinney.id.au>
Subject: Re: how to deal with deprecating API functionality in python module?
Date: Fri, 22 Nov 2013 10:56:59 +1100
References: <528D4D96.6010301@windriver.com> <CAPTjJmoe7S9sF=+1zMUw+zbqupLb-gBd-R0Up1YLLNyYF-Dz5A@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Gmane-NNTP-Posting-Host: rasputin.madmonks.org
X-Public-Key-ID: 0xAC128405
X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35  4855 B8B2 4C06 AC12 8405
X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-gpg.asc
X-Post-From: Ben Finney <bignose+hates-spam@benfinney.id.au>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux)
Cancel-Lock: sha1:+4BkEUrf89lTPtrlQ5riA9WlYpM=
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.3019.1385078233.18130.python-list@python.org>
Lines: 24
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1385078233 news.xs4all.nl 16008 [2001:888:2000:d::a6]:45866
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:60182

Chris Angelico <rosuav@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