Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue 9 add docstrings for discovery methods #21

Merged
merged 1 commit into from
Dec 21, 2023
Merged

Issue 9 add docstrings for discovery methods #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
273 changes: 267 additions & 6 deletions src/onc/onc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,22 +133,283 @@ def getLocations(self, filters: dict | None = None):
""" # noqa: E501
return self.discovery.getLocations(filters)

def getLocationHierarchy(self, filters: dict = None):
def getLocationHierarchy(self, filters: dict | None = None):
"""
Returns a filtered tree of locations with their children.

The API endpoint is api/locations/tree.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getLocationHierarchy
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return a tree of all available locations if None.

Returns
------
list of dict
API response.

Examples
--------
>>> filters = { 'locationCode': 'STR01' }
>>> onc.getLocationHierarchy(filters) # doctest: +SKIP
[
{
"locationName": "Neutrino Project Mooring 01 (Yellow)",
"description": "TBD",
"hasDeviceData": true,
"locationCode": "STR01",
"hasPropertyData": false,
"children": [
{
"locationName": "POCAM 110 mab",
"children": null,
"description": "",
"hasDeviceData": true,
"locationCode": "STR01.PO1",
"hasPropertyData": false
},
{
"locationName": "POCAM 50 mab",
"children": null,
"description": "",
"hasDeviceData": true,
"locationCode": "STR01.PO2",
"hasPropertyData": false
}
]
}
]
""" # noqa: E501
return self.discovery.getLocationHierarchy(filters)

def getDeployments(self, filters: dict = None):
def getDeployments(self, filters: dict | None = None):
"""
Returns a filtered list of deployments.

The API endpoint is api/deployments.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDeployments
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return all device deployment if None.

Returns
-------
list of dict
API response.

Examples
--------
>>> filters = { 'deviceCode': 'NORTEKADCP9917' }
>>> onc.getDeployments(filters) # doctest: +SKIP
[
{
"deviceCode": "NORTEKADCP9917",
"locationCode": "BACWL",
"begin": "2012-05-31T20:46:05.000Z",
"end": "2014-05-10T01:40:00.000Z",
"hasDeviceData": true,
"lat": 48.311743,
"lon": -126.065378,
"depth": 860.0,
"heading": null,
"pitch": null,
"roll": null
}
]
""" # noqa: E501
return self.discovery.getDeployments(filters)

def getDevices(self, filters: dict = None):
def getDevices(self, filters: dict | None = None):
"""
Returns a filtered list of devices.

The API endpoint is api/devices.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDevices
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return all devices available if None.

Returns
-------
list of dict
API response.

Examples
--------
>>> filters = {
'deviceCode': 'BPR-Folger-59',
'dateFrom': '2005-09-17T00:00:00.000Z',
'dateTo': '2020-09-17T13:00:00.000Z'
}
>>> onc.getDevices(filters) # doctest: +SKIP
[
{
"deviceCode": "BPR-Folger-59",
"deviceId": 21503,
"deviceCategoryCode": "BPR",
"deviceName": "NRCan Bottom Pressure Recorder 59",
"deviceLink": "https://data.oceannetworks.ca/DeviceListing?DeviceId=21503",
"hasDeviceData": true,
"dataRating": [
{
"dateFrom": "2007-01-01T00:00:00.000Z",
"dateTo": null,
"samplePeriod": 1,
"sampleSize": 1
}
],
"cvTerm": {
"device": [
{
"vocabulary": "SeaVoX Device Catalogue",
"uri": "http://vocab.nerc.ac.uk/collection/L22/current/TOOL1652/"
}
]
}
}
]
""" # noqa: E501
return self.discovery.getDevices(filters)

def getDeviceCategories(self, filters: dict = None):
def getDeviceCategories(self, filters: dict | None = None):
"""
Returns a filtered list of device categories.

The API endpoint is api/deviceCategories.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDeviceCategories
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return all device categories available if None.

Returns
-------
list of dict
API response.

Examples
--------
>>> filters = { 'locationCode': 'NCBC' }
>>> onc.getDeviceCategories(filters) # doctest: +SKIP
[
{
"deviceCategoryCode": "CTD",
"deviceCategoryName": "CTD",
"description": "Conductivity Temperature (and Depth Sensor)",
"longDescription": " Conductivity Temperature Depth (CTD) is (...)",
"hasDeviceData": "true",
"cvTerm": {
"deviceCategory": [
{
"uri": "http://vocab.nerc.ac.uk/collection/L05/current/130/",
"vocabulary": "SeaDataNet device categories"
}
]
}
}
]
""" # noqa: E501
return self.discovery.getDeviceCategories(filters)

def getProperties(self, filters: dict = None):
def getProperties(self, filters: dict | None = None):
"""
Returns a filtered list of properties.

The API endpoint is api/properties.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getProperties
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return all properties available if None.

Returns
-------
list of dict
API response.

Examples
--------
>>> filters = { 'deviceCode': 'BC_POD1_AD2M' }
>>> onc.getProperties(filters) # doctest: +SKIP
[
{
"propertyCode": "soundspeed",
"propertyName": "Sound Speed",
"description": "Sound Speed: sound velocity sensor",
"uom": "m/s",
"hasDeviceData": true,
"hasPropertyData": false,
"cvTerm": {
"property": [],
"uom": [
{
"uri": "http://vocab.nerc.ac.uk/collection/P06/current/UVAA/",
"vocabulary": "BODC data storage units"
}
]
}
},
(...)
]
""" # noqa: E501
return self.discovery.getProperties(filters)

def getDataProducts(self, filters: dict = None):
def getDataProducts(self, filters: dict | None = None):
"""
Returns a filtered list of data products.

The API endpoint is api/dataProducts.

See https://wiki.oceannetworks.ca/pages/viewpage.action?pageId=75170317#Discoverymethods-getDataProducts
for usage and available filters.

Parameters
----------
filters : dict, optional
Filters in the API request. Return all data products available if None.

Returns
-------
list of dict
API response.

Examples
--------
>>> filters = {
... 'locationCode': 'PHYD',
... 'extension': 'mat'
... }
>>> onc.getDataProducts(filters) # doctest: +SKIP
[
{
"dataProductCode": "TSSD",
"dataProductName": "Time Series Scalar Data",
"extension": "json",
"hasDeviceData": true,
"hasPropertyData": true,
"helpDocument": "https://wiki.oceannetworks.ca/display/DP/1"
},
(...)
]
""" # noqa: E501
return self.discovery.getDataProducts(filters)

# Delivery methods
Expand Down
Loading