haddock-development/claude-reflect-system/python-project-creator

Python Project Creator

Critical Corrections

Use 'uv' instead of 'pip'

• ✗ Don't: pip install, pip freeze
• ✓ Do: uv pip install, uv pip freeze (uv is faster and more modern)

Always use pytest, never unittest

• ✗ Don't: unittest framework
• ✓ Do: pytest for all testing needs

Overview

This skill creates well-structured Python projects with best practices for dependency management, testing, and code organization. It sets up virtual environments, installs dependencies, and configures common development tools.

Project Creation Workflow

1. Understand Requirements

Ask the user about:

• Project name and purpose
• Type: CLI tool, web app, library, data science project
• Dependencies: Required packages
• Testing: Testing framework preference (pytest, unittest)

2. Create Project Structure

Standard Python project structure:

project-name/
├── src/
│   └── project_name/
│       ├── __init__.py
│       └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── .gitignore
├── README.md
├── requirements.txt
└── setup.py (optional, for libraries)

3. Virtual Environment Setup

Create and activate virtual environment:

# Create virtual environment
python3 -m venv venv
 
# Activate (instructions for user)
# macOS/Linux: source venv/bin/activate
# Windows: venv\Scripts\activate

4. Install Dependencies

Install packages using uv:

uv pip install <package-name>
uv pip freeze > requirements.txt

For development dependencies:

uv pip install pytest black flake8 mypy

5. Initialize Git

git init
git add .
git commit -m "Initial commit: project setup"

Project Types

CLI Application

• Use argparse or click for command-line arguments
• Include main.py with proper entry point
• Add if __name__ == "__main__": guard

Web Application

• Flask: Lightweight, good for small APIs
• FastAPI: Modern, async, auto-documentation
• Django: Full-featured, batteries included

Library/Package

• Include setup.py for packaging
• Follow semantic versioning
• Add comprehensive docstrings

Data Science

• Include notebooks/ directory for Jupyter notebooks
• Add data/ directory (with .gitignore)
• Common packages: pandas, numpy, matplotlib, scikit-learn

Testing Setup

pytest (Required)

Always use pytest for testing:

uv pip install pytest pytest-cov

Example test file:

# tests/test_main.py
import pytest
from src.project_name.main import my_function
def test_my_function():
    assert my_function(2, 3) == 5

Run tests:

pytest
pytest --cov=src  # with coverage

Code Quality Tools

Black (Code Formatter)

uv pip install black
black src/ tests/

Flake8 (Linter)

uv pip install flake8
flake8 src/ tests/

mypy (Type Checker)

uv pip install mypy
mypy src/

Common Patterns

Entry Point Pattern

# src/project_name/main.py
def main():
    """Main application entry point."""
    print("Hello, World!")
if __name__ == "__main__":
    main()

Configuration Pattern

# src/project_name/config.py
import os
from pathlib import Path
# Project root directory
PROJECT_ROOT = Path(__file__).parent.parent.parent
# Load environment variables
DEBUG = os.getenv("DEBUG", "False") == "True"

Error Handling Pattern

class ProjectError(Exception):
    """Base exception for this project."""
    pass
class ConfigError(ProjectError):
    """Configuration-related errors."""
    pass

.gitignore Template

# Virtual environment
venv/
env/
.venv/
 
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
dist/
build/
 
# IDE
.vscode/
.idea/
*.swp
*.swo
 
# Environment
.env
.env.local
 
# Testing
.pytest_cache/
.coverage
htmlcov/
 
# OS
.DS_Store
Thumbs.db

Best Practices

Dependency Management

• Pin exact versions in production: package==1.2.3
• Use ranges for libraries: package>=1.2,<2.0
• Separate dev dependencies from production
• Keep requirements.txt minimal

Project Structure

• Use src/ layout to avoid import issues
• Keep tests separate from source code
• One module per file, clear naming
• Flat is better than nested (within reason)

Documentation

• Write clear README.md with setup instructions
• Add docstrings to all public functions/classes
• Include usage examples in README
• Document environment variables

Version Control

• Initialize git from the start
• Write meaningful commit messages
• Create .gitignore before first commit
• Never commit secrets or credentials

Quick Start Examples

Minimal CLI Tool

mkdir my-cli-tool && cd my-cli-tool
python3 -m venv venv
source venv/bin/activate
uv pip install click
# Create main.py, tests, etc.

FastAPI Web Service

mkdir my-api && cd my-api
python3 -m venv venv
source venv/bin/activate
uv pip install fastapi uvicorn
# Create app structure

Data Science Project

mkdir my-analysis && cd my-analysis
python3 -m venv venv
source venv/bin/activate
uv pip install pandas numpy matplotlib jupyter
# Create notebooks/, data/, src/

Resources

This skill includes examples in the bundled directories:

scripts/

• example.py - Template Python script with best practices

references/

• api_reference.md - Common library documentation references

assets/

• Project templates and boilerplate code