Initial commit: Create Python project starter template

Author: neubig

.github/workflows/lint.yml

@@ -0,0 +1,21 @@
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.8'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ".[dev]"
+    - name: Run ruff
+      run: ruff check .
+    - name: Run mypy
+      run: mypy src tests

.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11']
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install ".[dev]"
+    - name: Run tests
+      run: pytest

.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project specific
+*.png
+*.csv
+!data/sample.csv

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+-   repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.1.6
+    hooks:
+    -   id: ruff
+        args: [--fix]
+    -   id: ruff-format
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.1
+    hooks:
+    -   id: mypy
+        additional_dependencies: [types-all]

README.md

@@ -1,2 +1,93 @@
-# starter-repo
-An example starter repo for Python projects
+# Python Project Starter Repository
+
+This repository serves as a template demonstrating Python best practices for data analysis projects. It includes examples of:
+- CSV data processing
+- Data visualization with matplotlib
+- Command-line argument parsing
+- Type annotations
+- Testing
+- Code quality tools
+- Continuous Integration
+
+## Features
+
+### 1. Data Processing and Visualization
+The main script ([src/starter_repo/plot_data.py](src/starter_repo/plot_data.py)) demonstrates:
+- Reading CSV files using pandas
+- Creating plots with matplotlib
+- Modern Python type annotations
+- Command-line argument parsing with argparse
+
+Example usage:
+```bash
+# Install the package
+pip install .
+
+# Create a plot from the sample data
+python -m starter_repo.plot_data data/sample.csv year population --title "Population Growth" -o population.png
+```
+
+### 2. Testing
+The project uses pytest for testing. Test files are located in the [tests/](tests/) directory.
+
+To run tests:
+```bash
+pip install ".[dev]"  # Install development dependencies
+pytest
+```
+
+### 3. Code Quality Tools
+This project uses several tools to maintain code quality:
+
+#### Pre-commit Hooks
+We use [pre-commit](.pre-commit-config.yaml) with:
+- [Ruff](https://github.com/charliermarsh/ruff) for linting and formatting
+- [mypy](https://mypy.readthedocs.io/) for static type checking
+
+To set up pre-commit:
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+### 4. Continuous Integration
+GitHub Actions workflows are set up for:
+- [Linting](.github/workflows/lint.yml): Runs Ruff and mypy
+- [Testing](.github/workflows/test.yml): Runs pytest on multiple Python versions
+
+### 5. Project Structure
+```
+.
+|- src/
+|  |- starter_repo/      # Source code
+|     |- plot_data.py   # Main script
+|- tests/                 # Test files
+|  |- test_plot_data.py
+|- data/                  # Sample data
+|  |- sample.csv
+|- .github/workflows/     # CI configuration
+|- pyproject.toml        # Project metadata and dependencies
+|- .pre-commit-config.yaml # Pre-commit hook configuration
+|- README.md
+```
+
+## Installation
+
+```bash
+# For users
+pip install .
+
+# For developers
+pip install -e ".[dev]"
+```
+
+## Contributing
+1. Fork the repository
+2. Install development dependencies: `pip install -e ".[dev]"`
+3. Install pre-commit hooks: `pre-commit install`
+4. Make your changes
+5. Run tests: `pytest`
+6. Submit a pull request
+
+## Author
+Graham Neubig ([email protected])

data/sample.csv

@@ -0,0 +1,12 @@
+year,population
+2000,6115
+2001,6214
+2002,6312
+2003,6411
+2004,6510
+2005,6609
+2006,6709
+2007,6809
+2008,6909
+2009,7009
+2010,7109

pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "starter-repo"
+version = "0.1.0"
+authors = [
+    { name="Graham Neubig", email="[email protected]" },
+]
+description = "A starter repository demonstrating Python best practices"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "pandas",
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+    "mypy",
+    "pre-commit",
+]
+
+[tool.ruff]
+select = ["E", "F", "I"]
+line-length = 100
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

src/starter_repo/plot_data.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+
+from pathlib import Path
+import argparse
+import pandas as pd
+import matplotlib.pyplot as plt
+from typing import list, tuple
+
+def read_csv_data(file_path: Path, x_col: str, y_col: str) -> tuple[list[float], list[float]]:
+    """Read data from a CSV file and return specified columns.
+    
+    Args:
+        file_path: Path to the CSV file
+        x_col: Name of the column to use for x-axis
+        y_col: Name of the column to use for y-axis
+        
+    Returns:
+        Tuple of x and y data as lists
+    """
+    df = pd.read_csv(file_path)
+    return df[x_col].tolist(), df[y_col].tolist()
+
+def create_plot(x_data: list[float], y_data: list[float], 
+                x_label: str, y_label: str, title: str) -> plt.Figure:
+    """Create a plot from the provided data.
+    
+    Args:
+        x_data: Data for x-axis
+        y_data: Data for y-axis
+        x_label: Label for x-axis
+        y_label: Label for y-axis
+        title: Plot title
+        
+    Returns:
+        matplotlib Figure object
+    """
+    fig, ax = plt.subplots()
+    ax.plot(x_data, y_data)
+    ax.set_xlabel(x_label)
+    ax.set_ylabel(y_label)
+    ax.set_title(title)
+    return fig
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Create plots from CSV data")
+    parser.add_argument("file_path", type=Path, help="Path to the CSV file")
+    parser.add_argument("x_column", type=str, help="Column name for x-axis")
+    parser.add_argument("y_column", type=str, help="Column name for y-axis")
+    parser.add_argument("--output", "-o", type=Path, default=Path("plot.png"),
+                       help="Output file path (default: plot.png)")
+    parser.add_argument("--title", "-t", type=str, default="Data Plot",
+                       help="Plot title (default: Data Plot)")
+    
+    args = parser.parse_args()
+    
+    x_data, y_data = read_csv_data(args.file_path, args.x_column, args.y_column)
+    fig = create_plot(x_data, y_data, args.x_column, args.y_column, args.title)
+    fig.savefig(args.output)
+    plt.close(fig)
+
+if __name__ == "__main__":
+    main()

tests/test_plot_data.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+import pandas as pd
+import pytest
+from starter_repo.plot_data import read_csv_data, create_plot
+
+@pytest.fixture
+def sample_csv(tmp_path: Path) -> Path:
+    """Create a sample CSV file for testing."""
+    df = pd.DataFrame({
+        'x': [1, 2, 3, 4, 5],
+        'y': [2, 4, 6, 8, 10]
+    })
+    file_path = tmp_path / "test.csv"
+    df.to_csv(file_path, index=False)
+    return file_path
+
+def test_read_csv_data(sample_csv: Path) -> None:
+    """Test reading data from CSV file."""
+    x_data, y_data = read_csv_data(sample_csv, 'x', 'y')
+    assert x_data == [1, 2, 3, 4, 5]
+    assert y_data == [2, 4, 6, 8, 10]
+
+def test_create_plot() -> None:
+    """Test plot creation."""
+    x_data = [1, 2, 3]
+    y_data = [2, 4, 6]
+    fig = create_plot(x_data, y_data, "X", "Y", "Test Plot")
+    assert fig is not None
+    # Basic check that the figure contains the expected elements
+    ax = fig.axes[0]
+    assert ax.get_xlabel() == "X"
+    assert ax.get_ylabel() == "Y"
+    assert ax.get_title() == "Test Plot"