python-automation-tool 0.1.1

Production-style CLI to automate repetitive file and CSV workflows

python-automation-tool

A production-style Python CLI project for repetitive file and CSV workflows.

This project presents a practical automation CLI the way a hiring manager or reviewer would expect to see it shipped:

• modular src/ package layout instead of a single script
• safe file operations with dry-run support and undo history
• automated quality gates with Ruff, pytest, and distribution validation
• GitHub Actions release automation ready for PyPI trusted publishing

This tool is designed for local automation work such as:

• organizing mixed folders by file type
• batch renaming files with predictable numbering
• cleaning and transforming CSV files
• generating CSV action reports
• undoing the most recent organize/rename batch

Key Features

• Python 3.11+ CLI with subcommands
• Professional modular architecture (src layout)
• Safe file operations with duplicate-name handling
• Dry-run support for every destructive workflow
• Undo support for the latest organize/rename batch
• CSV action reporting (timestamp, source, destination, status, errors)
• File filters:
  • include/exclude extensions
  • filename keyword filter
  • min/max file size filtering
• CSV processing utility:
  • trim whitespace
  • remove duplicate rows
  • rename columns
  • filter rows by column value
• Unit tests for core logic plus CLI integration tests

Portfolio Highlights

• Real product behavior: organize, rename, CSV cleanup, reporting, and undo are exposed through a clean CLI instead of ad hoc scripts
• CI/CD: GitHub Actions validates lint, tests, and packaging on every push and pull request
• Release discipline: versioned releases are tied to Git tags and validated before publishing
• Operational safety: destructive workflows support dry runs, duplicate handling, reports, and undo
• Test depth: the suite covers both module-level logic and real CLI execution paths

Why This Project Stands Out

• It solves a concrete problem space that is common in operations, admin, and analyst workflows
• It demonstrates both application code and software engineering process: testing, packaging, CI, and release automation
• It is small enough to review quickly, but deep enough to show judgment around safety, edge cases, and maintainability

Project Docs

• Changelog
• Contributing Guide
• MIT License

Project Structure

python-automation-tool/
  src/
    python_automation_tool/
      __init__.py
      __main__.py
      cli.py
      models.py
      logging_config.py
      filters.py
      utils.py
      file_operations.py
      batch_renamer.py
      csv_processor.py
      reporting.py
      history.py
  tests/
    test_filters.py
    test_file_operations.py
    test_batch_renamer.py
    test_csv_processor.py
    test_history.py
  pyproject.toml
  requirements.txt
  README.md

Architecture Summary

• CLI Layer (cli.py)

  • Parses command arguments
  • Dispatches subcommands
  • Handles command-level errors and summaries
  • Controls report/history integration

• Service Layer

  • file_operations.py: scanning, categorization, safe moves
  • batch_renamer.py: deterministic rename planning and apply
  • csv_processor.py: CSV cleaning/transform pipeline
  • history.py: persistent last-operation history + undo
  • reporting.py: CSV report generation

• Shared Components

  • filters.py: reusable file filter criteria
  • models.py: typed data structures (action records, summaries)
  • utils.py: extension parsing, unique path logic, timestamps
  • logging_config.py: console/file logging setup

Setup

1. Create and activate a virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate

2. Install project and test dependencies:

pip install -e .
pip install -r requirements.txt

For a single dev install that includes lint, test, and packaging tools:

pip install -e ".[dev]"

3. Verify CLI is available:

python-automation-tool --help

You can also run it as a module:

python -m python_automation_tool --help

Commands

1) organize

Scan a folder and move files into category folders: images, documents, spreadsheets, code, archives, audio, video, others.

python-automation-tool organize \
  --source ./data/inbox \
  --recursive \
  --include-ext .jpg .png .pdf .csv \
  --keyword invoice \
  --min-size 100 \
  --report-path ./reports/organize_report.csv

Dry run:

python-automation-tool organize --source ./data/inbox --dry-run

2) rename

Preview and batch rename with numbered format (prefix_001.ext). By default it only previews. Use --apply to execute.

python-automation-tool rename \
  --source ./data/inbox \
  --prefix project_asset \
  --start-number 1 \
  --lower-ext \
  --recursive

Apply changes:

python-automation-tool rename \
  --source ./data/inbox \
  --prefix project_asset \
  --start-number 1 \
  --lower-ext \
  --apply \
  --report-path ./reports/rename_report.csv

Dry run with apply mode:

python-automation-tool rename \
  --source ./data/inbox \
  --prefix archive \
  --apply \
  --dry-run

3) process-csv

