feat: add ExtendMethodDoc for extending method docstrings

Author: machow

pins/boards.py

@@ -15,7 +15,7 @@
 from .meta import Meta, MetaRaw, MetaFactory
 from .errors import PinsError
 from .drivers import load_data, save_data, default_title
-from .utils import inform
+from .utils import inform, ExtendMethodDoc
 from .config import get_allow_rsc_short_name
 
 
@@ -732,7 +732,15 @@ def pin_list(self):
         names = [f"{cont['owner_username']}/{cont['name']}" for cont in results]
         return names
 
-    def pin_write(self, *args, **kwargs):
+    @ExtendMethodDoc
+    def pin_write(self, *args, access_type=None, **kwargs):
+        """Write a pin.
+
+        Extends parent method in the following ways:
+
+        * Modifies content item to include any title and description changes.
+        * Adds access_type argument to specify who can see content. Defaults to "acl".
+        """
 
         # run parent function ---
 
@@ -757,6 +765,7 @@ def pin_write(self, *args, **kwargs):
 
         return meta
 
+    @ExtendMethodDoc
     def pin_search(self, search=None, as_df=True):
         from pins.rsconnect.api import RsConnectApiRequestError
 
@@ -793,6 +802,7 @@ def pin_search(self, search=None, as_df=True):
 
         return res
 
+    @ExtendMethodDoc
     def pin_version_delete(self, *args, **kwargs):
         from pins.rsconnect.api import RsConnectApiRequestError
 
@@ -804,6 +814,7 @@ def pin_version_delete(self, *args, **kwargs):
 
             raise PinsError("RStudio Connect cannot delete the latest pin version.")
 
+    @ExtendMethodDoc
     def pin_versions_prune(self, *args, **kwargs):
         sig = inspect.signature(super().pin_versions_prune)
         if sig.bind(*args, **kwargs).arguments.get("days") is not None:

pins/utils.py

@@ -9,3 +9,33 @@ def inform(log, msg):
 
     if not pins_options.quiet:
         print(msg, file=sys.stderr)
+
+
+class ExtendMethodDoc:
+    template = """\
+{current_doc}
+
+Parent method documentation:
+
+{parent_doc}
+"""
+
+    def __init__(self, func):
+        self.func = func
+
+    def __set_name__(self, owner, name):
+        bound_parent_meth = getattr(super(owner, owner), name)
+
+        self._parent_doc = bound_parent_meth.__doc__
+        self._orig_doc = self.func.__doc__
+
+        self.func.__doc__ = self.template.format(
+            current_doc=self._orig_doc, parent_doc=self._parent_doc
+        )
+        self.__doc__ = self.func.__doc__
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+
+        return self.func