# 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)

```bash
npx kens-pythontools
```

### Using pip

```bash
# Install
pip install kens-pythontools

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

### Using Poetry

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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](LICENSE) file for details.

## Acknowledgments

- Inspired by [create-t3-app](https://create.t3.gg/) - the gold standard for project scaffolding
- Built with [Typer](https://typer.tiangolo.com/) for the CLI interface
- Uses [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- Powered by [Cookiecutter](https://cookiecutter.readthedocs.io/) for templating

---

**Happy coding!** 🐍✨