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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-empty
-Version: 1.2.2
+Version: 1.2.3
 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
@@ -115,7 +115,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.2.2 # repository version
+  rev: v1.2.3 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -131,7 +131,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.2"
+rev = "v1.2.3"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -155,7 +155,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.2"
+rev = "v1.2.3"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -175,7 +175,7 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.2.2 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v1.2.3 # 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:

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

@@ -80,7 +80,7 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v1.2.2 # repository version
+  rev: v1.2.3 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
@@ -96,7 +96,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.2"
+rev = "v1.2.3"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -120,7 +120,7 @@ or (TOML 1.1+):
 # using multiline inline tables
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v1.2.2"
+rev = "v1.2.3"
 hooks = [{
   id = "check-empty",
   args = ["-Q"],
@@ -140,7 +140,7 @@ As a GitHub Actions workflow step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v1.2.2 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v1.2.3 # 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:

check_empty-1.2.3/check_empty/__init__.py

@@ -0,0 +1,276 @@
+# 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

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

@@ -6,11 +6,8 @@ import check_empty as c
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    import typing
     from collections.abc import Iterable
-
-    from check_empty import ExitCode
-__all__ = 'main',
+__all__ = ('main',)
 _p = __import__('argparse').ArgumentParser(
     'check-empty',
     description='Assert or enforce that some files, or even directories, are empty. '
@@ -42,7 +39,7 @@ def _r():
     return _p
 
 
-def main(argv: Iterable[str] | None = None) -> ExitCode | typing.Literal[2]:
+def main(argv: Iterable[str] | None = None) -> int:
     """Run the hook/CLI on the files in the command-line arguments passed.
 
     Args:
@@ -59,18 +56,13 @@ def main(argv: Iterable[str] | None = None) -> ExitCode | typing.Literal[2]:
     o = n.out
     if o is not None:
         # ruff: ignore[open-file-with-context-handler]
-        o = open(o, 'w', encoding='utf-8')
-    try:
-        return c.check(
-            n.filenames,
-            clear=n.clear,
-            may_not_exist=n.may_not_exist,
-            verbosity=2 + n.verbose - n.quiet,
-            out=o,
-        )
-    finally:
-        if o is not None:
-            o.close()
+        c.default_reporter.to(open(o, 'w', encoding='utf-8'))
+    return c.check(
+        n.filenames,
+        clear=n.clear,
+        may_not_exist=n.may_not_exist,
+        verbosity=2 + n.verbose - n.quiet,
+    )
 
 
 del f, TYPE_CHECKING

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

@@ -1,7 +1,17 @@
 [build-system]
-requires = ["uv_build>=0.12.10"]
+requires = ["uv_build>=0.12.12"]
 build-backend = "uv_build"
 
+[dependency-groups]
+docs = [
+    "furo==2025.12.19",
+    "sphinx==9.1.0",
+    "sphinx-argparse-cli==1.22.1",
+    "sphinx-copybutton==0.5.2",
+    "sphinx-lint==1.0.2",
+    "sphinx-notfound-page==1.1.0",
+]
+
 [project]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -48,7 +58,7 @@ license-files = [
 name = "check-empty"
 readme = "README.md"
 requires-python = ">=3.6"
-version = "1.2.2"
+version = "1.2.3"
 
 [[project.authors]]
 name = "Jonathan Dung"
@@ -61,16 +71,6 @@ email = "jonathandung@yahoo.com"
 [project.scripts]
 check-empty = "check_empty.__main__:main"
 
-[dependency-groups]
-docs = [
-    "furo==2025.12.19",
-    "sphinx==9.1.0",
-    "sphinx-argparse-cli==1.22.1",
-    "sphinx-copybutton==0.5.2",
-    "sphinx-lint==1.0.2",
-    "sphinx-notfound-page==1.1.0",
-]
-
 [tool.ruff]
 required-version = ">=0.16.6"
 target-version = "py37"
@@ -129,7 +129,7 @@ all = "error"
 missing-override-decorator = "ignore"
 
 [tool.uv]
-required-version = ">=0.12.10"
+required-version = ">=0.12.12"
 
 [tool.uv.build-backend]
 module-name = "check_empty"

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

@@ -1,7 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.12.10"]
+requires = ["uv_build>=0.12.12"]
 build-backend = "uv_build"
 
+[dependency-groups]
+docs = ["furo==2025.12.19", "sphinx==9.1.0", "sphinx-argparse-cli==1.22.1", "sphinx-copybutton==0.5.2", "sphinx-lint==1.0.2", "sphinx-notfound-page==1.1.0"]
+
 [project]
 authors = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
 classifiers = ["Development Status :: 5 - Production/Stable", "Environment :: Console", "Intended Audience :: Developers", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", "Programming Language :: Python :: 3.15", "Programming Language :: Python :: 3.16", "Programming Language :: Python :: Free Threading :: 3 - Stable", "Topic :: Utilities", "Typing :: Typed"]
@@ -13,10 +16,7 @@ maintainers = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
 name = "check-empty"
 readme = "README.md"
 requires-python = ">=3.6"
-version = "1.2.2"
-
-[dependency-groups]
-docs = ["furo==2025.12.19", "sphinx==9.1.0", "sphinx-argparse-cli==1.22.1", "sphinx-copybutton==0.5.2", "sphinx-lint==1.0.2", "sphinx-notfound-page==1.1.0"]
+version = "1.2.3"
 
 [project.scripts]
 check-empty = "check_empty.__main__:main"
@@ -58,7 +58,7 @@ all = "error"
 missing-override-decorator = "ignore"
 
 [tool.uv]
-required-version = ">=0.12.10"
+required-version = ">=0.12.12"
 
 [tool.uv.build-backend]
 module-name = "check_empty"

check_empty-1.2.2/check_empty/__init__.py

@@ -1,195 +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
-
-__all__ = ('ExitCode', 'check')
-__version__ = '1.2.2'
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    import typing
-    from collections.abc import Iterable
-
-    from _typeshed import FileDescriptorOrPath
-
-    ExitCode: typing.TypeAlias = typing.Literal[0, 1, 4, 5, 8, 9, 12, 13]
-else:
-    ExitCode = int
-_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
-
-
-def check(
-    files: Iterable[FileDescriptorOrPath],
-    *,
-    clear: bool = False,
-    may_not_exist: bool = False,
-    verbosity: typing.SupportsIndex = 2,
-    out: typing.IO[str] | None = None,
-) -> ExitCode:
-    """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 (Unix) 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; verbosity > 5 is
-          equivalent to verbosity = 5, and a non-positive verbosity gives no output.
-        out: The file to which output is printed; default :data:`sys.stdout`.
-
-    Returns:
-        The integer exit code. 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.
-
-    """
-    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 = type(verbosity).__index__(verbosity)
-    if verbosity > 4:
-        b = ['']
-        f = b.append
-    else:
-        b, f = None, _(0)
-    if verbosity > 3:
-        rc = ['']
-        x = rc.append
-    else:
-        rc, 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(f'{c} ({s} bytes)')
-        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(f'{a} ({s} bytes)')
-        t += s
-        if clear:
-            _Handler(*i, a).o()
-    x = k[1] if z is None else len(z) - 1
-    y = k[3] if r is None else len(r) - 1
-    d = k[2] if w is None else len(w) - 1
-    v = bool(y) | (bool(x) and not may_not_exist) << 2 | bool(d) << 3
-    if verbosity <= 0:
-        return v  # ty: ignore[invalid-return-type]
-    q = (__import__('sys').stdout if out is None else out).write
-    if rc is not None:
-        q('\nRecursing into directory: '.join(rc))
-        q('\n\n')
-    if z is not None:
-        q('\nNot found: '.join(z))
-        q('\n')
-    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))
-        q('\n')
-    if d:
-        q(f'{d} I/O error{"s" if d > 1 else ""} encountered\n')
-    if b is not None:
-        q('\nEmpty: '.join(b))
-        q('\n')
-    if verbosity > 2:
-        p = k[0] if b is None else len(b) - 1
-        q(f'{p or "No"} empty file{"" if p == 1 else "s"}\n')
-    if y:
-        if r is not None:
-            q(('\nCleared: ' if clear else '\nNot empty: ').join(r))
-            q('\n\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')
-    return v  # ty: ignore[invalid-return-type]
-
-
-del TYPE_CHECKING