Deprecate Python2 compat shim sphinx.util.osutil.walk()

Code should use os.walk() instead, which works with either str or bytes.
All internal calls use str.

CHANGES

@@ -21,6 +21,7 @@ Deprecated
 * The string style ``base`` argument of ``env.doc2path()`` is deprecated.
 * ``sphinx.ext.doctest.doctest_encode()``
 * ``sphinx.testing.util.remove_unicode_literal()``
+* ``sphinx.util.osutil.walk()``
 
 For more details, see `deprecation APIs list
 <http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_

doc/extdev/index.rst

@@ -136,6 +136,11 @@ The following is a list of deprecated interface.
      - 4.0
      - N/A
 
+   * - ``sphinx.util.osutil.walk()``
+     - 2.0
+     - 4.0
+     - ``os.walk()``
+
    * - :rst:dir:`highlightlang`
      - 1.8
      - 4.0

sphinx/ext/apidoc.py

@@ -32,7 +32,7 @@ from sphinx import __display_version__, package_dir
 from sphinx.cmd.quickstart import EXTENSIONS
 from sphinx.locale import __
 from sphinx.util import rst
-from sphinx.util.osutil import FileAvoidWrite, ensuredir, walk
+from sphinx.util.osutil import FileAvoidWrite, ensuredir
 
 if False:
     # For type annotation
@@ -235,7 +235,7 @@ def recurse_tree(rootpath, excludes, opts):
         root_package = None
 
     toplevels = []
-    for root, subs, files in walk(rootpath, followlinks=followlinks):
+    for root, subs, files in os.walk(rootpath, followlinks=followlinks):
         # document only Python module files (that aren't excluded)
         py_files = sorted(f for f in files
                           if path.splitext(f)[1] in PY_SUFFIXES and

sphinx/util/__init__.py

@@ -87,7 +87,7 @@ def get_matching_files(dirname, exclude_matchers=()):
     dirname = path.normpath(path.abspath(dirname))
     dirlen = len(dirname) + 1    # exclude final os.path.sep
 
-    for root, dirs, files in walk(dirname, followlinks=True):
+    for root, dirs, files in os.walk(dirname, followlinks=True):
         relativeroot = root[dirlen:]
 
         qdirs = enumerate(path_stabilize(path.join(relativeroot, dn))

sphinx/util/fileutil.py

@@ -15,7 +15,7 @@ import posixpath
 
 from docutils.utils import relative_path
 
-from sphinx.util.osutil import copyfile, ensuredir, walk
+from sphinx.util.osutil import copyfile, ensuredir
 
 if False:
     # For type annotation
@@ -82,7 +82,7 @@ def copy_asset(source, destination, excluded=lambda path: False, context=None, r
         copy_asset_file(source, destination, context, renderer)
         return
 
-    for root, dirs, files in walk(source, followlinks=True):
+    for root, dirs, files in os.walk(source, followlinks=True):
         reldir = relative_path(source, root)
         for dir in dirs[:]:
             if excluded(posixpath.join(reldir, dir)):

sphinx/util/i18n.py

@@ -25,7 +25,7 @@ from sphinx.errors import SphinxError
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.matching import Matcher
-from sphinx.util.osutil import SEP, relpath, walk
+from sphinx.util.osutil import SEP, relpath
 
 
 logger = logging.getLogger(__name__)
@@ -139,7 +139,7 @@ def find_catalog_source_files(locale_dirs, locale, domains=None, gettext_compact
         if not path.exists(base_dir):
             continue  # locale path is not found
 
-        for dirpath, dirnames, filenames in walk(base_dir, followlinks=True):
+        for dirpath, dirnames, filenames in os.walk(base_dir, followlinks=True):
             filenames = [f for f in filenames if f.endswith('.po')]
             for filename in filenames:
                 if excluded(path.join(relpath(dirpath, base_dir), filename)):

sphinx/util/osutil.py

@@ -90,39 +90,12 @@ def ensuredir(path):
             raise
 
 
-# This function is same as os.walk of Python2.7 except a customization
-# that check UnicodeError.
-# The customization obstacle to replace the function with the os.walk.
 def walk(top, topdown=True, followlinks=False):
     # type: (unicode, bool, bool) -> Iterator[Tuple[unicode, List[unicode], List[unicode]]]
-    """Backport of os.walk from 2.6, where the *followlinks* argument was
-    added.
-    """
-    names = os.listdir(top)
-
-    dirs, nondirs = [], []
-    for name in names:
-        try:
-            fullpath = path.join(top, name)
-        except UnicodeError:
-            print('%s:: ERROR: non-ASCII filename not supported on this '
-                  'filesystem encoding %r, skipped.' % (name, fs_encoding),
-                  file=sys.stderr)
-            continue
-        if path.isdir(fullpath):
-            dirs.append(name)
-        else:
-            nondirs.append(name)
-
-    if topdown:
-        yield top, dirs, nondirs
-    for name in dirs:
-        fullpath = path.join(top, name)
-        if followlinks or not path.islink(fullpath):
-            for x in walk(fullpath, topdown, followlinks):
-                yield x
-    if not topdown:
-        yield top, dirs, nondirs
+    warnings.warn('sphinx.util.osutil.walk() is deprecated for removal. '
+                  'Please use os.walk() instead.',
+                  RemovedInSphinx40Warning)
+    return os.walk(top, topdown=topdown, followlinks=followlinks)
 
 
 def mtimes_of_files(dirnames, suffix):