Merge pull request #2228 from sopel-irc/tools-deprecations

tools: deprecate more Python 2-like shims

docs/source/api.rst

@@ -9,6 +9,7 @@ sopel.tools
 
 .. automodule:: sopel.tools
    :members:
+   :exclude-members: iteritems, iterkeys, itervalues, raw_input
    :private-members: Identifier._lower, Identifier._lower_swapped
 
 sopel.tools.web

sopel/tools/__init__.py

@@ -31,13 +31,6 @@
 from ._events import events  # NOQA
 
 
-# Kept for backward compatibility
-# TODO: consider removing that
-raw_input = input
-iteritems = dict.items
-itervalues = dict.values
-iterkeys = dict.keys
-
 _channel_prefixes = ('#', '&', '+', '!')
 
 # Can be implementation-dependent
@@ -205,6 +198,29 @@ def deprecated_func(*args, **kwargs):
 from . import time, web  # NOQA
 
 
+# Long kept for Python compatibility, but it's time we let these go.
+raw_input = deprecated(  # pragma: no cover
+    'Use the `input` function directly.',
+    version='8.0',
+    removed_in='8.1',
+    func=input)
+iteritems = deprecated(  # pragma: no cover
+    "Use the dict object's `.items()` method directly.",
+    version='8.0',
+    removed_in='8.1',
+    func=dict.items)
+itervalues = deprecated(  # pragma: no cover
+    "Use the dict object's `.values()` method directly.",
+    version='8.0',
+    removed_in='8.1',
+    func=dict.values)
+iterkeys = deprecated(  # pragma: no cover
+    "Use the dict object's `.keys()` method directly.",
+    version='8.0',
+    removed_in='8.1',
+    func=dict.keys)
+
+
 @deprecated('Shim for Python 2 cross-compatibility, no longer needed. '
             'Use built-in `input()` instead.',
             version='7.1',