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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-empty
-Version: 1.3.0
+Version: 2.0.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
@@ -15,9 +15,6 @@ Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -28,19 +25,19 @@ 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: py7zr==1.1.3 ; extra == '7z'
+Requires-Dist: acefile==0.6.14 ; extra == 'ace'
+Requires-Dist: check-empty[7z,ace,ar,lzh,rar]==2.0.0 ; extra == 'all'
+Requires-Dist: arpy==2.4.0 ; extra == 'ar'
 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'
+Requires-Dist: rarfile==4.5 ; extra == 'rar'
 Maintainer: Jonathan Dung
 Maintainer-email: Jonathan Dung <jonathandung@yahoo.com>
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Provides-Extra: 7z
+Provides-Extra: ace
 Provides-Extra: all
+Provides-Extra: ar
 Provides-Extra: lzh
 Provides-Extra: rar
 Description-Content-Type: text/markdown
@@ -60,11 +57,7 @@ specified.
 
 ## Prerequisites
 
-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.
+Supports every Python 3.10 runtime. There are no other requirements.
 
 ## Quickstart
 
@@ -132,7 +125,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.3.0 # repository version
+  rev: v2.0.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -148,7 +141,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.3.0"
+rev = "v2.0.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -172,7 +165,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.3.0"
+rev = "v2.0.0"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -192,13 +185,11 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.3.0 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v2.0.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.7 is supported but not recommended due to end-of-life
-    verbosity: 1
     filenames: |
       src/mylib/py.typed
       docs/.nojekyll
