anncsu-sdk 0.0.10.dev2__tar.gz → 0.0.10.dev3__tar.gz

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.10.dev2
+Version: 0.0.10.dev3
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev3}/docs/CLI.md

@@ -1789,15 +1789,18 @@ anncsu pa accesso --prognazacc 28586543 --raw
 
 #### `anncsu pa accessi`
 
-List access points (civici) for a street. First searches for the street by municipality code and partial name, then lists all access points.
+List access points (civici) for a street. Resolve the street either by `--denom` (municipality code + base64 partial name) **or** directly by `--prognaz`, then list its access points.
 
 ```bash
-# List all access points for a street
+# List access points by street name (base64)
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
 
 # Filter by partial civic number
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
 
+# Target a specific odonimo directly by its national progressive
+anncsu pa accessi --codcom H501 --prognaz 920585 --accparz 95
+
 # Production with JSON output
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 ```
@@ -1807,7 +1810,8 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | Option | Required | Description |
 |--------|----------|-------------|
 | `--codcom`, `-c` | Yes | Codice Belfiore del comune |
-| `--denom`, `-d` | Yes | Denominazione parziale dell'odonimo - base64 encoded |
+| `--denom`, `-d` | One of denom/prognaz | Denominazione parziale dell'odonimo - base64 encoded |
+| `--prognaz`, `-p` | One of denom/prognaz | Progressivo nazionale dell'odonimo (targets it directly) |
 | `--accparz`, `-a` | No | Valore parziale del civico (default: "1") |
 | `--validation/--production` | No | Environment (default: validation) |
 | `--token-endpoint`, `-e` | No | PDND token endpoint URL |
@@ -1816,6 +1820,10 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | `--json` | No | Output as JSON |
 | `--raw` | No | Print raw API responses to stderr (odonimo + accessi) |
 
+> **`--denom` is a substring search and can be ambiguous.** E.g. `--denom` for "taranto" matches both `VIA NINO TARANTO` and `VIA TARANTO`. When more than one odonimo matches, the command does **not** silently pick the first: it lists every candidate with its `--prognaz` and exits, so you can re-run targeting the exact one. `--denom` and `--prognaz` are mutually exclusive; provide exactly one.
+
+> **`--accparz` is a substring match on the civico** (not a prefix): `--accparz 9` returns 9, 19, 29, … 91, 97. To list *all* accessi you currently have to union several `accparz` values (e.g. `0`–`9`) and de-duplicate by `prognazacc` — the API has no "list all" wildcard. The esponente comes back in the `Esp.` column: civico 95 may yield three rows (95, 95/A, 95/D), each a distinct `prognazacc`.
+
 **Output columns:** Prog. Naz. Acc., Civico, Esp., Specif., Metrico, Coord X, Coord Y, Quota, Metodo
 
 **JSON output example:**

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev3}/docs/sdk-pa.md

@@ -178,16 +178,36 @@ if result.res == "OK":
 else:
     print(f"Odonimo non trovato")
 
-# 5. Elenco accessi per l'odonimo
+# 5. Elenco accessi per l'odonimo.
+# NB: ``accparz`` è OBBLIGATORIO (match per sottostringa sul civico) — non
+# esiste un valore "tutti". Vedi la nota sotto.
 accessi = sdk.queryparam.elenco_accessi_get_query_param(
     codcom=codcom,
     denom=denom,
+    accparz="1",  # es. tutti i civici che contengono "1"
 )
 
 for accesso in accessi.data:
-    print(f"Civico: {accesso.civico}, Coordinate: ({accesso.coord_x}, {accesso.coord_y})")
+    # L'esponente torna nel campo dedicato ``esp`` (civico e esponente sono
+    # separati): es. civico="95", esp="A" → 95/A.
+    print(
+        f"Civico: {accesso.civico}{('/' + accesso.esp) if accesso.esp else ''}, "
+        f"Coordinate: ({accesso.coord_x}, {accesso.coord_y})"
+    )
 ```
 
+> **`accparz` è obbligatorio ed è un match per sottostringa** (non prefisso): `accparz="9"`
+> ritorna `9, 19, 29, …, 91, 97` (tutti i civici che *contengono* "9"). **Non esiste un
+> wildcard "elenca tutti"**: per ottenere l'elenco completo bisogna unire più valori di
+> `accparz` (es. `"0"`–`"9"`) e deduplicare per `prognazacc`. Lo stesso vale per
+> `elenco_accessi_prog` (per `prognaz`).
+>
+> **Esponente / specificità**: un accesso è identificato da `civico` (numero) + `esp`
+> (esponente) + `specif`. Più accessi possono condividere lo stesso `civico` con `esp`
+> diversi → `prognazacc` distinti, **tutti** restituiti dalla stessa `accparz`. Es. su
+> VIA TARANTO (H501, prognaz `920585`) il civico `95` ritorna tre accessi: `95`, `95/A`,
+> `95/D`.
+
 ## Gestione Errori
 
 ```python

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev3}/src/anncsu/cli/commands/pa.py

