check-empty 0.1.0__py3-none-any.whl

check_empty/__init__.py

@@ -0,0 +1,9 @@
+# Copyright © 2026 Jonathan Dung. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""Utility to check the emptiness of files.
+
+Pre-commit hook, command-line tool and GitHub Action all-in-one.
+"""
+
+__all__ = ('main',)
+from check_empty.__main__ import __version__ as __version__, main

check_empty/__main__.py

@@ -0,0 +1,83 @@
+#!usr/bin/env python3
+"""Implementation of the main routine."""
+
+from __future__ import annotations
+
+from os.path import getsize
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Literal, Sequence
+
+__version__ = '0.1'
+parser = __import__('argparse').ArgumentParser(
+    'check-empty',
+    description='Assert or enforce that some files are empty.',
+    epilog='It is preferred that you use this as a pre-commit/prek hook or GitHub '
+    'Action for most cases which are not one-off.',
+)
+f = parser.add_argument
+f('filenames', nargs='+', help='the files that should be empty')
+f('-v', '--version', action='version', version='check-empty v' + __version__)
+f('-c', '--clear', action='store_true', help='clear files that are not empty')
+f('-m', '--must-exist', action='store_true', help='fail if any file is absent')
+f('-q', '--quiet', action='store_true', help='suppress output')
+
+
+def main(argv: Sequence[str] | None = None) -> Literal[0, 1, 2, 3]:
+    """Run the hook on the files in the (command-line) arguments passed.
+
+    Args:
+        argv: A list of arguments excluding the executable name, default sys.argv[1:].
+
+    Returns:
+        The exit code. A bitwise or of 1 (some files were not empty) and 2 (some files
+        were absent and --must-exist was specified), such that 0 is the only return
+        value that represents success as expected.
+
+    """
+    r, z, n = [''], [''], parser.parse_args(argv)
+    g, j, c, t, i = r.append, z.append, n.clear, 0, n.filenames
+    if c:
+        for a in i:
+            try:
+                s = getsize(a)
+            except FileNotFoundError:
+                j(a)
+                continue
+            if not s:
+                continue
+            g(f'{a} ({s} bytes)')
+            t += s
+            with open(a, 'wb'):
+                ...
+    else:
+        for a in i:
+            try:
+                s = getsize(a)
+            except FileNotFoundError:
+                j(a)
+                continue
+            if not s:
+                continue
+            g(f'{a} ({s} bytes)')
+            t += s
+    p, x, y = not n.quiet, len(z) - 1, len(r) - 1
+    v = n.must_exist << 1 if x else 0
+    if p:
+        print(*z, sep='\nNot found: ')
+        print(f'{x} files not found' if x else 'All files were found')
+    if y:
+        if p:
+            print(*r, sep='\nCleared: ' if c else '\nNot empty: ', end='\n\n')
+            print(y, 'offending files' if y > 1 else 'offending file')
+            print(f'Total size: {t} bytes')
+        return v | 1
+    if p:
+        print('All found files were empty')
+    return v
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())
+del f, TYPE_CHECKING

check_empty-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: check-empty
+Version: 0.1.0
+Summary: Command-line utility, as well as a hook usable by the Python pre-commit framework, to ensure that selected files are empty.
+Keywords: check,command-line,empty,github-action,hook,lightweight,pre-commit,prek,tool,utility
+Author: Jonathan Dung
+Author-email: Jonathan Dung <jonathandung@yahoo.com>
+License-Expression: MIT
+License-File: AUTHORS.md
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Maintainer: Jonathan Dung
+Maintainer-email: Jonathan Dung <jonathandung@yahoo.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# check-empty
+
+A simple [pre-commit](https://pre-commit.com)/[prek](https://prek.j178.dev) hook that
+makes sure selected files are empty according to a filesystem stat call and clears them
+effectively on demand with a write-mode open and immediate close. Also acts as a CLI,
+library and GitHub Action conglomerate.
+
+## Quickstart
+
+```bash
+uv tool install check-empty # uv
+pip install check-empty # pip
+```
+
+Check the version with:
+
+```bash
+check-empty -v
+```
+
+Run the CLI:
+
+```bash
+check-empty -q src/mylib/py.typed docs/.nojekyll static/.gitkeep
+```
+
+As a pre-commit hook:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+- repo: https://github.com/jonathandung/check-empty
+  rev: v0.1.0 # repository version
+  hooks:
+    - id: check-empty # the hook
+      args: # example list of arguments
+        - --quiet # flag to silence output (equivalent to -q)
+        # below: paths to files to clear or keep empty, either relative to the project
+        # root or absolute (not shown)
+        - src/mylib/py.typed
+        - docs/.nojekyll
+        - static/.gitkeep
+```
+
+equivalent in `prek.toml` format:
+
+```toml
+[[repos]]
+repo = "https://github.com/jonathandung/check-empty"
+rev = "v0.1.0"
+hooks = [{
+  id = "check-empty",
+  args = [
+    "--quiet",
+    "src/mylib/py.typed",
+    "docs/.nojekyll",
+    "static/.gitkeep",
+  ]
+}]
+```
+
+As a GitHub action step:
+
+```yaml
+steps:
+- uses: jonathandung/check-empty@v0.1.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
+    quiet: true
+    filenames: |
+      src/mylib/py.typed
+      docs/.nojekyll
+      static/.gitkeep
+```

check_empty-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+check_empty/__init__.py,sha256=ZwTpw7Q4EPIe9Z_pan-09unersdy7l4WltxfnLL_V9I,288
+check_empty/__main__.py,sha256=R1_3pg77sGP9kQeBsCbp-9Kcy7xWwEAr2_ilzk78Qqg,2660
+check_empty-0.1.0.dist-info/licenses/AUTHORS.md,sha256=T-8mfZkcPiEFqTOrT9GyJHTNMlPP2uIJsqlh_Xtk90Y,199
+check_empty-0.1.0.dist-info/licenses/LICENSE,sha256=AR3_dFZnIFJKe7uF7voc8gTVJUy7oh9jw4zrkHfJduE,1069
+check_empty-0.1.0.dist-info/WHEEL,sha256=YR4QUxGCbsyoOnWBVTv-p1I4yc3seKGPev46mvmc8Cg,81
+check_empty-0.1.0.dist-info/entry_points.txt,sha256=4ZgW7OP31yn95Fgd82uFn7OILSLsioIsTLOXVOtYzQo,59
+check_empty-0.1.0.dist-info/METADATA,sha256=Rkpp11Nvf0cdbynChxQLAbRj9i7C4Gcl9iz6bAMECo0,3294
+check_empty-0.1.0.dist-info/RECORD,,

check_empty-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.29
+Root-Is-Purelib: true
+Tag: py3-none-any

check_empty-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+check-empty = check_empty.__main__:main
+

check_empty-0.1.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,13 @@
+# Authors
+
+## Technical leads
+
+- Jonathan Dung - owner - Hong Kong
+
+## Developers
+
+- Jonathan Dung - sole maintainer - Hong Kong
+
+## All other contributors and their affiliations
+
+None at the moment.

check_empty-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Dung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.