feat: refinements in api generator; initial polytest integration for algod

.github/workflows/check-python.yaml

@@ -35,3 +35,10 @@ jobs:
         run: |
           # stop the build if there are files that don't meet formatting requirements
           uv run poe lint
+
+      - name: Setup Polytest
+        uses: aorumbayev/algokit-polytest/.github/actions/setup-polytest@main
+
+      # TODO: Uncomment once polytest with v_2 vs v2 word splitting fix is released
+      #- name: Validate polytest algod_client tests
+      #  run: uv run poe polytest-validate-algod

.gitignore

@@ -176,6 +176,9 @@ cython_debug/
 
 .references/
 
+# Downloaded OAS specs (fetched from algokit-oas-generator)
+api/specs/
+
 *.xml
 
 .polytest*/

.pre-commit-config.yaml

@@ -13,6 +13,16 @@ repos:
         minimum_pre_commit_version: "2.9.2"
         pass_filenames: false
         files: "^(src|tests)/"
+      - id: generate-api-clients
+        name: generate-api-clients
+        description: "Generate API clients before linting"
+        entry: uv run poe generate-api-clients
+        language: system
+        types_or: [python, pyi]
+        args: []
+        require_serial: true
+        pass_filenames: false
+        files: "^(src|tests)/"
       - id: lint
         name: lint
         description: "`mypy` and 'ruff' will check Python types for correctness"
@@ -25,10 +35,26 @@ repos:
         minimum_pre_commit_version: "2.9.2"
         pass_filenames: false
         files: "^(src|tests)/"
+      - id: docs
+        name: docs
+        description: "Build documentation (always passes)"
+        entry: bash -c 'uv run poe docs || true'
+        language: system
+        pass_filenames: false
+        always_run: true
+        verbose: true
       - id: docstrings-check
         name: docstrings-check
         description: "Check docstrings for correctness"
         entry: uv run poe docstrings-check
         language: system
         types: [python]
         files: "^(src)/"
+      - id: test
+        name: test
+        description: "Run pytest as final validation"
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]

MIGRATION-NOTES.md