@@ -360,13 +360,28 @@ def accessi(
         ),
     ],
     denom: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--denom",
             "-d",
-            help="Denominazione anche parziale dell'odonimo - base64 encoded.",
+            help=(
+                "Denominazione anche parziale dell'odonimo - base64 encoded. "
+                "Mutually exclusive with --prognaz."
+            ),
         ),
-    ],
+    ] = None,
+    prognaz: Annotated[
+        str | None,
+        typer.Option(
+            "--prognaz",
+            "-p",
+            help=(
+                "Progressivo nazionale dell'odonimo. Use it to target a "
+                "specific odonimo directly (skips the --denom search and its "
+                "ambiguity). Mutually exclusive with --denom."
+            ),
+        ),
+    ] = None,
     accparz: Annotated[
         str | None,
         typer.Option(
@@ -419,12 +434,16 @@ def accessi(
 ) -> None:
     """List access points for a street.
 
-    First searches for the street (odonimo) by municipality code and name,
-    then lists all access points (civici) for that street.
+    Resolve the street (odonimo) either by ``--denom`` (municipality code +
+    base64 name) or directly by ``--prognaz``, then list its access points
+    (civici). ``--denom`` is a substring search: when it matches more than one
+    odonimo the command stops and lists the candidates so you can re-run with
+    ``--prognaz`` (it never silently picks the first match).
 
     Example:
         anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
         anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
+        anncsu pa accessi --codcom H501 --prognaz 920585 --accparz 95
     """
     if server_url is None:
         server_url = (
@@ -440,43 +459,92 @@ def accessi(
         verify_ssl=not no_verify_ssl,
     )
 
-    # Step 1: Find odonimo prognaz
-    try:
-        odonimo_response = sdk.queryparam.elencoodonimiprog_get_query_param(
-            codcom=codcom,
-            denomparz=denom,
+    # Step 1: Resolve the odonimo — either directly via --prognaz or by
+    # searching --denom. The denom search can match multiple odonimi (it is a
+    # substring match), so we never silently pick the first: we error and ask
+    # the user to disambiguate with --prognaz.
+    if prognaz and denom:
+        error_console.print(
+            "[red]Error:[/red] --denom and --prognaz are mutually exclusive."
         )
-    except Exception as e:
-        error_console.print(f"[red]Error:[/red] Odonimo search failed: {e}")
-        raise typer.Exit(1) from None
+        raise typer.Exit(1)
 
-    if raw_output:
-        _print_raw(odonimo_response, "Raw odonimo response")
+    if prognaz:
+        try:
+            odonimo_response = sdk.queryparam.prognazarea_get_query_param(
+                prognaz=prognaz,
+            )
+        except Exception as e:
+            error_console.print(f"[red]Error:[/red] Odonimo lookup failed: {e}")
+            raise typer.Exit(1) from None
+
+        if raw_output:
+            _print_raw(odonimo_response, "Raw odonimo response")
+
+        if not odonimo_response.data:
+            error_console.print(
+                f"[red]No results:[/red] No odonimo found for prognaz={prognaz}"
+            )
+            raise typer.Exit(1) from None
 
-    if not odonimo_response.data:
+        odonimo_data = odonimo_response.data[0]
+        resolved_prognaz = prognaz
+    elif denom:
+        try:
+            odonimo_response = sdk.queryparam.elencoodonimiprog_get_query_param(
+                codcom=codcom,
+                denomparz=denom,
+            )
+        except Exception as e:
+            error_console.print(f"[red]Error:[/red] Odonimo search failed: {e}")
+            raise typer.Exit(1) from None
+
+        if raw_output:
+            _print_raw(odonimo_response, "Raw odonimo response")
+
+        if not odonimo_response.data:
+            error_console.print(
+                f"[red]No results:[/red] No odonimo found for codcom={codcom}, "
+                f"denom={denom}"
+            )
+            raise typer.Exit(1) from None
+
+        matches = list(odonimo_response.data)
+        if len(matches) > 1:
+            error_console.print(
+                f"[red]Ambiguous:[/red] {len(matches)} odonimi match codcom="
+                f"{codcom}, denom={denom}. Re-run with --prognaz to pick one:"
+            )
+            for m in matches:
+                error_console.print(
+                    f"  --prognaz {m.prognaz}  →  {m.dug or ''} {m.denomuff or ''}"
+                )
+            raise typer.Exit(1)
+
+        odonimo_data = matches[0]
+        resolved_prognaz = odonimo_data.prognaz
+    else:
         error_console.print(
-            f"[red]No results:[/red] No odonimo found for codcom={codcom}, denom={denom}"
+            "[red]Error:[/red] Provide --denom (street name, base64) or "
+            "--prognaz (national progressive of the odonimo)."
         )
-        raise typer.Exit(1) from None
-
-    odonimo_data = odonimo_response.data[0]
-    prognaz = odonimo_data.prognaz
+        raise typer.Exit(1)
 
-    if not prognaz:
+    if not resolved_prognaz:
         error_console.print("[red]Error:[/red] Odonimo found but no prognaz available")
         raise typer.Exit(1) from None
 
     if not json_output:
         console.print(
             f"[bold]Street:[/bold] {odonimo_data.dug} {odonimo_data.denomuff} "
-            f"(prognaz={prognaz})\n"
+            f"(prognaz={resolved_prognaz})\n"
         )
 
     # Step 2: List accessi for this odonimo
     search_accparz = accparz if accparz else "1"
     try:
         accessi_response = sdk.queryparam.elencoaccessiprog_get_query_param(
-            prognaz=prognaz,
+            prognaz=resolved_prognaz,
             accparz=search_accparz,
         )
     except Exception as e:
@@ -488,7 +556,8 @@ def accessi(
 
     if not accessi_response.data:
         error_console.print(
-            f"[red]No results:[/red] No access points found for prognaz={prognaz}"
+            f"[red]No results:[/red] No access points found for "
+            f"prognaz={resolved_prognaz}"
         )
         raise typer.Exit(1) from None
 

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev3}/tests/cli/test_pa.py

@@ -457,6 +457,78 @@ class TestAccessi:
             accparz="1",
         )
 
+    def test_accessi_ambiguous_denom_lists_matches_and_errors(
+        self, cli_runner: CliRunner
+    ) -> None:
+        """Multiple odonimi for a partial denom → error listing matches, no accessi call."""
+        from anncsu.cli import app
+
+        m1 = MagicMock()
+        m1.prognaz = "917960"
+        m1.dug = "VIA"
+        m1.denomuff = "NINO TARANTO"
+        m2 = MagicMock()
+        m2.prognaz = "920585"
+        m2.dug = "VIA"
+        m2.denomuff = "TARANTO"
+        odo_resp = MagicMock()
+        odo_resp.data = [m1, m2]
+
+        mock_sdk = MagicMock()
+        mock_sdk.queryparam.elencoodonimiprog_get_query_param.return_value = odo_resp
+
+        with patch("anncsu.cli.commands.pa._get_consult_sdk", return_value=mock_sdk):
+            result = cli_runner.invoke(
+                app,
+                ["pa", "accessi", "--codcom", "H501", "--denom", "dGFyYW50bw=="],
+            )
+
+        assert result.exit_code != 0
+        # Both candidates surfaced so the user can disambiguate
+        assert "917960" in result.output
+        assert "920585" in result.output
+        assert "--prognaz" in result.output
+        # Must NOT have guessed an odonimo and listed its accessi
+        mock_sdk.queryparam.elencoaccessiprog_get_query_param.assert_not_called()
+
+    def test_accessi_by_prognaz_skips_denom_search(self, cli_runner: CliRunner) -> None:
+        """--prognaz resolves the odonimo directly via prognazarea, not denom search."""
+        from anncsu.cli import app
+
+        mock_sdk = MagicMock()
+        mock_sdk.queryparam.prognazarea_get_query_param.return_value = (
+            _mock_prognazarea_response()
+        )
+        mock_sdk.queryparam.elencoaccessiprog_get_query_param.return_value = (
+            _mock_accessi_response()
+        )
+
+        with patch("anncsu.cli.commands.pa._get_consult_sdk", return_value=mock_sdk):
+            result = cli_runner.invoke(
+                app,
+                ["pa", "accessi", "--codcom", "H501", "--prognaz", "920585"],
+            )
+
+        assert result.exit_code == 0, result.output
+        # denom search must be skipped entirely
+        mock_sdk.queryparam.elencoodonimiprog_get_query_param.assert_not_called()
+        # accessi listed for the user-supplied prognaz
+        mock_sdk.queryparam.elencoaccessiprog_get_query_param.assert_called_once_with(
+            prognaz="920585",
+            accparz="1",
+        )
+
+    def test_accessi_requires_denom_or_prognaz(self, cli_runner: CliRunner) -> None:
+        """--codcom alone (no --denom, no --prognaz) errors with guidance."""
+        from anncsu.cli import app
+
+        mock_sdk = MagicMock()
+        with patch("anncsu.cli.commands.pa._get_consult_sdk", return_value=mock_sdk):
+            result = cli_runner.invoke(app, ["pa", "accessi", "--codcom", "H501"])
+
+        assert result.exit_code != 0
+        assert "--prognaz" in result.output or "--denom" in result.output
+
     def test_accessi_odonimo_not_found(self, cli_runner: CliRunner) -> None:
         """Test accessi exits with error when odonimo not found."""
         from anncsu.cli import app