Merge pull request #2205 from sopel-irc/web.decode-cleanup

tools, tools.web: rework `web.decode()` to use modern stdlib

Author: dgw

docs/source/api.rst

@@ -4,10 +4,6 @@ Additional API features
 Sopel includes a number of additional functions that are useful for various
 common IRC tasks.
 
-Note that ``sopel.web`` was deprecated in 6.2.0, and is not included in this
-documentation; it will be removed completely in Sopel 8. Plugins should use
-`requests <https://github.com/psf/requests>`_ directly.
-
 sopel.tools
 -----------
 

sopel/tools/__init__.py

@@ -29,7 +29,6 @@
 from sopel import __version__
 
 from ._events import events  # NOQA
-from . import time, web  # NOQA
 
 
 # Kept for backward compatibility
@@ -199,6 +198,13 @@ def deprecated_func(*args, **kwargs):
     return deprecated_func
 
 
+# This has to be *after* the definition of `deprecated()` or we
+# get "AttributeError: partially initialized module 'sopel.tools' has no
+# attribute 'deprecated' (most likely due to a circular import)" when trying
+# to use the decorator in submodules.
+from . import time, web  # NOQA
+
+
 @deprecated('Shim for Python 2 cross-compatibility, no longer needed. '
             'Use built-in `input()` instead.',
             version='7.1',

sopel/tools/web.py

@@ -3,11 +3,6 @@
 applications, APIs, or websites in your plugins.
 
 .. versionadded:: 7.0
-
-.. note::
-    Some parts of this module will remain accessible through ``sopel.web`` as
-    well until its final removal in Sopel 8. This is for backward
-    compatibility only; please update old code as soon as possible.
 """
 # Copyright © 2008, Sean B. Palmer, inamidst.com
 # Copyright © 2009, Michael Yanovich <[email protected]>
@@ -18,12 +13,13 @@
 
 from __future__ import generator_stop
 
+import html
 from html.entities import name2codepoint
 import re
 import urllib
 from urllib.parse import urlparse, urlunparse
 
-from sopel import __version__
+from sopel import __version__, tools
 
 
 __all__ = [
@@ -85,9 +81,19 @@
 
 
 r_entity = re.compile(r'&([^;\s]+);')
-"""Regular expression to match HTML entities."""
+"""Regular expression to match HTML entities.
+
+.. deprecated:: 8.0
+
+    Will be removed in Sopel 9, along with :func:`entity`.
+"""
 
 
+@tools.deprecated(
+    version='8.0',
+    removed_in='9.0',
+    reason="No longer needed now that Python 3.4+ has `html.unescape()`",
+)
 def entity(match):
     """Convert an entity reference to the appropriate character.
 
@@ -96,6 +102,12 @@ def entity(match):
     :return str: the Unicode character corresponding to the given ``match``
         string, or a fallback representation if the reference cannot be
         resolved to a character
+
+    .. deprecated:: 8.0
+
+        Will be removed in Sopel 9. Use :func:`decode` directly or migrate to
+        Python's standard-library equivalent, :func:`html.unescape`.
+
     """
     value = match.group(1).lower()
     if value.startswith('#x'):
@@ -107,13 +119,20 @@ def entity(match):
     return '[' + value + ']'
 
 
-def decode(html):
+def decode(text):
     """Decode HTML entities into Unicode text.
 
-    :param str html: the HTML page or snippet to process
-    :return str: ``html`` with all entity references replaced
+    :param str text: the HTML page or snippet to process
+    :return str: ``text`` with all entity references replaced
+
+    .. versionchanged:: 8.0
+
+        Renamed ``html`` parameter to ``text``. (Python gained a standard
+        library module named :mod:`html` in version 3.4.)
+
     """
-    return r_entity.sub(entity, html)
+    # TODO deprecated?
+    return html.unescape(text)
 
 
 def quote(string, safe='/'):