Merge pull request #50 from OceanNetworksCanada/update-new-method-names

Update new method names

Author: eliferguson

README.md

@@ -12,10 +12,10 @@
 onc is a Python client library that facilitates access to scientific data hosted by [Ocean Networks Canada](https://oceannetworks.ca)
 through the [Oceans 3.0 API](https://data.oceannetworks.ca/OpenAPI) public web services.
 It can help you explore and download our data, by consuming our
-_[discovery](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#discovery-methods)_,
-_[data product download](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#data-product-download-methods)_,
-_[archive file download](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#archive-file-download-methods)_, and
-_[near real-time data access](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#near-real-time-data-access-methods)_ services.
+_[discovery](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#discovery-methods)_,
+_[data product download](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#data-product-download-methods)_,
+_[archive file download](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#archive-file-download-methods)_, and
+_[near real-time data access](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#near-real-time-data-access-methods)_ services.
 
 # Getting Started
 
@@ -59,7 +59,7 @@ The example below uses the `getLocations` method to search for locations that in
 ```python
 from onc import ONC
 
-onc = ONC("YOUR_TOKEN_HERE")
+onc = ONC("YOUR_TOKEN")
 
 onc.getLocations({"locationName": "Burrard"})
 ```
@@ -74,7 +74,7 @@ onc.getDeviceCategories({"locationCode": "BIIP"})
 onc.getDataProducts({"locationCode": "BIIP", "deviceCategoryCode": "CTD"})
 ```
 
-Check more on the _[discovery methods guide](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#discovery-methods)_
+Check more on the _[discovery methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#discovery-methods)_
 and _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/index.html)_.
 
 ## Downloading data products
@@ -107,7 +107,7 @@ They also include a couple of filters to configure this specific data product ty
 which can be obtained from the [Data Product Options](https://wiki.oceannetworks.ca/display/DP/Data+Product+Options) documentation.
 You can download more than 120 different [types of data products](https://wiki.oceannetworks.ca/display/O2A/Available+Data+Products) including audio & video.
 
-Check more on the _[data product download methods guide](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#data-product-download-methods)_
+Check more on the _[data product download methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#data-product-download-methods)_
 and _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Download_Data_Products.html)_.
 
 ## Obtaining sensor readings in (near) real-time
@@ -125,13 +125,16 @@ params = {
     "dateFrom": "2019-06-20T00:00:00.000Z",
     "dateTo": "2019-06-20T00:00:05.000Z",
 }
-onc.getDirectByLocation(params)
+onc.getScalardata(params)
+
+# Longer method name
+# onc.getScalardataByLocation(params)
 ```
 
 The result includes matching lists of "values" and "sampleTimes" (increases performance for long time ranges).
 We also use the property code "conductivity" to limit results to a specific property available in this CTD.
 
-Check more on the _[near real-time data access methods guide](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#near-real-time-data-access-methods)_
+Check more on the _[near real-time data access methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#near-real-time-data-access-methods)_
 and _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Request_Real_Time_Data.html)_.
 
 ## Downloading archived files
@@ -149,16 +152,19 @@ params = {
     "dateFrom": "2016-12-01T00:00:00.000Z",
     "dateTo": "2016-12-01T00:05:00.000Z",
 }
-result = onc.getListByLocation(params, allPages=True)
+result = onc.getArchivefile(params, allPages=True)
+
+# Longer method name
+# result = onc.getArchivefileByLocation(params, allPages=True)
 
-# download one of the files from result["files"]
-onc.getFile("AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg")
+# Download one of the files from result["files"]
+onc.downloadArchivefile("AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg", overwrite=True)
 ```
 
-You can use the method `getFile()` as above to download individual files or the method `getDirectFiles()`
+You can use the method `downloadArchivefile()` as above to download individual files or the method `downloadDirectArchivefile()`
 to download all the files that match your filters.
 
-Check more on the _[archive file download methods guide](https://oceannetworkscanada.github.io/api-python-client/API_Guide.html#archive-file-download-methods)_
+Check more on the _[archive file download methods guide](https://oceannetworkscanada.github.io/Oceans3.0-API/API_Guide.html#archive-file-download-methods)_
 and _[code examples](https://oceannetworkscanada.github.io/api-python-client/Code_Examples/Download_Archived_Files.html)_.
 
 # Documentation

doc/source/Tutorial/onc_Library_Tutorial.ipynb

@@ -391,7 +391,7 @@
    "source": [
     "### 2.1 Near real-time scalar data download\n",
     "\n",
-    "In this example we want to download one minute of **Pressure** sensor data from a **CTD** at location \"Bullseye\" (locationCode: **NC89**)\n"
+    "In this example we want to download 10 seconds of **Pressure** sensor data from a **CTD** at location \"Bullseye\" (locationCode: **NC89**)\n"
    ]
   },
   {
@@ -417,7 +417,7 @@
     "}\n",
     "\n",
     "# 2. Call methods in the onc library\n",
-    "r = onc.getDirectByLocation(params)\n",
+    "r = onc.getScalardata(params)  # getScalardataByLocation(params) also works\n",
     "\n",
     "# 3. Return the dictionary keys (fields) of the query to get a sense what is contained in your returned message\n",
     "print(r.keys())\n",
@@ -470,7 +470,7 @@
    "source": [
     "### 2.2 Near real-time raw data readings\n",
     "\n",
-    "In this example we want to download one minute of raw data from a **CTD** at location \"Bullseye\" (locationCode: **NC89**)\n"
+    "In this example we want to download 10 seconds of raw data from a **CTD** at location \"Bullseye\" (locationCode: **NC89**)\n"
    ]
   },
   {
@@ -495,7 +495,7 @@
     "}\n",
     "\n",
     "# 2. Call methods in the onc library\n",
-    "r = onc.getDirectRawByLocation(params)\n",
+    "r = onc.getRawdata(params)  # getRawdataByLocation(params) also works\n",
     "\n",
     "# 3. Return the dictionary keys (fields) of the query to get a sense what is contained in your returned message\n",
     "print(r.keys())\n",
@@ -549,7 +549,7 @@
     "\n",
     "1. If you use **onc**.\n",
     "\n",
-    "`getDirectRawByLocation` supports a boolean `allPages` parameter. When set to `True`, it will try to retrieve all the pages.\n",
+    "`getRawdata` supports a boolean `allPages` parameter. When set to `True`, it will try to retrieve all the pages.\n",
     "\n",
     "2. If you use **requests**.\n",
     "\n",
@@ -570,7 +570,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# 1. Define your filter parameter with a longer date range (2 days of data)\n",
+    "# 1. Define your filter parameter with a longer date range (1 day of data)\n",
     "params_longer_range = {\n",
     "    \"locationCode\": \"NC89\",\n",
     "    \"deviceCategoryCode\": \"CTD\",\n",
@@ -579,7 +579,9 @@
     "}\n",
     "\n",
     "# 2. Call methods in the onc library\n",
-    "r = onc.getDirectRawByLocation(params_longer_range, allPages=True)\n",
+    "r = onc.getRawdata(\n",
+    "    params_longer_range, allPages=True\n",
+    ")  # getRawdataByLocation(params_longer_range, allPages=True) also works\n",
     "\n",
     "# 3. Read it into a DataFrame\n",
     "pd.DataFrame(r[\"data\"])"
@@ -704,7 +706,7 @@
     "}\n",
     "\n",
     "# 2. Call methods in the onc library\n",
-    "r = onc.getListByLocation(params)\n",
+    "r = onc.getArchivefile(params)  # getArchivefileByLocation(params) also works\n",
     "\n",
     "# 3. This is the list of archived files:\n",
     "r[\"files\"]"
@@ -754,7 +756,7 @@
     }
    },
    "source": [
-    "Once we have the file names, you can use the method **\"getFile()\"** to download individual files:\n"
+    "Once we have the file names, you can use the method **\"downloadArchivefile()\"** to download individual files:\n"
    ]
   },
   {
@@ -770,8 +772,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# 1. Call methods in the onc library with the filename. The file is downloaded in the output folder.\n",
-    "onc.getFile(\"AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg\", overwrite=True)"
+    "# 1. Call methods in the onc library with the filename. The file is downloaded in the output folder by default,\n",
+    "# which can be customized in the outPath parameter of the ONC class.\n",
+    "onc.downloadArchivefile(\n",
+    "    \"AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg\", overwrite=True\n",
+    ")"
    ]
   },
   {
@@ -985,7 +990,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },

src/onc/modules/_OncArchive.py

@@ -21,16 +21,16 @@ def getArchivefileByLocation(self, filters: dict, allPages: bool):
         """
         Return a list of archived files for a device category in a location.
 
-        The filenames obtained can be used to download files using the getFile() method.
-        """
+        The filenames obtained can be used to download files using the ``downloadArchivefile`` method.
+        """  # noqa: E501
         return self._getList(filters, by="location", allPages=allPages)
 
     def getArchivefileByDevice(self, filters: dict, allPages: bool):
         """
         Return a list of archived files from a specific device.
 
-        The filenames obtained can be used to download files using the getFile() method.
-        """
+        The filenames obtained can be used to download files using the ``downloadArchivefile`` method.
+        """  # noqa: E501
         return self._getList(filters, by="device", allPages=allPages)
 
     def getArchivefile(self, filters: dict, allPages: bool):
@@ -84,8 +84,8 @@ def downloadDirectArchivefile(
         """
         Download a list of archived files that match the filters provided.
 
-        This function invokes the method getListByLocation() or getListByDevice()
-        to obtain a list of files, and the method getFile() to download all files found.
+        This function invokes the method ``getArchivefile`` to obtain a list of files,
+        and the method ``downloadArchivefile`` to download all files found.
 
         See https://wiki.oceannetworks.ca/display/O2A/archivefiles
         for usage and available filters.
@@ -150,7 +150,7 @@ def _getDownloadUrl(self, filename: str):
 
     def _getList(self, filters: dict, by: str = "location", allPages: bool = False):
         """
-        Wraps archivefiles getListByLocation and getListByDevice methods
+        Wraps archivefiles getArchivefileByLocation and getArchivefileByDevice methods
         """
         url = self._serviceUrl("archivefiles")
         filters["token"] = self._config("token")

tests/archive_file/test_archivefile_device.py

@@ -23,31 +23,31 @@ def params_multiple_pages(params):
 def test_invalid_param_value(requester, params):
     params_invalid_param_value = params | {"deviceCode": "XYZ123"}
     with pytest.raises(requests.HTTPError, match=r"API Error 127"):
-        requester.getListByDevice(params_invalid_param_value)
+        requester.getArchivefile(params_invalid_param_value)
 
 
 def test_invalid_params_missing_required(requester, params):
     del params["deviceCode"]
-    with pytest.raises(requests.HTTPError, match=r"API Error 128"):
-        requester.getListByDevice(params)
+    with pytest.raises(ValueError):
+        requester.getArchivefile(params)
 
 
 def test_invalid_param_name(requester, params):
     params_invalid_param_name = params | {"deviceCodes": "BPR-Folger-59"}
     with pytest.raises(requests.HTTPError, match=r"API Error 129"):
-        requester.getListByDevice(params_invalid_param_name)
+        requester.getArchivefile(params_invalid_param_name)
 
 
 def test_no_data(requester, params):
     params_no_data = params | {"dateFrom": "2000-01-01", "dateTo": "2000-01-02"}
-    data = requester.getListByDevice(params_no_data)
+    data = requester.getArchivefile(params_no_data)
 
     assert len(data["files"]) == 0
 
 
 def test_valid_params_one_page(requester, params, params_multiple_pages):
-    data = requester.getListByDevice(params)
-    data_all_pages = requester.getListByDevice(params_multiple_pages, allPages=True)
+    data = requester.getArchivefile(params)
+    data_all_pages = requester.getArchivefile(params_multiple_pages, allPages=True)
 
     assert (
         len(data["files"]) > params_multiple_pages["rowLimit"]
@@ -63,7 +63,7 @@ def test_valid_params_one_page(requester, params, params_multiple_pages):
 
 
 def test_valid_params_multiple_pages(requester, params_multiple_pages):
-    data = requester.getListByDevice(params_multiple_pages)
+    data = requester.getArchivefile(params_multiple_pages)
 
     assert (
         len(data["files"]) == params_multiple_pages["rowLimit"]

tests/archive_file/test_archivefile_direct_download.py

@@ -1,14 +1,14 @@
 def test_valid_params_one_page(requester, params_location, util):
-    data = requester.getListByLocation(params_location)
-    result = requester.getDirectFiles(params_location)
+    data = requester.getArchivefile(params_location)
+    result = requester.downloadDirectArchivefile(params_location)
 
     assert util.get_download_files_num(requester) == len(data["files"])
 
     assert result["stats"]["fileCount"] == len(data["files"])
 
 
 def test_valid_params_multiple_pages(requester, params_location_multiple_pages, util):
-    result = requester.getDirectFiles(params_location_multiple_pages)
+    result = requester.downloadDirectArchivefile(params_location_multiple_pages)
 
     assert (
         util.get_download_files_num(requester)

tests/archive_file/test_archivefile_download.py

@@ -4,24 +4,24 @@
 
 def test_invalid_param_value(requester):
     with pytest.raises(requests.HTTPError, match=r"API Error 96"):
-        requester.getFile("FAKEFILE.XYZ")
+        requester.downloadArchivefile("FAKEFILE.XYZ")
 
 
 def test_invalid_params_missing_required(requester):
     with pytest.raises(requests.HTTPError, match=r"API Error 128"):
-        requester.getFile()
+        requester.downloadArchivefile()
 
 
 def test_valid_params(requester, util):
     filename = "BPR-Folger-59_20191123T000000.000Z.txt"
 
-    requester.getFile(filename)
+    requester.downloadArchivefile(filename)
 
     assert (requester.outPath / filename).exists()
 
     with pytest.raises(FileExistsError):
-        requester.getFile(filename)
+        requester.downloadArchivefile(filename)
 
-    requester.getFile(filename, overwrite=True)
+    requester.downloadArchivefile(filename, overwrite=True)
 
     assert util.get_download_files_num(requester) == 1

tests/archive_file/test_archivefile_location.py

@@ -5,19 +5,19 @@
 def test_invalid_param_value(requester, params_location):
     params_invalid_param_value = params_location | {"locationCode": "XYZ123"}
     with pytest.raises(requests.HTTPError, match=r"API Error 127"):
-        requester.getListByLocation(params_invalid_param_value)
+        requester.getArchivefile(params_invalid_param_value)
 
 
 def test_invalid_params_missing_required(requester, params_location):
     del params_location["locationCode"]
-    with pytest.raises(requests.HTTPError, match=r"API Error 128"):
-        requester.getListByLocation(params_location)
+    with pytest.raises(ValueError):
+        requester.getArchivefile(params_location)
 
 
 def test_invalid_param_name(requester, params_location):
     params_invalid_param_name = params_location | {"locationCodes": "NCBC"}
     with pytest.raises(requests.HTTPError, match=r"API Error 129"):
-        requester.getListByLocation(params_invalid_param_name)
+        requester.getArchivefile(params_invalid_param_name)
 
 
 def test_no_data(requester, params_location):
@@ -26,14 +26,14 @@ def test_no_data(requester, params_location):
         "dateTo": "2000-01-02",
     }
     with pytest.raises(requests.HTTPError, match=r"API Error 127"):
-        requester.getListByLocation(params_no_data)
+        requester.getArchivefile(params_no_data)
 
 
 def test_valid_params_one_page(
     requester, params_location, params_location_multiple_pages
 ):
-    data = requester.getListByLocation(params_location)
-    data_all_pages = requester.getListByLocation(
+    data = requester.getArchivefile(params_location)
+    data_all_pages = requester.getArchivefile(
         params_location_multiple_pages, allPages=True
     )
 
@@ -51,7 +51,7 @@ def test_valid_params_one_page(
 
 
 def test_valid_params_multiple_pages(requester, params_location_multiple_pages):
-    data = requester.getListByLocation(params_location_multiple_pages)
+    data = requester.getArchivefile(params_location_multiple_pages)
 
     assert (
         len(data["files"]) == params_location_multiple_pages["rowLimit"]