Skip to content

Commit 3f7d5fc

Browse files
Renfu-LiRenfu-Li
committed
docs: add docstrings for discovery methods
1 parent aaa578f commit 3f7d5fc

File tree

1 file changed

+261
-0
lines changed

1 file changed

+261
-0
lines changed

‎src/onc/onc.py

+261
Original file line numberDiff line numberDiff line change
@@ -134,21 +134,282 @@ def getLocations(self, filters: dict | None = None):
134134
return self.discovery.getLocations(filters)
135135

136136
def getLocationHierarchy(self, filters: dict = None):
137+
"""
138+
Returns a filtered tree of locations with their children.
139+
140+
The API endpoint is api/locations/tree.
141+
142+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getLocationHierarchy
143+
for usage and available filters.
144+
145+
Parameters
146+
----------
147+
filters : dict, optional
148+
Filters in the API request. Return a tree of all available locations if None.
149+
150+
Returns
151+
------
152+
list of dict
153+
API response.
154+
155+
Examples
156+
--------
157+
>>> filters = { 'locationCode': 'STR01' }
158+
>>> onc.getLocationHierarchy(filters) # doctest: +SKIP
159+
[
160+
{
161+
"locationName": "Neutrino Project Mooring 01 (Yellow)",
162+
"description": "TBD",
163+
"hasDeviceData": true,
164+
"locationCode": "STR01",
165+
"hasPropertyData": false,
166+
"children": [
167+
{
168+
"locationName": "POCAM 110 mab",
169+
"children": null,
170+
"description": "",
171+
"hasDeviceData": true,
172+
"locationCode": "STR01.PO1",
173+
"hasPropertyData": false
174+
},
175+
{
176+
"locationName": "POCAM 50 mab",
177+
"children": null,
178+
"description": "",
179+
"hasDeviceData": true,
180+
"locationCode": "STR01.PO2",
181+
"hasPropertyData": false
182+
}
183+
]
184+
}
185+
]
186+
""" # noqa: E501
137187
return self.discovery.getLocationHierarchy(filters)
138188

139189
def getDeployments(self, filters: dict = None):
190+
"""
191+
Returns a filtered list of deployments.
192+
193+
The API endpoint is api/deployments.
194+
195+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDeployments
196+
for usage and available filters.
197+
198+
Parameters
199+
----------
200+
filters : dict, optional
201+
Filters in the API request. Return all device deployment if None.
202+
203+
Returns
204+
-------
205+
list of dict
206+
API response.
207+
208+
Examples
209+
--------
210+
>>> filters = { 'deviceCode': 'NORTEKADCP9917' }
211+
>>> onc.getDeployments(filters) # doctest: +SKIP
212+
[
213+
{
214+
"deviceCode": "NORTEKADCP9917",
215+
"locationCode": "BACWL",
216+
"begin": "2012-05-31T20:46:05.000Z",
217+
"end": "2014-05-10T01:40:00.000Z",
218+
"hasDeviceData": true,
219+
"lat": 48.311743,
220+
"lon": -126.065378,
221+
"depth": 860.0,
222+
"heading": null,
223+
"pitch": null,
224+
"roll": null
225+
}
226+
]
227+
""" # noqa: E501
140228
return self.discovery.getDeployments(filters)
141229

142230
def getDevices(self, filters: dict = None):
231+
"""
232+
Returns a filtered list of devices.
233+
234+
The API endpoint is api/devices.
235+
236+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDevices
237+
for usage and available filters.
238+
239+
Parameters
240+
----------
241+
filters : dict, optional
242+
Filters in the API request. Return all devices available if None.
243+
244+
Returns
245+
-------
246+
list of dict
247+
API response.
248+
249+
Examples
250+
--------
251+
>>> filters = {
252+
'deviceCode': 'BPR-Folger-59',
253+
'dateFrom': '2005-09-17T00:00:00.000Z',
254+
'dateTo': '2020-09-17T13:00:00.000Z'
255+
}
256+
>>> onc.getDevices(filters) # doctest: +SKIP
257+
[
258+
{
259+
"deviceCode": "BPR-Folger-59",
260+
"deviceId": 21503,
261+
"deviceCategoryCode": "BPR",
262+
"deviceName": "NRCan Bottom Pressure Recorder 59",
263+
"deviceLink": "https://data.oceannetworks.ca/DeviceListing?DeviceId=21503",
264+
"hasDeviceData": true,
265+
"dataRating": [
266+
{
267+
"dateFrom": "2007-01-01T00:00:00.000Z",
268+
"dateTo": null,
269+
"samplePeriod": 1,
270+
"sampleSize": 1
271+
}
272+
],
273+
"cvTerm": {
274+
"device": [
275+
{
276+
"vocabulary": "SeaVoX Device Catalogue",
277+
"uri": "http://vocab.nerc.ac.uk/collection/L22/current/TOOL1652/"
278+
}
279+
]
280+
}
281+
}
282+
]
283+
""" # noqa: E501
143284
return self.discovery.getDevices(filters)
144285

