Python Enhancement Proposals

Python »
PEP Index »
PEP 387

PEP 387 – Backwards Compatibility Policy

Author:: Benjamin Peterson <benjamin at python.org>
PEP-Delegate:: Brett Cannon <brett at python.org>
Status:

Table of Contents

Abstract

This PEP outlines Python’s backwards compatibility policy.

As one of the most used programming languages today[1], thePython core language and its standard library play a critical role inmillions of applications and libraries. This is fantastic. However, itmeans the development team must be very careful not to break thisexisting 3rd party code with new releases.

This PEP takes the perspective that “backwards incompatibility” meanspreexisting code ceases to comparatively function after a change. It isacknowledged that this is not a concrete definition, but the expectationis people in general understand what is meant by“backwards incompatibility”, and if they are unsure they may ask thePython development team and/or steering council for guidance.

Backwards Compatibility Rules

This policy applies to all public APIs. These include:

Syntax and behavior of these constructs as defined by the referencemanual.
The C-API.
Function, class, module, attribute, and method names and types.
Given a set of arguments, the return value, side effects, and raisedexceptions of a function. This does not preclude changes fromreasonable bug fixes.
The position and expected types of arguments and returned values.
Behavior of classes with regards to subclasses: the conditions underwhich overridden methods are called.
Documented exceptions and the semantics which lead to their raising.
Exceptions commonly raised in EAFP scenarios.

Others are explicitly not part of the public API. They can change orbe removed at any time in any way. These include:

Function, class, module, attribute, method, and C-API names andtypes that are prefixed by “_” (except special names).
Anything documented publicly as being private.Note that if something is not documented at all, it isnotautomatically considered private.
Imported modules (unless explicitly documented as part of the publicAPI; e.g. importing thebacon module in thespam does notautomatically meanspam.bacon is part of the public API unlessit is documented as such).
Inheritance patterns of internal classes.
Test suites. (Anything in theLib/test directory or testsubdirectories of packages.)
Backward compatibility rules do not apply to any module or API that isexplicitly documented asProvisional perPEP 411.

Basic policy for backwards compatibility

In general, incompatibilities should have a large benefit tobreakage ratio, and the incompatibility should be easy to resolve inaffected code. For example, adding an stdlib module with the samename as a third party package is generally not acceptable. Addinga method or attribute that conflicts with 3rd party code throughinheritance, however, is likely reasonable.
Unless it is going through the deprecation process below, thebehavior of an APImust not change in an incompatible fashionbetween any two consecutive releases. Python’s yearly releaseprocess (PEP 602) means that the deprecation period must last atleast two years.
Similarly a feature cannot be removed without notice between any twoconsecutive releases.
For changes that are unable to raise a deprecation warning, consultwith the steering council.
The steering council may grant exceptions to this policy. Inparticular, they may shorten the required deprecation period for afeature. Exceptions are only granted for extreme situations such asdangerously broken or insecure features or features no one couldreasonably be depending on (e.g., support for completely obsoleteplatforms).

Soft Deprecation

A soft deprecation can be used when using an API which should no longerbe used to write new code, but it remains safe to continue using it inexisting code. The API remains documented and tested, but will not bedeveloped further (no enhancement).

The main difference between a “soft” and a (regular) “hard” deprecationis that the soft deprecation does not imply scheduling the removal ofthe deprecated API.

Another difference is that a soft deprecation does not issue a warning:it’s only mentioned in the documentation, whereas usually a “hard”deprecation issues aDeprecationWarning warning at runtime. Thedocumentation of a soft deprecation should explain why the API should beavoided, and if possible propose a replacement.

If the decision is made to deprecate (in the regular sense) a featurethat is currently soft deprecated, the deprecation must follow theBackwards Compatibility Rules (i.e., there is no exception becausethe feature is already soft deprecated).

Making Incompatible Changes

Making an incompatible change is a gradual process performed overseveral releases:

Discuss the change.Depending on the degree of incompatibility, this could be onDiscourse,theissue tracker,or in an appropriate workgroup or SIG.If the discussion reaches consensus aPEP orsimilar document may be written.Hopefully users of the affected API will pipe up to comment.
Add a warning to the currentmain branch.If behavior is changing, the API may gain a newfunction or method to perform the new behavior; old usage shouldraise the warning. If an API is being removed, simply warnwhenever it is entered.DeprecationWarning is the usualwarning category to use, butPendingDeprecationWarning may beused in special cases where the old and new versions of the API willcoexist for many releases[2]. The warning message shouldinclude the release the incompatibility is expected to become thedefault and a link to an issue that users can post feedback to.When feasible, also changetypeshedto add the@deprecated decorator (seePEP 702) to the deprecated API,so that users of static type checkers have another way to learnabout the deprecation.
For C API, a compiler warning generated by thePy_DEPRECATED macrois also acceptable.
Wait for the warning to appear in at least two minor Pythonversions of the same major version, or one minor version in an oldermajor version (e.g., for a warning in Python 3.10.0, you either waituntil at least Python 3.12 or Python 4.0 to make the change). It ispreferred, though, to wait 5 years before removal (e.g., warn starting inPython 3.10, removal in 3.15; this happens to coincide with the currentlifetime of a minor release of Python).
- If the expected maintenance overhead and security risk of thedeprecated behavior is small (e.g. an old function is reimplementedin terms of a new, more general one), it can stay indefinitely(or until the situation changes).
- If the deprecated feature is replaced by a new one, it shouldgenerally be removed only after the last Python versionwithout the new feature reaches end of support.
See if there’s any feedback. Users not involved in the originaldiscussions may comment now after seeing the warning. Perhapsreconsider.
The behavior change or feature removal may now be made default orpermanent having reached the declared version. Remove the oldversion and warning.
If a warning cannot be provided to users, consult with the steeringcouncil.

Changelog

2025-Jan-27: Updated to prefer a 5-year deprecation period before removal.
2023-Nov-14: Added@deprecated decorator perPEP 702.
2023-Jul-03: Added the Soft Deprecation section, as discussed inhttps://discuss.python.org/t/27957.
2023-Jun-26: Multiple smaller updates and clarifications, discussed inhttps://discuss.python.org/t/22042.
2022-Apr-04: Added explicit notes to ask the Steering Councilin several exceptional cases.
2021-Apr-16: Clarified how long a warning must be emitted beforea change can be made.
2020-Jul-20: Initial accepted version.