update back-compatibility section

This commit is contained in:
Ethan Furman 2021-09-10 22:43:42 -07:00
parent b496b1865b
commit 43e722f965
1 changed files with 11 additions and 14 deletions

View File

@ -176,26 +176,23 @@ to arguments for changing Enum's ``repr()`` to match Flag's.
Backwards Compatibility
=======================
My understanding is that ``str()`` and ``repr()`` output has much lower
backwards compatibility requirements. Even so, I expect the majority of
breakage to be in doc and unit tests. I'm less clear on the policy for
``format()``.
Backwards compatibility of stringified objects is not guarenteed across major
Python versions, and there will be backwards compatibility breaks where
software uses the ``repr()``, ``str()``, and ``format()`` output of enums in
tests, documentation, data structures, and/or code generation.
Normal usage of enum members will not change: ``re.ASCII`` can still be used
as ``re.ASCII`` and will still compare equal to ``256``.
If the previous output needs to be maintained, for example to ensure
compatibily between different Python versions, software projects will need to
create their own enum base class with the appropriate methods overridden.
Note that by changing the ``str()`` of the drop-in category, we will actually
prevent future breakage when ``IntEnum``, et al, are used to replace existing
constants.
Mitigation
==========
Normal usage of enum members will not change: ``re.ASCII`` can still be used
as ``re.ASCII`` and will still compare equal to ``256``. If one wants their
own enums in their own code to remain the same they will need to write their
own base Enum class and then write the appropriate ``repr``, ``str()``, and
``format()`` methods (or copy them from the 3.10 enum module).
Copyright
=========