archibald 1.0.0__tar.gz

archibald-1.0.0/.claude/plans/release-plan.md

@@ -0,0 +1,161 @@
+# Plan: Prepare `archie` for PyPI v1.0.0 Release
+
+## Context
+
+`archie` is an async-first Python client for ESRI ArcGIS REST APIs. The code is architecturally complete with a full test suite, but it's missing the packaging metadata, documentation, and automation expected of a production PyPI release. This plan addresses the gaps needed to publish a credible v1.0.0.
+
+---
+
+## Tasks
+
+### 1. Update `pyproject.toml` metadata
+
+**File:** `pyproject.toml`
+
+Add/update the following fields under `[project]`:
+
+- `version = "1.0.0"`
+- `authors = [{name = "City of Boulder Department of Innovation and Technology", email = "nestlerj@bouldercolorado.gov"}]`
+- `license = {file = "LICENSE"}`
+- `keywords = ["arcgis", "esri", "gis", "rest", "async", "geospatial"]`
+- `classifiers`:
+  ```toml
+  classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+  ]
+  ```
+- `[project.urls]` section:
+  ```toml
+  [project.urls]
+  Repository = "https://github.com/cityofboulder/archie"  # adjust if needed
+  ```
+
+Also update `readme` to use explicit content type:
+```toml
+readme = {file = "README.md", content-type = "text/markdown"}
+```
+
+---
+
+### 2. Write README.md
+
+**File:** `README.md` (currently empty)
+
+Minimum required content:
+- Package name, one-paragraph description
+- Installation: `pip install archie` or `uv add archie`
+- Quick-start code snippet (create client, authenticate, query a layer)
+- Brief API overview: `ArchieClient`, auth classes, service/layer classes
+- Link to CHANGELOG
+
+---
+
+### 3. Update CHANGELOG.md for v1.0.0
+
+**File:** `CHANGELOG.md`
+
+- Rename `## [Unreleased]` → `## [1.0.0] - 2026-06-01`
+- Add a new empty `## [Unreleased]` section above it
+- Add the compare link at the bottom: `[1.0.0]: https://github.com/.../compare/v0.1.0...v1.0.0`
+
+---
+
+### 4. Add `py.typed` marker
+
+**File:** `src/archie/py.typed` (empty file)
+
+Required for PEP 561 so that type checkers know this package ships inline types. Also add it to `pyproject.toml` under `[tool.hatch.build.targets.wheel]`:
+```toml
+[tool.hatch.build.targets.wheel]
+include = ["src/archie/py.typed"]
+```
+(Hatchling auto-includes everything under `src/`, so this may already be covered — verify.)
+
+---
+
+### 5. Expand public API in `__init__.py`
+
+**File:** `src/archie/__init__.py`
+
+Export commonly used symbols so users can do `from archie import FeatureLayer, ArcGISAuth, QueryResult` without digging into submodules:
+
+```python
+from archie.client import ArchieClient
+from archie.auth import ArcGISAuth, NoAuth, UserTokenAuth
+from archie.exceptions import (
+    ArcGISError,
+    TokenExpiredError,
+    # ... other user-facing exceptions
+)
+from archie.models import QueryResult, FieldsResult, ApplyEditsResult
+from archie.services import FeatureService, MapService
+from archie.services.layers import FeatureLayer, MapLayer
+
+__all__ = [
+    "ArchieClient",
+    "ArcGISAuth", "NoAuth", "UserTokenAuth",
+    "ArcGISError", "TokenExpiredError", ...,
+    "QueryResult", "FieldsResult", "ApplyEditsResult",
+    "FeatureService", "MapService",
+    "FeatureLayer", "MapLayer",
+]
+```
+
+---
+
+### 6. Add GitHub Actions CI
+
+**Files:**
+- `.github/workflows/ci.yml` — run `uv run pytest` on push/PR (Python 3.12, Windows + Ubuntu)
+- `.github/workflows/publish.yml` — publish to PyPI on `v*` tag push using Trusted Publishing (OIDC, no API keys needed)
+
+The publish workflow should:
+1. Build with `uv build`
+2. Publish with `uv publish` (or `twine upload dist/*`)
+3. Use `environment: pypi` with PyPI Trusted Publishing configured on the repo
+
+---
+
+### 7. (Optional but recommended) Add `pytest-cov` and coverage config
+
+Add to `pyproject.toml`:
+```toml
+[tool.coverage.run]
+source = ["archie"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 80
+```
+
+Add `pytest-cov` to `[project.optional-dependencies]` dev group.
+
+---
+
+## Verification
+
+1. `uv build` — confirm wheel and sdist build cleanly with no warnings
+2. `pip install dist/archie-1.0.0-*.whl` in a fresh virtualenv, then `python -c "import archie; print(archie.__version__)"` (if `__version__` is added) and `from archie import FeatureLayer`
+3. Check the PyPI preview: `twine check dist/*`
+4. `uv run pytest` — full suite must pass
+5. Review the PyPI upload form / package page preview for completeness
+
+---
+
+## Priority Order
+
+| # | Task | Blocker? |
+|---|------|----------|
+| 1 | pyproject.toml metadata | Yes — bare minimum for PyPI |
+| 2 | README.md | Yes — PyPI page will be blank |
+| 3 | CHANGELOG v1.0.0 header | Yes — semver convention |
+| 4 | py.typed marker | No, but important for type-checking users |
+| 5 | Expanded __init__.py exports | No, but important for usability |
+| 6 | GitHub Actions CI/publish | No, but important before ongoing development |
+| 7 | pytest-cov | Optional |

