feat: add data availability api, test case and documentation

Author: kan-fu

doc/source/Code_Examples/Discover_Data_Availability.md

@@ -0,0 +1,37 @@
+# Discover Data Availability for Data Products
+
+```python
+# Get the token from your Oceans 3.0 profile page
+from onc import ONC
+
+onc = ONC("YOUR_TOKEN")
+```
+
+## [/dataAvailability/dataproducts](https://data.oceannetworks.ca/OpenAPI#get-/dataAvailability/dataproducts)
+
+### Get data availability from a specific location and a device category
+
+Return which data products are available with _deviceCategoryCode_ "**BPR**" at location Barkley Upper Slope (
+_locationCode_:"**NCBC**").
+
+```python
+
+params = {
+    "deviceCategoryCode": "BPR",
+    "locationCode": "NCBC",
+}
+onc.getDataAvailability(params)
+```
+
+### Get data availability from a specific device with a specific extension
+
+Return which data products are available with _deviceCode_ "**BPR_BC**" and extension "**raw**"
+
+```python
+
+params = {
+    "deviceCode": "BPR_BC",
+    "extension": "raw",
+}
+onc.getDataAvailability(params)
+```

doc/source/Code_Examples/index.md

@@ -12,6 +12,7 @@ Discover_Deployments.ipynb
 Discover_Device_Categories.ipynb
 Discover_Properties.ipynb
 Discover_Data_Products.ipynb
+Discover_Data_Availability.ipynb
 Download_Data_Products.ipynb
 Request_Real_Time_Data.ipynb
 Download_Archived_Files.ipynb

src/onc/modules/_OncDiscovery.py

@@ -46,6 +46,10 @@ def getProperties(self, filters: dict):
     def getDataProducts(self, filters: dict):
         filters = filters or {}
         return self._discoveryRequest(filters, service="dataProducts")
+    
+    def getDataAvailability(self, filters: dict):
+        filters = filters or {}
+        return self._discoveryRequest(filters, service="dataAvailability/dataproducts")
 
     def _sanitizeBooleans(self, data: list):
         """

src/onc/modules/_OncService.py

@@ -104,6 +104,7 @@ def _serviceUrl(self, service: str):
             "archivefile",
             "scalardata",
             "rawdata",
+            "dataAvailability/dataproducts",
         ]:
             return f"{self._config('baseUrl')}api/{service}"
 

src/onc/onc.py

@@ -784,6 +784,78 @@ def getDataProducts(self, filters: dict | None = None):
         ]
         """  # noqa: E501
         return self.discovery.getDataProducts(filters)
+    
+    def getDataAvailability(self, filters: dict | None = None):
+        """
+        Return information about which data products are available at a given time.
+
+        The API endpoint is ``/dataAvailability/dataproducts``.
+
+        See https://data.oceannetworks.ca/OpenAPI#get-/dataAvailability/dataproducts
+        for usage and available filters.
+
+        Parameters
+        ----------
+        filters : dict, optional
+            Query string parameters in the API request. 
+
+            Supported parameters are:
+
+            - locationCode
+            - deviceCategoryCode
+            - deviceCode
+            - propertyCode
+            - dateFrom
+            - dateTo
+            - dataProductCode
+            - extension
+            - minimumCoverage
+            - maximumCoverage
+            - getLatest
+            - groupBy
+            - mergeGaps  
+            - includeEmptyDays  
+            - rowLimit  
+
+        Returns
+        -------
+        list of dict
+            API response. 
+
+        Examples
+        --------
+        >>> params = {
+        ...     "locationCode": "NCBC",
+        ...     "deviceCategoryCode": "BPR",
+        ...     "dateFrom": "2019-11-23",
+        ...     "dateTo": "2019-11-30",
+        ... }  # doctest: +SKIP
+        >>> onc.getDataAvailability(params)  # doctest: +SKIP
+        {
+            "availableDataProducts": [
+                {
+                    "averageFileCoverage": 0.875,
+                    "dataProductCode": "LF",
+                    "dateFrom": "2019-11-23T00:00:00.000Z",
+                    "dateTo": "2019-12-01T00:00:00.000Z",
+                    "deviceCode": "BPR-Folger-59",
+                    "extension": "txt",
+                    "fileCount": 7,
+                    "maxFileCoverage": 1.0,
+                    "maxFileCoverageDate": "2019-11-23T00:00:00.000Z",
+                    "minFileCoverage": 0.0,
+                    "minFileCoverageDate": "2019-11-30T00:00:00.000Z",
+                    "totalFileSize": 8707618,
+                    "totalUncompressedFileSize": 33868912,
+                }
+            ],
+            "messages": [],
+            "next": None,
+            "queryUrl": "https://data.oceannetworks.ca/api/dataAvailability/dataproducts?locationCode=NCBC&deviceCategoryCode=BPR&dateFrom=2019-11-23&dateTo=2019-11-30&token=ONC_TOKEN",
+        }
+        
+        """  # noqa: E501
+        return self.discovery.getDataAvailability(filters)
 
     # Delivery methods
 

tests/discover_data_availability/test_data_availability.py

@@ -0,0 +1,50 @@
+import pytest
+import requests
+
+
+@pytest.fixture
+def params():
+    return {
+        "locationCode": "NCBC",
+        "deviceCategoryCode": "BPR",
+        "dateFrom": "2019-11-23",
+        "dateTo": "2019-11-30",
+    }
+
+
+def test_invalid_param_value(requester, params):
+    params_invalid_param_value = params | {"locationCode": "INVALID"}
+    with pytest.raises(requests.HTTPError, match=r"API Error 127"):
+        requester.getDataAvailability(params_invalid_param_value)
+
+
+def test_valid_params(requester, params, util):
+    data = requester.getDataAvailability(params)
+
+    expected_keys = {
+        "availableDataProducts": list,
+        "messages": list,
+        "next": None,
+        "queryUrl": str,
+    }
+
+    expected_keys_available_data_products = {
+        "averageFileCoverage": float,
+        "dataProductCode": str,
+        "dateFrom": str,
+        "dateTo": str,
+        "deviceCode": str,
+        "extension": str,
+        "fileCount": int,
+        "maxFileCoverage": float,
+        "maxFileCoverageDate": str,
+        "minFileCoverage": float,
+        "minFileCoverageDate": str,
+        "totalFileSize": int,
+        "totalUncompressedFileSize": int,
+    }
+
+    util.assert_dict_key_types(data, expected_keys)
+    util.assert_dict_key_types(
+        data["availableDataProducts"][0], expected_keys_available_data_products
+    )