chore: mark steal_docs as deprecated in favor of wraps() or copy_docs()

The steal_docs api signature was fairly daft and py3k tooling allows doing
this saner, so do so.  copy_docs can handle both class and function, removing
a ton of noise.

In parallel to cleaning that out, convert to functools.wraps where appropriate,
and drop docstrings where py3k now transfers annotations and docs across.

Also do the full deprecation cleanup for this change also.

Signed-off-by: Brian Harring <ferringb@gmail.com>

Author: ferringb

src/snakeoil/containers.py

@@ -14,7 +14,7 @@
 
 from itertools import chain, filterfalse
 
-from .klass import steal_docs
+from .klass import copy_docs
 
 
 class InvertedContains(set):
@@ -41,6 +41,7 @@ def __iter__(self):
         raise TypeError("InvertedContains cannot be iterated over")
 
 
+@copy_docs(set)
 class SetMixin:
     """
     Base class for implementing set classes
@@ -52,47 +53,39 @@ class SetMixin:
 
     """
 
-    @steal_docs(set)
     def __and__(self, other, kls=None):
         # Note: for these methods we don't bother to filter dupes from this
         # list -  since the subclasses __init__ should already handle this,
         # there's no point doing it twice.
         return (kls or self.__class__)(x for x in self if x in other)
 
-    @steal_docs(set)
     def __rand__(self, other):
         return self.__and__(other, kls=other.__class__)
 
-    @steal_docs(set)
     def __or__(self, other, kls=None):
         return (kls or self.__class__)(chain(self, other))
 
-    @steal_docs(set)
     def __ror__(self, other):
         return self.__or__(other, kls=other.__class__)
 
-    @steal_docs(set)
     def __xor__(self, other, kls=None):
         return (kls or self.__class__)(
             chain(
                 (x for x in self if x not in other), (x for x in other if x not in self)
             )
         )
 
-    @steal_docs(set)
     def __rxor__(self, other):
         return self.__xor__(other, kls=other.__class__)
 
-    @steal_docs(set)
     def __sub__(self, other):
         return self.__class__(x for x in self if x not in other)
 
-    @steal_docs(set)
     def __rsub__(self, other):
         return other.__class__(x for x in other if x not in self)
 
-    __add__ = steal_docs(set)(__or__)
-    __radd__ = steal_docs(set)(__ror__)
+    __add__ = __or__
+    __radd__ = __ror__
 
 
 class LimitedChangeSet(SetMixin):
@@ -147,7 +140,6 @@ def __init__(self, initial_keys, unchangable_keys=None, key_validator=None):
         self._change_order = []
         self._orig = frozenset(self._new)
 
-    @steal_docs(set)
     def add(self, key):
         key = self._validater(key)
         if key in self._changed or key in self._blacklist:
@@ -160,7 +152,6 @@ def add(self, key):
         self._changed.add(key)
         self._change_order.append((self._added, key))
 
-    @steal_docs(set)
     def remove(self, key):
         key = self._validater(key)
         if key in self._changed or key in self._blacklist:
@@ -173,7 +164,6 @@ def remove(self, key):
         self._changed.add(key)
         self._change_order.append((self._removed, key))
 
-    @steal_docs(set)
     def __contains__(self, key):
         return self._validater(key) in self._new
 
@@ -201,23 +191,19 @@ def rollback(self, point=0):
     def __str__(self):
         return "LimitedChangeSet([%s])" % (str(self._new)[1:-1],)
 
-    @steal_docs(set)
     def __iter__(self):
         return iter(self._new)
 
-    @steal_docs(set)
     def __len__(self):
         return len(self._new)
 
-    @steal_docs(set)
     def __eq__(self, other):
         if isinstance(other, LimitedChangeSet):
             return self._new == other._new
         elif isinstance(other, (frozenset, set)):
             return self._new == other
         return False
 
-    @steal_docs(set)
     def __ne__(self, other):
         return not self == other
 
@@ -260,6 +246,7 @@ def add(self, key):
             self._new.add(key)
 
 
