geocodio-library-python 0.1.0__tar.gz

geocodio_library_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test-and-lint:
+    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"
+#          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: |
+          uv sync
+          uv pip install .
+          uv pip install .[dev]
+
+      - name: Run unit tests
+        run: |
+          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: |
+          uv run flake8 src/ --ignore=E501

geocodio_library_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+      - hotfix/*
+      - release/*
+  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 PyPI (on release)
+      if: github.event_name == 'release'
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        uv run twine upload --verbose dist/*
+    
+    - name: Publish to TestPyPI (manual)
+      if: github.event.inputs.publish_to == 'testpypi'
+      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 (manual)
+      if: github.event.inputs.publish_to == 'pypi'
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        uv run twine upload --verbose dist/*

geocodio_library_python-0.1.0/.github/workflows/test-act-event-ci.json

@@ -0,0 +1,9 @@
+{
+    "event": "workflow_dispatch",
+    "workflow": "publish.yml",
+    "ref": "refs/heads/feature/ci-pipeline-tasks",
+    "inputs": {
+      "version": "0.0.1",
+      "publish_to": "testpypi"
+    }
+  }

geocodio_library_python-0.1.0/.github/workflows/test-act-event-publish.json

@@ -0,0 +1,9 @@
+{
+    "event": "workflow_dispatch",
+    "workflow": "publish.yml",
+    "ref": "refs/heads/feature/ci-pipeline-tasks",
+    "inputs": {
+      "version": "0.0.1",
+      "publish_to": "testpypi"
+    }
+  }

geocodio_library_python-0.1.0/.gitignore

@@ -0,0 +1,80 @@
+# macOS system files
+.DS_Store
+
+# 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/
+.cursor/
+*.swp
+*.swo
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE specific files
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Environment variables
+.env
+
+# Documentation
+docs/_build/

geocodio_library_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-08-08
+
+### Added
+- Initial release of the official Python client for the Geocodio API
+- Forward geocoding for single addresses and batch operations (up to 10,000 addresses)
+- Reverse geocoding for single coordinates and batch operations
+- List API support for managing large batch jobs
+- Field appending capabilities (census data, timezone, congressional districts, etc.)
+- Comprehensive error handling with structured exception hierarchy
+- Full test coverage with unit and end-to-end tests
+- Support for Geocodio Enterprise API via hostname parameter
+- Modern async-capable HTTP client using httpx
+- Type hints and dataclass models for better IDE support
+- GitHub Actions CI/CD pipeline for automated testing and publishing
+
+## Release Process
+
+When ready to release:
+1. Update the version in `pyproject.toml`
+2. Move all "Unreleased" items to a new version section with date
+3. Commit with message: `chore: prepare release vX.Y.Z`
+4. Tag the release: `git tag vX.Y.Z`
+5. Push tags: `git push --tags`
+6. GitHub Actions will automatically publish to PyPI
+
+[Unreleased]: https://github.com/Geocodio/geocodio-library-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Geocodio/geocodio-library-python/releases/tag/v0.1.0

geocodio_library_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Dotsquare LLC <hello@geocod.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

geocodio_library_python-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: geocodio-library-python
+Version: 0.1.0
+Summary: A Python client for the Geocodio API
+Project-URL: Homepage, https://www.geocod.io
+Project-URL: Documentation, https://www.geocod.io/docs/?python
+Project-URL: Repository, https://github.com/geocodio/geocodio-library-python
+Project-URL: Issues, https://github.com/geocodio/geocodio-library-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geocodio
+
+The official Python client for the Geocodio API.
+
+Features
+--------
+
+- Forward geocoding of single addresses or in batches (up to 10,000 lookups).
+- Reverse geocoding of coordinates (single or batch).
+- Append additional data fields (e.g. congressional districts, timezone, census data).
+- Automatic parsing of address components.
+- Simple exception handling for authentication, data, and server errors.
+
+Installation
+------------
+
+Install via pip:
+
+    pip install geocodio-library-python
+
+Development Installation
+-----------------------
+
+1. Clone the repository:
+    ```bash
+    git clone https://github.com/geocodio/geocodio-library-python.git
+    cd geocodio-library-python
+    ```
+
+2. Create and activate a virtual environment:
+    ```bash
+    python -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
+    ```
+
+3. Install development dependencies:
+    ```bash
+    pip install -e .
+    pip install -r requirements-dev.txt
+    ```
+
+Usage
+-----
+
+### Geocoding
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize the client with your API key
+client = GeocodioClient("YOUR_API_KEY")
+
+# Single forward geocode
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
+
+# Batch forward geocode
+addresses = [
+    "1600 Pennsylvania Ave, Washington, DC",
+    "1 Infinite Loop, Cupertino, CA"
+]
+batch_response = client.geocode(addresses)
+for result in batch_response.results:
+    print(result.formatted_address)
+
+# Single reverse geocode
+rev = client.reverse("38.9002898,-76.9990361")
+print(rev.results[0].formatted_address)
+
+# Append additional fields
+data = client.geocode(
+    "1600 Pennsylvania Ave, Washington, DC",
+    fields=["cd", "timezone"]
+)
+print(data.results[0].fields.timezone.name if data.results[0].fields.timezone else "No timezone data")
+```
+
+### List API
+
+The List API allows you to manage lists of addresses or coordinates for batch processing.
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize the client with your API key
+client = GeocodioClient("YOUR_API_KEY")
+
+# Get all lists
+lists = client.get_lists()
+print(f"Found {len(lists.data)} lists")
+
+# 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}")
+
+# Get a specific list
+list_details = client.get_list(new_list.id)
+print(f"List status: {list_details.status}")
+
+# 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(new_list.id)
+```
+
+Error Handling
+--------------
+
+```python
+from geocodio import GeocodioClient
+from geocodio.exceptions import 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}")
+```
+
+Geocodio Enterprise
+-------------------
+
+To use this library with Geocodio Enterprise, pass `api.enterprise.geocod.io` as the `hostname` parameter when initializing the client:
+
+```python
+from geocodio import GeocodioClient
+
+# Initialize client for Geocodio Enterprise
+client = GeocodioClient(
+    "YOUR_API_KEY",
+    hostname="api.enterprise.geocod.io"
+)
+
+# All methods work the same as with the standard API
+response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
+print(response.results[0].formatted_address)
+```
+
+Documentation
+-------------
+
+Full documentation is available at <https://www.geocod.io/docs/?python>.
+
+Contributing
+------------
+
+Contributions are welcome! Please open issues and pull requests on GitHub.
+
+Issues: <https://github.com/geocodio/geocodio-library-python/issues>
+
+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.