Document limitations on @deprecated with multiple-inheritance.

anntzer · anntzer · commit 2ce4d7ea26c9 · 2020-10-08T23:06:05.000+02:00
This is tricky to fix correctly and anyways quite rare, so just document
the limitation for now.
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -119,6 +119,12 @@ def deprecated(since, *, message='', name='', alternative='', pending=False,
     ``@staticmethod`` (i.e., `deprecated` should directly decorate the
     underlying callable), but *over* ``@property``.
 
+    When deprecating a class ``C`` intended to be used as a base class in a
+    multiple inheritance hierarchy, ``C`` *must* define an ``__init__`` method
+    (if ``C`` instead inherited its ``__init__`` from its own base class, then
+    ``@deprecated`` would mess up ``__init__`` inheritance when installing its
+    own (deprecation-emitting) ``C.__init__``).
+
     Parameters
     ----------
     since : str
