streamstats: should get_watershed always return a Watershed?
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
调研方向
先阅读 dataretrieval.streamstats.get_watershed 和 Watershed.init，然后检查 commit b3a5d29 中已撤回的修复草案 fix/streamstats-watershed-class。审查 breaking change 对文档所述格式的影响，并确定项目应采用该提案、将其推迟到 major release，还是使用 deprecation；完成的标准是记录该决定及其兼容性计划。
由索引模型根据 Issue 内容生成。
描述
Background
dataretrieval.streamstats.get_watershed currently has a format parameter that selects between three return types:
format="geojson"(default): the rawrequests.Responseformat="object": the parsed JSONdictformat="watershed": aWatershedinstance 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), noUnion[Response, dict, Watershed]. - Function name matches its contract.
- Removes the silent-fallthrough bug class entirely (no
formatstring to typo). - Callers wanting the raw
Responsecan userequests.get(...); callers wanting JSON can callWatershed.from_streamstats_json(r.json())or readWatershed.parameters/Watershed.workspace_iddirectly.
Cons:
- Breaking change for callers using
format="geojson"(the current default) orformat="object". - The default behavior changes silently if a caller passed no
format— they previously got aResponseand would now get aWatershed.
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?
- 主要语言
- Python
- 星标
- 269
- 派生
- 67
- 平均合并
- 3 天 17 小时
- 30 天内合并 PR
- 18
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
DOI-USGS/dataretrieval-python 的其他 Issue
-
难度 5/5 一周以上 新手友好度 30/100
DOI-USGS/dataretrieval-python#406 · 1 条评论 ·
维护者通常 1 天内回复
-
Check getter parameter docs against the service's queryables可能已有人在做 @acalebratliff 于 4 天前认领。 未关闭documentation ready-for-agent
难度 5/5 一周以上 新手友好度 30/100
DOI-USGS/dataretrieval-python#379 · 4 条评论 ·
维护者通常 1 天内回复
查看 DOI-USGS/dataretrieval-python 的全部 Issue
相似的 Issue
-
Edit tool converts CRLF files to LF可能已有人在做 @RaphaelFakhri 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 68/100
huggingface/tau#774 ·
维护者通常 1 天内回复
-
show ignores the row limit when a column or table name contains "limit"可能已有人在做 @RaphaelFakhri 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 84/100
维护者通常 2 天内回复
-
documentation good first issue
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 74/100
eclipse-score/inc_someip_gateway#356 ·
维护者通常 2 天内回复