anncsu-sdk 0.0.8.dev1__tar.gz → 0.0.9.dev8__tar.gz

{anncsu_sdk-0.0.8.dev1 → anncsu_sdk-0.0.9.dev8}/.gitignore

@@ -136,6 +136,7 @@ celerybeat.pid
 
 # Environments
 .env
+.env.*
 .envrc
 .venv
 env/
@@ -144,6 +145,11 @@ ENV/
 env.bak/
 venv.bak/
 
+# Private keys / credentials — never commit
+keys/
+*.pem
+*.key
+
 # Spyder project settings
 .spyderproject
 .spyproject

{anncsu_sdk-0.0.8.dev1 → anncsu_sdk-0.0.9.dev8}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.8.dev1
+Version: 0.0.9.dev8
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: authlib>=1.3.0
-Requires-Dist: duckdb>=1.0.0
+Requires-Dist: authlib>=1.7.2
+Requires-Dist: duckdb>=1.5.2
 Requires-Dist: httpcore>=1.0.9
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic-settings>=2.12.0
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: rich>=13.0.0
-Requires-Dist: typer>=0.15.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.25.0
 Description-Content-Type: text/markdown
 
 # anncsu-sdk

{anncsu_sdk-0.0.8.dev1 → anncsu_sdk-0.0.9.dev8}/docs/CLI.md

@@ -603,6 +603,7 @@ Options:
 - `--validation/--production` - Use validation (UAT) or production environment
 - `--no-verify-ssl` - Disable SSL certificate verification (use with caution)
 - `--json` - Output as JSON
+- `--raw` - Print raw API response to stderr
 
 Example with JSON output:
 ```bash
@@ -647,6 +648,7 @@ Options:
 - `--validation/--production` - Use validation (UAT) or production environment
 - `--no-verify-ssl` - Disable SSL certificate verification
 - `--json` - Output as JSON
+- `--raw` - Print raw API response to stderr
 
 Example checking production environment:
 ```bash
@@ -769,6 +771,7 @@ Options:
 - `--validation/--production` - Use validation (UAT) or production environment
 - `--no-verify-ssl` - Disable SSL certificate verification (use with caution)
 - `--json` - Output as JSON
+- `--raw` - Print raw API responses to stderr (one per API call: lookup, test update, restore)
 
 > **Note**: You must provide either `--prognazacc` OR both `--codcom` and `--denom`.
 > If `--prognazacc` is provided, `--codcom` and `--denom` are ignored.
