check-empty 0.6.0__tar.gz → 0.7.0__tar.gz

{check_empty-0.6.0 → check_empty-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: check-empty
-Version: 0.6.0
+Version: 0.7.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
@@ -32,18 +32,20 @@ Maintainer-email: Jonathan Dung <jonathandung@yahoo.com>
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 
-# check-empty
+# [check-empty](https://pypi.org/p/check-empty)
 
 A simple, dependency-free and intuitive [pre-commit](https://pre-commit.com) /
-[prek](https://prek.j178.dev) hook, CLI, library and GitHub Action conglomerate that
-makes sure selected files are empty according to a filesystem stat call and clears them
-effectively with minimal I/O if required, written in Python. Also available as a tool on
-uv. Supports CPython 3.6+, PyPy 7.0+, GraalPy 19.0+ and most likely every Python 3.6
-runtime you can think of.
+[prek](https://prek.j178.dev) hook, CLI, library,
+[`uv` tool](https://docs.astral.sh/uv/guides/tools/) and
+[GitHub Action](https://github.com/marketplace/actions/check-empty-files) conglomerate
+written in Python that makes sure selected files, even within directories, are empty
+according to as little filesystem stat calls as possible and clears them effectively
+with minimal I/O if specified. 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.
 
 ## Quickstart
 
-Without installation (testing out the capabilities):
+Without installation (just trying out the capabilities):
 
 ```bash
 uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_directory
@@ -52,12 +54,12 @@ uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_direct
 ```bash
 # uv
 uv tool install check-empty # bare executable on PATH
-uv pip install check-empty # if you want the library as well
+uv pip install check-empty # if you want to import check_empty for programmatic usage
 
 pip install check-empty # pip
 ```
 
-Check the version with:
+Show the version with:
 
 ```bash
 check-empty --version # or check-empty -v
@@ -75,11 +77,11 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v0.6.0 # repository version
+  rev: v0.7.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
-        - -Q # flag to silence output (shorthand for --quiet)
+        - -Q # flag to decrease output, applicable twice (shorthand for --quiet)
         # below: paths to files/directories to clear or keep empty, relative to project
         # root (absolute paths are possible but not recommended)
         - src/mylib/py.typed
@@ -93,7 +95,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v0.6.0"
+rev = "v0.7.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -111,7 +113,7 @@ or a more terse format (TOML 1.1+):
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v0.6.0"
+rev = "v0.7.0"
 hooks = [{
   id = "check-empty",
   args = [
@@ -124,7 +126,7 @@ As a GitHub action step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v0.6.0 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v0.7.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:
@@ -138,7 +140,26 @@ steps:
       some_directory
 ```
 
+## 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`. Thus, for a
+file literally named "--", you have little choice but to call the underlying library
+function (`check`) directly.
+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. 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.
+
 ## Development
 
 If you wish to contribute to this project, you are more than welcome, but please
-remember to read the [contributing guide](CONTRIBUTING.md).
+remember to read the [contributing guide](CONTRIBUTING.md). Tests are run with:
+
+```bash
+python -m test_check_empty # explicit
+python -m unittest discover # alternative
+```
+
+at the project root.

{check_empty-0.6.0 → check_empty-0.7.0}/README.md

@@ -1,15 +1,17 @@
-# check-empty
+# [check-empty](https://pypi.org/p/check-empty)
 
 A simple, dependency-free and intuitive [pre-commit](https://pre-commit.com) /
-[prek](https://prek.j178.dev) hook, CLI, library and GitHub Action conglomerate that
-makes sure selected files are empty according to a filesystem stat call and clears them
-effectively with minimal I/O if required, written in Python. Also available as a tool on
-uv. Supports CPython 3.6+, PyPy 7.0+, GraalPy 19.0+ and most likely every Python 3.6
-runtime you can think of.
+[prek](https://prek.j178.dev) hook, CLI, library,
+[`uv` tool](https://docs.astral.sh/uv/guides/tools/) and
+[GitHub Action](https://github.com/marketplace/actions/check-empty-files) conglomerate
+written in Python that makes sure selected files, even within directories, are empty
+according to as little filesystem stat calls as possible and clears them effectively
+with minimal I/O if specified. 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.
 
 ## Quickstart
 
-Without installation (testing out the capabilities):
+Without installation (just trying out the capabilities):
 
 ```bash
 uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_directory
@@ -18,12 +20,12 @@ uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_direct
 ```bash
 # uv
 uv tool install check-empty # bare executable on PATH
-uv pip install check-empty # if you want the library as well
+uv pip install check-empty # if you want to import check_empty for programmatic usage
 
 pip install check-empty # pip
 ```
 
-Check the version with:
+Show the version with:
 
 ```bash
 check-empty --version # or check-empty -v
@@ -41,11 +43,11 @@ As a pre-commit hook:
 # .pre-commit-config.yaml
 repos:
 - repo: https://github.com/jonathandung/check-empty
-  rev: v0.6.0 # repository version
+  rev: v0.7.0 # repository version
   hooks:
     - id: check-empty # the hook
       args: # example list of arguments
-        - -Q # flag to silence output (shorthand for --quiet)
+        - -Q # flag to decrease output, applicable twice (shorthand for --quiet)
         # below: paths to files/directories to clear or keep empty, relative to project
         # root (absolute paths are possible but not recommended)
         - src/mylib/py.typed
@@ -59,7 +61,7 @@ equivalent in `prek.toml` format:
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v0.6.0"
+rev = "v0.7.0"
 
 [[repos.hooks]]
 id = "check-empty"
@@ -77,7 +79,7 @@ or a more terse format (TOML 1.1+):
 ```toml
 [[repos]]
 repo = "https://github.com/jonathandung/check-empty"
-rev = "v0.6.0"
+rev = "v0.7.0"
 hooks = [{
   id = "check-empty",
   args = [
@@ -90,7 +92,7 @@ As a GitHub action step:
 
 ```yaml
 steps:
-- uses: jonathandung/check-empty@v0.6.0 # the latest version on the GitHub Actions
+- uses: jonathandung/check-empty@v0.7.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:
@@ -104,7 +106,26 @@ steps:
       some_directory
 ```
 
+## 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`. Thus, for a
+file literally named "--", you have little choice but to call the underlying library
+function (`check`) directly.
+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. 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.
+
 ## Development
 
 If you wish to contribute to this project, you are more than welcome, but please
-remember to read the [contributing guide](CONTRIBUTING.md).
+remember to read the [contributing guide](CONTRIBUTING.md). Tests are run with:
+
+```bash
+python -m test_check_empty # explicit
+python -m unittest discover # alternative
+```
+
+at the project root.

{check_empty-0.6.0 → check_empty-0.7.0}/check_empty/__init__.py

@@ -10,21 +10,26 @@ from __future__ import annotations
 import os
 
 __all__ = ('check',)
-__version__ = '0.6.0'
+__version__ = '0.7.0'
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     from collections.abc import Iterable
+    from typing import IO
 
     from _typeshed import FileDescriptorOrPath
-    from typing_extensions import Literal, SupportsIndex
+    from typing_extensions import Literal, SupportsIndex, TypeAlias
+
+    ExitCode: TypeAlias = Literal[0, 1, 4, 5, 8, 9, 12, 13]
 
 DIRECTORY_DESCRIPTOR_UNSUPPORTED: BaseException = (
-    SystemError('got directory descriptor on Windows??')
+    SystemError('somehow got directory descriptor on Windows')
     if os.name == 'nt'
     else NotImplementedError('directory descriptors are not supported')
 )
 
+TYPE_MASK, S_IFDIR = 0xF000, 0x4000
+
 
 class _Handler:
     __slots__ = 'a', 'c', 'f', 'j', 'v'
@@ -46,13 +51,14 @@ class _Handler:
         self.v = r = (s if a < 0 else t) % a if isinstance(a, int) else os.fsdecode(a)
         return r
 
-    def _x(self, v):
-        self.j(self.e) if v.errno == 2 else self.f(str(v))
+    def __call__(self):
+        with self, open(self.a, 'wb'):
+            ...
 
     def __exit__(self, t, v, _):
         if t is None or not issubclass(t, OSError):
             return False
-        self._x(v)
+        self.j(self.e) if v.errno == 2 else self.f(str(v))
         self.c = True
         return True
 
@@ -63,8 +69,9 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
     clear: bool = False,
     may_not_exist: bool = False,
     verbosity: SupportsIndex = 2,
-) -> Literal[0, 1, 4, 5, 8, 9, 12, 13]:
-    """Check the emptiness of files and directories.
+    out: 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
@@ -74,14 +81,14 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
         may_not_exist: if True, do not treat absent files or directories as errors.
         verbosity: how much detail the program should print to stdout; if 0, print
         nothing; verbosity > 5 is equivalent to verbosity = 5.
+        out: The file to which output is printed; default `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 `-m`/`--may-not-exist` was not specified)
-        and 8 (caught OSError while processing some files), such that 0 is the only
-        return value that represents success as expected. The 2 bit is skipped since it
-        conflicts with the exit code of `argparse.ArgumentParser` when it encounters
-        invalid arguments.
+        files or directories were absent and `-m`/`--may-not-exist` was omitted) and 8
+        (caught 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 `argparse.ArgumentParser` when it encounters invalid arguments.
 
     """
     files = list(files)
@@ -90,11 +97,8 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
     k, j, t, n, o = [0] * 4, [], 0, len(files), files.pop
     u, e = j.extend, j.pop
 
-    def _(v, k=k):
-        def f(_):
-            k[v] += 1
-
-        return f
+    def _(v):
+        return lambda _, k=k: k.__setitem__(v, k[v] + 1)
 
     verbosity = type(verbosity).__index__(verbosity)
     if verbosity > 4:
@@ -102,6 +106,14 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
         f = b.append
     else:
         b, f = None, _(0)
+    if verbosity > 3:
+        rc = ['']
+        ra = rc.append
+    else:
+        rc = None
+
+        def ra(_): ...
+
     if verbosity > 2:
         z, w = [''], ['']
         i = z.append, w.append
@@ -120,11 +132,10 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
         if h.c:
             continue
         c = h.e
-        if (q.st_mode >> 12) & 15 == 4:
+        if q.st_mode & TYPE_MASK == S_IFDIR:
             if isinstance(a, int):
                 raise DIRECTORY_DESCRIPTOR_UNSUPPORTED
-            if verbosity > 3:
-                print('Recursing into directory:', c)
+            ra(c)
             u(os.scandir(c))
             continue
         s = q.st_size
@@ -134,15 +145,13 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
         g(f'{c} ({s} bytes)')
         t += s
         if clear:
-            with h, open(a, 'wb'):
-                ...
+            h()
     del o, files
     while j:
         m = e()
         a = m.path
         if m.is_dir():
-            if verbosity > 3:
-                print('Recursing into directory:', a)
+            ra(a)
             u(os.scandir(a))
             continue
         n += 1
@@ -153,32 +162,37 @@ def check(  # ruff: ignore[too-many-branches, too-many-locals, too-many-statemen
         g(f'{a} ({s} bytes)')
         t += s
         if clear:
-            with _Handler(*i, a), open(a, 'wb'):
-                ...
+            _Handler(*i, a)()
     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]
-    if verbosity > 2:
-        print(*z, sep='\nNot found: ')
-    print(f'{x} file{"" if x == 1 else "s"} not found' if x else 'All files were found')
-    if verbosity > 2:
-        print(*w, sep='\nError: ')
+    fw = (__import__('sys').stdout if out is None else out).write
+    if rc is not None:
+        fw('\nRecursing into directory: '.join(rc))
+        fw('\n\n')
+    if z is not None:
+        fw('\nNot found: '.join(z))
+        fw('\n')
+    fw(f'{x} file{"s" if x > 1 else ""} not found\n' if x else 'All files were found\n')
+    if w is not None:
+        fw('\nError: '.join(w))
+        fw('\n')
     if d:
-        print(f'{d} I/O error{"s" if d > 1 else ""} encountered')
-    if verbosity > 4:
-        print(*b, sep='\nEmpty: ')
+        fw(f'{d} I/O error{"s" if d > 1 else ""} encountered\n')
+    if b is not None:
+        fw('\nEmpty: '.join(b))
+        fw('\n')
     if verbosity > 2:
         p = k[0] if b is None else len(b) - 1
-        print(f'{p} empty file{"" if p == 1 else "s"}' if p else 'No empty files')
+        fw(f'{p} empty file{"" if p == 1 else "s"}\n' if p else 'No empty files\n')
     if y:
-        if verbosity > 1:
-            print(*r, sep='\nCleared: ' if clear else '\nNot empty: ', end='')
-            print(end='\n\n')
-        print(y, 'offending files' if y > 1 else 'offending file')
-        print(f'Total size: {t} bytes')
+        if r is not None:
+            fw(('\nCleared: ' if clear else '\nNot empty: ').join(r))
+            fw('\n\n')
+        fw(f'{y} offending file{"s" if y > 1 else ""}\nTotal size: {t} bytes\n')
     elif n > x:
-        print('All found files were empty')
+        fw('All found files were empty\n')
     return v  # ty: ignore[invalid-return-type]

{check_empty-0.6.0 → check_empty-0.7.0}/check_empty/__main__.py

@@ -7,7 +7,8 @@ import check_empty as c
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     from collections.abc import Iterable
-    from typing import Literal
+
+    from typing_extensions import Literal
 
 parser = __import__('argparse').ArgumentParser(
     'check-empty',
@@ -31,8 +32,8 @@ f('-Q', '--quiet', action='count', default=0, help='decrease output verbosity')
 f('-V', '--verbose', action='count', default=0, help='increase output verbosity')
 
 
-def main(argv: Iterable[str] | None = None) -> Literal[0, 1, 2, 4, 5, 8, 9, 12, 13]:
-    """Run the hook on the files in the command-line arguments passed.
+def main(argv: Iterable[str] | None = None) -> c.ExitCode | Literal[2]:
+    """Run the hook/CLI on the files in the command-line arguments passed.
 
     Args:
         argv: a list of arguments; default `sys.argv[1:]`.
@@ -53,6 +54,6 @@ def main(argv: Iterable[str] | None = None) -> Literal[0, 1, 2, 4, 5, 8, 9, 12,
     )
 
 
+del f, TYPE_CHECKING
 if __name__ == '__main__':
     parser.exit(main())
-del f, TYPE_CHECKING

{check_empty-0.6.0 → check_empty-0.7.0}/pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
 name = "check-empty"
 readme = "README.md"
 requires-python = ">=3.6"
-version = "0.6.0"
+version = "0.7.0"
 
 [project.scripts]
 check-empty = "check_empty.__main__:main"
@@ -36,7 +36,7 @@ select = ["ALL"]
 combine-as-imports = true
 
 [tool.ruff.lint.per-file-ignores]
-"test.py" = ["D"]
+"test_check_empty.py" = ["D"]
 "!__init__.py" = ["missing-copyright-notice"]
 
 [tool.ruff.lint.pydocstyle]
@@ -53,10 +53,6 @@ python-platform = "all"
 all = "error"
 missing-override-decorator = "ignore"
 
-[[tool.ty.overrides]]
-include = ["check_empty/__init__.py"]
-rules = {not-iterable = "ignore"}
-
 [tool.uv]
 required-version = ">=0.11.31,<0.12"