Deprecate listdir(), trim its doc section, accept pathlib in search_base

- listdir() now emits DeprecationWarning on every call; use os.walk() +
  getsize() directly
- search_base type annotation widened to str | pathlib.Path; :type field
  added to module.rst param block
- module.rst listdir section cut from 156 to 82 lines: removed the
  os.walk explainer wall, the reduce() Python 2 holdover, the list()
  trivial example, and the misplaced versionadded::2.0.0 tag; replaced
  with one progressive code block covering default, relpath, glob, and sum
- Admonition referencing issue #27 ("scheduled for introduction") removed;
  replaced with deprecated:: 2.1.0 and versionchanged:: 2.0.0 (filter→glob)
- test_listdir_filter_kwarg_emits_deprecation_warning updated to expect
  two DeprecationWarnings now that the function-level warning fires first

Closes #27

Author: timlnx

bitmath/__init__.py

@@ -1580,7 +1580,7 @@ def getsize(path: str | pathlib.Path, bestprefix: bool = True, system: int = NIS
 
 
 def listdir(  # pylint: disable=too-many-arguments,too-many-positional-arguments
-    search_base: str,
+    search_base: str | pathlib.Path,
     followlinks: bool = False,
     glob: str = '*',
     relpath: bool = False,
@@ -1594,7 +1594,8 @@ def listdir(  # pylint: disable=too-many-arguments,too-many-positional-arguments
 * The absolute/relative path to a discovered file
 * A bitmath instance representing the "apparent size" of the file.
 
-    - `search_base` - The directory to begin walking down.
+    - `search_base` - The directory to begin walking down. May be a
+      plain string or a :class:`pathlib.Path` object.
     - `followlinks` - Whether or not to follow symbolic links to directories
     - `glob` - A glob (see :py:mod:`fnmatch`) to filter results with
       (default: ``*``, everything)
@@ -1605,11 +1606,19 @@ def listdir(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     - `system` - Provide a preferred unit system by setting `system`
       to either ``bitmath.NIST`` (default) or ``bitmath.SI``.
 
-.. note:: This function does NOT return tuples for directory entities.
-
 .. note:: Symlinks to **files** are followed automatically
 
+.. deprecated:: 2.1.0
+   :func:`bitmath.listdir` is deprecated and will be removed in a future
+   release. Use :func:`os.walk` with :func:`bitmath.getsize` directly.
+
     """
+    warnings.warn(
+        "bitmath.listdir() is deprecated and will be removed in a future release. "
+        "Use os.walk() with bitmath.getsize() directly.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     if 'filter' in kwargs:
         warnings.warn(
             "The 'filter' parameter of listdir() is deprecated as of 2.0.0 and will be "

docsite/source/module.rst

@@ -91,7 +91,9 @@ bitmath.listdir()
    * The absolute/relative path to a discovered file
    * A bitmath instance representing the *apparent size* of the file
 
-   :param string search_base: The directory to begin walking down
+   :param search_base: The directory to begin walking down. May be a
+                       plain string or a :class:`pathlib.Path` object.
+   :type search_base: str or pathlib.Path
    :param bool followlinks: **Default:** ``False``, do not follow
                             links. Whether or not to follow symbolic
                             links to directories. Setting to ``True``
@@ -117,123 +119,53 @@ bitmath.listdir()
                   ``True``
    :type system: One of :py:data:`bitmath.NIST` or :py:data:`bitmath.SI`
 
-   .. note::
-
-      * This function does **not** return tuples for directory
-        entities. Including directories in results is `scheduled for
-        introduction <https://github.com/timlnx/bitmath/issues/27>`_
-        in an upcoming release.
-      * Symlinks to **files** are followed automatically
+   .. note:: Symlinks to **files** are followed automatically
 
+   .. deprecated:: 2.1.0
 
-   When interpreting the results from this function it is *crucial* to
-   understand exactly which items are being taken into account, what
-   decisions were made to select those items, and how their sizes are
-   measured.
+      :func:`bitmath.listdir` is deprecated and will be removed in a future
+      release. Use :func:`os.walk` with :func:`bitmath.getsize` directly.
 
-   Results from this function may seem invalid when directly compared
-   to the results from common command line utilities, such as ``du``,
-   or ``tree``.
 
-   Let's pretend we have a directory structure like the following::
+   Given this directory tree::
 
       some_files/
       ├── deeper_files/
-      │   └── second_file
-      └── first_file
-
-   Where ``some_files/`` is a directory, and so is
-   ``some_files/deeper_files/``. There are two regular files in this
-   tree:
-
-   * ``somefiles/first_file`` - 1337 Bytes
-   * ``some_files/deeper_files/second_file`` - 13370 Bytes
-
-   The **total** size of the files in this tree is **1337 + 13370 =
-   14707** bytes.
-
-   .. versionadded:: 2.0.0
-
-   By far the simplest way to sum all of the results is using the built-in
-   :py:func:`sum` function, or :py:func:`bitmath.sum` for additional control
-   (complete docs on that following this section).
-
-   .. code-block:: python
-
-      >>> discovered_files = [f[1] for f in bitmath.listdir('./some_files')]
-      >>> print(discovered_files)
-      [Byte(1337.0), Byte(13370.0)]
-      >>> print(sum(discovered_files))
-      14707.0 B
-      >>> print(sum(discovered_files).best_prefix())
-      14.3623046875 KiB
-
-
-
-   Let's call :py:func:`bitmath.listdir` on the ``some_files/``
-   directory and see what the results look like. First we'll use all
-   the default parameters, then we'll set ``relpath`` to ``True``:
+      │   └── second_file   (13370 bytes)
+      └── first_file        (1337 bytes)
 
    .. code-block:: python
-      :linenos:
-      :emphasize-lines: 5-6,10-11
 
       >>> import bitmath
-      >>> for f in bitmath.listdir('./some_files'):
-      ...     print(f)
-      ...
-      ('/tmp/tmp.P5lqtyqwPh/some_files/first_file', Byte(1337.0))
-      ('/tmp/tmp.P5lqtyqwPh/some_files/deeper_files/second_file', Byte(13370.0))
-      >>> for f in bitmath.listdir('./some_files', relpath=True):
-      ...     print(f)
-      ...
-      ('some_files/first_file', Byte(1337.0))
-      ('some_files/deeper_files/second_file', Byte(13370.0))
 
-   On lines **5** and **6** the results print the full path, whereas
-   on lines **10** and **11** the path is relative to the present
-   working directory.
-
-   Let's play with the ``glob`` parameter now. Let's say we only
-   want to include results for files whose name begins with "second":
-
-   .. code-block:: python
-
-      >>> for f in bitmath.listdir('./some_files', glob='second*'):
-      ...     print(f)
-      ...
-      ('/tmp/tmp.P5lqtyqwPh/some_files/deeper_files/second_file', Byte(13370.0))
-
-
-   If we wish to avoid having to write for-loops, we can collect the
-   results into a list rather simply:
-
-   .. code-block:: python
-
-      >>> files = list(bitmath.listdir('./some_files'))
-      >>> print(files)
-      [('/tmp/tmp.P5lqtyqwPh/some_files/first_file', Byte(1337.0)), ('/tmp/tmp.P5lqtyqwPh/some_files/deeper_files/second_file', Byte(13370.0))]
-
-   Here's a more advanced example where we will sum the size of all
-   the returned results and then play around with the possible
-   formatting. Recall that a bitmath instance representing the size of
-   the discovered file is the second item in each returned tuple.
-
-   .. code-block:: python
-
-      >>> discovered_files = [f[1] for f in bitmath.listdir('./some_files')]
-      >>> print(discovered_files)
-      [Byte(1337.0), Byte(13370.0)]
-      >>> print(reduce(lambda x,y: x+y, discovered_files))
-      14707.0 B
-      >>> print(reduce(lambda x,y: x+y, discovered_files).best_prefix())
+      >>> # Default: absolute paths, Byte instances
+      >>> for path, size in bitmath.listdir('./some_files'):
+      ...     print(path, size)
+      /tmp/some_files/first_file Byte(1337.0)
+      /tmp/some_files/deeper_files/second_file Byte(13370.0)
+
+      >>> # Relative paths
+      >>> for path, size in bitmath.listdir('./some_files', relpath=True):
+      ...     print(path, size)
+      some_files/first_file Byte(1337.0)
+      some_files/deeper_files/second_file Byte(13370.0)
+
+      >>> # Filter by glob
+      >>> for path, size in bitmath.listdir('./some_files', glob='second*'):
+      ...     print(path, size)
+      /tmp/some_files/deeper_files/second_file Byte(13370.0)
+
+      >>> # Sum all results
+      >>> sizes = [size for _, size in bitmath.listdir('./some_files')]
+      >>> print(sum(sizes).best_prefix())
       14.3623046875 KiB
-      >>> print(reduce(lambda x,y: x+y, discovered_files).best_prefix().format("{value:.3f} {unit}"))
-      14.362 KiB
-
 
    .. versionadded:: 1.0.7
 
+   .. versionchanged:: 2.0.0
+      The ``filter`` parameter was renamed to ``glob``. Passing ``filter``
+      still works but emits a :exc:`DeprecationWarning`.
+
 
 .. _bitmath_sum:
 

tests/test_file_size.py

@@ -271,10 +271,9 @@ def test_listdir_filter_kwarg_emits_deprecation_warning(self):
         with warnings.catch_warnings(record=True) as w:
             warnings.simplefilter("always")
             list(bitmath.listdir('./tests/listdir_nosymlinks/', filter='*'))
-            self.assertEqual(len(w), 1)
-            self.assertTrue(issubclass(w[0].category, DeprecationWarning))
-            self.assertIn("filter", str(w[0].message))
-            self.assertIn("glob", str(w[0].message))
+            messages = [str(warning.message) for warning in w]
+            self.assertTrue(all(issubclass(warning.category, DeprecationWarning) for warning in w))
+            self.assertTrue(any("filter" in m and "glob" in m for m in messages))
 
     def test_listdir_filter_kwarg_still_works(self):
         """listdir() with deprecated filter= kwarg returns correct results"""