55< head >
66 < meta charset ="utf-8 " />
77 < meta name ="viewport " content ="width=device-width, initial-scale=1.0 " />
8- < title > dataretrieval.streamstats — dataretrieval 0.1.dev1+g484a86aa7 documentation</ title >
8+ < title > dataretrieval.streamstats — dataretrieval 0.1.dev1+gcdd533e1e documentation</ title >
99 < link rel ="stylesheet " type ="text/css " href ="../../_static/pygments.css?v=b86133f3 " />
1010 < link rel ="stylesheet " type ="text/css " href ="../../_static/css/theme.css?v=9edc463e " />
1111
1212
1313 < script src ="../../_static/jquery.js?v=5d32c60e "> </ script >
1414 < script src ="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c "> </ script >
15- < script src ="../../_static/documentation_options.js?v=2cd4c98e "> </ script >
15+ < script src ="../../_static/documentation_options.js?v=b748f937 "> </ script >
1616 < script src ="../../_static/doctools.js?v=fd6eb6e6 "> </ script >
1717 < script src ="../../_static/sphinx_highlight.js?v=6ffebe34 "> </ script >
1818 < script crossorigin ="anonymous " integrity ="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA= " src ="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js "> </ script >
@@ -141,7 +141,7 @@ <h1>Source code for dataretrieval.streamstats</h1><div class="highlight"><pre>
141141< span class ="sd "> from the streamstats JSON object.</ span >
142142
143143< span class ="sd "> """</ span >
144- < span class ="k "> return</ span > < span class ="n "> get_watershed</ span > < span class ="p "> (</ span > < span class ="s2 "> "NY"</ span > < span class ="p "> ,</ span > < span class ="o "> -</ span > < span class ="mf "> 74.524</ span > < span class ="p "> ,</ span > < span class ="mf "> 43.939</ span > < span class ="p "> )</ span > </ div >
144+ < span class ="k "> return</ span > < span class ="n "> get_watershed</ span > < span class ="p "> (</ span > < span class ="s2 "> "NY"</ span > < span class ="p "> ,</ span > < span class ="o "> -</ span > < span class ="mf "> 74.524</ span > < span class ="p "> ,</ span > < span class ="mf "> 43.939</ span > < span class ="p "> , </ span > < span class =" nb " > format </ span > < span class =" o " > = </ span > < span class =" s2 " > "object" </ span > < span class =" p " > )</ span > </ div >
145145
146146
147147
@@ -219,13 +219,15 @@ <h1>Source code for dataretrieval.streamstats</h1><div class="highlight"><pre>
219219 < span class ="k "> return</ span > < span class ="n "> r</ span >
220220
221221 < span class ="k "> if</ span > < span class ="nb "> format</ span > < span class ="o "> ==</ span > < span class ="s2 "> "shape"</ span > < span class ="p "> :</ span >
222- < span class ="c1 "> # use Fiona to return a shape object</ span >
223- < span class ="k "> pass</ span >
224-
225- < span class ="k "> if</ span > < span class ="nb "> format</ span > < span class ="o "> ==</ span > < span class ="s2 "> "object"</ span > < span class ="p "> :</ span >
226- < span class ="c1 "> # return a python object</ span >
227- < span class ="k "> pass</ span >
228-
222+ < span class ="c1 "> # Returning a shapefile/Fiona object isn't implemented; fail</ span >
223+ < span class ="c1 "> # loudly instead of silently falling through to a Watershed.</ span >
224+ < span class ="k "> raise</ span > < span class ="ne "> NotImplementedError</ span > < span class ="p "> (</ span >
225+ < span class ="s2 "> "format='shape' is not implemented. Use format='geojson' "</ span >
226+ < span class ="s2 "> "(default) for the raw response, or format='object' for a "</ span >
227+ < span class ="s2 "> "parsed Watershed."</ span >
228+ < span class ="p "> )</ span >
229+
230+ < span class ="c1 "> # format == "object" (and any other value): parse into a Watershed.</ span >
229231 < span class ="n "> data</ span > < span class ="o "> =</ span > < span class ="n "> json</ span > < span class ="o "> .</ span > < span class ="n "> loads</ span > < span class ="p "> (</ span > < span class ="n "> r</ span > < span class ="o "> .</ span > < span class ="n "> text</ span > < span class ="p "> )</ span >
230232 < span class ="k "> return</ span > < span class ="n "> Watershed</ span > < span class ="o "> .</ span > < span class ="n "> from_streamstats_json</ span > < span class ="p "> (</ span > < span class ="n "> data</ span > < span class ="p "> )</ span > </ div >
231233
@@ -234,25 +236,62 @@ <h1>Source code for dataretrieval.streamstats</h1><div class="highlight"><pre>
234236< div class ="viewcode-block " id ="Watershed ">
235237< a class ="viewcode-back " href ="../../reference/streamstats.html#dataretrieval.streamstats.Watershed "> [docs]</ a >
236238< span class ="k "> class</ span > < span class ="w "> </ span > < span class ="nc "> Watershed</ span > < span class ="p "> :</ span >
237- < span class ="w "> </ span > < span class ="sd "> """Class to extract information from the streamstats JSON object.""" </ span >
239+ < span class ="w "> </ span > < span class ="sd "> """Parsed StreamStats watershed result. </ span >
238240
239- < div class ="viewcode-block " id ="Watershed.from_streamstats_json ">
240- < a class ="viewcode-back " href ="../../reference/streamstats.html#dataretrieval.streamstats.Watershed.from_streamstats_json "> [docs]</ a >
241- < span class ="nd "> @classmethod</ span >
242- < span class ="k "> def</ span > < span class ="w "> </ span > < span class ="nf "> from_streamstats_json</ span > < span class ="p "> (</ span > < span class ="bp "> cls</ span > < span class ="p "> ,</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> ):</ span >
243- < span class ="w "> </ span > < span class ="sd "> """Method that creates a Watershed object from a streamstats JSON."""</ span >
244- < span class ="bp "> cls</ span > < span class ="o "> .</ span > < span class ="n "> watershed_point</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "featurecollection"</ span > < span class ="p "> ][</ span > < span class ="mi "> 0</ span > < span class ="p "> ][</ span > < span class ="s2 "> "feature"</ span > < span class ="p "> ]</ span >
245- < span class ="bp "> cls</ span > < span class ="o "> .</ span > < span class ="n "> watershed_polygon</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "featurecollection"</ span > < span class ="p "> ][</ span > < span class ="mi "> 1</ span > < span class ="p "> ][</ span > < span class ="s2 "> "feature"</ span > < span class ="p "> ]</ span >
246- < span class ="bp "> cls</ span > < span class ="o "> .</ span > < span class ="n "> parameters</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "parameters"</ span > < span class ="p "> ]</ span >
247- < span class ="bp "> cls</ span > < span class ="o "> .</ span > < span class ="n "> _workspaceID</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "workspaceID"</ span > < span class ="p "> ]</ span >
248- < span class ="k "> return</ span > < span class ="bp "> cls</ span > </ div >
241+ < span class ="sd "> Holds the delineated watershed features, the computed basin</ span >
242+ < span class ="sd "> parameters, and the service ``workspaceID`` extracted from a</ span >
243+ < span class ="sd "> StreamStats watershed response. Build one from an already-fetched</ span >
244+ < span class ="sd "> payload with :meth:`from_streamstats_json`, or construct directly</ span >
245+ < span class ="sd "> from a location to fetch and parse in a single step.</ span >
249246
247+ < span class ="sd "> Attributes</ span >
248+ < span class ="sd "> ----------</ span >
249+ < span class ="sd "> watershed_point : dict</ span >
250+ < span class ="sd "> GeoJSON feature for the delineation (pour) point.</ span >
251+ < span class ="sd "> watershed_polygon : dict</ span >
252+ < span class ="sd "> GeoJSON feature for the delineated basin polygon.</ span >
253+ < span class ="sd "> parameters : list</ span >
254+ < span class ="sd "> Basin characteristics returned by the service.</ span >
255+ < span class ="sd "> _workspaceID : str</ span >
256+ < span class ="sd "> Service workspace id, usable with</ span >
257+ < span class ="sd "> :obj:`dataretrieval.streamstats.download_workspace`.</ span >
258+ < span class ="sd "> """</ span >
250259
251260< div class ="viewcode-block " id ="Watershed.__init__ ">
252261< a class ="viewcode-back " href ="../../reference/streamstats.html#dataretrieval.streamstats.Watershed.__init__ "> [docs]</ a >
253262 < span class ="k "> def</ span > < span class ="w "> </ span > < span class ="fm "> __init__</ span > < span class ="p "> (</ span > < span class ="bp "> self</ span > < span class ="p "> ,</ span > < span class ="n "> rcode</ span > < span class ="p "> ,</ span > < span class ="n "> xlocation</ span > < span class ="p "> ,</ span > < span class ="n "> ylocation</ span > < span class ="p "> ):</ span >
254- < span class ="w "> </ span > < span class ="sd "> """Init method that calls the :obj:`from_streamstats_json` method."""</ span >
255- < span class ="n "> get_watershed</ span > < span class ="p "> (</ span > < span class ="n "> rcode</ span > < span class ="p "> ,</ span > < span class ="n "> xlocation</ span > < span class ="p "> ,</ span > < span class ="n "> ylocation</ span > < span class ="p "> )</ span > </ div >
263+ < span class ="w "> </ span > < span class ="sd "> """Delineate the watershed at ``(xlocation, ylocation)`` and</ span >
264+ < span class ="sd "> parse the response onto this instance."""</ span >
265+ < span class ="n "> response</ span > < span class ="o "> =</ span > < span class ="n "> get_watershed</ span > < span class ="p "> (</ span > < span class ="n "> rcode</ span > < span class ="p "> ,</ span > < span class ="n "> xlocation</ span > < span class ="p "> ,</ span > < span class ="n "> ylocation</ span > < span class ="p "> ,</ span > < span class ="nb "> format</ span > < span class ="o "> =</ span > < span class ="s2 "> "geojson"</ span > < span class ="p "> )</ span >
266+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> _populate</ span > < span class ="p "> (</ span > < span class ="n "> json</ span > < span class ="o "> .</ span > < span class ="n "> loads</ span > < span class ="p "> (</ span > < span class ="n "> response</ span > < span class ="o "> .</ span > < span class ="n "> text</ span > < span class ="p "> ))</ span > </ div >
267+
268+
269+ < div class ="viewcode-block " id ="Watershed.from_streamstats_json ">
270+ < a class ="viewcode-back " href ="../../reference/streamstats.html#dataretrieval.streamstats.Watershed.from_streamstats_json "> [docs]</ a >
271+ < span class ="nd "> @classmethod</ span >
272+ < span class ="k "> def</ span > < span class ="w "> </ span > < span class ="nf "> from_streamstats_json</ span > < span class ="p "> (</ span > < span class ="bp "> cls</ span > < span class ="p "> ,</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> )</ span > < span class ="o "> -></ span > < span class ="s2 "> "Watershed"</ span > < span class ="p "> :</ span >
273+ < span class ="w "> </ span > < span class ="sd "> """Create a :class:`Watershed` from an already-parsed StreamStats</ span >
274+ < span class ="sd "> JSON payload, without issuing a new request.</ span >
275+
276+ < span class ="sd "> Builds a fresh instance (via ``__new__``, so the</ span >
277+ < span class ="sd "> network-fetching ``__init__`` is bypassed) and populates it; each</ span >
278+ < span class ="sd "> call returns an independent object rather than mutating shared</ span >
279+ < span class ="sd "> class state.</ span >
280+ < span class ="sd "> """</ span >
281+ < span class ="bp "> self</ span > < span class ="o "> =</ span > < span class ="bp "> cls</ span > < span class ="o "> .</ span > < span class ="fm "> __new__</ span > < span class ="p "> (</ span > < span class ="bp "> cls</ span > < span class ="p "> )</ span >
282+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> _populate</ span > < span class ="p "> (</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> )</ span >
283+ < span class ="k "> return</ span > < span class ="bp "> self</ span > </ div >
284+
285+
286+ < div class ="viewcode-block " id ="Watershed._populate ">
287+ < a class ="viewcode-back " href ="../../reference/streamstats.html#dataretrieval.streamstats.Watershed._populate "> [docs]</ a >
288+ < span class ="k "> def</ span > < span class ="w "> </ span > < span class ="nf "> _populate</ span > < span class ="p "> (</ span > < span class ="bp "> self</ span > < span class ="p "> ,</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> )</ span > < span class ="o "> -></ span > < span class ="kc "> None</ span > < span class ="p "> :</ span >
289+ < span class ="w "> </ span > < span class ="sd "> """Extract watershed fields from a StreamStats JSON payload onto</ span >
290+ < span class ="sd "> this instance."""</ span >
291+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> watershed_point</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "featurecollection"</ span > < span class ="p "> ][</ span > < span class ="mi "> 0</ span > < span class ="p "> ][</ span > < span class ="s2 "> "feature"</ span > < span class ="p "> ]</ span >
292+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> watershed_polygon</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "featurecollection"</ span > < span class ="p "> ][</ span > < span class ="mi "> 1</ span > < span class ="p "> ][</ span > < span class ="s2 "> "feature"</ span > < span class ="p "> ]</ span >
293+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> parameters</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "parameters"</ span > < span class ="p "> ]</ span >
294+ < span class ="bp "> self</ span > < span class ="o "> .</ span > < span class ="n "> _workspaceID</ span > < span class ="o "> =</ span > < span class ="n "> streamstats_json</ span > < span class ="p "> [</ span > < span class ="s2 "> "workspaceID"</ span > < span class ="p "> ]</ span > </ div >
256295</ div >
257296
258297</ pre > </ div >
0 commit comments