check-empty 1.2.3__tar.gz → 1.3.0__tar.gz

{check_empty-1.2.3 → check_empty-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-empty
-Version: 1.2.3
+Version: 1.3.0
 Summary: Command-line utility, as well as a hook usable by the Python pre-commit framework, and a GitHub Action, to ensure that selected files are empty.
 Keywords: check,command-line,empty,files,github-action,helper,hook,lightweight,pre-commit,prek,tool,utility
 Author: Jonathan Dung
@@ -28,13 +28,27 @@ Classifier: Programming Language :: Python :: 3.16
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
+Requires-Dist: py7zr==1.1.3 ; python_full_version >= '3.10' and extra == '7z'
+Requires-Dist: py7zr==1.0.0 ; python_full_version == '3.9.*' and extra == '7z'
+Requires-Dist: py7zr==0.22.0 ; python_full_version == '3.8.*' and extra == '7z'
+Requires-Dist: py7zr==0.20.6 ; python_full_version == '3.7.*' and extra == '7z'
+Requires-Dist: check-empty[7z,lzh,rar]==1.3.0 ; extra == 'all'
+Requires-Dist: lhafile==0.3.1 ; extra == 'lzh'
+Requires-Dist: rarfile==4.5 ; python_full_version >= '3.10' and extra == 'rar'
+Requires-Dist: rarfile==4.2 ; python_full_version < '3.10' and extra == 'rar'
 Maintainer: Jonathan Dung
 Maintainer-email: Jonathan Dung <jonathandung@yahoo.com>
-Requires-Python: >=3.6
+Requires-Python: >=3.7
+Provides-Extra: 7z
+Provides-Extra: all
+Provides-Extra: lzh
+Provides-Extra: rar
 Description-Content-Type: text/markdown
 
 # [check-empty](https://pypi.org/p/check-empty)
 
+[![#StandWithPalestine](https://raw.githubusercontent.com/TheBSD/StandWithPalestine/main/badges/StandWithPalestine.svg)](https://github.com/TheBSD/StandWithPalestine/blob/main/docs/README.md)
+
 A simple, dependency-free [pre-commit](https://pre-commit.com) /
 [prek](https://prek.j178.dev) hook, CLI, library and
 [GitHub Action](https://github.com/marketplace/actions/check-empty-files) conglomerate
@@ -46,8 +60,11 @@ specified.
 
 ## Prerequisites
 
-Supports CPython 3.6+, PyPy 7.0+, GraalPy 19.0+ out-of-the-box, and most likely every
-Python 3.6 runtime you can think of. This is the only requirement to use this tool.
+Supports CPython 3.7+, PyPy 7.3.4+, GraalPy 19.0+ out-of-the-box, and most likely every
+Python 3.7 runtime you can think of. This is the only requirement to use this tool.
+
+We cannot support Python 3.6 because of a vulnerability in `py7zr` 0.19.2, which is the
+latest version of `py7zr` that supports Python 3.6.
 
 ## Quickstart
 
@@ -115,7 +132,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.2.3 # repository version
+  rev: v1.3.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -131,7 +148,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.3"
+rev = "v1.3.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -155,7 +172,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.3"
+rev = "v1.3.0"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -175,12 +192,12 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.2.3 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v1.3.0 # the latest version on the GitHub Actions
   # marketplace; this step will fail and subsequent jobs will not run if any file is
   # not empty
   with:
     python-version: '3.14' # run the script on the latest stable Python version
-    # Python down to 3.6 is supported but not recommended due to end-of-life
+    # Python down to 3.7 is supported but not recommended due to end-of-life
     verbosity: 1
     filenames: |
       src/mylib/py.typed
@@ -227,9 +244,10 @@ to read the
 and the
 [contributing guide](https://github.com/jonathandung/.github/blob/main/CONTRIBUTING.md).
 
-To build the docs locally (needs Python 3.12+), install with the `docs`
-[group](https://packaging.python.org/en/latest/specifications/dependency-groups),
-preferably into a virtual environment.
+To build the docs locally (needs Python 3.12+ because of Sphinx), install with the
+`docs` [group](https://packaging.python.org/en/latest/specifications/dependency-groups)
+using a package manager that supports it (e.g. pip 25.1+ or uv 0.4.27+), preferably
+into a virtual environment.
 
 Tests are run with:
 

{check_empty-1.2.3 → check_empty-1.3.0}/README.md

@@ -1,5 +1,7 @@
 # [check-empty](https://pypi.org/p/check-empty)
 
+[![#StandWithPalestine](https://raw.githubusercontent.com/TheBSD/StandWithPalestine/main/badges/StandWithPalestine.svg)](https://github.com/TheBSD/StandWithPalestine/blob/main/docs/README.md)
+
 A simple, dependency-free [pre-commit](https://pre-commit.com) /
 [prek](https://prek.j178.dev) hook, CLI, library and
 [GitHub Action](https://github.com/marketplace/actions/check-empty-files) conglomerate
@@ -11,8 +13,11 @@ specified.
 
 ## Prerequisites
 
-Supports CPython 3.6+, PyPy 7.0+, GraalPy 19.0+ out-of-the-box, and most likely every
-Python 3.6 runtime you can think of. This is the only requirement to use this tool.
+Supports CPython 3.7+, PyPy 7.3.4+, GraalPy 19.0+ out-of-the-box, and most likely every
+Python 3.7 runtime you can think of. This is the only requirement to use this tool.
+
+We cannot support Python 3.6 because of a vulnerability in `py7zr` 0.19.2, which is the
+latest version of `py7zr` that supports Python 3.6.
 
 ## Quickstart
 
@@ -80,7 +85,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.2.3 # repository version
+  rev: v1.3.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -96,7 +101,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.3"
+rev = "v1.3.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -120,7 +125,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.3"
+rev = "v1.3.0"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -140,12 +145,12 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.2.3 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v1.3.0 # the latest version on the GitHub Actions
   # marketplace; this step will fail and subsequent jobs will not run if any file is
   # not empty
   with:
     python-version: '3.14' # run the script on the latest stable Python version
-    # Python down to 3.6 is supported but not recommended due to end-of-life
+    # Python down to 3.7 is supported but not recommended due to end-of-life
     verbosity: 1
     filenames: |
       src/mylib/py.typed
@@ -192,9 +197,10 @@ to read the
 and the
 [contributing guide](https://github.com/jonathandung/.github/blob/main/CONTRIBUTING.md).
 
-To build the docs locally (needs Python 3.12+), install with the `docs`
-[group](https://packaging.python.org/en/latest/specifications/dependency-groups),
-preferably into a virtual environment.
+To build the docs locally (needs Python 3.12+ because of Sphinx), install with the
+`docs` [group](https://packaging.python.org/en/latest/specifications/dependency-groups)
+using a package manager that supports it (e.g. pip 25.1+ or uv 0.4.27+), preferably
+into a virtual environment.
 
 Tests are run with:
 

check_empty-1.3.0/check_empty/__init__.py

@@ -0,0 +1,234 @@
+# Copyright © 2026 Jonathan Dung. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""Utility to check the emptiness of files and directories.
+
+Pre-commit hook, command-line tool and GitHub Action all-in-one.
+"""
+
+from __future__ import annotations
+
+import os
+
+from . import constants, reporter, util
+
+if constants.TYPE_CHECKING:
+    import typing
+    from collections.abc import Iterable
+
+    from _typeshed import FileDescriptorOrPath
+
+__all__ = ('check', 'default_reporter')
+__version__ = '1.3.0'
+default_reporter: reporter.Reporter = reporter.Reporter()
+"""The default reporter used by :func:`check`."""
+
+
+def check(
+    files: Iterable[FileDescriptorOrPath],
+    *,
+    clear: bool = False,
+    may_not_exist: bool = False,
+    verbosity: typing.SupportsIndex = 2,
+    recurse_into: typing.SupportsIndex = constants.RecurseInto.NONE,
+    reporter: reporter.Reporter = default_reporter,
+) -> int:
+    # ruff: ignore[docstring-missing-exception]
+    r"""Check the emptiness of files, recursing into directories if passed.
+
+    If using a custom reporter, remember to pass a ``verbosity`` greater than or equal
+    to 5, since some info will be missing from the parameters passed to
+    :meth:`Reporter.report` otherwise.
+
+    Args:
+        files: an iterable of file descriptors or paths representing the files and
+          directories to check; directory descriptors (\*nix) are not supported.
+        clear: if ``True``, clear the contents of non-empty files; directories, notably,
+          are not purged, but all files within should become empty.
+        may_not_exist: if ``True``, do not treat absent files or directories as errors.
+        verbosity: how much detail the program should print to stdout.
+        recurse_into: a bitwise or of flags indicating which types of archives to
+          recurse into; by default, all archives are treated as regular files.
+        reporter: The reporter to use for reporting the results. All output of this
+          function is produced by the reporter.
+
+    Returns:
+        The integer exit code calculated by the reporter.
+
+    """
+    files = list(files)
+    if not files:
+        return 0
+    k, j, t, n, o = [0] * 5, [], 0, len(files), files.pop
+    u, e, _ = j.extend, j.pop, lambda v: lambda _, k=k: k.__setitem__(v, k[v] + 1)
+    verbosity, recurse_into = (type(x).__index__(x) for x in (verbosity, recurse_into))
+    # ruff: disable[magic-value-comparison]
+    if verbosity > 4:
+        b = ['']
+        f = b.append
+    else:
+        b, f = None, _(0)
+    if verbosity > 3:
+        v, ra = [''], ['']
+        x, aa = v.append, ra.append
+    else:
+        v = ra = None
+        x = aa = lambda _: None
+    if verbosity > 2:
+        z, w = [''], ['']
+        i = z.append, w.append
+    else:
+        z = w = None
+        i = _(1), _(2)
+    if verbosity > 1:
+        r = []
+        g = r.append
+    else:
+        r, g = None, _(3)
+    # ruff: enable[magic-value-comparison]
+    zp, tr, rr, z7, lh = map(
+        recurse_into.__and__,
+        (x for x in constants.RecurseInto if x > 0 == x & (x - 1))
+        if __import__('sys').version_info < (3, 11)
+        else constants.RecurseInto,
+    )
+    an = bool(recurse_into)
+    if an:
+        from . import archives as ar
+    md = 'a' if clear else 'r'
+    if constants.TYPE_CHECKING:
+        import tarfile as tr
+        import zipfile as zp
+
+        import lhafile as lh
+        import py7zr as z7
+        import rarfile as rr
+    else:
+        if tr:
+            import tarfile as tr
+        if zp:
+            import zipfile as zp
+        if lh:
+            import lhafile as lh
+        if z7:
+            import py7zr as z7
+        if rr:
+            import rarfile as rr
+
+    def ha(a: str) -> bool:
+        if not an:
+            return False
+
+        def c() -> None:
+            nonlocal t
+            g(q)
+            t += s
+
+        def e() -> None:
+            c() if s else f(a)
+
+        def w() -> None:
+            if s:
+                if clear:
+                    raise NotImplementedError(m)
+                c()
+            else:
+                f(a)
+
+        y = []
+        if tr and util.try_tar(a, y.append):
+            d = y.pop()
+            aa(a)
+            for r in d.getmembers():
+                a, s = q = r.name, r.size
+                e()
+            if clear:
+                ar.clear_tar(d)
+        elif zp and zp.is_zipfile(a):
+            with zp.ZipFile(a, md) as d:
+                aa(a)
+                for r in d.infolist():
+                    a, s = q = r.filename, r.file_size
+                    if s:
+                        c()
+                        if clear:
+                            ar.clear_file_in_zip(d, r)
+                    else:
+                        f(a)
+        elif z7 and z7.is_7zfile(a):
+            with z7.SevenZipFile(a) as d:
+                aa(a)
+                for r in d.files:
+                    a, s = q = r.filename, r.origin.stat().st_size
+                    e()
+                if clear:
+                    ar.clear_7z(d)
+        elif rr and rr.is_rarfile(a):
+            m = 'Cannot clear files in RAR archives'
+            with rr.RarFile(a) as d:
+                aa(a)
+                for r in d.infolist():
+                    a, s = q = r.filename, r.file_size
+                    w()
+        else:
+            try:
+                d = lh.LhaFile(a)
+            except (RuntimeError, lh.BadLhafile):
+                return False
+            m = 'Cannot clear files in LHA archives'
+            aa(a)
+            for r in d.filelist:
+                a, s = q = r.filename, r.file_size
+                w()
+        return True
+
+    while files:
+        a, q = o(), None
+        m = isinstance(a, int)
+        if not m:
+            a = os.fsdecode(a)
+            if ha(a):
+                continue
+        with util.Handler(*i, a) as h:
+            q = os.stat(a)  # ruff: ignore[os-stat]
+        if q is None:
+            continue
+        c = h.e
+        if q.st_mode & constants.TYPE_MASK == constants.S_IFDIR:
+            if m:
+                raise constants.DIRFD_UNSUPPORTED
+            x(c)
+            u(os.scandir(c))
+            continue
+        s = q.st_size
+        if not s:
+            f(c)
+            continue
+        g((c, s))
+        t += s
+        if clear:
+            h.o()
+    del o, files
+    while j:
+        m = e()
+        a = m.path
+        if m.is_dir():
+            x(a)
+            u(os.scandir(a))
+            continue
+        if ha(a):
+            continue
+        n += 1
+        s = m.stat().st_size
+        if not s:
+            f(a)
+            continue
+        g((a, s))
+        t += s
+        if clear:
+            util.Handler(*i, a).o()
+    del j
+    x, d = k[1] if z is None else len(z) - 1, k[2] if w is None else len(w) - 1
+    y, p = k[3] if r is None else len(r), k[0] if b is None else len(b) - 1
+    reporter.report(z, w, v, b, r, x, y, d, p, t, n, verbosity, clear)
+    reporter.reset_stream()
+    return reporter.calculate_result(*map(bool, (y, x and not may_not_exist, d)))

{check_empty-1.2.3 → check_empty-1.3.0}/check_empty/__main__.py

@@ -1,4 +1,4 @@
-"""Implementation of the main routine. Also exports the argument parser."""
+"""Implementation of the main routine."""
 
 from __future__ import annotations
 

check_empty-1.3.0/check_empty/archives.py

@@ -0,0 +1,45 @@
+"""Functions used to clear files in archives."""
+
+from __future__ import annotations
+
+from .constants import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import zipfile
+    from tarfile import TarFile
+
+    from py7zr import SevenZipFile
+__all__ = ('clear_7z', 'clear_file_in_zip', 'clear_tar')
+_ = __import__('io').BytesIO()
+
+
+def clear_file_in_zip(z: zipfile.ZipFile, i: zipfile.ZipInfo) -> None:
+    """Clear the contents of a file in a .zip archive."""
+    z.writestr(i, b'')
+
+
+def clear_7z(z: SevenZipFile) -> None:
+    """Clear the contents of each file in a .7z archive."""
+    x = z.filename
+    if x is None:
+        raise NotImplementedError
+    y = z.namelist()
+    with __import__('py7zr').SevenZipFile(x, 'w') as a:
+        for n in y:
+            a.writef(_, n)
+
+
+def clear_tar(t: TarFile) -> None:
+    """Clear the contents of each file in a .tar archive."""
+    x = t.name
+    if x is None:
+        raise NotImplementedError
+    import tarfile as z
+
+    with __import__('tempfile').NamedTemporaryFile(
+        suffix='.tar.gz', delete=False
+    ) as p, z.open(fileobj=p, mode='w:gz') as f:
+        a = f.addfile
+        for m in t.getmembers():
+            a(z.TarInfo(m.name))
+    __import__('os').replace(p.name, x)

check_empty-1.3.0/check_empty/constants.py

@@ -0,0 +1,44 @@
+"""Defines constants used by :mod:`check_empty`."""
+
+from __future__ import annotations
+
+import os
+
+TYPE_CHECKING: bool = False
+if TYPE_CHECKING:
+    import typing
+__all__ = ('DIRFD_UNSUPPORTED', 'ENOENT', 'S_IFDIR', 'TYPE_MASK', 'RecurseInto')
+TYPE_MASK: typing.Final = 0xF000
+"""This mask extracts the type of a file from its mode bits from :func:`os.stat`."""
+S_IFDIR: typing.Final = 0x4000
+"""Equal to :const:`stat.S_IFDIR`."""
+ENOENT: typing.Final = 2
+"""Equal to :const:`errno.ENOENT`."""
+DIRFD_UNSUPPORTED: typing.Final[BaseException] = (
+    SystemError('got directory descriptor on Windows')
+    if os.name == 'nt'
+    else NotImplementedError('directory descriptors are not supported')
+)
+"""The exception raised when a directory descriptor is passed to :func:`check`."""
+
+
+class RecurseInto(__import__('enum').IntFlag):
+    """Flags for the ``recurse_into`` argument of :func:`check_empty.check`."""
+
+    NONE = 0
+    """Don't recurse into any archives; the default behaviour."""
+    ZIP = 1
+    """Recurse into .zip archives."""
+    TAR = 2
+    """Recurse into .tar archives."""
+    RAR = 4
+    """Recurse into .rar archives; requires :mod:`!rarfile`."""
+    _7Z = 8
+    """Recurse into .7z archives; requires :mod:`!py7zr`."""
+    LZH = 16
+    """Recurse into .lzh and .lha archives; requires :mod:`!lhafile`."""
+    ALL = 31
+    """Recurse into all archive types."""
+
+
+del os

check_empty-1.3.0/check_empty/reporter.py

@@ -0,0 +1,144 @@
+"""The reporter API for :func:`~check_empty.check`."""
+
+from __future__ import annotations
+
+import sys as s
+
+from .constants import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import typing
+
+__all__ = ('DelayedReporter', 'Reporter')
+
+
+class Reporter:
+    """Type of all reporters accepted by :func:`check` for the ``reporter`` argument."""
+
+    __slots__ = ('o',)
+    o: typing.IO[str] | None
+
+    def __init__(self) -> None:
+        """Initialize the reporter."""
+        self.o = None
+
+    def to(self, out: typing.IO[str] | None = None) -> typing.IO[str] | None:
+        """Temporarily redirect the output of the reporter for one check.
+
+        Args:
+            out: The output stream to redirect to. If ``None``, the reporter will write
+              to :data:`sys.stdout`.
+
+        Returns:
+            The previous output stream, or ``None`` if no redirection is in effect.
+
+        """
+        self.o, o = out, self.o
+        return o
+
+    @staticmethod
+    def calculate_result(y: bool, x: bool, d: bool) -> int:
+        """Set the result of the check as :attr:`r`.
+
+        Returns:
+            The exit code of the check. For the default implementation, this is a
+            bitwise or of 1 (some files were not empty), 4 (some files or directories
+            were absent and :ref:`-m <check-empty--m>` /
+            :ref:`--may-not-exist <check-empty---may-not-exist>` was omitted) and 8
+            (caught :exc:`OSError` while processing some files), such that 0 is
+            correctly the only return value that represents success. The 2 bit is
+            skipped since 2 is the exit code of :class:`argparse.ArgumentParser` when
+            it encounters invalid arguments.
+        """
+        return y | x << 2 | d << 3
+
+    def report(  # ruff: ignore[too-many-arguments, too-many-positional-arguments]
+        self,
+        z: list[str] | None,
+        w: list[str] | None,
+        a: list[str] | None,
+        b: list[str] | None,
+        r: list[tuple[str, int]] | None,
+        x: int,
+        y: int,
+        d: int,
+        p: int,
+        t: int,
+        n: int,
+        v: int,
+        c: bool,
+    ) -> None:
+        """Report the results of the check.
+
+        Args:
+            z: List of paths to files that were not found.
+            w: List of error messages for files that could not be processed.
+            a: List of directories that were recursed into.
+            b: List of empty file paths.
+            r: List of 2-tuples representing non-empty files and their sizes.
+            x: Number of files that were not found.
+            y: Number of non-empty files.
+            d: Number of I/O errors encountered.
+            p: Number of empty files.
+            t: Total size of non-empty files in bytes.
+            n: Total number of files checked.
+            v: The integer value of ``verbosity`` as passed to :func:`check`. For the
+              default implementation, verbosity > 5 is equivalent to verbosity = 5, and
+              a non-positive verbosity gives no output.
+            c: The value of ``clear`` as passed to :func:`check`.
+        """
+        if v <= 0:
+            return
+        q = self.o
+        q = (s.stdout if q is None else q).write
+        if a is not None:
+            q('\nRecursing into directory: '.join(a))
+            q('\n')
+        if z is not None:
+            q('\nNot found: '.join(z))
+        q(
+            f'{x} file{"s" if x > 1 else ""} not found\n'
+            if x
+            else 'All files were found\n'
+        )
+        if w is not None:
+            q('\nError: '.join(w))
+        if d:
+            q(f'{d} I/O error{"s" if d > 1 else ""} encountered\n')
+        if b is not None:
+            q('\nEmpty: '.join(b))
+        if v > 2:  # ruff: ignore[magic-value-comparison]
+            q(f'\n{p or "No"} empty file{"" if p == 1 else "s"}\n')
+        if y:
+            if r is not None:
+                q(
+                    ('\nCleared: ' if c else '\nNot empty: ').join(
+                        __import__('itertools').chain(
+                            ('',), map('%s (%d bytes)'.__mod__, r)
+                        )
+                    )
+                )
+                q('\n')
+            q(f'{y} offending file{"s" if y > 1 else ""}\nTotal size: {t} bytes\n')
+        elif n > x:
+            q('All found files were empty\n')
+
+    def reset_stream(self) -> None:
+        """Reset the reporter, closing the output stream if appropriate."""
+        q, self.o = self.o, None
+        if q not in {None, s.stdout, s.stderr, s.__stdout__, s.__stderr__}:
+            q.close()
+
+
+class DelayedReporter(Reporter):
+    """Only report the results only when :meth:`do_report` is called."""
+
+    __slots__ = ('a',)
+
+    def report(self, *a: typing.Any) -> None:  # ruff: ignore[any-type] # ty: ignore[invalid-method-override]
+        """Store the report arguments for later use."""
+        self.a = a
+
+    def do_report(self) -> None:
+        """Conduct the report for the most recent check using this reporter."""
+        super().report(*self.a)

check_empty-1.3.0/check_empty/util.py

@@ -0,0 +1,86 @@
+"""Utility functions for :mod:`check_empty`."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+
+from .constants import ENOENT, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from tarfile import TarFile
+    from types import TracebackType
+    from typing import Any
+
+    from typing_extensions import Self
+__all__ = ('try_tar',)
+
+
+def try_tar(a: str, f: Callable[[TarFile], Any]) -> bool:
+    """Open a file as a .tar archive and return success.
+
+    Since :func:`tarfile.is_tarfile` calls :func:`tarfile.open` internally and
+    discards the result, using the LBYL approach ends up opening the file twice,
+    incurring twice the I/O cost.
+    Thus, the resultant tarfile is recorded by the callback ``f`` via which the user
+    may retrieve it later. The tarfile is not returned directly because the boolean
+    return value allows this function to be used as a condition in an if-elif-else
+    block, which is integral to the handling of multiple archive formats.
+
+    Args:
+        a: the string path to the file
+        f: the callback
+
+    Returns:
+        Whether the archive was opened and appended to ``e`` with no errors.
+    """
+    import tarfile as m
+
+    with suppress(m.TarError):
+        f(m.open(a))  # ruff: ignore[open-file-with-context-handler]
+        return True
+    return False
+
+
+class Handler:
+    __slots__ = 'a', 'c', 'f', 'j', 'v'
+    a: int | str
+    c: bool
+    f: Callable[[str], None]
+    j: Callable[[str], None]
+    v: str | None
+
+    def __init__(self, *a: Any) -> None:  # ruff: ignore[any-type]
+        self.j, self.f, self.a = a
+        self.v = None
+
+    def __enter__(self) -> Self:
+        self.c = False
+        return self
+
+    def o(self) -> None:
+        with self, open(self.a, 'wb'):
+            ...
+
+    @property
+    def e(self, s: str = 'invalid fd (negative): %d', t: str = 'fd: %d') -> str:  # ruff: ignore[property-with-parameters]
+        r = self.v
+        if r is None:
+            a = self.a
+            self.v = r = (t, s)[a < 0] % a if isinstance(a, int) else a
+        return r
+
+    def __exit__(
+        self,
+        t: type[BaseException] | None,
+        v: BaseException | None,
+        _: TracebackType | None,
+    ) -> bool:
+        if t is None or not isinstance(v, OSError):
+            return False
+        self.j(self.e) if v.errno == ENOENT else self.f(str(v))
+        self.c = True
+        return True
+
+
+del TYPE_CHECKING

{check_empty-1.2.3 → check_empty-1.3.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["uv_build>=0.12.12"]
+requires = ["uv_build>=0.12.13"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -57,8 +57,8 @@ license-files = [
 ]
 name = "check-empty"
 readme = "README.md"
-requires-python = ">=3.6"
-version = "1.2.3"
+requires-python = ">=3.7"
+version = "1.3.0"
 
 [[project.authors]]
 name = "Jonathan Dung"
@@ -68,11 +68,25 @@ email = "jonathandung@yahoo.com"
 name = "Jonathan Dung"
 email = "jonathandung@yahoo.com"
 
+[project.optional-dependencies]
+7z = [
+    "py7zr==1.1.3; python_version >= '3.10'",
+    "py7zr==1.0.0; python_version == '3.9'",
+    "py7zr==0.22.0; python_version == '3.8'",
+    "py7zr==0.20.6; python_version == '3.7'",
+]
+all = ["check-empty[7z,lzh,rar]==1.3.0"]
+lzh = ["lhafile==0.3.1"]
+rar = [
+    "rarfile==4.5; python_version >= '3.10'",
+    "rarfile==4.2; python_version < '3.10'",
+]
+
 [project.scripts]
 check-empty = "check_empty.__main__:main"
 
 [tool.ruff]
-required-version = ">=0.16.6"
+required-version = ">=0.16.7"
 target-version = "py37"
 
 [tool.ruff.analyze]
@@ -83,19 +97,17 @@ quote-style = "single"
 
 [tool.ruff.lint]
 ignore = [
-    "ANN",
     "COM",
     "FBT",
     "PT",
-    "PTH",
     "avoidable-escaped-quote",
     "bad-quotes-inline-string",
+    "builtin-open",
     "complex-structure",
     "docstring-extraneous-exception",
     "implicit-namespace-package",
     "import-outside-top-level",
     "incorrect-blank-line-before-class",
-    "magic-value-comparison",
     "multi-line-summary-second-line",
     "non-empty-init-module",
     "print",
@@ -111,12 +123,20 @@ select = ["ALL"]
 combine-as-imports = true
 
 [tool.ruff.lint.per-file-ignores]
-"test_check_empty.py" = ["D"]
+"test_check_empty.py" = [
+    "ANN",
+    "D",
+]
 "!__init__.py" = ["missing-copyright-notice"]
+"__main__.py" = ["missing-return-type-private-function"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ruff.lint.pylint]
+max-args = 6
+max-nested-blocks = 6
+
 [tool.ty.analysis]
 respect-type-ignore-comments = false
 
@@ -128,8 +148,29 @@ python-platform = "all"
 all = "error"
 missing-override-decorator = "ignore"
 
+[[tool.ty.overrides]]
+include = ["check_empty/__init__.py"]
+
+[tool.ty.overrides.rules]
+redundant-condition = "ignore"
+unsound-assignment = "ignore"
+
 [tool.uv]
-required-version = ">=0.12.12"
+required-version = ">=0.12.13"
+
+[tool.uv.audit]
+ignore = [
+    "GHSA-gjrg-mpp7-g774",
+    "GHSA-h4gh-22qq-72r7",
+    "GHSA-q6rc-2cgv-63h7",
+    "GHSA-gjrg-mpp7-g774",
+    "GHSA-h4gh-22qq-72r7",
+    "GHSA-q6rc-2cgv-63h7",
+    "GHSA-gjrg-mpp7-g774",
+    "GHSA-h4gh-22qq-72r7",
+    "GHSA-q6rc-2cgv-63h7",
+    "GHSA-jfmj-5v4g-7637",
+]
 
 [tool.uv.build-backend]
 module-name = "check_empty"

{check_empty-1.2.3 → check_empty-1.3.0}/pyproject.toml.orig

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["uv_build>=0.12.12"]
+requires = ["uv_build>=0.12.13"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -15,14 +15,20 @@ license-files = ["LICENSE", "AUTHORS.md"]
 maintainers = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
 name = "check-empty"
 readme = "README.md"
-requires-python = ">=3.6"
-version = "1.2.3"
+requires-python = ">=3.7"
+version = "1.3.0"
+
+[project.optional-dependencies]
+"7z" = ["py7zr==1.1.3; python_version >= '3.10'", "py7zr==1.0.0; python_version == '3.9'", "py7zr==0.22.0; python_version == '3.8'", "py7zr==0.20.6; python_version == '3.7'"]
+all = ["check-empty[7z,lzh,rar]==1.3.0"]
+lzh = ["lhafile==0.3.1"]
+rar = ["rarfile==4.5; python_version >= '3.10'", "rarfile==4.2; python_version < '3.10'"]
 
 [project.scripts]
 check-empty = "check_empty.__main__:main"
 
 [tool.ruff]
-required-version = ">=0.16.6"
+required-version = ">=0.16.7"
 target-version = "py37"
 
 [tool.ruff.analyze]
@@ -32,7 +38,7 @@ type-checking-imports = false
 quote-style = "single"
 
 [tool.ruff.lint]
-ignore = ["ANN", "COM", "FBT", "PT", "PTH", "avoidable-escaped-quote", "bad-quotes-inline-string", "complex-structure", "docstring-extraneous-exception", "implicit-namespace-package", "import-outside-top-level", "incorrect-blank-line-before-class", "magic-value-comparison", "multi-line-summary-second-line", "non-empty-init-module", "print", "too-many-branches", "too-many-locals", "too-many-statements", "unnecessary-dunder-call"]
+ignore = ["COM", "FBT", "PT", "avoidable-escaped-quote", "bad-quotes-inline-string", "builtin-open", "complex-structure", "docstring-extraneous-exception", "implicit-namespace-package", "import-outside-top-level", "incorrect-blank-line-before-class", "multi-line-summary-second-line", "non-empty-init-module", "print", "too-many-branches", "too-many-locals", "too-many-statements", "unnecessary-dunder-call"]
 preview = true
 select = ["ALL"]
 
@@ -40,12 +46,17 @@ select = ["ALL"]
 combine-as-imports = true
 
 [tool.ruff.lint.per-file-ignores]
-"test_check_empty.py" = ["D"]
+"test_check_empty.py" = ["ANN", "D"]
 "!__init__.py" = ["missing-copyright-notice"]
+"__main__.py" = ["missing-return-type-private-function"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ruff.lint.pylint]
+max-args = 6
+max-nested-blocks = 6
+
 [tool.ty.analysis]
 respect-type-ignore-comments = false
 
@@ -57,8 +68,26 @@ python-platform = "all"
 all = "error"
 missing-override-decorator = "ignore"
 
+[[tool.ty.overrides]]
+include = ["check_empty/__init__.py"]
+rules = {redundant-condition = "ignore", unsound-assignment = "ignore"}
+
 [tool.uv]
-required-version = ">=0.12.12"
+required-version = ">=0.12.13"
+
+[tool.uv.audit]
+ignore = [
+  "GHSA-gjrg-mpp7-g774",
+  "GHSA-h4gh-22qq-72r7",
+  "GHSA-q6rc-2cgv-63h7",
+  "GHSA-gjrg-mpp7-g774",
+  "GHSA-h4gh-22qq-72r7",
+  "GHSA-q6rc-2cgv-63h7",
+  "GHSA-gjrg-mpp7-g774",
+  "GHSA-h4gh-22qq-72r7",
+  "GHSA-q6rc-2cgv-63h7",
+  "GHSA-jfmj-5v4g-7637",
+]
 
 [tool.uv.build-backend]
 module-name = "check_empty"

check_empty-1.2.3/check_empty/__init__.py

@@ -1,276 +0,0 @@
-# Copyright © 2026 Jonathan Dung. All rights reserved.
-# SPDX-License-Identifier: MIT
-"""Utility to check the emptiness of files and directories.
-
-Pre-commit hook, command-line tool and GitHub Action all-in-one.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from itertools import chain
-
-__all__ = ('DelayedReporter', 'Reporter', 'check', 'default_reporter')
-__version__ = '1.2.3'
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    import typing
-    from collections.abc import Iterable
-
-    from _typeshed import FileDescriptorOrPath
-_DIRECTORY_DESCRIPTOR_UNSUPPORTED: BaseException = (
-    SystemError('got directory descriptor on Windows')
-    if os.name == 'nt'
-    else NotImplementedError('directory descriptors are not supported')
-)
-_TYPE_MASK: int = 0xF000
-_S_IFDIR: int = 0x4000
-
-
-class _Handler:
-    __slots__ = 'a', 'c', 'f', 'j', 'v'
-
-    def __init__(self, *a):
-        self.j, self.f, self.a = a
-        self.v = None
-
-    def __enter__(self):
-        self.c = False
-        return self
-
-    def o(self):
-        with self, open(self.a, 'wb'):
-            ...
-
-    @property
-    def e(self, s='invalid fd (negative): %d', t='fd: %d'):  # ruff: ignore[property-with-parameters]
-        r = self.v
-        if r is None:
-            a = self.a
-            self.v = r = (t, s)[a < 0] % a if isinstance(a, int) else os.fsdecode(a)
-        return r
-
-    def __exit__(self, t, v, _):
-        if t is None or not issubclass(t, OSError):
-            return False
-        self.j(self.e) if v.errno == 2 else self.f(str(v))
-        self.c = True
-        return True
-
-
-class Reporter:
-    """Type of all reporters that :func:`check` accepts as the ``reporter`` argument."""
-    __slots__ = 'o',
-    o: typing.IO[str] | None
-
-    def __init__(self):
-        """Initialize the reporter."""
-        self.o = None
-
-    def to(self, out: typing.IO[str] | None = None) -> typing.IO[str] | None:
-        """Temporarily redirect the output of the reporter for one check.
-
-        Args:
-            out: The output stream to redirect to. If ``None``, the reporter will write
-              to :data:`sys.stdout`.
-
-        Returns:
-            The previous output stream.
-
-        """
-        self.o, o = out, self.o
-        return o
-
-    @staticmethod
-    def calculate_result(y: bool, x: bool, d: bool) -> int:
-        """Set the result of the check as :attr:`r`.
-
-        Returns:
-            The exit code of the check. For the default implementation, this is a
-            bitwise or of 1 (some files were not empty), 4 (some files or directories
-            were absent and :ref:`-m <check-empty--m>` / :ref:`--may-not-exist
-            <check-empty---may-not-exist>` was omitted) and 8 (caught :exc:`OSError`
-            while processing some files), such that 0 is correctly the only return
-            value that represents success. The 2 bit is skipped since 2 is the exit
-            code of :class:`argparse.ArgumentParser` when it encounters invalid
-            arguments.
-        """
-        return y | x << 2 | d << 3
-
-    def report(self, z, w, r, x, y, d, p, a, b, t, n, v, c):  # ruff: ignore[too-many-arguments, too-many-positional-arguments]
-        """Report the results of the check.
-
-        Args:
-            z: List of files that were not found.
-            w: List of error messages for files that could not be processed.
-            r: List of 2-tuples representing non-empty files and their sizes.
-            x: Number of files that were not found.
-            y: Number of non-empty files.
-            d: Number of I/O errors encountered.
-            p: Number of empty files.
-            a: List of directories that were recursed into.
-            b: List of empty file paths.
-            t: Total size of non-empty files in bytes.
-            n: Total number of files checked.
-            v: The value of ``verbosity`` as passed to :func:`check`. For the default
-              implementation, verbosity > 5 is equivalent to verbosity = 5, and a
-              non-positive verbosity gives no output.
-            c: The value of ``clear`` as passed to :func:`check`.
-        """
-        q = self.o
-        q = (sys.stdout if q is None else q).write
-        if a is not None:
-            q('\nRecursing into directory: '.join(a))
-            q('\n')
-        if z is not None:
-            q('\nNot found: '.join(z))
-        q(
-            f'{x} file{"s" if x > 1 else ""} not found\n'
-            if x
-            else 'All files were found\n'
-        )
-        if w is not None:
-            q('\nError: '.join(w))
-        if d:
-            q(f'{d} I/O error{"s" if d > 1 else ""} encountered\n')
-        if b is not None:
-            q('\nEmpty: '.join(b))
-        if v > 2:
-            q(f'\n{p or "No"} empty file{"" if p == 1 else "s"}\n')
-        if y:
-            if r is not None:
-                q(
-                    ('\nCleared: ' if c else '\nNot empty: ').join(
-                        chain(('',), map('%s (%d bytes)'.__mod__, r))
-                    )
-                )
-                q('\n')
-            q(f'{y} offending file{"s" if y > 1 else ""}\nTotal size: {t} bytes\n')
-        elif n > x:
-            q('All found files were empty\n')
-
-    def reset_stream(self) -> None:
-        """Reset the reporter, closing the output stream if appropriate."""
-        q, self.o = self.o, None
-        if q not in {None, sys.stdout, sys.stderr, sys.__stdout__, sys.__stderr__}:
-            q.close()
-
-
-class DelayedReporter(Reporter):
-    """Only report the results only when :meth:`do_report` is called."""
-    __slots__ = ('a',)
-
-    def report(self, *a):  # ty: ignore[invalid-method-override]
-        """Store the report arguments for later use."""
-        self.a = a
-
-    def do_report(self) -> None:
-        """Conduct the report for the most recent check using this reporter."""
-        super().report(*self.a)
-
-
-default_reporter: Reporter = Reporter()
-"""The default reporter used by :func:`check`."""
-
-
-def check(
-    files: Iterable[FileDescriptorOrPath],
-    *,
-    clear: bool = False,
-    may_not_exist: bool = False,
-    verbosity: typing.SupportsIndex = 2,
-    reporter: Reporter = default_reporter,
-) -> int:
-    """Check the emptiness of files, recursing into directories if passed.
-
-    Args:
-        files: an iterable of file descriptors or paths representing the files and
-          directories to check; directory descriptors (*nix) are not supported.
-        clear: if ``True``, clear the contents of non-empty files; directories, notably,
-          are not purged, but all files within should become empty.
-        may_not_exist: if ``True``, do not treat absent files or directories as errors.
-        verbosity: how much detail the program should print to stdout.
-        reporter: The reporter to use for reporting the results. All output of this
-          function is produced by the reporter.
-
-    Returns:
-        The integer exit code calculated by the reporter.
-    """
-    files = list(files)
-    if not files:
-        return 0
-    k, j, t, n, o = [0] * 4, [], 0, len(files), files.pop
-    u, e, _ = j.extend, j.pop, lambda v: lambda _, k=k: k.__setitem__(v, k[v] + 1)
-    verbosity = max(0, type(verbosity).__index__(verbosity))
-    if verbosity > 4:
-        b = ['']
-        f = b.append
-    else:
-        b, f = None, _(0)
-    if verbosity > 3:
-        v = ['']
-        x = v.append
-    else:
-        v, x = None, lambda _: None
-    if verbosity > 2:
-        z, w = [''], ['']
-        i = z.append, w.append
-    else:
-        z = w = None
-        i = _(1), _(2)
-    if verbosity > 1:
-        r = []
-        g = r.append
-    else:
-        r, g = None, _(3)
-    while files:
-        a = o()
-        with _Handler(*i, a) as h:
-            q = os.stat(a)
-        if h.c:
-            continue
-        c = h.e
-        if q.st_mode & _TYPE_MASK == _S_IFDIR:
-            if isinstance(a, int):
-                raise _DIRECTORY_DESCRIPTOR_UNSUPPORTED
-            x(c)
-            u(os.scandir(c))
-            continue
-        s = q.st_size
-        if not s:
-            f(c)
-            continue
-        g((c, s))
-        t += s
-        if clear:
-            h.o()
-    del o, files
-    while j:
-        m = e()
-        a = m.path
-        if m.is_dir():
-            x(a)
-            u(os.scandir(a))
-            continue
-        n += 1
-        s = m.stat().st_size
-        if not s:
-            f(a)
-            continue
-        g((a, s))
-        t += s
-        if clear:
-            _Handler(*i, a).o()
-    x = k[1] if z is None else len(z) - 1
-    d = k[2] if w is None else len(w) - 1
-    y = k[3] if r is None else len(r)
-    if verbosity:
-        p = k[0] if b is None else len(b) - 1
-        reporter.report(z, w, r, x, y, d, p, v, b, t, n, verbosity, clear)
-    reporter.reset_stream()
-    return reporter.calculate_result(*map(bool, (y, x and not may_not_exist, d)))
-
-
-del TYPE_CHECKING