+@copy_docs(set)
 class RefCountingSet(dict):
     """
     Set implementation that implements refcounting for add/remove, removing the key only when its refcount is 0.
@@ -281,27 +268,24 @@ def __init__(self, iterable=None):
         if iterable is not None:
             self.update(iterable)
 
-    @steal_docs(set)
     def add(self, item):
         count = self.get(item, 0)
         self[item] = count + 1
 
-    @steal_docs(set)
     def remove(self, item):
         count = self[item]
         if count == 1:
             del self[item]
         else:
             self[item] = count - 1
 
-    @steal_docs(set)
     def discard(self, item):
         try:
             self.remove(item)
         except KeyError:
             pass
 
-    @steal_docs(set)
-    def update(self, items):
+    # the signature conflict is expected, thus the incompatible override.
+    def update(self, items):  # pyright: ignore[reportIncompatibleMethodOverride]
         for item in items:
             self.add(item)

src/snakeoil/data_source.py

@@ -43,10 +43,10 @@
 )
 
 import errno
-from functools import partial
 import io
+from functools import partial
 
-from . import compression, fileutils, klass, stringio
+from . import compression, fileutils, stringio
 from .currying import post_curry
 
 
@@ -210,7 +210,6 @@ def __init__(self, path, mutable=False, encoding=None):
         self.mutable = mutable
         self.encoding = encoding
 
-    @klass.steal_docs(base)
     def text_fileobj(self, writable=False):
         if writable and not self.mutable:
             raise TypeError("data source %s is immutable" % (self,))
@@ -230,7 +229,6 @@ def text_fileobj(self, writable=False):
                 raise
             return opener(self.path, "w+")
 
-    @klass.steal_docs(base)
     def bytes_fileobj(self, writable=False):
         if not writable:
             return open_file(self.path, "rb", self.buffering_window)
@@ -321,7 +319,6 @@ def _convert_data(self, mode):
             return self.data
         return self.data.decode()
 
-    @klass.steal_docs(base)
     def text_fileobj(self, writable=False):
         if writable:
             if not self.mutable:
@@ -337,7 +334,6 @@ def _reset_data(self, data):
             data = data.decode()
         self.data = data
 
-    @klass.steal_docs(base)
     def bytes_fileobj(self, writable=False):
         if writable:
             if not self.mutable:
@@ -354,7 +350,6 @@ class text_data_source(data_source):
 
     __slots__ = ()
 
-    @klass.steal_docs(data_source)
     def __init__(self, data, mutable=False):
         if not isinstance(data, str):
             raise TypeError("data must be a str")
@@ -374,7 +369,6 @@ class bytes_data_source(data_source):
 
     __slots__ = ()
 
-    @klass.steal_docs(data_source)
     def __init__(self, data, mutable=False):
         if not isinstance(data, bytes):
             raise TypeError("data must be bytes")
@@ -405,13 +399,11 @@ def __init__(self, data):
         """
         data_source.__init__(self, data, mutable=False)
 
-    @klass.steal_docs(data_source)
     def text_fileobj(self, writable=False):
         if writable:
             raise TypeError(f"data source {self} data is immutable")
         return self.data(True)
 
-    @klass.steal_docs(data_source)
     def bytes_fileobj(self, writable=False):
         if writable:
             raise TypeError(f"data source {self} data is immutable")

src/snakeoil/formatters.py

@@ -7,7 +7,7 @@
 import typing
 from functools import partial
 