@@ -211,26 +202,34 @@ steps:
 
 Also see the GitHub Action
 [manifest](https://github.com/jonathandung/check-empty/blob/main/action.yaml), which
-contains the accepted action inputs and descriptions thereof.
+contains the accepted action inputs, action outputs produced and their respective
+descriptions.
 
 ## Notes
 
-1. If your file name starts with a hyphen, to avoid having it misinterpreted as a flag,
-use a command of the form `check-empty -- -this_is_actually_a_file.txt`.
+1. If your file name starts with a hyphen, use a command of the form
+`check-empty -- -this_is_actually_a_file.txt` to avoid having the filename
+misinterpreted as a flag.
 2. Forward slashes can be used even on Windows, so there is no need to escape anything.
 3. Glob patterns are supported on \*nix only. If on Windows, use a shell like Git Bash.
 4. To pass an
 [argfile](https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars), use
 the `@` prefix, and escape files whose names actually start with `@` using the
 double-hyphen syntax.
-5. It may be unintuitive that a directory being "empty" means all its files are empty,
-but this project explicitly targets files, since version control systems track files
-rather than directories.
-6. The program does not recurse into archives, since identification of compressed
-archives would require reading the first few bytes of each file seen, which is
-error-prone and inefficient.
-
-## Additional Links
+5. It may be unintuitive that a directory or archive being "empty" means all its files
+are empty, but this project explicitly targets files, since version control systems
+track files rather than directories.
+6. The program can recurse into some archives if specified, but it requires certain
+libraries to be installed to do so for certain formats. .7z (corresponding to the `7z`
+extra) needs `py7zr`, .rar (the `rar` extra) needs `rarfile`, .lha / .lzh (the `lzh`
+extra) needs `lhafile`, .a / .ar / .lib (the `ar` extra) needs `arpy`, .ace (the `ace`
+extra) needs `acefile`. These may also slow down the checking significantly for large
+directories, since magic numbers must be read for every file and the I/O overhead
+accumulates. All the above extras are included in the `all` extra.
+7. Keep weird characters in your filenames to a minimum. They may become a problem in
+GitHub Actions usage.
+
+## Additional links
 
 - [API and CLI Reference](https://check-empty.readthedocs.io)
 - [Releases](https://github.com/jonathandung/check-empty/releases)
@@ -252,8 +251,7 @@ into a virtual environment.
 Tests are run with:
 
 ```bash
-python -m test_check_empty # explicit; or
-python -m unittest discover # alternative
+python -m test_check_empty
 ```
 
 at the project root. `pytest` is not needed.

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

@@ -13,11 +13,7 @@ specified.
 
 ## Prerequisites
 
-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.
+Supports every Python 3.10 runtime. There are no other requirements.
 
 ## Quickstart
 
@@ -85,7 +81,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.3.0 # repository version
+  rev: v2.0.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -101,7 +97,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.3.0"
+rev = "v2.0.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -125,7 +121,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.3.0"
+rev = "v2.0.0"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -145,13 +141,11 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.3.0 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v2.0.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.7 is supported but not recommended due to end-of-life
-    verbosity: 1
     filenames: |
       src/mylib/py.typed
       docs/.nojekyll
@@ -164,26 +158,34 @@ steps:
 
 Also see the GitHub Action
 [manifest](https://github.com/jonathandung/check-empty/blob/main/action.yaml), which
-contains the accepted action inputs and descriptions thereof.
+contains the accepted action inputs, action outputs produced and their respective
+descriptions.
 
 ## Notes
 
-1. If your file name starts with a hyphen, to avoid having it misinterpreted as a flag,
-use a command of the form `check-empty -- -this_is_actually_a_file.txt`.
+1. If your file name starts with a hyphen, use a command of the form
+`check-empty -- -this_is_actually_a_file.txt` to avoid having the filename
+misinterpreted as a flag.
 2. Forward slashes can be used even on Windows, so there is no need to escape anything.
 3. Glob patterns are supported on \*nix only. If on Windows, use a shell like Git Bash.
 4. To pass an
 [argfile](https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars), use
 the `@` prefix, and escape files whose names actually start with `@` using the
 double-hyphen syntax.
-5. It may be unintuitive that a directory being "empty" means all its files are empty,
-but this project explicitly targets files, since version control systems track files
-rather than directories.
-6. The program does not recurse into archives, since identification of compressed
-archives would require reading the first few bytes of each file seen, which is
-error-prone and inefficient.
-
-## Additional Links
+5. It may be unintuitive that a directory or archive being "empty" means all its files
+are empty, but this project explicitly targets files, since version control systems
+track files rather than directories.
+6. The program can recurse into some archives if specified, but it requires certain
+libraries to be installed to do so for certain formats. .7z (corresponding to the `7z`
+extra) needs `py7zr`, .rar (the `rar` extra) needs `rarfile`, .lha / .lzh (the `lzh`
+extra) needs `lhafile`, .a / .ar / .lib (the `ar` extra) needs `arpy`, .ace (the `ace`
+extra) needs `acefile`. These may also slow down the checking significantly for large
+directories, since magic numbers must be read for every file and the I/O overhead
+accumulates. All the above extras are included in the `all` extra.
+7. Keep weird characters in your filenames to a minimum. They may become a problem in
+GitHub Actions usage.
+
+## Additional links
 
 - [API and CLI Reference](https://check-empty.readthedocs.io)
 - [Releases](https://github.com/jonathandung/check-empty/releases)
@@ -205,8 +207,7 @@ into a virtual environment.
 Tests are run with:
 
 ```bash
-python -m test_check_empty # explicit; or
-python -m unittest discover # alternative
+python -m test_check_empty
 ```
 
 at the project root. `pytest` is not needed.

{check_empty-1.3.0 → check_empty-2.0.0}/check_empty/__init__.py

@@ -1,6 +1,6 @@
 # Copyright © 2026 Jonathan Dung. All rights reserved.
 # SPDX-License-Identifier: MIT
-"""Utility to check the emptiness of files and directories.
+"""Utility to check the emptiness of files.
 
 Pre-commit hook, command-line tool and GitHub Action all-in-one.
 """
@@ -8,36 +8,111 @@ Pre-commit hook, command-line tool and GitHub Action all-in-one.
 from __future__ import annotations
 
 import os
+from contextlib import suppress
 
-from . import constants, reporter, util
+from . import constants, reporter
 
-if constants.TYPE_CHECKING:
-    import typing
-    from collections.abc import Iterable
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from types import ModuleType, TracebackType
+    from typing import Any, SupportsIndex
 
     from _typeshed import FileDescriptorOrPath
+    from typing_extensions import Self
 
-__all__ = ('check', 'default_reporter')
-__version__ = '1.3.0'
+__all__ = ('Handler', 'check', 'default_reporter')
+__version__ = '2.0.0'
+"""The version of the package."""
 default_reporter: reporter.Reporter = reporter.Reporter()
 """The default reporter used by :func:`check`."""
 
 
+class Handler:
+    """Used to handle errors when opening a file."""
+
+    __slots__ = 'a', 'c', 'f', 'j', 'v'
+    a: int | str
+    """The file descriptor or string path to the file being handled."""
+    c: bool
+    """Whether an I/O error was handled."""
+    f: Callable[[str], None]
+    """The function to call when handling an I/O error.
+
+    Should take a string representing the error message as the only argument and
+    preferably return ``None``.
+    """
+    j: Callable[[str], None]
+    """The function to call when handling the case where the file is missing.
+
+    Should take the path to the file or a string encapsulating the validity of the file
+    descriptor as the only argument and preferably return ``None``.
+    """
+    v: str | None
+    """The cached value of :attr:`e`."""
+
+    def __init__(self, *a: Any) -> None:  # ruff: ignore[any-type]
+        """Initialize the handler."""
+        self.j, self.f, self.a = a
+        self.v = None
+
+    def __enter__(self) -> Self:
+        """Enter the handler context.
+
+        Returns:
+            The handler itself.
+        """
+        self.c = False
+        return self
+
+    def o(self) -> None:
+        """Clear the file immediately."""
+        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]
+        """The file path itself, or the file descriptor coerced to a string."""
+        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:
+        """Exit the handler context.
+
+        Returns:
+            Whether there was an exception that is to be suppressed.
+        """
+        if t is None or not isinstance(v, OSError):
+            return False
+        self.j(self.e) if v.errno == constants.ENOENT else self.f(str(v))
+        self.c = True
+        return True
+
+
 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,
+    verbosity: SupportsIndex = 2,
+    recurse_into: SupportsIndex = constants.RecurseInto.NONE,
+    reporter: reporter.abc.ReporterABC = 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.
+    If using a custom reporter and you want to use all the information that can be
+    gathered during the check, remember to pass a ``verbosity`` greater than or equal
+    to 5, since some parameters to :meth:`~check_empty.reporter.Reporter.report` will
+    take values of ``None`` otherwise.
 
     Args:
         files: an iterable of file descriptors or paths representing the files and
@@ -85,20 +160,17 @@ def check(
     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,
-    )
+    zp, tr, rr, z7, ar, lh, ac = map(recurse_into.__and__, constants.ARCHIVE_FORMATS)
     an = bool(recurse_into)
     if an:
-        from . import archives as ar
+        from . import archives as av
     md = 'a' if clear else 'r'
-    if constants.TYPE_CHECKING:
+    if TYPE_CHECKING:
         import tarfile as tr
         import zipfile as zp
 
+        import acefile as ac
+        import arpy as ar
         import lhafile as lh
         import py7zr as z7
         import rarfile as rr
@@ -107,6 +179,10 @@ def check(
             import tarfile as tr
         if zp:
             import zipfile as zp
+        if ac:
+            import acefile as ac
+        if ar:
+            import arpy as ar
         if lh:
             import lhafile as lh
         if z7:
@@ -115,8 +191,6 @@ def check(
             import rarfile as rr
 
     def ha(a: str) -> bool:
-        if not an:
-            return False
 
         def c() -> None:
             nonlocal t
@@ -134,15 +208,20 @@ def check(
             else:
                 f(a)
 
-        y = []
-        if tr and util.try_tar(a, y.append):
-            d = y.pop()
+        def v(m: ModuleType, e: str) -> bool:
+            nonlocal d
+            with suppress(getattr(m, e)):
+                d = m.open(a)
+                return True
+            return False
+
+        if tr and v(tr, 'TarError'):
             aa(a)
             for r in d.getmembers():
                 a, s = q = r.name, r.size
                 e()
             if clear:
-                ar.clear_tar(d)
+                av.purge_tar(d)
         elif zp and zp.is_zipfile(a):
             with zp.ZipFile(a, md) as d:
                 aa(a)
@@ -151,7 +230,7 @@ def check(
                     if s:
                         c()
                         if clear:
-                            ar.clear_file_in_zip(d, r)
+                            av.clear_file_in_zip(d, r)
                     else:
                         f(a)
         elif z7 and z7.is_7zfile(a):
@@ -161,7 +240,7 @@ def check(
                     a, s = q = r.filename, r.origin.stat().st_size
                     e()
                 if clear:
-                    ar.clear_7z(d)
+                    av.purge_7z(d)
         elif rr and rr.is_rarfile(a):
             m = 'Cannot clear files in RAR archives'
             with rr.RarFile(a) as d:
@@ -169,7 +248,19 @@ def check(
                 for r in d.infolist():
                     a, s = q = r.filename, r.file_size
                     w()
-        else:
+        elif ar and v(ar, 'ArchiveFormatError'):
+            aa(a)
+            for r in d.infolist():
+                a, s = q = r.name, r.size
+                e()
+            if clear:
+                av.purge_ar(d, ar.HEADER_GNU)
+        elif ac and v(ac, 'AceError'):
+            aa(a)
+            for r in filter(ac.AceMember.is_reg, d):
+                a, s = q = r.filename, r.size
+                w()
+        elif lh:
             try:
                 d = lh.LhaFile(a)
             except (RuntimeError, lh.BadLhafile):
@@ -179,16 +270,23 @@ def check(
             for r in d.filelist:
                 a, s = q = r.filename, r.file_size
                 w()
+        else:
+            return False
         return True
 
+    def hb(a: str) -> bool:
+        try:
+            return an and ha(a)
+        except Exception as e:  # ruff: ignore[blind-except]
+            i[1](str(e))
+            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:
+        with Handler(*i, a) as h:
             q = os.stat(a)  # ruff: ignore[os-stat]
         if q is None:
             continue
@@ -199,6 +297,8 @@ def check(
             x(c)
             u(os.scandir(c))
             continue
+        if isinstance(a, str) and hb(a):
+            continue
         s = q.st_size
         if not s:
             f(c)
@@ -215,7 +315,7 @@ def check(
             x(a)
             u(os.scandir(a))
             continue
-        if ha(a):
+        if hb(a):
             continue
         n += 1
         s = m.stat().st_size
@@ -225,10 +325,10 @@ def check(
         g((a, s))
         t += s
         if clear:
-            util.Handler(*i, a).o()
+            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()
+    reporter.report(z, w, v, b, r, x, y, d, p, n, t, verbosity, clear)
+    reporter.reset_out()
     return reporter.calculate_result(*map(bool, (y, x and not may_not_exist, d)))

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

@@ -33,6 +33,16 @@ f(
 f('-Q', '--quiet', action='count', default=0, help='decrease output verbosity')
 f('-V', '--verbose', action='count', default=0, help='increase output verbosity')
 f('-o', '--out', help='write output to this file instead of stdout')
+f = _p.add_argument_group(
+    'archive recursion', 'options for recursing into archives'
+).add_argument
+f('-z', '--zip', action='store_true', help='recurse into .zip archives')
+f('-t', '--tar', action='store_true', help='recurse into .tar archives')
+f('-r', '--rar', action='store_true', help='recurse into .rar archives')
+f('-a', '--ar', action='store_true', help='recurse into .a, .ar and .lib archives')
+f('-7', '--7z', action='store_true', dest='z7', help='recurse into .7z archives')
+f('-l', '--lzh', action='store_true', help='recurse into .lzh and .lha archives')
+f('-A', '--ace', action='store_true', help='recurse into .ace archives')
 
 
 def _r():
@@ -57,10 +67,16 @@ def main(argv: Iterable[str] | None = None) -> int:
     if o is not None:
         # ruff: ignore[open-file-with-context-handler]
         c.default_reporter.to(open(o, 'w', encoding='utf-8'))
+    m = c.constants
+    r = m.RecurseInto.NONE
+    for a in m.ARCHIVE_FORMATS:
+        if getattr(n, a._name_.lower()):
+            r |= a
     return c.check(
         n.filenames,
         clear=n.clear,
         may_not_exist=n.may_not_exist,
+        recurse_into=r,
         verbosity=2 + n.verbose - n.quiet,
     )