Make get_watershed always return a Watershed

Per Copilot review: the function's name and narrative docstring both
promise a Watershed, but the actual contract was three different return
types selected by `format` (Response, dict, Watershed) — and the default
returned a `requests.Response`, contradicting the narrative.

Drop the `format` parameter and always return a `Watershed`. Extract the
HTTP+parse into a private `_fetch_streamstats_json` helper that both
`get_watershed` and `Watershed.__init__` use, so they share fetch logic
without circular calls. The narrative docstring now matches the
contract.

Also drop dead commented-out lines in `download_workspace` while in
the file.

Breaking change for callers using `format="geojson"`/`"object"`/etc.
Callers needing the raw JSON or Response can use
`Watershed.from_streamstats_json(...)` and `requests.get(...)` directly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/streamstats.py

@@ -34,12 +34,6 @@ def download_workspace(workspaceID, format=""):
 
     r.raise_for_status()
     return r
-    # data = r.raw.read()
-
-    # with open(filepath, 'wb') as f:
-    #    f.write(data)
-
-    # return
 
 
 def get_sample_watershed():
@@ -56,7 +50,35 @@ def get_sample_watershed():
         from the streamstats JSON object.
 
     """
-    return get_watershed("NY", -74.524, 43.939, format="watershed")
+    return get_watershed("NY", -74.524, 43.939)
+
+
+def _fetch_streamstats_json(
+    rcode,
+    xlocation,
+    ylocation,
+    crs=4326,
+    includeparameters=True,
+    includeflowtypes=False,
+    includefeatures=True,
+    simplify=True,
+):
+    """Hit the StreamStats watershed endpoint and return the parsed JSON."""
+    payload = {
+        "rcode": rcode,
+        "xlocation": xlocation,
+        "ylocation": ylocation,
+        "crs": crs,
+        "includeparameters": includeparameters,
+        "includeflowtypes": includeflowtypes,
+        "includefeatures": includefeatures,
+        "simplify": simplify,
+    }
+    url = "https://streamstats.usgs.gov/streamstatsservices/watershed.geojson"
+
+    r = requests.get(url, params=payload)
+    r.raise_for_status()
+    return r.json()
 
 
 def get_watershed(
@@ -68,16 +90,14 @@ def get_watershed(
     includeflowtypes=False,
     includefeatures=True,
     simplify=True,
-    format="geojson",
 ):
-    """Get watershed object based on location
+    """Get watershed object based on location.
 
-    **Streamstats documentation:**
-    Returns a watershed object. The request configuration will determine the
-    overall request response. However all returns will return a watershed
-    object with at least the workspaceid. The workspace id is the id to the
-    service workspace where files are stored and can be used for further
-    processing such as for downloads and flow statistic computations.
+    Delineates a watershed via the StreamStats ``watershed.geojson`` endpoint
+    and returns it as a :obj:`Watershed` instance carrying the pour point,
+    polygon, parameters, and workspace identifier from the response. The
+    workspace identifier can be passed to :obj:`download_workspace` for
+    further processing.
 
     See: https://streamstats.usgs.gov/streamstatsservices/#/ for more
     information.
@@ -103,49 +123,24 @@ def get_watershed(
     simplify: bool, optional
         Boolean flag controlling whether or not to simplify the returned
         result.
-    format: string, optional
-        Selects the return shape. ``"geojson"`` (default) returns the raw
-        ``requests.Response``; ``"object"`` returns the parsed JSON ``dict``;
-        ``"watershed"`` returns a :obj:`Watershed` instance built from the
-        parsed JSON. Any other value raises ``ValueError``.
 
     Returns
     -------
-    requests.Response, dict, or :obj:`dataretrieval.streamstats.Watershed`
-        Watershed information from StreamStats. The exact return type
-        depends on ``format`` (see above).
+    Watershed: :obj:`dataretrieval.streamstats.Watershed`
+        Watershed instance built from the StreamStats response.
 
     """
-    payload = {
-        "rcode": rcode,
-        "xlocation": xlocation,
-        "ylocation": ylocation,
-        "crs": crs,
-        "includeparameters": includeparameters,
-        "includeflowtypes": includeflowtypes,
-        "includefeatures": includefeatures,
-        "simplify": simplify,
-    }
-    url = "https://streamstats.usgs.gov/streamstatsservices/watershed.geojson"
-
-    r = requests.get(url, params=payload)
-
-    r.raise_for_status()
-
-    if format == "geojson":
-        return r
-
-    data = r.json()
-
-    if format == "object":
-        return data
-
-    if format == "watershed":
-        return Watershed.from_streamstats_json(data)
-
-    raise ValueError(
-        f"Invalid format {format!r}; expected 'geojson', 'object', or 'watershed'."
+    data = _fetch_streamstats_json(
+        rcode,
+        xlocation,
+        ylocation,
+        crs=crs,
+        includeparameters=includeparameters,
+        includeflowtypes=includeflowtypes,
+        includefeatures=includefeatures,
+        simplify=simplify,
     )
+    return Watershed.from_streamstats_json(data)
 
 
 class Watershed:
@@ -165,8 +160,7 @@ class Watershed:
 
     def __init__(self, rcode, xlocation, ylocation):
         """Delineate a watershed and populate the instance from the response."""
-        data = get_watershed(rcode, xlocation, ylocation, format="object")
-        self._populate_from_json(data)
+        self._populate_from_json(_fetch_streamstats_json(rcode, xlocation, ylocation))
 
     @classmethod
     def from_streamstats_json(cls, streamstats_json):