find-python.py

A small Python utility to search for directories and print basic metadata (path, size, modified) as JSON. Configured via .env or CLI.

Configure

Copy .env.example to .env and adjust:

SEARCH_PATH=.
NAME_PATTERN=theunparty*
FOLLOW_SYMLINKS=0

You can also set environment variables directly or use CLI flags to override.

Run

From the repo root:

Optional flags:

• -r, --root — root directory to search
• -p, --pattern — directory name pattern (fnmatch)
• --follow-symlinks / --no-follow-symlinks
• -v, --verbose — log progress and each match to stderr

Examples:

python3 find-python.py -r . -p "theunparty*"
python3 find-python.py --follow-symlinks
python3 find-python.py -v -r ~ -p "theunparty*"

FOLLOW_SYMLINKS explained

• What it does: Controls whether the walker descends into symlinked directories.

  • OFF (default): The script will still report symlinked directories that match the pattern, but it will not traverse their children.
  • ON: The script will traverse into symlinked directories and discover matches beneath them.

• Metadata and symlinks: The script collects metadata using lstat (do not follow). If a matched entry is a symlink, the size/modified reflect the symlink itself, not the target directory.

• Caveats:

  • Turning it ON may cause large traversals if symlinks point outside the root or create deep trees.
  • There is no cycle detection; symlink loops can revisit directories multiple times via different paths.
  • To keep output bounded, prefer leaving it OFF or scoping --root/SEARCH_PATH narrowly.

Output

A JSON array similar to:

[
  {
    "path": "./theunparty-porter",
    "size": 102,
    "modified": "2025-08-07 16:03:11"
  }
]

Notes:

• size is the directory entry size from os.stat, not the recursive folder size (matches the shell stat behavior used originally).
• Timestamps are local time in YYYY-MM-DD HH:MM:SS.