Calc - CLI Template

A sample CLI application template for CSV processing, built with Python, Typer, and Poetry. This template demonstrates best practices for CLI application development, testing, and project structure.

Features

• Typer CLI Framework: Modern, type-safe CLI with automatic help generation
• Poetry Dependency Management: Reliable dependency management and virtual environments
• Comprehensive Testing: Unit tests with CLIRunner for command testing
• Code Quality Tools: Pre-commit hooks, type checking, and code formatting
• Modular Structure: Organized command namespaces and utility modules

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd app-template

# Install dependencies
poetry install

# Set up pre-commit hooks
poetry run pre-commit install

# Copy environment configuration
cp env.example .env

Usage

# Show help
poetry run calc --help

# Check commands
poetry run calc check hello
poetry run calc check goodbye --name "Alice"

# Ingest commands (with sample data)
poetry run calc ingest read-csv sample_data/sample.csv
poetry run calc ingest validate-csv sample_data/sample.csv

# Process commands
poetry run calc process calculate-average sample_data/sample.csv
poetry run calc process calculate-average sample_data/sample.csv --column age
poetry run calc process calculate-average sample_data/sample_large.csv --by department
poetry run calc process calculate-max sample_data/sample.csv --column age

Command Structure

Ingest Namespace

• read-csv: Read and display CSV data
• validate-csv: Validate CSV structure and data

Check Namespace

• hello: Print a hello message
• goodbye: Print a goodbye message

Process Namespace

• calculate-average: Calculate average of numeric columns with options for specific columns and grouping
• calculate-max: Calculate maximum value of numeric columns (placeholder implementation)

Development

Running Tests

# Run unit tests
make test-unit

# Run all tests
make test

# Run with coverage
poetry run pytest --cov=src/calc

Code Quality

# Type checking
make type-check

# Code formatting
make format

# Install dependencies
make install

Project Structure

app-template/
├── src/calc/              # Main application code
│   ├── cli.py              # CLI entry point
│   ├── config.py           # Configuration management
│   ├── commands/           # Command implementations
│   └── utils/              # Utility functions
├── tests/                  # Test suite
├── sample_data/            # Sample CSV files
├── .cursor/                # Cursor IDE configuration
└── pyproject.toml          # Poetry configuration

Configuration

The application uses environment variables for configuration:

• ENVIRONMENT: Application environment (development/test/production)
• LOG_LEVEL: Logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL)

Testing

The project includes comprehensive tests using pytest and CLIRunner:

• Command Tests: Test CLI commands with various options
• Utility Tests: Test helper functions and utilities
• Integration Tests: Test with sample data files

Contributing

1. Follow the established code structure and patterns
2. Add tests for new functionality
3. Run make type-check and make test-unit before committing
4. Use pre-commit hooks for code quality

License

MIT License - see LICENSE file for details.