Merge pull request #9326 from tk0miya/rebirth_of_force_decode

Revert the removal of sphinx.util:force_decode()

CHANGES

@@ -16,6 +16,8 @@ Features added
 * C, add C23 keywords ``_Decimal32``, ``_Decimal64``, and ``_Decimal128``.
 * #9354: C, add :confval:`c_extra_keywords` to allow user-defined keywords
   during parsing.
+* Revert the removal of ``sphinx.util:force_decode()`` to become some 3rd party
+  extensions available again during 5.0
 
 Bugs fixed
 ----------

doc/extdev/deprecated.rst

@@ -1015,7 +1015,7 @@ The following is a list of deprecated interfaces.
 
    * - ``sphinx.util.force_decode()``
      - 2.0
-     - 4.0
+     - 5.0
      - N/A
 
    * - ``sphinx.util.get_matching_docs()``

sphinx/util/__init__.py

@@ -337,6 +337,23 @@ def parselinenos(spec: str, total: int) -> List[int]:
     return items
 
 
+def force_decode(string: str, encoding: str) -> str:
+    """Forcibly get a unicode string out of a bytestring."""
+    warnings.warn('force_decode() is deprecated.',
+                  RemovedInSphinx50Warning, stacklevel=2)
+    if isinstance(string, bytes):
+        try:
+            if encoding:
+                string = string.decode(encoding)
+            else:
+                # try decoding with utf-8, should only work for real UTF-8
+                string = string.decode()
+        except UnicodeError:
+            # last resort -- can't fail
+            string = string.decode('latin1')
+    return string
+
+
 def rpartition(s: str, t: str) -> Tuple[str, str]:
     """Similar to str.rpartition from 2.5, but doesn't return the separator."""
     warnings.warn('rpartition() is now deprecated.', RemovedInSphinx50Warning, stacklevel=2)