[Python-checkins] Add notes for maintaining ABCs (#92736)

rhettinger webhook-mailer at python.org
Thu May 12 14:18:55 EDT 2022


https://github.com/python/cpython/commit/a834e2d8e1230c17193c19b425e83e0bf736179e
commit: a834e2d8e1230c17193c19b425e83e0bf736179e
branch: main
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2022-05-12T13:18:39-05:00
summary:

Add notes for maintaining ABCs (#92736)

files:
M Lib/_collections_abc.py
M Lib/numbers.py

diff --git a/Lib/_collections_abc.py b/Lib/_collections_abc.py
index e96e4c3535586..c62233b81a5c9 100644
--- a/Lib/_collections_abc.py
+++ b/Lib/_collections_abc.py
@@ -6,6 +6,32 @@
 Unit tests are in test_collections.
 """
 
+############ Maintenance notes #########################################
+#
+# ABCs are different from other standard library modules in that they
+# specify compliance tests.  In general, once an ABC has been published,
+# new methods (either abstract or concrete) cannot be added.
+#
+# Though classes that inherit from an ABC would automatically receive a
+# new mixin method, registered classes would become non-compliant and
+# violate the contract promised by ``isinstance(someobj, SomeABC)``.
+#
+# Though irritating, the correct procedure for adding new abstract or
+# mixin methods is to create a new ABC as a subclass of the previous
+# ABC.  For example, union(), intersection(), and difference() cannot
+# be added to Set but could go into a new ABC that extends Set.
+#
+# Because they are so hard to change, new ABCs should have their APIs
+# carefully thought through prior to publication.
+#
+# Since ABCMeta only checks for the presence of methods, it is possible
+# to alter the signature of a method by adding optional arguments
+# or changing parameters names.  This is still a bit dubious but at
+# least it won't cause isinstance() to return an incorrect result.
+#
+#
+#######################################################################
+
 from abc import ABCMeta, abstractmethod
 import sys
 
diff --git a/Lib/numbers.py b/Lib/numbers.py
index 5b98e642083b3..9548aebd776a7 100644
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -5,6 +5,31 @@
 
 TODO: Fill out more detailed documentation on the operators."""
 
+############ Maintenance notes #########################################
+#
+# ABCs are different from other standard library modules in that they
+# specify compliance tests.  In general, once an ABC has been published,
+# new methods (either abstract or concrete) cannot be added.
+#
+# Though classes that inherit from an ABC would automatically receive a
+# new mixin method, registered classes would become non-compliant and
+# violate the contract promised by ``isinstance(someobj, SomeABC)``.
+#
+# Though irritating, the correct procedure for adding new abstract or
+# mixin methods is to create a new ABC as a subclass of the previous
+# ABC.
+#
+# Because they are so hard to change, new ABCs should have their APIs
+# carefully thought through prior to publication.
+#
+# Since ABCMeta only checks for the presence of methods, it is possible
+# to alter the signature of a method by adding optional arguments
+# or changing parameter names.  This is still a bit dubious but at
+# least it won't cause isinstance() to return an incorrect result.
+#
+#
+#######################################################################
+
 from abc import ABCMeta, abstractmethod
 
 __all__ = ["Number", "Complex", "Real", "Rational", "Integral"]



More information about the Python-checkins mailing list