Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

streamstats: should get_watershed always return a Watershed?

Abierto
  • ¿Algo no está bien?
#260 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
python
Área
api, backend

Línea de trabajo

Lee primero dataretrieval.streamstats.get_watershed y Watershed.init, y después inspecciona el borrador revertido fix/streamstats-watershed-class en el commit b3a5d29. Revisa las implicaciones del cambio incompatible para los formatos documentados y determina si el proyecto debe adoptar la propuesta, aplazarla a una versión major o usar deprecation; la tarea estará terminada cuando se hayan registrado esa decisión y su plan de compatibilidad.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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?

Lenguaje dominante
Python
Estrellas
269
Forks
67
Merge medio
3 d 17 h
PR fusionados (30 d)
18

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de DOI-USGS/dataretrieval-python

Todos los issues de DOI-USGS/dataretrieval-python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.