Metadata-Version: 2.4
Name: check-empty
Version: 0.8.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
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.6
Description-Content-Type: text/markdown

# [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,
[`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 (just trying out the capabilities):

```bash
uvx check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_directory
```

```bash
# uv
uv tool install check-empty # bare executable on PATH
uv pip install check-empty # if you want to import check_empty for programmatic usage

pip install check-empty # pip
```

Show the version with:

```bash
check-empty --version # or check-empty -v
```

All the snippets below should do the same thing.

Run the CLI:

```bash
check-empty -Q src/mylib/py.typed docs/.nojekyll static/.gitkeep some_directory
```

In Python:

```py
from check_empty import check
check(
    ['src/mylib/py.typed', 'docs/.nojekyll', 'static/.gitkeep', 'some_directory'],
    verbosity=1  # default 2; each -Q decreases it by 1 and each -V increases it by 1
)
```

As a pre-commit hook:

```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/jonathandung/check-empty
  rev: v0.8.0 # repository version
  hooks:
    - id: check-empty # the hook
      args: # example list of arguments
        - -Q # flag to decrease output, applicable twice (shorthand for --quiet)
      files: # 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
        - docs/.nojekyll
        - static/.gitkeep
        - some_directory
```

equivalent in `prek.toml` format:

```toml
[[repos]]
repo = "https://github.com/jonathandung/check-empty"
rev = "v0.8.0"

[[repos.hooks]]
id = "check-empty"
args = ["-Q"]
files = ["src/mylib/py.typed", "docs/.nojekyll", "static/.gitkeep", "some_directory"]
```

or (TOML 1.1+):

```toml
[[repos]]
repo = "https://github.com/jonathandung/check-empty"
rev = "v0.8.0"
hooks = [{
  id = "check-empty",
  args = ["-Q"]
  files = ["src/mylib/py.typed", "docs/.nojekyll", "static/.gitkeep", "some_directory"]
}]
```

As a GitHub action step:

```yaml
steps:
- uses: jonathandung/check-empty@v0.8.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
      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). Tests are run with:

```bash
python -m test_check_empty # explicit
python -m unittest discover # alternative
```

at the project root.
