remove code from samples module, etc.

Author: ehinman

dataretrieval/samples.py

@@ -11,99 +11,18 @@
 from typing import TYPE_CHECKING, Literal, get_args
 
 import pandas as pd
+import warnings
 import requests
 from requests.models import PreparedRequest
 
 from dataretrieval.utils import BaseMetadata, to_str
+from dataretrieval.waterdata import get_codes, get_args, _check_profiles, _BASE_URL, _CODE_SERVICES, _PROFILES, _SERVICES, _PROFILE_LOOKUP
 
 if TYPE_CHECKING:
     from typing import Optional, Tuple, Union
 
     from pandas import DataFrame
 
-
-_BASE_URL = "https://api.waterdata.usgs.gov/samples-data"
-
-_CODE_SERVICES = Literal[
-    "characteristicgroup",
-    "characteristics",
-    "counties",
-    "countries",
-    "observedproperty",
-    "samplemedia",
-    "sitetype",
-    "states",
-]
-
-
-_SERVICES = Literal["activities", "locations", "organizations", "projects", "results"]
-
-_PROFILES = Literal[
-    "actgroup",
-    "actmetric",
-    "basicbio",
-    "basicphyschem",
-    "count",
-    "fullbio",
-    "fullphyschem",
-    "labsampleprep",
-    "narrow",
-    "organization",
-    "project",
-    "projectmonitoringlocationweight",
-    "resultdetectionquantitationlimit",
-    "sampact",
-    "site",
-]
-
-_PROFILE_LOOKUP = {
-    "activities": ["sampact", "actmetric", "actgroup", "count"],
-    "locations": ["site", "count"],
-    "organizations": ["organization", "count"],
-    "projects": ["project", "projectmonitoringlocationweight"],
-    "results": [
-        "fullphyschem",
-        "basicphyschem",
-        "fullbio",
-        "basicbio",
-        "narrow",
-        "resultdetectionquantitationlimit",
-        "labsampleprep",
-        "count",
-    ],
-}
-
- 
-def get_codes(code_service: _CODE_SERVICES) -> DataFrame:
-    """Return codes from a Samples code service.
-    
-    Parameters
-    ----------
-    code_service : string
-        One of the following options: "states", "counties", "countries"
-        "sitetype", "samplemedia", "characteristicgroup", "characteristics",
-        or "observedproperty"
-    """
-    valid_code_services = get_args(_CODE_SERVICES)
-    if code_service not in valid_code_services:
-        raise ValueError(
-            f"Invalid code service: '{code_service}'. "
-            f"Valid options are: {valid_code_services}."
-        )
-
-    url = f"{_BASE_URL}/codeservice/{code_service}?mimeType=application%2Fjson"
-    
-    response = requests.get(url)
-    
-    response.raise_for_status()
-
-    data_dict = json.loads(response.text)
-    data_list = data_dict['data']
-
-    df = pd.DataFrame(data_list)
-
-    return df
-
 def get_usgs_samples(
     ssl_check: bool = True,
     service: _SERVICES = "results",
@@ -272,26 +191,33 @@ def get_usgs_samples(
     .. code::
 
         >>> # Get PFAS results within a bounding box
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.samples.get_usgs_samples(
         ...     boundingBox=[-90.2,42.6,-88.7,43.2],
         ...     characteristicGroup="Organics, PFAS"
         ... )
 
         >>> # Get all activities for the Commonwealth of Virginia over a date range
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.samples.get_usgs_samples(
         ...     service="activities",
         ...     profile="sampact",
         ...     activityStartDateLower="2023-10-01",
         ...     activityStartDateUpper="2024-01-01",
         ...     stateFips="US:51")
 
         >>> # Get all pH samples for two sites in Utah
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.samples.get_usgs_samples(
         ...     monitoringLocationIdentifier=['USGS-393147111462301', 'USGS-393343111454101'],
         ...     usgsPCode='00400')
 
     """
 
+    warnings.warn("The `get_usgs_samples` function is moving from" \
+    " the samples module to the new waterdata module, where" \
+    " it will be called simply `get_samples`. All of the same" \
+    " functionality will be retained. The samples module is" \
+    " deprecated and will eventually be removed. Switch to the" \
+    " waterdata module as soon as possible, thank you.")
+
     _check_profiles(service, profile)
 
     params = {
@@ -320,32 +246,4 @@ def get_usgs_samples(
 
     return df, BaseMetadata(response)
 
-def _check_profiles(
-        service: _SERVICES,
-        profile: _PROFILES,
-) -> None:
-    """Check whether a service profile is valid.
-
-    Parameters
-    ----------
-    service : string
-        One of the service names from the "services" list.
-    profile : string
-        One of the profile names from "results_profiles",
-        "locations_profiles", "activities_profiles",
-        "projects_profiles" or "organizations_profiles". 
-    """
-    valid_services = get_args(_SERVICES)
-    if service not in valid_services:
-        raise ValueError(
-            f"Invalid service: '{service}'. "
-            f"Valid options are: {valid_services}."
-        )
-
-    valid_profiles = _PROFILE_LOOKUP[service]
-    if profile not in valid_profiles:
-        raise ValueError(
-            f"Invalid profile: '{profile}' for service '{service}'. "
-            f"Valid options are: {valid_profiles}."
-        )
 

dataretrieval/waterdata.py

@@ -271,21 +271,21 @@ def get_samples(
     .. code::
 
         >>> # Get PFAS results within a bounding box
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.waterdata.get_samples(
         ...     boundingBox=[-90.2,42.6,-88.7,43.2],
         ...     characteristicGroup="Organics, PFAS"
         ... )
 
         >>> # Get all activities for the Commonwealth of Virginia over a date range
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.waterdata.get_samples(
         ...     service="activities",
         ...     profile="sampact",
         ...     activityStartDateLower="2023-10-01",
         ...     activityStartDateUpper="2024-01-01",
         ...     stateFips="US:51")
 
         >>> # Get all pH samples for two sites in Utah
-        >>> df, md = dataretrieval.samples.get_samples(
+        >>> df, md = dataretrieval.waterdata.get_samples(
         ...     monitoringLocationIdentifier=['USGS-393147111462301', 'USGS-393343111454101'],
         ...     usgsPCode='00400')
 

demos/hydroshare/USGS_dataretrieval_WaterSamples_Examples.ipynb

@@ -389,7 +389,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "dr-test",
+   "display_name": "hyswap-dev-environment",
    "language": "python",
    "name": "python3"
   },
@@ -403,7 +403,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.12"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,