145 lines
4.5 KiB
Plaintext
145 lines
4.5 KiB
Plaintext
PEP: 387
|
||
Title: Backwards Compatibility Policy
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Benjamin Peterson <benjamin@python.org>
|
||
BDFL-Delegate: Brett Cannon (on behalf of the steering council)
|
||
Status: Draft
|
||
Type: Process
|
||
Content-Type: text/x-rst
|
||
Created: 18-Jun-2009
|
||
Post-History: 19-Jun-2009
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP outlines Python's backwards compatibility policy.
|
||
|
||
|
||
Rationale
|
||
=========
|
||
|
||
As one of the most used programming languages today [#tiobe]_, the
|
||
Python core language and its standard library play a critical role in
|
||
millions of applications and libraries. This is fantastic. However, it
|
||
means the development team must be very careful not to break this
|
||
existing 3rd party code with new releases.
|
||
|
||
|
||
Backwards Compatibility Rules
|
||
=============================
|
||
|
||
This policy applies to all public APIs. These include:
|
||
|
||
- Syntax and behavior of these constructs as defined by the reference
|
||
manual
|
||
|
||
- The C-API
|
||
|
||
- Function, class, module, attribute, and method names and types.
|
||
|
||
- Given a set of arguments, the return value, side effects, and raised
|
||
exceptions of a function. This does not preclude changes from
|
||
reasonable bug fixes.
|
||
|
||
- The position and expected types of arguments and returned values.
|
||
|
||
- Behavior of classes with regards to subclasses: the conditions under
|
||
which overridden methods are called.
|
||
|
||
Others are explicitly not part of the public API. They can change or
|
||
be removed at any time in any way. These include:
|
||
|
||
- Function, class, module, attribute, method, and C-API names and types that
|
||
are prefixed by "_" (except special names). The contents of these
|
||
are also not subject to the policy.
|
||
|
||
- Inheritance patterns of internal classes.
|
||
|
||
- Test suites. (Anything in the Lib/test directory or test
|
||
subdirectories of packages.)
|
||
|
||
This is the basic policy for backwards compatibility:
|
||
|
||
* In general, incompatibilities should have a large benefit to
|
||
breakage ratio, and the incompatibility should be easy to resolve in
|
||
affected code. For example, adding an stdlib module with the same
|
||
name as a third party package is not acceptable. Adding a method or
|
||
attribute that conflicts with 3rd party code through inheritance,
|
||
however, is likely reasonable.
|
||
|
||
* Unless it is going through the deprecation process below, the
|
||
behavior of an API *must* not change between any two consecutive
|
||
releases. Python's yearly release process (:pep:`602`) means that
|
||
the deprecation period must last at least two years.
|
||
|
||
* Similarly a feature cannot be removed without notice between any two
|
||
consecutive releases.
|
||
|
||
* The steering council may grant exceptions to this policy. In
|
||
particular, they may shorten the required deprecation period for a
|
||
feature. Exceptions are only granted for extreme situations such as
|
||
dangerously broken or insecure features or features no one could
|
||
reasonably be depending on (e.g., support for completely obsolete
|
||
platforms).
|
||
|
||
|
||
Making Incompatible Changes
|
||
===========================
|
||
|
||
Making an incompatible change is a gradual process performed over several
|
||
releases:
|
||
|
||
1. Discuss the change. Depending on the degree of incompatibility,
|
||
this could be on the bug tracker, python-dev, python-list, or the
|
||
appropriate SIG. A PEP or similar document may be written.
|
||
Hopefully users of the affected API will pipe up to comment.
|
||
|
||
2. Add a warning [#warnings]_. If behavior is changing, the API may
|
||
gain a new function or method to perform the new behavior; old
|
||
usage should raise the warning. If an API is being removed, simply
|
||
warn whenever it is entered. ``DeprecationWarning`` is the usual
|
||
warning category to use, but ``PendingDeprecationWarning`` may be
|
||
used in special cases were the old and new versions of the API will
|
||
coexist for many releases.
|
||
|
||
3. Wait for the warning to appear in at least two major Python
|
||
versions. It's fine to wait more than two releases.
|
||
|
||
4. See if there's any feedback. Users not involved in the original
|
||
discussions may comment now after seeing the warning. Perhaps
|
||
reconsider.
|
||
|
||
5. The behavior change or feature removal may now be made default or
|
||
permanent in the N+3 release. Remove the old version and warning.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
.. [#tiobe] TIOBE Programming Community Index
|
||
|
||
http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
|
||
|
||
.. [#warnings] The warnings module
|
||
|
||
http://docs.python.org/library/warnings.html
|
||
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|