@@ -39,3 +39,114 @@ A collection of notes to consolidate todos during decoupling efforts (similar do
 - What do we do with SourceMap abstraction? AlgoSDK version is more feature complete, while we also have a simple autogenerated sourcemap variant in algosdk. ts currently relies on ProgramSourceMap which is vendored from js algosdk. Do we drop the vendored variants completely and enhance api generator to hand roll a custom sourcemap variant we need and rely on that everywhere? Or do we move the vendored source map variant into the algokit-utils and enhance it there?
 
 - BoxReference used to be a subclass of algosdk BoxReference, now there is a direct equivalent imported from transact package. Do we want to keep aliasing the BoxReference to transact version or do we want to deprecate and advice consumers to import directly from transact?
+
+## Contributing Guide
+
+- Introduce comprehensive contributing guide around running tests/updating snapshots in API client tests and dealing with Polytest
+
+## Polytest Integration
+
+This section tracks the generated API endpoint tests from Polytest. Tests are categorized by implementation status.
+
+### Algod Client Endpoints
+
+#### ✅ Implemented (21 endpoints)
+
+| Endpoint | Test File | Notes |
+|----------|-----------|-------|
+| `GET /genesis` | `test_get_genesis.py` | |
+| `GET /health` | `test_get_health.py` | |
+| `GET /ready` | `test_get_ready.py` | |
+| `GET /versions` | `test_get_versions.py` | |
+| `GET /v2/accounts/{address}` | `test_get_v2_accounts_address.py` | |
+| `GET /v2/accounts/{address}/applications/{application-id}` | `test_get_v2_accounts_address_applications_application_id.py` | |
+| `GET /v2/accounts/{address}/assets/{asset-id}` | `test_get_v2_accounts_address_assets_asset_id.py` | |
+| `GET /v2/accounts/{address}/transactions/pending` | `test_get_v2_accounts_address_transactions_pending.py` | |
+| `GET /v2/applications/{application-id}` | `test_get_v2_applications_application_id.py` | |
+| `GET /v2/assets/{asset-id}` | `test_get_v2_assets_asset_id.py` | |
+| `GET /v2/blocks/{round}` | `test_get_v2_blocks_round.py` | |
+| `GET /v2/blocks/{round}/hash` | `test_get_v2_blocks_round_hash.py` | |
+| `GET /v2/blocks/{round}/lightheader/proof` | `test_get_v2_blocks_round_lightheader_proof.py` | |
+| `GET /v2/blocks/{round}/txids` | `test_get_v2_blocks_round_txids.py` | |
+| `GET /v2/deltas/{round}` | `test_get_v2_deltas_round.py` | |
+| `GET /v2/ledger/supply` | `test_get_v2_ledger_supply.py` | |
+| `GET /v2/ledger/sync` | `test_get_v2_ledger_sync.py` | |
+| `GET /v2/status` | `test_get_v2_status.py` | |
+| `GET /v2/status/wait-for-block-after/{round}` | `test_get_v2_status_wait_for_block_after_round.py` | |
+| `GET /v2/transactions/params` | `test_get_v2_transactions_params.py` | |
+| `GET /v2/transactions/pending` | `test_get_v2_transactions_pending.py` | |
+
+#### ⏳ Stub (Not Implemented) (21 endpoints)
+
+| Endpoint | Test File | Notes |
+|----------|-----------|-------|
+| `DELETE /v2/catchup/{catchpoint}` | `test_delete_v2_catchup_catchpoint.py` | Admin endpoint |
+| `DELETE /v2/ledger/sync` | `test_delete_v2_ledger_sync.py` | Admin endpoint |
+| `GET /v2/applications/{application-id}/box` | `test_get_v2_applications_application_id_box.py` | |
+| `GET /v2/applications/{application-id}/boxes` | `test_get_v2_applications_application_id_boxes.py` | |
+| `GET /v2/blocks/{round}/transactions/{txid}/proof` | `test_get_v2_blocks_round_transactions_txid_proof.py` | |
+| `GET /v2/deltas/{round}/txn/group` | `test_get_v2_deltas_round_txn_group.py` | |
+| `GET /v2/deltas/txn/group/{id}` | `test_get_v2_deltas_txn_group_id.py` | |
+| `GET /v2/devmode/blocks/offset` | `test_get_v2_devmode_blocks_offset.py` | Dev mode only |
+| `GET /v2/experimental` | `test_get_v2_experimental.py` | |
+| `GET /v2/stateproofs/{round}` | `test_get_v2_stateproofs_round.py` | |
+| `GET /v2/transactions/pending/{txid}` | `test_get_v2_transactions_pending_txid.py` | |
+| `POST /v2/catchup/{catchpoint}` | `test_post_v2_catchup_catchpoint.py` | Admin endpoint |
+| `POST /v2/devmode/blocks/offset/{offset}` | `test_post_v2_devmode_blocks_offset_offset.py` | Dev mode only |
+| `POST /v2/ledger/sync/{round}` | `test_post_v2_ledger_sync_round.py` | Admin endpoint |
+| `POST /v2/shutdown` | `test_post_v2_shutdown.py` | Admin endpoint |
+| `POST /v2/teal/compile` | `test_post_v2_teal_compile.py` | |
+| `POST /v2/teal/disassemble` | `test_post_v2_teal_disassemble.py` | |
+| `POST /v2/teal/dryrun` | `test_post_v2_teal_dryrun.py` | |
+| `POST /v2/transactions` | `test_post_v2_transactions.py` | |
+| `POST /v2/transactions/async` | `test_post_v2_transactions_async.py` | |
+| `POST /v2/transactions/simulate` | `test_post_v2_transactions_simulate.py` | |
+
+#### 🔧 Manual Tests (6 tests)
+
+These tests are hand-written to cover complex scenarios not easily generated:
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_block.py` | Block endpoint against mainnet/testnet with state proof tracking |
+| `manual/test_ledger_state_delta.py` | Ledger state delta endpoint against mainnet/testnet |
+| `manual/test_pending_transaction_information.py` | Pending transaction info flow on localnet |
+| `manual/test_raw_transaction.py` | Raw transaction broadcast on localnet |
+| `manual/test_simulate_transactions.py` | Transaction simulation with trace config |
+| `manual/test_suggested_params.py` | Suggested params and error handling |
+
+### Indexer Client Endpoints
+
+#### 🔧 Manual Tests (2 tests)
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_search_applications.py` | Search for applications and app creation flow |
+| `manual/test_search_transactions.py` | Search and lookup transactions |
+
+### KMD Client Endpoints
+
+#### 🔧 Manual Tests (2 tests)
+
+| Test File | Description |
+|-----------|-------------|
+| `manual/test_wallet_lifecycle.py` | Wallet creation and listing |
+| `manual/test_key_management.py` | Key generation and wallet handle management |
+
+### Test Infrastructure
+
+The Polytest-generated tests use a mock server infrastructure:
+
+- **Mock Server**: Docker container running `algorandfoundation/algod-mock:latest`
+- **Parallel Execution**: Uses `filelock` for xdist worker coordination
+- **Container Management**: Named containers with fixed ports (18000, 18001, 18002)
+- **Test Configuration**: Located in `tests/modules/conftest.py`
+
+### Summary
+
+| Client | Implemented | Stub | Manual | Total |
+|--------|-------------|------|--------|-------|
+| Algod | 21 | 21 | 6 | 48 |
+| Indexer | 0 | 0 | 2 | 2 |
+| KMD | 0 | 0 | 2 | 2 |
+| **Total** | **21** | **21** | **10** | **52** |

api/oas-generator/README.md

@@ -14,7 +14,7 @@ api/oas-generator/
 ### Key modules
 
 - `cli.py` – argument parser and CLI entrypoint
-- `parser.py` / `loader.py` – read & validate OpenAPI specs
+- `parser.py` / `loader.py` – read & validate OpenAPI specs (supports local paths, URLs, and shorthand)
 - `builder.py` / `models.py` – shape spec data for rendering
 - `renderer/engine.py` / `filters.py` – Jinja environment and helpers
 - `writer.py` – emit generated files into the target package
@@ -30,7 +30,34 @@ api/oas-generator/
 
 ## Usage
 
+The `--spec` argument accepts:
+- **Local paths**: `api/specs/algod.oas3.json`
+- **Remote URLs**: `https://raw.githubusercontent.com/.../algod.oas3.json`
+- **Shorthand**: `oas://algod` (fetches from `algokit-oas-generator` main branch)
+- **Shorthand with branch/tag**: `oas://algod@v1.0.0` or `oas://indexer@feature-branch`
+
+### Examples
+
 ```bash
+# Using shorthand (recommended - single source of truth)
+uv run --project api/oas-generator python -m oas_generator.cli \
+  --spec oas://algod \
+  --out src \
+  --package algokit_algod_client
+
+# Using shorthand with specific branch/tag
+uv run --project api/oas-generator python -m oas_generator.cli \
+  --spec oas://algod@v1.0.0 \
+  --out src \
+  --package algokit_algod_client
+
+# Using a remote URL directly
+uv run --project api/oas-generator python -m oas_generator.cli \
+  --spec https://raw.githubusercontent.com/algorandfoundation/algokit-oas-generator/main/specs/algod.oas3.json \
+  --out src \
+  --package algokit_algod_client
+
+# Using a local path
 uv run --project api/oas-generator python -m oas_generator.cli \
   --spec api/specs/algod.oas3.json \
   --out src \