DOI-USGS / DOI-USGS/dataretrieval-python
streamstats: should get_watershed always return a Watershed?
- 主要言語
- Python
- スター
- 266
- フォーク
- 63
- 平均マージ
- 1日 20時間
- マージ済み PR(30日)
- 19
説明
## 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?
コントリビューションガイド
調査の方向性
まず dataretrieval.streamstats.get_watershed と Watershed.__init__ を読み、その後、commit b3a5d29 にある取り消された修正案 fix/streamstats-watershed-class を調査する。文書化されている形式に対する breaking change の影響を確認し、プロジェクトが提案を採用するべきか、major release まで延期するべきか、または deprecation を使用するべきかを判断する;その決定と互換性計画を記録すれば完了とする。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- python
- 領域
- api, backend
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 静か
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 45/100