DOI-USGS / DOI-USGS/dataretrieval-python

streamstats: should get_watershed always return a Watershed?

Offen
#260 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Python
Sterne
265
Forks
63
Ø Merge
1 T. 20 Std.
Gemergte PRs (30 T.)
19

Beschreibung

## Background

`dataretrieval.streamstats.get_watershed` currently has a `format` parameter that selects between three return types:

- `format="geojson"` (default): the raw `requests.Response`
- `format="object"`: the parsed JSON `dict`
- `format="watershed"`: a `Watershed` instance built from the parsed JSON
- anything else: `ValueError`

The multi-return contract is documented in #245 (after that PR's fix). But the function's name and StreamStats' own conceptual model both suggest it should return a *watershed*.

## Proposal

Drop the `format` parameter and have `get_watershed` always return a `Watershed`.

Pros:
- Single return type → cleaner type annotation (`-> Watershed`), no `Union[Response, dict, Watershed]`.
- Function name matches its contract.
- Removes the silent-fallthrough bug class entirely (no `format` string to typo).
- Callers wanting the raw `Response` can use `requests.get(...)`; callers wanting JSON can call `Watershed.from_streamstats_json(r.json())` or read `Watershed.parameters` / `Watershed.workspace_id` directly.

Cons:
- **Breaking change** for callers using `format="geojson"` (the current default) or `format="object"`.
- The default behavior changes silently if a caller passed no `format` — they previously got a `Response` and would now get a `Watershed`.

## Implementation sketch

Extract the HTTP+parse into a private helper (`_fetch_streamstats_json`) so `get_watershed` and `Watershed.__init__` can share fetch logic without circular calls. A working draft of this lived briefly on the `fix/streamstats-watershed-class` branch (commit `b3a5d29`, since reverted to keep #245 non-breaking).

## Decision needed

Is this worth the breaking change? If so, when — current minor cycle, next major, or behind a deprecation warning?

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Lies zuerst dataretrieval.streamstats.get_watershed und Watershed.__init__, und untersuche dann den zurückgenommenen Fix-Entwurf fix/streamstats-watershed-class bei Commit b3a5d29. Prüfe die Auswirkungen der inkompatiblen Änderung auf die dokumentierten Formate und bestimme, ob das Projekt den Vorschlag übernehmen, ihn auf ein Major-Release verschieben oder eine Deprecation verwenden sollte; abgeschlossen ist die Aufgabe, wenn diese Entscheidung und ihr Kompatibilitätsplan festgehalten wurden.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
api, backend
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.