Copy docstring via decorator

... to play nicely with deprecation warnings in docstrings

Author: timhoffm

lib/matplotlib/_api/__init__.py

@@ -423,3 +423,43 @@ def warn_external(message, category=None):
         # preemptively break reference cycle between locals and the frame
         del frame
     warnings.warn(message, category, **kwargs)
+
+
+
+def copy_docstring(source):
+    """
+    A decorator to copy a docstring from another function.
+
+    Parameters
+    ----------
+    source : callable
+        The function from which to copy the docstring.
+
+    Examples
+    --------
+    ::
+
+        @copy_docstring(source=source_func)
+        def my_func():
+            ...
+
+    Notes
+    -----
+    This is particularly useful when making a function private and providing
+    a backward-compatible public wrapper. You can simply prefix the existing
+    function with an underscore and create the backward-compatible public
+    wrapper as ::
+
+        @_api.deprecated("3.11")
+        @_api.copy_docstring(source=source_func)
+        def my_func():
+            ...
+
+    This ensures that the docstring is present and amended with the deprecation
+    note.
+    """
+    def decorator(func):
+        func.__doc__ = source.__doc__
+        return func
+
+    return decorator

lib/matplotlib/_api/__init__.pyi

@@ -61,3 +61,4 @@ def recursive_subclasses(cls: type) -> Generator[type, None, None]: ...
 def warn_external(
     message: str | Warning, category: type[Warning] | None = ...
 ) -> None: ...
+def copy_docstring(func: Callable[..., Any]) -> Callable[..., Any]: ...

lib/matplotlib/transforms.py

@@ -2924,9 +2924,9 @@ def _nonsingular(vmin, vmax, expander=0.001, tiny=1e-15, increasing=True):
 
 
 @_api.deprecated("3.11")
+@_api.copy_docstring(_nonsingular)
 def nonsingular(vmin, vmax, expander=0.001, tiny=1e-15, increasing=True):
     return _nonsingular(vmin, vmax, expander, tiny, increasing)
-nonsingular.__doc__ = _nonsingular.__doc__
 
 
 def _interval_contains(interval, val):
@@ -2952,9 +2952,9 @@ def _interval_contains(interval, val):
 
 
 @_api.deprecated("3.11")
+@_api.copy_docstring(_interval_contains)
 def interval_contains(interval, val):
     return _interval_contains(interval, val)
-interval_contains.__doc__ = _interval_contains.__doc__
 
 
 def _interval_contains_close(interval, val, rtol=1e-10):
@@ -3007,9 +3007,9 @@ def _interval_contains_open(interval, val):
 
 
 @_api.deprecated("3.11")
+@_api.copy_docstring(_interval_contains_open)
 def interval_contains_open(interval, val):
     return _interval_contains_open(interval, val)
-_interval_contains_open.__doc__ = _interval_contains_open.__doc__
 
 
 def offset_copy(trans, fig=None, x=0.0, y=0.0, units='inches'):