-from .klass import GetAttrProxy, steal_docs
+from .klass import GetAttrProxy, copy_docs
 from .mappings import defaultdictkey
 
 __all__ = (
@@ -201,7 +201,6 @@ def _write_prefix(self, wrap):
             # but it is completely arbitrary.
             self._pos = self.width - 10
 
-    @steal_docs(Formatter)
     def write(self, *args, **kwargs):
         wrap = kwargs.get("wrap", self.wrap)
         autoline = kwargs.get("autoline", self.autoline)
@@ -487,15 +486,14 @@ def __init__(
             self._fg_cache = defaultdictkey(partial(TerminfoColor, 0))
             self._bg_cache = defaultdictkey(partial(TerminfoColor, 1))
 
-        @steal_docs(Formatter)
+        @copy_docs(Formatter.fg)
         def fg(self, color=None):
             return self._fg_cache[color]
 
-        @steal_docs(Formatter)
+        @copy_docs(Formatter.bg)
         def bg(self, color=None):
             return self._bg_cache[color]
 
-        @steal_docs(Formatter)
         def write(self, *args, **kwargs):
             super().write(*args, **kwargs)
             try:
@@ -509,8 +507,8 @@ def write(self, *args, **kwargs):
                     raise StreamClosed(e)
                 raise
 
-        @steal_docs(Formatter)
-        def title(self, string):
+        def title(self, title: str):  # pyright: ignore[reportIncompatibleMethodOverride]
+            """ "Set the title"""
             # I want to use curses.tigetflag('hs') here but at least
             # the screen-s entry defines a tsl and fsl string but does
             # not set the hs flag. So just check for the ability to
@@ -519,7 +517,7 @@ def title(self, string):
             tsl = curses.tigetstr("tsl")
             fsl = curses.tigetstr("fsl")
             if tsl and fsl:
-                self.stream.write(tsl + string.encode(self.encoding, "replace") + fsl)
+                self.stream.write(tsl + title.encode(self.encoding, "replace") + fsl)
                 self.stream.flush()
 
 

src/snakeoil/klass/__init__.py

@@ -21,6 +21,7 @@
     "cached_hash",
     "cached_property",
     "cached_property_named",
+    "copy_docs",
     "steal_docs",
     "ImmutableInstance",
     "immutable_instance",
@@ -36,7 +37,6 @@
 )
 
 import abc
-import inspect
 from collections import deque
 from operator import attrgetter
 
@@ -48,6 +48,7 @@
     immutable_instance,
     inject_immutable_instance,
     inject_richcmp_methods_from_cmp,
+    steal_docs,
 )
 from .properties import (
     _uncached_singleton,  # noqa: F401 .  This exists purely due to a stupid usage of pkgcore.ebuild.profile which is being removed.
@@ -62,7 +63,7 @@
     jit_attr_named,
     jit_attr_none,
 )
-from .util import combine_classes, get_attrs_of, get_slots_of
+from .util import combine_classes, copy_docs, get_attrs_of, get_slots_of
 
 sentinel = object()
 
@@ -407,55 +408,6 @@ def __hash__(self):
     return __hash__
 
 
-def steal_docs(target, ignore_missing=False, name=None):
-    """
-    decorator to steal __doc__ off of a target class or function
-
-    Specifically when the target is a class, it will look for a member matching
-    the functors names from target, and clones those docs to that functor;
-    otherwise, it will simply clone the targeted function's docs to the
-    functor.
-
-    :param target: class or function to steal docs from
-    :param ignore_missing: if True, it'll swallow the exception if it
-        cannot find a matching method on the target_class.  This is rarely
-        what you want- it's mainly useful for cases like `dict.has_key`, where it
-        exists in py2k but doesn't in py3k
-    :param name: function name from class to steal docs from, by default the name of the
-        decorated function is used; only used when the target is a class name
-
-    Example Usage:
-
-    >>> from snakeoil.klass import steal_docs
-    >>> class foo(list):
-    ...   @steal_docs(list)
-    ...   def extend(self, *a):
-    ...     pass
-    >>>
-    >>> f = foo([1,2,3])
-    >>> assert f.extend.__doc__ == list.extend.__doc__
-    """
-
-    def inner(functor):
-        if inspect.isclass(target):
-            if name is not None:
-                target_name = name
-            else:
-                target_name = functor.__name__
-            try:
-                obj = getattr(target, target_name)
-            except AttributeError:
-                if not ignore_missing:
-                    raise
-                return functor
-        else:
-            obj = target
-        functor.__doc__ = obj.__doc__
-        return functor
-
-    return inner
-
-
 class SlotsPicklingMixin:
     """Default pickling support for classes that use __slots__."""