Herkules 1.0.0__tar.gz

herkules-1.0.0/.flake8

@@ -0,0 +1,4 @@
+[flake8]
+extend-ignore = E301,E303
+max-cognitive-complexity = 7
+max-line-length = 80

herkules-1.0.0/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.ps1 text eol=crlf
+
+*.jpg -text binary
+*.png -text binary

herkules-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# environments
+.envrc
+.venv
+
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# pytest
+.pytest_cache/
+
+# Stempelwerk
+*_Debug.txt
+.last_run

herkules-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

herkules-1.0.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Change Log
+
+_All notable changes to this project will be documented in this
+file. This change log follows the conventions of
+[keepachangelog.com]._
+
+_I tend to not use
+[semantic versioning](https://semver.org/), but we will see what
+happens._
+
+<!--- ---------------------------------------------------------------------- -->
+
+## [Unreleased]
+
+### Changed
+
+<!--- ---------------------------------------------------------------------- -->
+
+## [1.0.0] - 2024-08-08
+
+- This is the first stable release (although I have been using it professionally for over two years now).
+
+<!--- ---------------------------------------------------------------------- -->
+
+[keepachangelog.com]: http://keepachangelog.com/
+[unreleased]: https://github.com/mzuther/Herkules/tree/develop
+[1.0.0]: https://github.com/mzuther/Herkules/commits/v1.0.0

herkules-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at http://www.mzuther.de/en/contact/. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+

herkules-1.0.0/LICENSE.md

@@ -0,0 +1,31 @@
+# BSD 3-Clause License
+
+**Copyright (c) 2022-2025 [Martin Zuther](https://www.mzuther.de/)**
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the
+   distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived
+   from this software without specific prior written permission.
+
+_THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE._

herkules-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: Herkules
+Version: 1.0.0
+Summary: Crawl directories with style
+Project-URL: Homepage, https://github.com/mzuther/herkules
+Project-URL: Repository, https://github.com/mzuther/herkules.git
+Project-URL: Changelog, https://github.com/mzuther/herkules/blob/main/CHANGELOG.md
+Author-email: Martin Zuther <code@mzuther.de>
+License-Expression: BSD-3-Clause
+License-File: LICENSE.md
+Keywords: file search,pure,simple
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+
+# Herkules
+
+_Crawl directories with style_
+
+<figure style="display: flex; flex-flow: column; max-width: 25em;">
+  <img src="include/hercules_beetle_george_shaw.jpg"
+       alt="Illustration of a Hercules beetle" />
+  <figurecaption>
+    <small>
+      <em>
+        Illustration by George Shaw (obtained from
+        <a href="https://en.wikipedia.org/wiki/File:%22_Hercules_beetle_illustration_from_The_Naturalist%27s_Miscellany_(1789-1813)_by_George_Shaw_(1751-1813)._%22.jpg">
+          Wikimedia Commons</a>)
+      </em>
+    </small>
+  </figurecaption>
+</figure>
+
+## Introduction
+
+Herkules is named after the beautiful large Hercules beetle (Dynastes hercules).
+It provides a recursive, filtered and sorted list of the contents of a given
+root directory. I find it easier to use than Python's `os.scandir`, but your
+mileage may differ.
+
+## Installation
+
+_Herkules is now developed using Python v3.12. Older versions of Python used to
+work and will probably still do, but you are on your own here._
+
+Unless you want to test Herkules, simply store it somewhere and import it. For
+testing, you must install it into a virtual environment. The easiest way is to
+run
+
+```bash
+# bash
+./script/bootstrap
+```
+
+or
+
+```ps1
+# PowerShell
+.\script\bootstrap.ps1
+```
+
+For a very simple "no-options" experience, install from PyPI and execute the
+included script:
+
+```bash
+# bash
+pip install herkules
+herkules "./directory/"
+```
+
+## Execution
+
+See [example_herkules.py](./example_herkules.py) for example code and an
+explanation of parameters.
+
+## Code of conduct
+
+Please read the [code of conduct](./CODE_OF_CONDUCT.md) before asking for help,
+filing bug reports or contributing to this project. Thanks!
+
+## License
+
+Copyright (c) 2022-2025 [Martin Zuther](https://www.mzuther.de/)
+
+This program is free software and licensed under the terms of the [BSD 3-Clause
+License](./LICENSE.md).
+
+**Thank you for using free software!**

herkules-1.0.0/README.md

@@ -0,0 +1,73 @@
+# Herkules
+
+_Crawl directories with style_
+
+<figure style="display: flex; flex-flow: column; max-width: 25em;">
+  <img src="include/hercules_beetle_george_shaw.jpg"
+       alt="Illustration of a Hercules beetle" />
+  <figurecaption>
+    <small>
+      <em>
+        Illustration by George Shaw (obtained from
+        <a href="https://en.wikipedia.org/wiki/File:%22_Hercules_beetle_illustration_from_The_Naturalist%27s_Miscellany_(1789-1813)_by_George_Shaw_(1751-1813)._%22.jpg">
+          Wikimedia Commons</a>)
+      </em>
+    </small>
+  </figurecaption>
+</figure>
+
+## Introduction
+
+Herkules is named after the beautiful large Hercules beetle (Dynastes hercules).
+It provides a recursive, filtered and sorted list of the contents of a given
+root directory. I find it easier to use than Python's `os.scandir`, but your
+mileage may differ.
+
+## Installation
+
+_Herkules is now developed using Python v3.12. Older versions of Python used to
+work and will probably still do, but you are on your own here._
+
+Unless you want to test Herkules, simply store it somewhere and import it. For
+testing, you must install it into a virtual environment. The easiest way is to
+run
+
+```bash
+# bash
+./script/bootstrap
+```
+
+or
+
+```ps1
+# PowerShell
+.\script\bootstrap.ps1
+```
+
+For a very simple "no-options" experience, install from PyPI and execute the
+included script:
+
+```bash
+# bash
+pip install herkules
+herkules "./directory/"
+```
+
+## Execution
+
+See [example_herkules.py](./example_herkules.py) for example code and an
+explanation of parameters.
+
+## Code of conduct
+
+Please read the [code of conduct](./CODE_OF_CONDUCT.md) before asking for help,
+filing bug reports or contributing to this project. Thanks!
+
+## License
+
+Copyright (c) 2022-2025 [Martin Zuther](https://www.mzuther.de/)
+
+This program is free software and licensed under the terms of the [BSD 3-Clause
+License](./LICENSE.md).
+
+**Thank you for using free software!**

herkules-1.0.0/example_herkules.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+
+# %% Imports
+import datetime
+import pathlib
+
+from src.herkules.Herkules import herkules
+
+
+# %% Initialization
+# directory to be crawled (can also be a string)
+ROOT_DIRECTORY = pathlib.Path('.')
+
+# optional: return directories and their contents before regular files
+DIRECTORIES_FIRST = True
+
+# optional: whether subdirectories should be included in the output; their
+# contents will always be crawled, however, regardless of this setting
+INCLUDE_DIRECTORIES = False
+
+# optional: include files and directories which are symlinks
+FOLLOW_SYMLINKS = False
+
+# globs: https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match
+SELECTOR = {
+    # optional: directories that should not be crawled (full name is matched)
+    'excluded_directory_names': [
+        '.git',
+    ],
+    # optional: file names that should be included in the result (glob)
+    'excluded_file_names': [
+        '*.*c',
+    ],
+    # optional: file names that should be excluded from the result (glob,
+    # "*" by default)
+    'included_file_names': [
+    ],
+}
+
+# optional: only include directories and files with were modified at or past
+# the given time; for symlinks, this checks the original file
+MODIFIED_SINCE = datetime.datetime(2024, 8, 1, 8, 30, 0)
+
+
+# %% Crawl directory & display results
+# "herkules()" returns a list of "pathlib.Path" objects
+contents = herkules(
+    ROOT_DIRECTORY, DIRECTORIES_FIRST, INCLUDE_DIRECTORIES,
+    FOLLOW_SYMLINKS, SELECTOR, MODIFIED_SINCE)
+
+print()
+for entry in contents:
+    print(f'* { entry }')
+print()

herkules-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "Herkules"
+dynamic = ["version"]
+description = "Crawl directories with style"
+keywords = ["file search", "simple", "pure"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+authors = [{ name = "Martin Zuther", email = "code@mzuther.de" }]
+requires-python = ">=3.10,<4.0"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE.md"]
+
+[project.scripts]
+herkules = "herkules.Herkules:main_cli"
+
+[project.urls]
+Homepage = "https://github.com/mzuther/herkules"
+Repository = "https://github.com/mzuther/herkules.git"
+Changelog = "https://github.com/mzuther/herkules/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "flake8>=6.0.0,<7",
+    "flake8-cognitive-complexity>=0.1.0,<0.2",
+    "flake8-fixme>=1.1.1,<2",
+    "flake8-pytest-style>=1.7.2,<2",
+    "pip-licenses>=5.0.0,<6",
+    "pytest>=7.3.0,<8",
+    "pytest-datafiles>=3.0.0,<4",
+]
+
+[build-system]
+requires = ["hatchling >= 1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/herkules/Herkules.py"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+markers = [
+    "current: marks tests as current (select with '-m current')",
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+testpaths = [
+    "tests",
+]

herkules-1.0.0/script/README.md

@@ -0,0 +1 @@
+Scripts for setting up and testing this application (https://github.com/github/scripts-to-rule-them-all).

herkules-1.0.0/script/bootstrap

@@ -0,0 +1,14 @@
+#! /bin/bash
+
+echo
+
+# create virtual environment and install dependencies
+uv sync --no-managed-python
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+   echo
+   exit $EXIT_CODE
+fi
+
+echo

herkules-1.0.0/script/bootstrap.ps1

@@ -0,0 +1,6 @@
+Write-Output ""
+
+# create virtual environment and install dependencies
+uv sync --no-managed-python
+
+Write-Output ""

herkules-1.0.0/script/lint

@@ -0,0 +1,11 @@
+#! /bin/bash
+
+echo
+
+uv run flake8 --config="./.flake8" src/
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+   echo
+   exit $EXIT_CODE
+fi

herkules-1.0.0/script/lint.ps1

@@ -0,0 +1,8 @@
+Write-Output ""
+
+uv run flake8 --config=".flake8" src/
+
+If (-Not $?)
+{
+    exit
+}

herkules-1.0.0/script/setup

@@ -0,0 +1,24 @@
+#! /bin/bash
+
+echo
+uv tree --no-dev
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+   echo
+   exit $EXIT_CODE
+fi
+
+echo
+echo "------------------------------------------------------------------------"
+echo
+
+uv tree --only-dev
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+   echo
+   exit $EXIT_CODE
+fi
+
+echo

herkules-1.0.0/script/setup.ps1

@@ -0,0 +1,11 @@
+Write-Output ""
+
+uv tree --no-dev
+
+Write-Output ""
+Write-Output "------------------------------------------------------------------------"
+Write-Output ""
+
+uv tree --only-dev
+
+Write-Output ""

herkules-1.0.0/script/test

@@ -0,0 +1,42 @@
+#! /bin/bash
+
+echo
+
+# run quick tests first
+echo "[QUICK TESTS]"
+echo
+
+uv run pytest --ignore="./.git" -m "not slow" "$@"
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+	echo
+	exit $EXIT_CODE
+fi
+
+echo
+
+# run slow tests only when all other tests have passed
+echo "[SLOW TESTS]"
+echo
+
+uv run pytest --ignore="./.git" -m "slow" "$@"
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 5 ]; then
+	echo
+	echo "No tests selected."
+	EXIT_CODE=0
+fi
+
+if [ $EXIT_CODE -ne 0 ]; then
+	echo
+	exit $EXIT_CODE
+fi
+
+./script/lint
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+	exit $EXIT_CODE
+fi

herkules-1.0.0/script/test.ps1

@@ -0,0 +1,25 @@
+Write-Output ""
+Write-Output "[QUICK TESTS]"
+Write-Output ""
+
+# run quick tests first
+uv run pytest --ignore=".\.git" -m "not slow" $args
+
+If (-Not $?)
+{
+    exit
+}
+
+Write-Output ""
+Write-Output "[SLOW TESTS]"
+Write-Output ""
+
+# run slow tests only when all other tests have passed
+uv run pytest --ignore=".\.git" -m "slow" $args
+
+If (-Not $?)
+{
+    exit
+}
+
+. ".\script\lint.ps1"

herkules-1.0.0/script/update

@@ -0,0 +1,13 @@
+#! /bin/bash
+
+echo
+
+uv sync --upgrade
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+   echo
+   exit $EXIT_CODE
+fi
+
+echo

herkules-1.0.0/script/update.ps1

@@ -0,0 +1,5 @@
+Write-Output ""
+
+uv sync --upgrade
+
+Write-Output ""