check-empty 0.1.0__tar.gz

check_empty-0.1.0/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/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.

check_empty-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,77 @@
+# 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/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-0.1.0/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/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12"]
+build-backend = "uv_build"
+
+[project]
+authors = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
+classifiers = ["Development Status :: 3 - Alpha", "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 :: Free Threading :: 3 - Stable", "Topic :: Utilities", "Typing :: Typed"]
+description = "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"]
+license = "MIT"
+license-files = ["LICENSE", "AUTHORS.md"]
+maintainers = [{name = "Jonathan Dung", email = "jonathandung@yahoo.com"}]
+name = "check-empty"
+readme = "README.md"
+requires-python = ">=3.7"
+version = "0.1.0"
+
+[project.scripts]
+check-empty = "check_empty.__main__:main"
+
+[tool.ruff]
+target-version = "py37"
+
+[tool.ruff.analyze]
+type-checking-imports = false
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+ignore = ["ANN", "COM", "PT", "PTH", "avoidable-escaped-quote", "bad-quotes-inline-string", "complex-structure", "docstring-extraneous-exception", "incorrect-blank-line-before-class", "multi-line-summary-second-line", "print", "unnecessary-dunder-call"]
+preview = true
+select = ["ALL"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+"test.py" = ["D"]
+"!__init__.py" = ["missing-copyright-notice"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ty.analysis]
+respect-type-ignore-comments = false
+
+[tool.ty.environment]
+python-version = "3.7"
+python-platform = "all"
+
+[tool.ty.rules]
+all = "error"
+missing-override-decorator = "ignore"
+
+[tool.uv]
+required-version = ">=0.11.29,<0.12"
+
+[tool.uv.build-backend]
+module-name = "check_empty"
+module-root = ""