py_plate

A modern Python CLI template with best practices, featuring Typer, Ruff, pre-commit hooks, and comprehensive tooling setup.

✨ Features

• 🚀 Modern CLI with Typer and Rich
• 🔧 Development tools with Ruff for linting and formatting
• 🛡️ Security with pre-commit hooks and secret detection
• 🧪 Testing with pytest and coverage reporting
• 📦 Easy installation with pipx support
• 🎯 Type safety with mypy
• 📋 Code quality with comprehensive linting rules
• 🚀 CI/CD with GitHub Actions for testing, linting, and releases
• 📊 Coverage reporting with Codecov integration

🛡️ Security Tools

This template includes comprehensive security scanning tools that run automatically in CI/CD pipelines and can be used during development:

• Trivy - Vulnerability scanner for filesystems, containers, and packages

  • Scans for known vulnerabilities in dependencies
  • Generates detailed security reports in multiple formats
  • Integrated into CI pipeline and release artifacts

• Bandit - Security linter for Python code

  • Identifies common security issues in Python code
  • Configurable via pyproject.toml
  • Runs automatically in CI pipeline

• Safety - Dependency vulnerability scanner

  • Checks Python dependencies against known security vulnerabilities
  • Integrates with requirements and package files
  • Provides detailed vulnerability reports

• detect-secrets - Prevents secrets from being committed

  • Scans for API keys, tokens, and other sensitive data
  • Uses baseline file to track known false positives
  • Runs as pre-commit hook and in CI pipeline

All security tools generate JSON reports that are included as artifacts in GitHub releases, providing transparency and audit trails for security compliance.

🚀 Quick Start with pipx

pipx is the recommended way to install Python CLI applications. It installs packages in isolated environments while making their entry points available globally.

Install pipx (if not already installed)

# On macOS
brew install pipx

# On Ubuntu/Debian
sudo apt update && sudo apt install pipx

# On other systems with pip
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Install the CLI

# Install from PyPI (when published)
pipx install py-plate-template

# Or install from local directory
pipx install .

# Or install in development mode
pipx install --editable .

Usage

# Show help
py-plate --help

# Greet someone
py-plate hello Alice

# Greet with options
py-plate hello Bob --count 3 --shout

# Show system information
py-plate info

# Show version
py-plate --version

# Manage configuration
py-plate config --show
py-plate config --set debug true

🛠️ Development Setup

Prerequisites

• Python 3.9 or higher
• pip or pipx

Development Installation

# Clone the repository
git clone https://github.com/GRodolphe/py_plate.git
cd py_plate

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Or use pipx for isolated development
pipx install --editable ".[dev]"

Set up pre-commit hooks

# Install pre-commit hooks
pre-commit install

# Run hooks on all files (optional)
pre-commit run --all-files

🧪 Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific test file
pytest tests/test_cli.py

# Run with verbose output
pytest -v

🔧 Development Commands

# Format code
ruff format

# Lint code
ruff check

# Fix linting issues automatically
ruff check --fix

# Type check
mypy src/

# Run all quality checks
ruff check && ruff format --check && mypy src/ && pytest

📦 Building and Publishing

# Build the package
python -m build

# Upload to PyPI (requires authentication)
python -m twine upload dist/*

🏗️ Project Structure

py_plate/
├── src/
│   └── py_plate/
│       ├── __init__.py          # Package version and metadata
│       └── cli.py               # Main CLI application
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # Pytest configuration and fixtures
│   └── test_cli.py              # CLI tests
├── .gitignore                   # Git ignore rules
├── .pre-commit-config.yaml      # Pre-commit hooks configuration
├── .secrets.baseline            # Secrets detection baseline
├── pyproject.toml               # Project configuration and dependencies
└── README.md                    # This file

⚙️ Configuration

The project uses pyproject.toml for all configuration:

• Build system: Hatchling
• Dependencies: Typer, Rich
• Development tools: Ruff, mypy, pytest
• Code quality: Pre-commit hooks with multiple checkers

Key Configuration Sections

• Ruff: Linting and formatting rules
• Pytest: Test configuration and coverage
• MyPy: Type checking settings
• Pre-commit: Hook definitions for code quality

🚀 GitHub Actions Workflows

The template includes comprehensive CI/CD pipelines:

CI Pipeline (ci.yml)

• Multi-version testing: Tests against Python 3.9, 3.10, 3.11, and 3.12
• Code quality: Ruff linting and formatting checks
• Type safety: MyPy type checking
• Test coverage: Pytest with coverage reporting
• Security scanning: Bandit and Safety checks
• Secret detection: Automated secret scanning
• Build verification: Package building and artifact upload

Release Pipeline (release.yml)

• Automated releases: Triggered on version tags
• PyPI publishing: Automatic package publishing
• GitHub releases: Automated release notes generation
• Pre-release validation: Full test suite before release

Pre-commit Pipeline (pre-commit.yml)

• Code quality gates: Automated pre-commit hook validation
• Consistent formatting: Ensures code standards across contributions

🔒 Security Features

• Secret detection with detect-secrets
• Dependency vulnerability scanning with Safety
• Security linting with Bandit
• Pre-commit hooks for automated checking
• Automated security scans in CI pipeline

🎯 Best Practices Included

• Type hints throughout the codebase
• Comprehensive error handling
• Rich console output for better UX
• Structured logging ready for implementation
• Configuration management pattern
• Test coverage tracking
• Documentation with examples

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request

The pre-commit hooks will automatically run code quality checks on each commit.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.