kens-pythontools

🐍 A create-t3-app-style interactive CLI for scaffolding modern Python CLI tools

Overview

kens-pythontools is a powerful project generator that creates production-ready Python CLI applications with modern best practices, secure dependencies, and professional tooling built-in. Inspired by create-t3-app, it provides an opinionated foundation while remaining flexible for your specific needs.

Features

• ⚡ Modern CLI Frameworks - Choose from Typer, Click, or argparse
• 🎨 Beautiful Terminal Output - Rich formatting with colors and progress bars
• 📦 Multiple Package Managers - Support for Poetry, pip, and Pipenv
• 🔒 Security First - Latest secure dependencies with vulnerability scanning
• 🧪 Testing Ready - Pytest setup with coverage reporting
• 🔍 Code Quality - Ruff, Black, and MyPy pre-configured
• 🚀 CI/CD Included - GitHub Actions workflow ready to go
• 📝 Comprehensive Logging - Structured logging with Loguru
• ⚙️ Configuration Support - TOML, YAML, or JSON config files
• 🌐 HTTP Client - Modern async HTTP client with httpx
• 🎯 Type Safe - Full type hints throughout

Quick Start

Using npx (Recommended)

npx kens-pythontools

Using pip

# Install
pip install kens-pythontools

# Create new project
kens-pythontools my-awesome-cli

Using Poetry

# Install
poetry add --dev kens-pythontools

# Create new project
poetry run kens-pythontools my-awesome-cli

Interactive Setup

kens-pythontools guides you through setting up your project with smart questions:

1. Project Name - What to call your CLI tool
2. CLI Framework - Typer (recommended), Click, or argparse
3. Package Manager - Poetry (recommended), pip, or Pipenv
4. Optional Features - Rich output, config files, logging, HTTP client, etc.
5. Development Tools - Testing, linting, pre-commit hooks, CI/CD
6. Git Integration - Initialize repository and install dependencies

Generated Project Structure

my-awesome-cli/
├── src/
│   └── my_awesome_cli/
│       ├── __init__.py
│       ├── main.py          # Main CLI entry point
│       ├── cli/             # CLI commands
│       └── core/            # Core business logic
├── tests/                   # Test files
├── docs/                    # Documentation
├── .github/workflows/       # CI/CD workflows
├── pyproject.toml           # Project configuration
├── README.md
└── LICENSE

Technology Choices

CLI Frameworks

• Typer - Modern, type-safe, auto-documented (recommended)
• Click - Mature, widely-used, highly configurable
• argparse - Standard library, minimal dependencies

Package Managers

• Poetry - Modern dependency management with lock files (recommended)
• pip - Traditional pip with requirements.txt
• Pipenv - Pipfile-based workflow

Optional Features

• Rich - Beautiful terminal output with colors and formatting
• Loguru - Structured logging with rotation and filtering
• httpx - Modern async HTTP client for API calls
• Configuration - TOML, YAML, or JSON config file support
• File Watching - Watch files for changes with watchdog
• Async Support - Full async/await compatibility

Development Tools

• pytest - Testing framework with fixtures and plugins
• ruff - Lightning-fast linting (replaces flake8, isort, etc.)
• black - Opinionated code formatting
• mypy - Static type checking
• pre-commit - Git hooks for code quality
• GitHub Actions - CI/CD with testing and publishing

Example Usage

After creating a project:

cd my-awesome-cli

# Install dependencies (Poetry)
poetry install && poetry shell

# Run your CLI
my-awesome-cli --help
my-awesome-cli hello --name "World"

# Development commands
poetry run pytest              # Run tests
poetry run black .             # Format code
poetry run ruff check          # Lint code
poetry run mypy .              # Type check

Non-Interactive Mode

For automation and CI/CD:

# Use defaults
kens-pythontools my-project --non-interactive

# Specify project name only
kens-pythontools my-project -y

Requirements

• Python 3.10+
• Git (for repository initialization)
• Poetry, pip, or Pipenv (depending on choice)

Why kens-pythontools?

Problems It Solves

• ❌ Setup Friction - No more hours spent configuring tools
• ❌ Security Vulnerabilities - Always uses latest secure dependencies
• ❌ Inconsistent Structure - Follows Python packaging best practices
• ❌ Missing Tooling - Includes testing, linting, and CI/CD setup
• ❌ Poor Documentation - Generates comprehensive README and docs

Benefits

• ✅ Professional Quality - Production-ready code from day one
• ✅ Modern Stack - Uses current Python ecosystem best practices
• ✅ Flexible Foundation - Easy to extend without fighting the structure
• ✅ Security First - Regular dependency updates with vulnerability scanning
• ✅ Developer Experience - Beautiful CLI with helpful guidance

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (poetry run pytest && poetry run ruff check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development

# Clone the repository
git clone https://github.com/kenkai/kens-pythontools.git
cd kens-pythontools

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Test the CLI locally
poetry run kens-pythontools test-project

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by create-t3-app - the gold standard for project scaffolding
• Built with Typer for the CLI interface
• Uses Rich for beautiful terminal output
• Powered by Cookiecutter for templating

Happy coding! 🐍✨