archibald-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    name: pytest / ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest

archibald-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group docs
+      - run: uv run mkdocs gh-deploy --force

archibald-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

archibald-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tests
+.pytest*
+.coverage
+htmlcov/
+
+# Claude-specific files
+.claude/*.local.*
+
+# MkDocs build output
+site/
+
+# Code editors
+.vscode/
+.idea/

archibald-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.13
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]

archibald-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

archibald-1.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# 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]
+
+## [1.0.0] - 2026-06-01
+
+### Added
+
+- Add a suite of exceptions split into those that are raised by the ESRI API (`ArcGISError`) and those raised by the `archie` tool itself (`ArchieClientError`).
+- Error handling for quirky ESRI response errors. Functions exist for both parsing ESRI errors (`parse_esri_error()`) and handling ESRI errors for callers as a decorator (`handle_esri_errors()`).
+- Base async auth handler class called `ArcGISAuth` that mandates a `get_token()` method in any subclasses.
+- User token auth flows, where a user supplies a username and password in exchange for a token from ESRI's generateToken endpoint. Implemented as `UserTokenAuth`.
+- Base httpx client that handles authentication, enforces response formatting, and routes get and post requests from any endpoint. Implemented as `ArchieClient`.
+- Base service class that handles service metadata retreival, url validation, and client injection, implemented as `BaseService`.
+- `QueryResult` data class will be returned from all feature layer queries. Has attributes for features returned, field names, whether features are geojson, and the output crs if geometries are returned.
+- `FieldsResult` data class returned from querying a feature layer for field names, types, etc.
+- `QueryOperation` executes queries against a feature layer with automatic pagination. Validates requested field names against the layer's field metadata, builds ESRI REST query parameters with deterministic `OBJECTID ASC` ordering by default, and fans out remaining pages in parallel via `anyio` task groups when `exceededTransferLimit` is returned. Geometry output is always encoded as GeoJSON; CRS defaults to the layer's native spatial reference when `out_sr` is not provided.
+- `FeatureLayer` service class represents a single ESRI FeatureServer layer. Caches layer-level metadata (field definitions, `objectIdField`, `globalIdField`, capabilities) on first access. Exposes `objectid_field()`, `globalid_field()`, `supports_query()`, and `fields()` accessors. Provides a `query()` method that guards against layers lacking query capability and delegates to `QueryOperation`.
+- `NoAuth` auth handler for anonymous/public ArcGIS services. Satisfies the `ArcGISAuth` interface but injects no token.
+- `FeatureService` service class representing a FeatureServer endpoint; validates the service path and provides service-level metadata.
+- `MapService` service class representing a MapServer endpoint; same metadata interface as `FeatureService`.
+- `BaseLayer` abstract base class for individual service layers. Extends `BaseService` with a `layer_id` parameter. Caches layer-level metadata (fields, `objectIdField`, `globalIdField`, capabilities) on first access and exposes `objectid_field()`, `globalid_field()`, `supports_query()`, `fields()`, and `query()`.
+- `MapLayer` read-only layer class for MapServer layers. Inherits MapServer path validation from `MapService` and query capability from `BaseLayer`.
+- `ApplyEditsResult` and `EditResultItem` data classes model the response from `applyEdits`. `ApplyEditsResult` exposes `has_failures`, `failed_adds`, `failed_updates`, and `failed_deletes` properties and supports merging multiple per-batch results via `ApplyEditsResult.merge()`.
+- `ApplyEditsOperation` executes `applyEdits` calls against a `FeatureLayer`. Serializes adds (OBJECTID excluded) and updates (OBJECTID included), normalizes deletes from `DataFrame`, `Series`, or `list[int]`, greedy-packs payloads into ≤ 1.8 MB batches, fans out batch POSTs in parallel via `anyio` task groups, and polls async job status with exponential backoff (0.5–5 s) when the layer declares async edit support.
+- `FeatureLayer.apply_edits()` accepts `adds`, `updates`, and `deletes` (all optional) and delegates to `ApplyEditsOperation`. Issues a `UserWarning` when `rollback_on_failure=True` but the layer does not advertise that capability.
+- `FeatureLayer.append()` convenience method that adds all rows of a `DataFrame` or `GeoDataFrame` as new features.
+- `FeatureLayer.upsert()` queries the layer to identify existing keys, partitions incoming rows into adds and updates, and applies both in a single `apply_edits` call. Raises `InvalidParameterError` if key fields are unknown or produce duplicates.
+- `FeatureLayer.sync()` performs a full dataset replacement keyed on caller-supplied fields: adds absent features, updates matching ones, and deletes features in the layer that have no match in the incoming data.
+- `FieldsResult.filter()` returns a new `FieldsResult` restricted by any combination of field names, ESRI type strings, editability, or nullability. `names` and `types` are mutually exclusive; raises `InvalidParameterError` on unrecognised type strings.
+- `FieldsResult.domain_maps` property returns `{field_name: {"to_name": {code: name}, "to_code": {name: code}}}` for all fields carrying a `codedValue` domain. Fields without a domain or with a non-`codedValue` domain type (e.g. `range`) are excluded.
+- `QueryResult.to_frame()` and `QueryResult.to_geodataframe()` convert query results to `pandas.DataFrame` and `geopandas.GeoDataFrame` respectively. Both accept `parse_dtypes=True` to apply ESRI→pandas type coercions automatically (dates to UTC-aware datetime, integer fields to nullable `Int64`/`Int32`, etc.). `to_geodataframe()` raises `MissingGeometryError` when the result contains no geometry.
+- `QueryResult.apply_coded_values` flag: when `True`, `to_frame()` and `to_geodataframe()` automatically translate coded domain values to their human-readable names after type coercion. Set by passing `apply_coded_values=True` to `BaseLayer.query()`.
+- `geometry_to_esri()` converts shapely geometries (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon) to ESRI JSON dicts with Z-coordinate support. Returns `None` for null geometries; raises `InvalidParameterError` for unsupported types.
+- `serialize_features()` converts a `DataFrame` or `GeoDataFrame` to ESRI feature dicts, applying outbound type coercions and optionally pairing geometry. Issues a `UserWarning` for columns that are skipped (non-editable or absent from field metadata). Accepts `apply_coded_values=True` to translate human-readable domain names back to their codes before type coercion.
+- `pack_batches()` greedy-packs serialized features and delete IDs into POST body dicts capped at a configurable byte limit (default 1.8 MB).
+- `recode_domains(df, fields, *, direction)` added to `archie.serializers._coercions`. Translates coded domain values bidirectionally: `from_esri` maps codes to names, `to_esri` maps names to codes. Unmapped values pass through unchanged. Emits a `UserWarning` when mapped and unmapped non-null values coexist in the same column, as the result will be mixed-type.
+- `ApplyEditsOperation.execute()` accepts a `poll_timeout` keyword argument (default 300 s) that caps how long the async polling loop will wait for a server-side job to complete before raising `TimeoutError`.
+
+### Changed
+
+- `enforce_types(df, fields, *, direction)` added to `archie.serializers._coercions` as a unified ESRI ↔ pandas type-coercion function. `direction="from_esri"` applies `ESRI_TO_PANDAS` conversions (integer fields → nullable dtype, dates → UTC-aware datetime); `direction="to_esri"` applies `PANDAS_TO_ESRI` conversions for serialization. `QueryResult._apply_esri_types` and `_coerce_columns` both delegate to it internally.
+- `BaseLayer.query()`, `FeatureLayer.apply_edits()`, `append()`, `upsert()`, and `sync()` all accept an `apply_coded_values` keyword argument (default `False`) that threads through to the serialization and result-construction layers.
+- `FeatureLayer` now inherits from both `FeatureService` and `BaseLayer` via cooperative MRO; previously it inherited directly from `BaseService`.
+- Layer classes (`FeatureLayer`, `MapLayer`, `BaseLayer`) moved to a `services/layers/` sub-package.
+- `FieldsResult.names` is now a computed property (was a plain attribute). The `editable_only` parameter is removed; use `FieldsResult.filter(editable=True)` instead.
+- `FieldsResult.field_type_map` replaces the former `esri_field_types` attribute.
+- Custom exception classes from `archie.errors` are now used consistently throughout the package in place of built-in Python exceptions.
+- Import paths simplified: all public symbols are re-exported from their respective sub-package `__init__.py` files.
+- `ApplyEditsOperation` now uses server-side async editing only when the payload spans multiple batches. Single-batch payloads always use the synchronous path to avoid unnecessary polling round-trips.
+
+### Fixed
+
+- `ArchieClient` now validates that the base URL ends with `rest/services` at construction time, raising `InvalidServiceURL` on mismatch.
+- Query pagination now correctly detects `exceededTransferLimit` in the response body before fanning out additional page requests.
+- CRS defaults correctly to the layer's native spatial reference when `out_sr` is not supplied to `QueryOperation`.
+- `LayerCapabilityError` is raised (instead of a generic exception) when a caller attempts to query a layer that lacks query capability.
+- `UserTokenAuth` token request now sends `referer` instead of `requestip` in the POST body, matching the ESRI `generateToken` API contract.
+- Async `applyEdits` polling now uses the correct ESRI status strings (`"COMPLETED"` / `"PROCESSING"`) instead of the geoprocessing-task strings (`esriJobSucceeded` / `esriJobFailed`) that were previously used and caused the polling loop to never exit.
+- When an async `applyEdits` job completes, the operation now follows the `resultUrl` returned in the status body to fetch the actual edit results (`addResults`, `updateResults`, `deleteResults`). Previously the status body itself was parsed as the result, which always produced empty result sets.
+- Async polling loop is now bounded by `anyio.fail_after`; previously it could spin indefinitely if the server never returned a terminal status.
+
+[Unreleased]: https://github.com/cityofboulder/archie/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/cityofboulder/archie/releases/tag/v1.0.0

archibald-1.0.0/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md
+
+## Project overview
+
+`archie` is an async-first Python client for ESRI ArcGIS REST APIs, built around dependency injection and modern analysis libraries. The stack is `httpx`, `anyio`, `pydantic`, `pytest` + `pytest-anyio` + `pytest-mock`, `pandas`, `geopandas`.
+
+Layers (bottom to top):
+
+```
+auth          →  token acquisition and header injection
+client        →  HTTP methods, error handling, format enforcement
+operations    →  ESRI-idiomatic calls (query, applyEdits, addAttachment, ...)
+models        →  Models returned by operation calls (QueryResult, ApplyEditsResult, ...)
+services      →  cohesive service APIs (FeatureLayer, FeatureService, MapService, ...)
+```
+
+## Project structure
+
+```
+src/
+  archie/
+    auth/
+    models/
+    operations/
+    services/
+    client.py
+    errors.py
+    exceptions.py
+tests/
+  auth/
+  models/
+  operations/
+  services/
+  helpers.py
+  conftest.py
+pyproject.toml
+```
+
+## Coding conventions
+
+- Surface tradeoffs explicitly; do not assume or hide confusion
+- Minimum code that solves the problem; nothing speculative
+- Touch only what is necessary; clean up only your own mess
+- Leverage existing library plumbing wherever possible
+- No inline comments unless truly non-obvious
+- Always add docstrings to non-test functions and methods
+
+## Testing conventions
+
+- Framework: `pytest` + `pytest-mock`; never `unittest`
+- Async tests: `@pytest.mark.anyio` (or `anyio_mode = "auto"` in `pyproject.toml`)
+- AAA format with blank lines separating Arrange / Act / Assert
+- Do not write tests until the underlying code change is confirmed
+- When mocks become excessive, flag it and suggest a refactor rather than adding more
+- Fixtures should go in the root `tests/conftest.py` file
+- Helper functions and globals should go in the `tests/helpers.py` file
+- Prioritize parametrizing tests where logical
+- Parametrized tests always include `ids=`
+- Leverage existing fixtures and helpers wherever possible; if either need tweaks in order to make new tests work, prefer updating and verify that they will still work elsewhere.
+
+## Architectural decisions
+
+- Async-first throughout; use `anyio` primitives (not `asyncio` directly)
+- `@handle_esri_errors` is applied at `_request`, not at the operations layer
+- ESRI format param (`f=json`) is enforced by the client on every request; `f=geojson` is the only exception
+- Per-feature edit errors (`applyEdits`) belong in `ApplyEditsResult` at the endpoint layer, not in the client

archibald-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to archie
+
+## Prerequisites
+
+- Python 3.12+
+- [`uv`](https://docs.astral.sh/uv/) for dependency management
+
+## Getting started
+
+1. Fork and clone the repository
+2. Install dependencies:
+   ```sh
+   uv sync
+   ```
+3. Install the pre-commit hooks (runs ruff format and lint on every commit):
+   ```sh
+   pre-commit install
+   ```
+   If you don't have `pre-commit` installed: `uv tool install pre-commit`
+
+## Running tests
+
+```sh
+uv run pytest
+```
+
+Tests marked `integration` hit a mocked HTTP transport and are included by default. To run only unit tests:
+
+```sh
+uv run pytest -m "not integration"
+```
+
+Coverage must stay at or above 80%. The suite will fail if it drops below that threshold.
+
+## Code style
+
+Ruff handles formatting and linting. The pre-commit hooks run both automatically on every commit. To run them manually:
+
+```sh
+uv run ruff format .
+uv run ruff check .
+```
+
+All public functions and methods (outside of tests) require docstrings in [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+
+## Documentation
+
+Install the docs dependencies and serve locally:
+
+```sh
+uv sync --group docs
+uv run mkdocs serve
+```
+
+Documentation is deployed automatically to GitHub Pages when changes are merged to `main` — you don't need to deploy manually.
+
+## Opening issues
+
+**Bug reports** — include steps to reproduce, expected vs. actual behavior, your Python version, and a stack trace if one is available.
+
+**Feature requests** — describe the use case and, if possible, what you'd want the API to look like.
+
+For non-trivial changes, open an issue to align on the approach before investing time in a PR.
+
+## Submitting a pull request
+
+- Open PRs against `main`
+- CI runs the test suite on Ubuntu and Windows — both must pass
+- Keep PRs focused; one logical change per PR
+
+## Releases (maintainers only)
+
+Releases are triggered by pushing a version tag:
+
+```sh
+git tag v1.1.0
+git push --tags
+```
+
+The publish workflow builds the package and pushes it to PyPI automatically via OIDC — no manual upload or API token required.

archibald-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Department of Innovation and Technology, City of Boulder
+
+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.