hakai_api 1.5.2__py3-none-any.whl

hakai_api/Client.py

@@ -0,0 +1,168 @@
+"""Get authorized requests to the Hakai API using the requests library.
+
+Written by: Taylor Denouden, Chris Davis, and Nate Rosenstock
+Last updated: April 2021
+"""
+
+import json
+import os
+from datetime import datetime
+from time import mktime
+from typing import Dict, Union
+
+from requests_oauthlib import OAuth2Session
+
+
+class Client(OAuth2Session):
+    _credentials_file = os.path.expanduser("~/.hakai-api-auth")
+    DEFAULT_API_ROOT = "https://hecate.hakai.org/api"
+    DEFAULT_LOGIN_PAGE = "https://hecate.hakai.org/api-client-login"
+    CREDENTIALS_ENV_VAR = "HAKAI_API_CREDENTIALS"
+    USER_AGENT_ENV_VAR = "HAKAI_API_USER_AGENT"
+
+    def __init__(
+        self,
+        api_root: str = DEFAULT_API_ROOT,
+        login_page: str = DEFAULT_LOGIN_PAGE,
+        credentials: Union[str, Dict] = None,
+    ):
+        """Create a new Client class with credentials.
+
+        Params:
+            api_root: The base url of the hakai api you want to call.
+                Defaults to the production server.
+            login_page: The url of the login page to direct users to.
+                Defaults to the production login page.
+            credentials (str, Dict): Credentials token retrieved from the hakai api
+                login page. If `None`, loads cached credentials or prompts for log in.
+        """
+        self._api_root = api_root
+        self._login_page = login_page
+        self._credentials = None
+
+        env_credentials = os.getenv(self.CREDENTIALS_ENV_VAR, None)
+        if isinstance(credentials, dict):
+            self._credentials = credentials
+        elif isinstance(credentials, str):
+            # Parse credentials from string
+            self._credentials = self._parse_credentials_string(credentials)
+        elif env_credentials is not None:
+            self._credentials = self._parse_credentials_string(env_credentials)
+        elif self.file_credentials_are_valid():
+            self._credentials = self._get_credentials_from_file()
+        else:
+            self._credentials = self._get_credentials_from_web()
+
+        if self._credentials is None:
+            raise ValueError("Credentials could not be set.")
+
+        # Cache the credentials
+        self._save_credentials_to_file(self._credentials)
+
+        # Init the OAuth2Session parent class with credentials
+        super(Client, self).__init__(token=self._credentials)
+        
+        # Set User-Agent header
+        user_agent = os.getenv(self.USER_AGENT_ENV_VAR, "hakai-api-client-py")
+        self.headers.update({"User-Agent": user_agent})
+
+    @property
+    def api_root(self) -> str:
+        """Return the api base url."""
+        return self._api_root
+
+    @property
+    def login_page(self) -> str:
+        """Return the login page url."""
+        return self._login_page
+
+    @property
+    def credentials(self) -> Dict:
+        """Return the credentials object."""
+        if self._credentials is None:
+            raise ValueError("Credentials have not been set.")
+        return self._credentials
+
+    @classmethod
+    def reset_credentials(cls):
+        """Remove the cached credentials file."""
+        if os.path.isfile(cls._credentials_file):
+            os.remove(cls._credentials_file)
+
+    def _save_credentials_to_file(self, credentials: Dict):
+        """Save the credentials object to a file."""
+        with open(self._credentials_file, "w") as outfile:
+            json.dump(credentials, outfile)
+
+    @classmethod
+    def file_credentials_are_valid(cls) -> bool:
+        """Check if the cached credentials exist and are valid."""
+        if not os.path.isfile(cls._credentials_file):
+            return False
+        with open(cls._credentials_file, "r"):
+            try:
+                credentials = cls._get_credentials_from_file()
+                expires_at = credentials["expires_at"]
+            except (KeyError, ValueError):
+                os.remove(cls._credentials_file)
+                return False
+
+            now = int(
+                (
+                    mktime(datetime.now().timetuple())
+                    + datetime.now().microsecond / 1000000.0
+                )
+            )  # utc timestamp
+
+        if now > expires_at:
+            cls.reset_credentials()
+            return False
+
+        return True
+
+    @classmethod
+    def _get_credentials_from_file(cls) -> Dict:
+        """Get user credentials from a cached file."""
+        with open(cls._credentials_file, "r") as infile:
+            result = json.load(infile)
+        result = Client._check_keys_convert_types(result)
+        return result
+
+    def _get_credentials_from_web(self) -> Dict:
+        """Get user credentials from a web sign-in."""
+        print("Please go here and authorize:")
+        print(self.login_page, flush=True)
+        response = input("\nCopy and past your credentials from the login page:\n")
+
+        # Reformat response to dict
+        credentials = dict(map(lambda x: x.split("="), response.split("&")))
+        return credentials
+
+    @staticmethod
+    def _parse_credentials_string(credentials: str) -> Dict:
+        """Parse a credentials string into a dictionary."""
+        result = dict(map(lambda x: x.split("="), credentials.split("&")))
+        result = Client._check_keys_convert_types(result)
+        return result
+
+    @staticmethod
+    def _check_keys_convert_types(credentials: dict) -> dict:
+        """Check that the credentials dict has the required keys and convert types."""
+        missing_keys = [
+            key
+            for key in ["access_token", "token_type", "expires_at"]
+            if key not in credentials
+        ]
+        if len(missing_keys) > 0:
+            raise ValueError(
+                f"Credentials string is missing required keys: {str(missing_keys)}."
+            )
+
+        # Convert expires_at to int
+        credentials["expires_at"] = int(float(credentials["expires_at"]))
+
+        # If expires_in is present, convert to int
+        if "expires_in" in credentials:
+            credentials["expires_in"] = int(float(credentials["expires_in"]))
+
+        return credentials

