Python Toolbox

A collection of reusable Python command-line tools for automation, data processing, web tasks, system inspection, security utilities, and developer workflows.

The repository is organized so shared logic lives in core/, lightweight command wrappers live in cli/, and task-specific tools live in scripts/.

Quick Start

1. Create and activate a virtual environment

python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1

macOS/Linux:

source .venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

requirements.txt is currently empty. Most tools use the Python standard library. Optional tools:

• psutil for richer process stats in scripts/system/process_monitor.py
• ruff, black, isort for scripts/dev_tools/code_formatter.py

3. (Optional) create .env

Windows PowerShell:

Copy-Item .env.example .env

macOS/Linux:

cp .env.example .env

4. Run commands

Main CLI:

python cli/main.py --help

Script tools:

python scripts/<category>/<tool>.py --help

Architecture Overview

python-toolbox/
+-- core/        # Shared config, logging, and file utilities
+-- cli/         # Aggregated entrypoint for common core utilities
+-- scripts/     # Category-based standalone tools
+-- tests/       # Test placeholders

Layer responsibilities

• core/config.py
  • Loads .env files.
  • Parses environment values and builds typed Settings.
• core/logger.py
  • Sets consistent console/file logging (with rotating file support).
• core/file_utils.py
  • Provides reusable file operations (read/write, copy/move, list, hash, JSON helpers).
• cli/main.py
  • Exposes small cross-cutting commands: env, hash, ls, cat.
• scripts/*
  • Task-specific CLIs grouped by domain.

Key Concepts

• Standalone script tools: Each script under scripts/ can be run directly with python.
• Shared core utilities: Scripts reuse core modules instead of duplicating file/config/log code.
• Category-driven layout: Tools are grouped for discoverability (automation, web, security, etc.).
• Exit-code friendly CLIs: Scripts return non-zero on validation/operational failures where appropriate.

Configuration

Environment variables consumed by core/config.py:

• PROJECT_NAME: defaults to python-toolbox
• APP_ENV: primary environment name
• ENV: fallback environment name if APP_ENV is missing
• DEBUG: boolean-like string (true/false, 1/0, yes/no, etc.)
• LOG_LEVEL: default logging level (e.g. INFO, DEBUG)
• LOG_FILE: optional log file path (relative paths resolve from repo root)

Example .env:

PROJECT_NAME=python-toolbox
APP_ENV=development
DEBUG=false
LOG_LEVEL=INFO
# LOG_FILE=logs/toolbox.log

CLI Reference

Core CLI (cli/main.py)

• env: print loaded runtime settings
• hash: hash a file (sha256 by default)
• ls: list files by glob pattern
• cat: print file contents

Examples:

python cli/main.py env --json
python cli/main.py hash README.md --algorithm sha256
python cli/main.py ls scripts --pattern *.py --recursive
python cli/main.py cat README.md

Script Catalog

Automation (scripts/automation)

• rename_files.py: bulk rename with prefix/suffix/replace/numbering and dry-run support
• backup_folder.py: create timestamped .zip or .tar.gz backups
• organize_downloads.py: sort files into category folders by extension

Example:

python scripts/automation/rename_files.py ./files --pattern *.txt --prefix archived_ --dry-run
python scripts/automation/backup_folder.py ./project --format zip --exclude "*.log"
python scripts/automation/organize_downloads.py ~/Downloads --recursive

Data Processing (scripts/data_processing)

• csv_cleaner.py: trim values, remove empty rows, deduplicate
• json_to_csv.py: convert JSON objects/lists to CSV (with flattening option)
• data_validator.py: validate required/non-empty/numeric fields for CSV/JSON data

Example:

python scripts/data_processing/csv_cleaner.py input.csv --drop-empty-rows --deduplicate
python scripts/data_processing/json_to_csv.py data.json --records-key items
python scripts/data_processing/data_validator.py data.csv --required id,name --numeric amount --report report.json

Web (scripts/web)

• web_scraper.py: fetch page title, text excerpt, and links
• api_client.py: send HTTP requests with headers/body and inspect responses
• link_checker.py: check URL status codes from args, file, or extracted page links

Example:

python scripts/web/web_scraper.py https://example.com --output page.json
python scripts/web/api_client.py https://httpbin.org/get --pretty --show-headers
python scripts/web/link_checker.py --from-page https://example.com --broken-only

System (scripts/system)

• disk_usage.py: report filesystem totals and largest entries
• process_monitor.py: show top processes by CPU or memory
• env_checker.py: validate Python version, environment variables, and required commands

Example:

python scripts/system/disk_usage.py . --top 15 --min-mb 1
python scripts/system/process_monitor.py --sort memory --top 10
python scripts/system/env_checker.py --required API_KEY --command git --command python

Dev Tools (scripts/dev_tools)

• project_generator.py: scaffold new projects (basic, package, cli templates)
• code_formatter.py: run ruff, black, and/or isort in apply/check mode
• git_helper.py: quick wrappers for common git operations (status, last, commit, etc.)

Example:

python scripts/dev_tools/project_generator.py demo-app --template package --git-init
python scripts/dev_tools/code_formatter.py . --tools ruff,black,isort --check
python scripts/dev_tools/git_helper.py status

Security (scripts/security)

• password_generator.py: generate strong configurable passwords
• file_hasher.py: hash files/directories and verify checksum manifests
• port_scanner.py: concurrent TCP port scanner

Example:

python scripts/security/password_generator.py --length 20 --count 3
python scripts/security/file_hasher.py ./dist --recursive --output checksums.txt
python scripts/security/port_scanner.py 127.0.0.1 --start 1 --end 1024

Misc (scripts/misc)

• random_utils.py: random utilities via subcommands (int, float, choice, sample, shuffle, uuid, token)

Example:

python scripts/misc/random_utils.py int --min 10 --max 99 --count 5
python scripts/misc/random_utils.py token --bytes 24 --urlsafe

Development

Validate syntax

python -m compileall core cli scripts

Run tests

python -m pytest

Current status:

• tests/test_scripts.py exists as a placeholder and does not yet include full test coverage.

Contribution workflow (recommended)

1. Create a feature branch.
2. Add or modify tools under the appropriate scripts/<category>/ folder.
3. Reuse shared helpers in core/ whenever possible.
4. Run formatters/lint checks (if installed) and tests.
5. Update this README with any new commands or behavior changes.

Notes

• Scripts are intentionally independent and callable directly.
• For command details, use --help on any script.