Directory Validator (dirval) 📂✅

GitHub Sponsors Patreon Buy Me a Coffee PayPal Tests License: MIT GitHub stars Tests PyPI version Python versions

Directory Validator is a Python utility that creates and verifies a unique hash stamp for a directory. This stamp, saved as a JSON file, represents the directory’s structure (relative paths, excluding the stamp file itself), allowing you to quickly detect changes in the directory layout.

🛠 Features

  • Stamp Creation: Generate a deterministic SHA-256 hash from all relative paths (files and subdirectories).
  • Validation: Recalculate the hash to determine if any files or directories have changed.
  • Exclusion Handling: Automatically ignores the stamp file (directory_stemp.json) in the directory root.
  • Simple CLI Interface: Easily create or validate stamps via command-line options.

📥 Installation

Install Directory Validator directly from PyPI:

pip install dirval

For a user-local installation (recommended if you don’t use virtual environments):

pip install --user dirval

For development or editable installs:

git clone https://github.com/kevinveenbirkenbach/directory-validator.git
cd directory-validator
pip install -e .

After installation, the dirval command will be available in your shell.

🚀 Usage

Create a Directory Stamp

Generate a stamp (hash and timestamp) for a directory. The stamp is saved as directory_stemp.json inside the directory.

dirval <path_to_directory> --stamp

Example:

dirval ./my-folder --stamp

Validate a Directory

Compare the current directory state against the stored stamp to check for any modifications.

dirval <path_to_directory> --validate

Example:

dirval ./my-folder --validate

Exit codes:

  • 0 → directory matches the stored stamp
  • 1 → directory has changed
  • 3 → directory or stamp file not found

📖 How It Works

  • The tool recursively walks through the given directory and collects all file and subdirectory paths.
  • The stamp file (directory_stemp.json) in the directory root is ignored automatically.
  • All collected relative paths are sorted deterministically.
  • A cumulative SHA-256 hash is generated from those paths.
  • The hash and a timestamp are stored in directory_stemp.json.
  • During validation, the hash is recalculated and compared against the stored value.

🧑‍💻 Author

Developed by Kevin Veen-Birkenbach

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributions

Contributions are welcome! Feel free to fork the repository, submit pull requests, or open issues if you have suggestions or encounter any problems. Let's improve directory validation together! 😊

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kevinveenbirkenbach from gravatar.com kevinveenbirkenbach

Credits

Author: Kevin Veen-Birkenbach

License

MIT License (MIT License)

Requires

Python >=3.9

Tags

hash directory stamp validation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dirval-1.1.4.tar.gz (6.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

dirval-1.1.4-py3-none-any.whl (6.5 kB view details)

Uploaded Python 3

File details

Details for the file dirval-1.1.4.tar.gz.

File metadata

  • Download URL: dirval-1.1.4.tar.gz
  • Upload date:
  • Size: 6.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dirval-1.1.4.tar.gz
Algorithm Hash digest
SHA256 9fcd1ccd24cc441e3b304b00b64387df36b91db36bc4e3aaf9a48df97615736e
MD5 d70107d15f32c5ce5fec2523e0d56f21
BLAKE2b-256 1e33f4bc55b070eae1fc0e53df6c6f72b0a3fc8a234debbebcfbb7e9cc213bee

See more details on using hashes here.

Provenance

The following attestation bundles were made for dirval-1.1.4.tar.gz:

Publisher: publish-pypi.yml on kevinveenbirkenbach/directory-validator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dirval-1.1.4-py3-none-any.whl.

File metadata

  • Download URL: dirval-1.1.4-py3-none-any.whl
  • Upload date:
  • Size: 6.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dirval-1.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 e56a0daf219c93c8bf5cb4ebb83cbda2ecc9f31b14cc47be4caf6fdb0aecbc3e
MD5 65e950dbd6d18bbab6d21d3cb4da3b1d
BLAKE2b-256 ec95af7059ab40d8c7a343fff324760e86b2bd97a3b735220fe257865e6f38ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for dirval-1.1.4-py3-none-any.whl:

Publisher: publish-pypi.yml on kevinveenbirkenbach/directory-validator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.1.4 This release

2 files

1.1.3

2 files

1.1.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page