hakai_api/__init__.py

@@ -0,0 +1,3 @@
+from hakai_api.Client import Client
+
+__all__ = [Client]

hakai_api-1.5.2.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: hakai_api
+Version: 1.5.2
+Summary: Get Hakai database resources using http calls
+Author-email: Taylor Denouden <taylor.denouden@hakai.org>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: pytz>=2025.2
+Requires-Dist: requests-oauthlib>=2.0.0
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# Hakai Api Python Client
+
+This project exports a single Python class that can be used to make HTTP requests to the
+Hakai API resource server.
+The exported `Client` class extends the functionality of the
+Python [requests library](https://docs.python-requests.org/en/master/) to supply Hakai
+OAuth2 credentials with url requests.
+
+![PyPI](https://img.shields.io/pypi/v/hakai-api)   [![tests](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml/badge.svg)](https://github.com/HakaiInstitute/hakai-api-client-py/actions/workflows/test.yaml)  [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](https://opensource.org/licenses/MIT)
+
+<details>
+
+<summary>Table of Contents</summary>
+
+[Installation](#installation)
+
+[Quickstart](#quickstart)
+
+[Methods](#methods)
+
+[API endpoints](#api-endpoints)
+
+[Advanced usage](#advanced-usage)
+
+[Contributing](#contributing)
+
+</details>
+
+# Installation
+
+Python 3.8 or higher is required. Install with pip:
+
+```bash
+pip install hakai-api
+```
+
+# Quickstart
+
+```python
+from hakai_api import Client
+
+# Get the api request client
+client = Client()  # Follow stdout prompts to get an API token
+
+# Make a data request for chlorophyll data
+url = '%s/%s' % (client.api_root, 'eims/views/output/chlorophyll?limit=50')
+response = client.get(url)
+
+print(url)  # https://hecate.hakai.org/api/eims/views/output/chlorophyll...
+print(response.json())
+# [{'action': '', 'event_pk': 7064, 'rn': '1', 'date': '2012-05-17', 'work_area': 'CALVERT'...
+```
+
+# Methods
+
+This library exports a single client name `Client`. Instantiating this class produces
+a `requests.Session` client from the Python requests library. The Hakai API Python
+Client inherits directly from `requests.Session` thus all methods available on that
+parent class are available. For details see
+the [requests documentation](http://docs.python-requests.org/).
+
+The hakai_api `Client` class also contains a property `api_root` which is useful for
+constructing urls to access data from the API. The
+above [Quickstart example](#quickstart) demonstrates using this property to construct a
+url to access project names.
+
+# API endpoints
+
+For details about the API, including available endpoints where data can be requested
+from, see the [Hakai API documentation](https://github.com/HakaiInstitute/hakai-api).
+
+# Advanced usage
+
+You can specify which API to access when instantiating the Client. By default, the API
+uses `https://hecate.hakai.org/api` as the API root. It may be useful to use this
+library to access a locally running API instance or to access the Goose API for testing
+purposes. If you are always going to be accessing data from a locally running API
+instance, you are better off using the requests.py library directly since Authorization
+is not required for local requests.
+
+```python
+from hakai_api import Client
+
+# Get a client for a locally running API instance
+client = Client("http://localhost:8666")
+print(client.api_root)  # http://localhost:8666
+```
+
+You can also pass in the credentials string retrieved from the hakai API login page
+while initiating the Client class.
+
+```python
+from hakai_api import Client
+
+# Pass a credentials token as the Client Class is initiated
+client = Client(credentials="CREDENTIAL_TOKEN")
+```
+
+Finally, you can set credentials for the client class using the `HAKAI_API_CREDENTIALS`
+environment variable. This is useful for e.g. setting credentials in a docker container.
+The value of the environment variable should be the credentials token retrieved from the
+Hakai API login page.
+
+# Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md)
+
+# License
+
+See [LICENSE](LICENSE.md)

hakai_api-1.5.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+hakai_api/Client.py,sha256=L4K-Hhb-IGZJ3wydi7hMEdENM_h7duPaL4RtsACCQvw,6062
+hakai_api/__init__.py,sha256=6jSdZtw1AZRFEsPxiYB7jpQ1B_xlBCho6IPZdGarOxA,56
+hakai_api-1.5.2.dist-info/METADATA,sha256=e219ERceF9DFeR_eWzxmCB9vudXSGviKAXIr8PCJFA4,4023
+hakai_api-1.5.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hakai_api-1.5.2.dist-info/licenses/LICENSE,sha256=Ag7Q1MVBG7kruFExfcgV9OajxdpvGDbo0n4lft2yMWs,1072
+hakai_api-1.5.2.dist-info/RECORD,,

hakai_api-1.5.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hakai_api-1.5.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Hakai Institute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.