Merge pull request #4 from Geocodio/feature/ci-pipeline-tasks

funkatron · web-flow · commit d8dbf4665d5a · 2025-07-01T16:30:06.000-04:00
Feature/ci pipeline tasks
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -27,9 +27,20 @@ jobs:
           uv pip install .
           uv pip install .[dev]
 
-      - name: Run tests
+      - name: Run unit tests
         run: |
-          uv run pytest
+          uv run pytest tests/unit/
+
+      - name: Run e2e tests
+        env:
+          GEOCODIO_API_KEY: ${{ secrets.GEOCODIO_API_KEY }}
+        run: |
+          if [ -n "$GEOCODIO_API_KEY" ]; then
+            echo "Running e2e tests with API key"
+            uv run pytest tests/e2e/ -v
+          else
+            echo "No API key provided, skipping e2e tests"
+          fi
 
       - name: Lint with flake8
         run: |
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 1.0.0)'
+        required: true
+        default: '1.0.0'
+      publish_to:
+        description: 'Where to publish'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+        - testpypi
+        - pypi
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install dependencies
+      run: |
+        uv sync
+        uv pip install build twine
+
+    - name: Update version
+      if: github.event.inputs.version
+      run: |
+        # Update version in pyproject.toml
+        sed -i 's/^version = ".*"/version = "${{ github.event.inputs.version }}"/' pyproject.toml
+
+    - name: Build package
+      run: |
+        uv run python -m build
+
+    - name: Publish to TestPyPI
+      if: github.event.inputs.publish_to == 'testpypi' || github.event_name == 'release'
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        TWINE_REPOSITORY_URL: https://test.pypi.org/legacy/
+      run: |
+        uv run twine upload --verbose dist/*
+
+    - name: Publish to PyPI
+      if: github.event.inputs.publish_to == 'pypi'
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        uv run twine upload --verbose dist/*
diff --git a/README.md b/README.md
@@ -29,14 +29,13 @@ Development Installation
 
 2. Create and activate a virtual environment:
     ```bash
-    python -m .venv venv
-    source .venv/bin/activate  # On Windows: venv\Scripts\activate
+    python -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
     ```
 
 3. Install development dependencies:
     ```bash
-    pip install .
-    pip install .[dev]
+    pip install -e .
     pip install -r requirements-dev.txt
     ```
 
@@ -52,27 +51,28 @@ from geocodio import GeocodioClient
 client = GeocodioClient("YOUR_API_KEY")
 
 # Single forward geocode
-response = client.geocode("123 Anywhere St, Chicago, IL")
-print(response)
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
 
 # Batch forward geocode
 addresses = [
-    "123 Anywhere St, Chicago, IL",
-    "456 Oak St, Los Angeles, CA"
+    "1600 Pennsylvania Ave, Washington, DC",
+    "1 Infinite Loop, Cupertino, CA"
 ]
 batch_response = client.geocode(addresses)
-print(batch_response)
+for result in batch_response.results:
+    print(result.formatted_address)
 
 # Single reverse geocode
 rev = client.reverse("38.9002898,-76.9990361")
-print(rev)
+print(rev.results[0].formatted_address)
 
 # Append additional fields
 data = client.geocode(
-    "123 Anywhere St, Chicago, IL",
+    "1600 Pennsylvania Ave, Washington, DC",
     fields=["cd", "timezone"]
 )
-print(data)
+print(data.results[0].fields.timezone.name if data.results[0].fields.timezone else "No timezone data")
 ```
 
 ### List API
@@ -85,68 +85,50 @@ from geocodio import GeocodioClient
 # Initialize the client with your API key
 client = GeocodioClient("YOUR_API_KEY")
 
-# Create a new list
-new_list = client.create_list(
-    name="My Addresses",
-    description="A list of addresses to geocode",
-    items=[
-        "1600 Pennsylvania Ave, Washington, DC",
-        "1 Infinite Loop, Cupertino, CA"
-    ]
-)
-print(new_list)
-
 # Get all lists
 lists = client.get_lists()
-print(lists)
+print(f"Found {len(lists.data)} lists")
 
-# Get a specific list
-list_id = new_list.list.id
-list_details = client.get_list(list_id)
-print(list_details)
-
-# Update a list
-updated_list = client.update_list(
-    list_id=list_id,
-    name="Updated List Name",
-    description="Updated description"
-)
-print(updated_list)
-
-# Add items to a list
-added_items = client.add_items_to_list(
-    list_id=list_id,
-    items=[
-        "123 Anywhere St, Chicago, IL",
-        "456 Oak St, Los Angeles, CA"
-    ]
-)
-print(added_items)
+# Create a new list from a file
+with open("addresses.csv", "rb") as f:
+    new_list = client.create_list(
+        file=f,
+        filename="addresses.csv",
+        direction="forward"
+    )
+print(f"Created list: {new_list.id}")
 
-# Geocode all items in a list
-geocoded_list = client.geocode_list(
-    list_id=list_id,
-    fields=["timezone", "cd"]
-)
-print(geocoded_list)
+# Get a specific list
+list_details = client.get_list(new_list.id)
+print(f"List status: {list_details.status}")
 
-# Remove items from a list
-item_ids = [item.id for item in added_items.items]
-client.remove_items_from_list(
-    list_id=list_id,
-    item_ids=item_ids
-)
+# Download a completed list
+if list_details.status and list_details.status.get("state") == "COMPLETED":
+    file_content = client.download(new_list.id, "downloaded_results.csv")
+    print("List downloaded successfully")
 
 # Delete a list
-client.delete_list(list_id)
+client.delete_list(new_list.id)
 ```
 
 Error Handling
 --------------
 
-- `GeocodioAuthError` is raised for authentication failures (HTTP 403).
-- `GeocodioDataError` is raised for invalid requests (HTTP 422).
-- `GeocodioServerError` is raised for server-side errors (HTTP 5xx).
+```python
+from geocodio import GeocodioClient, AuthenticationError, InvalidRequestError
+
+try:
+    client = GeocodioClient("INVALID_API_KEY")
+    response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+
+try:
+    client = GeocodioClient("YOUR_API_KEY")
+    response = client.geocode("")  # Empty address
+except InvalidRequestError as e:
+    print(f"Invalid request: {e}")
+```
 
 Documentation
 -------------
@@ -164,3 +146,30 @@ License
 -------
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+CI & Publishing
+---------------
+
+- CI runs unit tests and linting on every push. E2E tests run if `GEOCODIO_API_KEY` is set as a secret.
+- PyPI publishing workflow supports both TestPyPI and PyPI. See `.github/workflows/publish.yml`.
+- Use `test_pypi_release.py` for local packaging and dry-run upload.
+
+### Testing GitHub Actions Workflows
+
+The project includes tests for GitHub Actions workflows using `act` for local development:
+
+```bash
+# Test all workflows (requires act and Docker)
+pytest tests/test_workflows.py
+
+# Test specific workflow
+pytest tests/test_workflows.py::test_ci_workflow
+pytest tests/test_workflows.py::test_publish_workflow
+```
+
+**Prerequisites:**
+- Install [act](https://github.com/nektos/act) for local GitHub Actions testing
+- Docker must be running
+- For publish workflow tests: Set `TEST_PYPI_API_TOKEN` environment variable
+
+**Note:** Workflow tests are automatically skipped in CI environments.
diff --git a/test_pypi_release.py b/test_pypi_release.py
@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Test script for PyPI release process
+"""
+
+import os
+import subprocess
+import sys
+
+def run_command(cmd, description):
+    """Run a command and handle errors"""
+    print(f"\n{description}...")
+    print(f"Running: {cmd}")
+
+    try:
+        result = subprocess.run(cmd, shell=True, check=True, capture_output=True, text=True)
+        print(f"✓ {description} successful")
+        if result.stdout:
+            print(f"Output: {result.stdout}")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"✗ {description} failed")
+        print(f"Error: {e.stderr}")
+        return False
+
+def main():
+    print("Testing PyPI release process...")
+
+    # Step 1: Build the package
+    if not run_command("python -m build", "Building package"):
+        return False
+
+    # Step 2: Check the built files
+    if not os.path.isdir("dist/"):
+        print("✗ Build directory not found")
+        return False
+
+    files = os.listdir("dist/")
+    print(f"✓ Built files: {files}")
+
+    # Step 3: Check package with twine
+    if not run_command("twine check dist/*", "Checking package with twine"):
+        return False
+
+    # Step 4: Test upload to TestPyPI (dry run)
+    print("\nTesting upload to TestPyPI (dry run)...")
+    print("Note: This requires TEST_PYPI_API_TOKEN to be set")
+
+    test_pypi_token = os.getenv("TEST_PYPI_API_TOKEN")
+    if not test_pypi_token:
+        print("⚠ TEST_PYPI_API_TOKEN not set - skipping upload test")
+        print("To test upload, set TEST_PYPI_API_TOKEN environment variable")
+        return True
+
+    # Test upload to TestPyPI
+    upload_cmd = "twine upload --repository testpypi --verbose dist/*"
+    if not run_command(upload_cmd, "Uploading to TestPyPI"):
+        return False
+
+    print("\n✓ PyPI release process test completed successfully!")
+    return True
+
+if __name__ == "__main__":
+    success = main()
+    sys.exit(0 if success else 1)
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
