feat: add pre-commit hooks and format codebase

- Add .pre-commit-config.yaml with black, isort, flake8 hooks
- Configure black with 89 char line limit to match existing style
- Configure isort to be compatible with black
- Format entire codebase with black and isort
- Fix trailing whitespace and missing newlines
- Update CI workflows to use consistent linting
- Add pre-commit workflow for automated checks
- Add scripts for easy formatting and setup
- Update documentation with pre-commit instructions

All Python files now follow consistent formatting standards.

Author: andrewkern

.flake8

@@ -1,2 +1,18 @@
 [flake8]
-max-line-length = 89 
+max-line-length = 89
+extend-ignore = E203, E266, E501, W503, E402
+max-complexity = 10
+exclude =
+    .git,
+    __pycache__,
+    docs/source/conf.py,
+    old,
+    build,
+    dist,
+    .eggs,
+    *.egg,
+    work/,
+    out/
+per-file-ignores =
+    __init__.py:F401,F403
+    tests/*:F401,F403,E501

.github/CI_CD_SETUP.md

@@ -0,0 +1,70 @@
+# CI/CD Setup for Locator
+
+This repository uses GitHub Actions for continuous integration and deployment.
+
+## Workflows
+
+### 1. Tests (`.github/workflows/test.yml`)
+- **Triggers**: Push and pull requests to main/develop branches
+- **Python versions**: 3.9, 3.10, 3.11
+- **Features**:
+  - Parallel test execution with pytest-xdist (`-n auto`)
+  - Coverage reporting with pytest-cov
+  - CPU-only mode (no GPU required)
+  - Dependency caching for faster runs
+  - Code linting with black, isort, and flake8
+
+### 2. Documentation (`.github/workflows/docs.yml`) 
+- Builds Sphinx documentation
+- Checks for documentation warnings
+- Uploads built docs as artifacts
+
+### 3. Publishing (`.github/workflows/publish.yml`)
+- Triggered on GitHub releases
+- Publishes to PyPI and Test PyPI
+- Requires secrets: `PYPI_API_TOKEN`, `TEST_PYPI_API_TOKEN`
+
+### 4. Manual Testing (`.github/workflows/manual-test.yml`)
+- Allows manual workflow triggers
+- Configurable Python version and test patterns
+
+## Local Testing
+
+Run tests locally with parallel execution:
+```bash
+# Run all tests in parallel
+pytest -n auto
+
+# Run with 4 workers
+pytest -n 4
+
+# Run without GPU (recommended)
+CUDA_VISIBLE_DEVICES=-1 pytest -n auto
+
+# Run specific test file
+pytest tests/test_verbosity_control.py -n auto
+
+# Run with coverage
+pytest -n auto --cov=locator --cov-report=html
+```
+
+## Configuration
+
+- **pytest configuration**: See `pyproject.toml`
+- **Coverage settings**: See `pyproject.toml` 
+- **Dependabot**: See `.github/dependabot.yml`
+
+## Required Secrets (for publishing)
+
+Set these in your GitHub repository settings:
+- `CODECOV_TOKEN` (optional, for private repos)
+- `PYPI_API_TOKEN` (for PyPI publishing)
+- `TEST_PYPI_API_TOKEN` (for Test PyPI publishing)
+
+## Status Badges
+
+Add these to your README.md:
+```markdown
+[![Tests](https://github.com/YOUR_USERNAME/relocator/actions/workflows/test.yml/badge.svg)](https://github.com/YOUR_USERNAME/relocator/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/YOUR_USERNAME/relocator/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_USERNAME/relocator)
+```

.github/ISSUE_TEMPLATE/bug_report.md

@@ -41,4 +41,4 @@ If applicable, paste the full error traceback here.
  - CUDA/GPU info (if relevant): [e.g. CUDA 12.1, RTX 4090]
 
 **Additional context**
-Add any other context about the problem here.
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -27,4 +27,4 @@ import locator
 ```
 
 **Additional context**
-Add any other context or screenshots about the feature request here.
+Add any other context or screenshots about the feature request here.

.github/dependabot.yml

@@ -33,4 +33,4 @@ updates:
       - "adkern"
     labels:
       - "dependencies"
-      - "github-actions"
+      - "github-actions"

.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Description
+
+Please include a summary of the changes and which issue is fixed. Include relevant motivation and context.
+
+Fixes #(issue)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code refactoring
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce.
+
+- [ ] Test A
+- [ ] Test B
+
+**Test Configuration**:
+* Python version:
+* TensorFlow version:
+* Operating System:
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published in downstream modules

.github/workflows/badges.md

@@ -9,4 +9,4 @@ Add these badges to your README.md:
 ```
 
 Replace YOUR_USERNAME with your GitHub username or organization name.
-EOF < /dev/null
+EOF < /dev/null

.github/workflows/docs.yml

@@ -9,15 +9,15 @@ on:
 jobs:
   build-docs:
     runs-on: ubuntu-latest
-    
+
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
-    
+
     - name: Cache pip packages
       uses: actions/cache@v4
       with:
@@ -26,37 +26,37 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-pip-docs-
           ${{ runner.os }}-pip-
-    
+
     - name: Install system dependencies
       run: |
         sudo apt-get update
         sudo apt-get install -y libproj-dev proj-data proj-bin libgeos-dev
         sudo apt-get install -y pandoc
-    
+
     - name: Install package with docs dependencies
       env:
         CUDA_VISIBLE_DEVICES: "-1"
       run: |
         python -m pip install --upgrade pip
         pip install wheel
         pip install -e ".[docs]"
-    
+
     - name: Build documentation
       run: |
         cd docs
         make clean
         make html
-    
+
     - name: Check for documentation warnings
       run: |
         cd docs
         if make html 2>&1 | grep -i "warning"; then
           echo "Documentation build produced warnings"
           exit 1
         fi
-    
+
     - name: Upload documentation artifacts
       uses: actions/upload-artifact@v4
       with:
         name: documentation
-        path: docs/_build/html/
+        path: docs/_build/html/

.github/workflows/manual-test.yml

@@ -26,15 +26,15 @@ on:
 jobs:
   manual-test:
     runs-on: ubuntu-latest
-    
+
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Set up Python ${{ inputs.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ inputs.python-version }}
-    
+
     - name: Cache pip packages
       uses: actions/cache@v4
       with:
@@ -43,20 +43,20 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-pip-${{ inputs.python-version }}-
           ${{ runner.os }}-pip-
-    
+
     - name: Install system dependencies
       run: |
         sudo apt-get update
         sudo apt-get install -y libproj-dev proj-data proj-bin libgeos-dev
-    
+
     - name: Install package and dependencies
       env:
         CUDA_VISIBLE_DEVICES: "-1"
       run: |
         python -m pip install --upgrade pip
         pip install wheel
         pip install -e ".[dev]"
-    
+
     - name: Show environment info
       run: |
         echo "Python version: $(python --version)"
@@ -67,7 +67,7 @@ jobs:
         echo "TensorFlow info:"
         python -c "import tensorflow as tf; print(f'TensorFlow version: {tf.__version__}')"
         python -c "import tensorflow as tf; print(f'GPU available: {tf.config.list_physical_devices(\"GPU\")}')"
-    
+
     - name: Run specific tests
       if: inputs.test-pattern != ''
       env:
@@ -79,7 +79,7 @@ jobs:
         else
           pytest -n auto tests/${{ inputs.test-pattern }}
         fi
-    
+
     - name: Run all tests
       if: inputs.test-pattern == ''
       env:
@@ -90,4 +90,4 @@ jobs:
           pytest -v -n auto --cov=locator --cov-report=xml --cov-report=term-missing
         else
           pytest -n auto --cov=locator --cov-report=xml --cov-report=term-missing
-        fi
+        fi

.github/workflows/pre-commit.yml

@@ -0,0 +1,49 @@
+name: Pre-commit
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    
+    - name: Cache pre-commit environments
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+        restore-keys: |
+          pre-commit-${{ runner.os }}-
+    
+    - name: Install pre-commit
+      run: |
+        python -m pip install --upgrade pip
+        pip install pre-commit
+    
+    - name: Run pre-commit on all files
+      run: |
+        pre-commit run --all-files --show-diff-on-failure --color=always
+      continue-on-error: true
+    
+    - name: Comment PR on failure
+      if: failure() && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: '❌ Pre-commit checks failed. Please run `pre-commit run --all-files` locally and commit the changes.'
+          })