@@ -893,6 +896,120 @@ Note: Access has no coordinates. Using test coordinates (will be cleared after t
 
 ---
 
+#### `anncsu coordinate duckdb-batch-update`
+
+Batch update coordinates from a DuckDB table for small municipalities that don't have access to the bulk coordinate API endpoint. Reads geocoded data from a DuckDB source table, updates coordinates one-by-one via the ANNCSU API, and stores all results in a `batch_update_results` table for auditing.
+
+Supports resumable multi-day execution with `--resume` to respect the daily limit of 4,000 records per municipality.
+
+```bash
+# First run (day 1): process up to 4000 records
+anncsu coordinate duckdb-batch-update \
+  --db ~/Downloads/anncsu_anagni/A269.duckdb \
+  --source-table deoverlapped_geocoded_anncsu_prepared \
+  --codcom A269 \
+  --production \
+  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
+  --max-records 4000
+
+# Day 2: resume with same run ID
+anncsu coordinate duckdb-batch-update \
+  --db ~/Downloads/anncsu_anagni/A269.duckdb \
+  --source-table deoverlapped_geocoded_anncsu_prepared \
+  --codcom A269 \
+  --production \
+  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
+  --max-records 4000 \
+  --resume 20260319_140554
+
+# Day 3: finish remaining records (no --max-records needed)
+anncsu coordinate duckdb-batch-update \
+  --db ~/Downloads/anncsu_anagni/A269.duckdb \
+  --source-table deoverlapped_geocoded_anncsu_prepared \
+  --codcom A269 \
+  --production \
+  --token-endpoint https://auth.interop.pagopa.it/token.oauth2 \
+  --resume 20260319_140554
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--db`, `-d` | Path to DuckDB file (required) | — |
+| `--codcom`, `-c` | Codice comune / Belfiore code (required) | — |
+| `--source-table`, `-t` | Source table name | `deoverlapped_geocoded_anncsu` |
+| `--max-records`, `-m` | Max records to process (0 = all) | `0` |
+| `--resume` | Resume a previous run by its Run ID | — |
+| `--token-endpoint`, `-e` | PDND token endpoint URL | UAT endpoint |
+| `--server-url`, `-s` | API server URL (auto-detected) | — |
+| `--validation/--production` | Environment selection | `--validation` |
+| `--no-verify-ssl` | Disable SSL verification | `false` |
+| `--json` | Output as JSON | `false` |
+
+**Source table requirements:**
+
+The source table must have coordinate columns as `VARCHAR` with length ≤ 12 for `x`/`y` and ≤ 7 for `z`. If the coordinates are stored as `FLOAT`/`DOUBLE`, create a `_prepared` table first:
+
+```sql
+CREATE TABLE deoverlapped_geocoded_anncsu_prepared AS
+SELECT
+    PROGRESSIVO_ACCESSO::INTEGER as PROGRESSIVO_ACCESSO,
+    CIVICO::INTEGER as CIVICO,
+    CODICE_COMUNE,
+    CAST(ROUND(COORD_X_COMUNE, 6) AS VARCHAR) as COORD_X_COMUNE,
+    CAST(ROUND(COORD_Y_COMUNE, 6) AS VARCHAR) as COORD_Y_COMUNE,
+    CASE WHEN QUOTA IS NOT NULL THEN CAST(ROUND(QUOTA, 1) AS VARCHAR) ELSE NULL END as QUOTA,
+    CAST(METODO AS VARCHAR) as METODO
+FROM deoverlapped_geocoded_anncsu
+WHERE CODICE_COMUNE = 'A269'
+AND PROGRESSIVO_ACCESSO IS NOT NULL
+AND COORD_X_COMUNE IS NOT NULL
+AND COORD_Y_COMUNE IS NOT NULL;
+```
+
+The command will reject the source table if any coordinate exceeds the maxLength limits.
+
+**Resume behavior:**
+
+- `--resume RUN_ID` skips records already succeeded (esito='0') for that run
+- Failed records are retried on resume
+- The same `run_id` is reused across all days for consistent auditing
+- When all records are complete, exits with code 0 and a confirmation message
+
+**JSON output (`--json`):**
+
+```json
+{
+  "run_id": "20260319_140554",
+  "timestamp": "2026-03-19T14:05:54",
+  "total": 4000,
+  "success": 3998,
+  "failed": 2,
+  "errors": [
+    {"progr_accesso": 12345, "error": "Network error"}
+  ]
+}
+```
+
+**Query results in DuckDB:**
+
+```sql
+-- Summary by run
+SELECT run_id, COUNT(*) as total,
+       SUM(CASE WHEN esito = '0' THEN 1 ELSE 0 END) as success,
+       SUM(CASE WHEN esito != '0' OR esito IS NULL THEN 1 ELSE 0 END) as failed
+FROM batch_update_results
+GROUP BY run_id;
+
+-- Failed records for retry analysis
+SELECT progressivo_accesso, error_detail, elapsed_ms
+FROM batch_update_results
+WHERE run_id = '20260319_140554' AND (esito != '0' OR esito IS NULL);
+```
+
+---
+
 ### `anncsu coordinate bulk` - Bulk Coordinate Operations
 
 Bulk coordinate operations with CSV input and DuckDB local persistence.
@@ -1585,6 +1702,7 @@ anncsu pa odonimo --codcom I501 --denom "VklBIFJPTUE=" --json
 | `--server-url`, `-s` | No | API server URL (overrides environment default) |
 | `--no-verify-ssl` | No | Disable SSL verification |
 | `--json` | No | Output as JSON |
+| `--raw` | No | Print raw API response to stderr |
 
 **Output columns:** Prog. Naz., DUG, Denominazione Ufficiale, Denominazione Locale, Lingua 1, Lingua 2
 
@@ -1596,12 +1714,12 @@ Lookup a single access point by its national progressive number. Returns complet
 # Lookup access point
 anncsu pa accesso --prognazacc 28586543
 
-# With enrichment (additional API call to fetch street denomination)
-anncsu pa accesso --prognazacc 28586543 --enrich
-
 # Production with JSON output
 anncsu pa accesso --prognazacc 28586543 --production \
   --token-endpoint https://auth.interop.pagopa.it/token.oauth2 --json
+
+# See raw API response on stderr
+anncsu pa accesso --prognazacc 28586543 --raw
 ```
 
 **Options:**
@@ -1609,16 +1727,16 @@ anncsu pa accesso --prognazacc 28586543 --production \
 | Option | Required | Description |
 |--------|----------|-------------|
 | `--prognazacc`, `-p` | Yes | Progressivo nazionale dell'accesso |
-| `--enrich/--no-enrich` | No | Enrich with street denomination via prognazarea (default: no-enrich) |
 | `--validation/--production` | No | Environment (default: validation) |
 | `--token-endpoint`, `-e` | No | PDND token endpoint URL |
 | `--server-url`, `-s` | No | API server URL (overrides environment default) |
 | `--no-verify-ssl` | No | Disable SSL verification |
 | `--json` | No | Output as JSON |
+| `--raw` | No | Print raw API response to stderr |
 
 **Output fields:** Prog. Naz. Odonimo, DUG, Denominazione Ufficiale, Denominazione Locale, Lingua 1, Lingua 2, Prog. Naz. Accesso, Civico, Esponente, Specificita, Metrico, Coord X, Coord Y, Quota, Metodo
 
-**Note:** The `prognazacc` API does not return the street denomination (`denomuff`). Use `--enrich` to fetch it via an additional `prognazarea` call. This is optional because some odonimi in ANNCSU have empty `denomuff` at the database level.
+**Note:** The `denomuff` field is now correctly populated via Pydantic alias mapping (`duf` → `denomuff`). See Issue #12.
 
 **JSON output example:**
 
@@ -1627,7 +1745,7 @@ anncsu pa accesso --prognazacc 28586543 --production \
   {
     "prognaz": "1222543",
     "dug": "LARGO",
-    "denomuff": null,
+    "denomuff": "CHIAFFREDO BERGIA",
     "denomloc": "",
     "denomlingua1": "",
     "denomlingua2": "",
@@ -1672,6 +1790,7 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production \
 | `--server-url`, `-s` | No | API server URL (overrides environment default) |
 | `--no-verify-ssl` | No | Disable SSL verification |
 | `--json` | No | Output as JSON |
+| `--raw` | No | Print raw API responses to stderr (odonimo + accessi) |
 
 **Output columns:** Prog. Naz. Acc., Civico, Esp., Specif., Metrico, Coord X, Coord Y, Quota, Metodo
 

{anncsu_sdk-0.0.8.dev1 → anncsu_sdk-0.0.9.dev8}/pyproject.toml

@@ -9,13 +9,13 @@ authors = [
 requires-python = ">=3.12"
 dependencies = [
     "httpcore >=1.0.9",
-    "httpx >=0.28.1",
-    "pydantic >=2.12.5",
-    "authlib>=1.3.0",
-    "pydantic-settings>=2.12.0",
-    "typer>=0.15.0",
-    "rich>=13.0.0",
-    "duckdb>=1.0.0",
+    "httpx >=0.28.0",
+    "pydantic >=2.13.4",
+    "authlib>=1.7.2",
+    "pydantic-settings>=2.14.0",
+    "typer>=0.25.0",
+    "rich>=15.0.0",
+    "duckdb>=1.5.2",
 ]
 
 [project.scripts]
@@ -40,7 +40,7 @@ dev = [
 requires = ["hatchling", "uv-dynamic-versioning"]
 build-backend = "hatchling.build"
 [tool.uv.build-backend]
-module-name = "anncsu.pa"
+module-name = "anncsu"
 module-root = "src"
 [tool.hatch.version]
 source = "uv-dynamic-versioning"

anncsu_sdk-0.0.9.dev8/src/anncsu/cli/commands/constants.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025-present Geobeyond <info@geobeyond.it>
+# SPDX-License-Identifier: MIT
+"""Shared constants for CLI commands."""
+
+# Default token endpoint for UAT
+DEFAULT_TOKEN_ENDPOINT = "https://auth.uat.interop.pagopa.it/token.oauth2"
+
+# Default server URLs for coordinate API
+# Note: Uses AgenziaEntrate-PDND path and anncsu-aggiornamento-coordinate endpoint
+SERVERS = {
+    "production": "https://modipa.agenziaentrate.gov.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-coordinate/v1",
+    "validation": "https://modipa-val.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-coordinate/v1",
+}