Transform CSV files and write cleaned output.

python-automation-tool process-csv \
  --input ./data/raw/customers.csv \
  --output ./data/clean/customers_clean.csv \
  --trim-whitespace \
  --remove-duplicates \
  --rename-column Name:customer_name \
  --rename-column Email:email_address \
  --filter-column Status \
  --filter-value Active \
  --report-path ./reports/csv_report.csv

Dry run:

python-automation-tool process-csv \
  --input ./data/raw/customers.csv \
  --output ./data/clean/customers_clean.csv \
  --trim-whitespace \
  --dry-run

4) undo

Undo the most recent successful organize or rename batch.

python-automation-tool undo --report-path ./reports/undo_report.csv

Dry run undo:

python-automation-tool undo --dry-run

5) report

Export the latest saved operation history to CSV.

python-automation-tool report --output ./reports/latest_history_report.csv

Example End-To-End Workflow

python-automation-tool organize --source ./data/inbox --dry-run
python-automation-tool organize --source ./data/inbox --report-path ./reports/organize.csv
python-automation-tool rename --source ./data/inbox/documents --prefix archive --apply
python-automation-tool undo

That sequence demonstrates the main design goals of the tool:

• preview before destructive changes
• generate traceable reports
• apply deterministic batch operations
• recover from the most recent organize or rename run

Logging

Verbose console logs:

python-automation-tool --verbose organize --source ./data/inbox --dry-run

Write logs to file:

python-automation-tool --log-file ./logs/tool.log organize --source ./data/inbox

Undo History File

By default, operation history is saved at:

• ~/.python_automation_tool/last_operation.json

You can override it per command:

python-automation-tool organize --source ./data/inbox --history-file ./state/last_op.json
python-automation-tool undo --history-file ./state/last_op.json

Error Handling Highlights

The CLI includes explicit handling for:

• invalid or missing paths
• empty source folders
• permission failures during move/rename
• malformed CSV files or invalid column mappings
• invalid filter ranges and argument combinations

Run Tests

pytest

Run lint checks:

ruff check .

Build and validate release artifacts locally:

python -m build
python -m twine check --strict dist/*

Shortcut with Make:

make check

Quality Gates

• GitHub Actions CI runs Ruff linting, pytest, and distribution build checks
• Integration tests exercise the CLI end-to-end through python -m python_automation_tool
• Packaging validation checks both sdist and wheel metadata before release

Versioning And Releases

• Package version is defined once in src/python_automation_tool/__init__.py
• pyproject.toml reads that version dynamically during packaging
• Create a release by updating __version__, committing the change, and pushing a matching tag such as v0.1.0
• The release workflow verifies that the Git tag matches the package version before publishing

GitHub Actions Workflows

• .github/workflows/ci.yml Runs lint, tests, and package build validation on pushes and pull requests
• .github/workflows/release.yml Runs on version tags, rebuilds and validates the package, publishes to PyPI via trusted publishing, and creates a GitHub Release

PyPI Trusted Publishing Setup

The release workflow is already configured for PyPI trusted publishing. To activate it, configure the matching publisher on PyPI using these exact values:

• Owner: muhammadakfz
• Repository name: python-automation-tool
• Workflow name: release.yml
• Environment name: pypi

GitHub-side requirements already present in this repo:

• job-level id-token: write permission in .github/workflows/release.yml
• environment: pypi on the publish job
• pypa/gh-action-pypi-publish@release/v1 for OIDC-based publishing

Manual PyPI setup still required:

1. Create the python-automation-tool project on PyPI, or add a trusted publisher to the existing project.
2. In PyPI, open the project settings and add a GitHub Actions trusted publisher.
3. Enter the exact repository and workflow values listed above.
4. In GitHub, create or review the pypi environment under repository settings.

This setup follows the official PyPI trusted publishing documentation:

• https://docs.pypi.org/trusted-publishers/
• https://docs.pypi.org/trusted-publishers/adding-a-publisher/
• https://docs.pypi.org/trusted-publishers/using-a-publisher/

Practical Portfolio Workflow

1. Preview an organize run:

python-automation-tool organize --source ./workspace --recursive --dry-run

2. Apply organize + save report:

python-automation-tool organize --source ./workspace --recursive --report-path ./reports/organize.csv

3. Preview rename:

python-automation-tool rename --source ./workspace/images --prefix event --start-number 100

4. Apply rename:

python-automation-tool rename --source ./workspace/images --prefix event --start-number 100 --apply --report-path ./reports/rename.csv

5. If needed, undo last batch:

python-automation-tool undo --report-path ./reports/undo.csv