145286
def getDeviceCategories(self, filters: dict = None):
287+
"""
288+
Returns a filtered list of device categories.
289+
290+
The API endpoint is api/deviceCategories.
291+
292+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDeviceCategories
293+
for usage and available filters.
294+
295+
Parameters
296+
----------
297+
filters : dict, optional
298+
Filters in the API request. Return all device categories available if None.
299+
300+
Returns
301+
-------
302+
list of dict
303+
API response.
304+
305+
Examples
306+
--------
307+
>>> filters = { 'locationCode': 'NCBC' }
308+
>>> onc.getDeviceCategories(filters) # doctest: +SKIP
309+
[
310+
{
311+
"deviceCategoryCode": "CTD",
312+
"deviceCategoryName": "CTD",
313+
"description": "Conductivity Temperature (and Depth Sensor)",
314+
"longDescription": " Conductivity Temperature Depth (CTD) is (...)",
315+
"hasDeviceData": "true",
316+
"cvTerm": {
317+
"deviceCategory": [
318+
{
319+
"uri": "http://vocab.nerc.ac.uk/collection/L05/current/130/",
320+
"vocabulary": "SeaDataNet device categories"
321+
}
322+
]
323+
}
324+
}
325+
]
326+
""" # noqa: E501
146327
return self.discovery.getDeviceCategories(filters)
147328

148329
def getProperties(self, filters: dict = None):
330+
"""
331+
Returns a filtered list of properties.
332+
333+
The API endpoint is api/properties.
334+
335+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getProperties
336+
for usage and available filters.
337+
338+
Parameters
339+
----------
340+
filters : dict, optional
341+
Filters in the API request. Return all properties available if None.
342+
343+
Returns
344+
-------
345+
list of dict
346+
API response.
347+
348+
Examples
349+
--------
350+
>>> filters = { 'deviceCode': 'BC_POD1_AD2M' }
351+
>>> onc.getProperties(filters) # doctest: +SKIP
352+
[
353+
{
354+
"propertyCode": "soundspeed",
355+
"propertyName": "Sound Speed",
356+
"description": "Sound Speed: sound velocity sensor",
357+
"uom": "m/s",
358+
"hasDeviceData": true,
359+
"hasPropertyData": false,
360+
"cvTerm": {
361+
"property": [],
362+
"uom": [
363+
{
364+
"uri": "http://vocab.nerc.ac.uk/collection/P06/current/UVAA/",
365+
"vocabulary": "BODC data storage units"
366+
}
367+
]
368+
}
369+
},
370+
(...)
371+
]
372+
""" # noqa: E501
149373
return self.discovery.getProperties(filters)
150374

151375
def getDataProducts(self, filters: dict = None):
376+
"""
377+
Returns a filtered list of data products.
378+
379+
The API endpoint is api/dataProducts.
380+
381+
See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDataProducts
382+
for usage and available filters.
383+
384+
Parameters
385+
----------
386+
filters : dict, optional
387+
Filters in the API request. Return all data products available if None.
388+
389+
Returns
390+
-------
391+
list of dict
392+
API response.
393+
394+
Examples
395+
--------
396+
>>> filters = {
397+
... 'locationCode': 'PHYD',
398+
... 'extension': 'mat'
399+
... }
400+
>>> onc.getDataProducts(filters) # doctest: +SKIP
401+
[
402+
{
403+
"dataProductCode": "TSSD",
404+
"dataProductName": "Time Series Scalar Data",
405+
"extension": "json",
406+
"hasDeviceData": true,
407+
"hasPropertyData": true,
408+
"helpDocument": "https://wiki.oceannetworks.ca/display/DP/1"
409+
},
410+
(...)
411+
]
412+
""" # noqa: E501
152413
return self.discovery.getDataProducts(filters)
153414

154415
# Delivery methods

0 commit comments

Comments
 (0)