d2spy 0.2.1__tar.gz

d2spy-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Geospatial Data Science Lab
+
+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.

d2spy-0.2.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.1
+Name: d2spy
+Version: 0.2.1
+Summary: Python package for interacting with a Data to Science instance.
+License: MIT
+Keywords: python,data to science,uas
+Author: Ben Hancock
+Author-email: hancocb@purdue.edu
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: exifread (>=3.0.0,<4.0.0)
+Requires-Dist: geojson-pydantic (>=1.1.1,<2.0.0)
+Requires-Dist: geopandas (>=1.0.1,<2.0.0)
+Requires-Dist: rasterio (>=1.3.11,<2.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Welcome to Data to Science Python (d2spy)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<p align="center">
+  <img
+    src="https://py.d2s.org/assets/d2s-logo.png"
+    alt="Data to Science logo"
+    width="128"
+  >
+</p>
+
+D2spy is a Python package for interacting with Data to Science instances.
+
+## Features
+
+- Sign in to your Data to Science instance
+- Access your projects, flights, and data products
+- Create new projects and flights
+- Upload data products to flights
+
+## Documentation
+
+- [Homepage](https://py.d2s.org/)
+- [Guides](https://py.d2s.org/guides)
+- [API Reference](https://py.d2s.org/api_client/)
+

d2spy-0.2.1/README.md

@@ -0,0 +1,26 @@
+# Welcome to Data to Science Python (d2spy)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<p align="center">
+  <img
+    src="https://py.d2s.org/assets/d2s-logo.png"
+    alt="Data to Science logo"
+    width="128"
+  >
+</p>
+
+D2spy is a Python package for interacting with Data to Science instances.
+
+## Features
+
+- Sign in to your Data to Science instance
+- Access your projects, flights, and data products
+- Create new projects and flights
+- Upload data products to flights
+
+## Documentation
+
+- [Homepage](https://py.d2s.org/)
+- [Guides](https://py.d2s.org/guides)
+- [API Reference](https://py.d2s.org/api_client/)

d2spy-0.2.1/d2spy/api_client.py

@@ -0,0 +1,89 @@
+from typing import Any, Dict, List, Union
+
+from requests import Session
+
+from d2spy.extras.utils import pretty_print_response
+
+
+class APIClient:
+    """Makes API requests to D2S API."""
+
+    def __init__(self, base_url: str, session: Session):
+        """Constructor for APIClient class.
+
+        Args:
+            base_url (str): Base URL for D2S instance.
+            session (Session): Session set by Auth.
+
+        Raises:
+            ValueError: Raised if access token missing from session.
+        """
+        self.base_url = base_url
+        self.session = session
+
+        # Check if access token in session cookies
+        if not self.session.cookies.get("access_token"):
+            raise ValueError("Session missing access token. Must sign in first.")
+
+    def make_get_request(
+        self, endpoint: str, **kwargs
+    ) -> Union[Dict[Any, Any], List[Dict[Any, Any]]]:
+        """Makes GET request to D2S API.
+
+        Args:
+            endpoint (str): D2S endpoint for request.
+
+        Returns:
+            Union[Dict, List]: JSON response from request.
+        """
+        url = self.base_url + endpoint
+        response = self.session.get(url, **kwargs)
+
+        if response.status_code != 200:
+            pretty_print_response(response)
+            response.raise_for_status()
+
+        return response.json()
+
+    def make_post_request(self, endpoint: str, **kwargs) -> Dict[Any, Any]:
+        """Make POST request to D2S API.
+
+        Args:
+            endpoint (str): D2S endpoint for request.
+
+        Returns:
+            Dict: JSON response from request.
+        """
+        url = self.base_url + endpoint
+        response = self.session.post(url, **kwargs)
+
+        if (
+            response.status_code != 200
+            and response.status_code != 201
+            and response.status_code != 202
+        ):
+            pretty_print_response(response)
+            response.raise_for_status()
+
+        if response.status_code == 202:
+            return {"status": "accepted"}
+
+        return response.json()
+
+    def make_put_request(self, endpoint: str, **kwargs) -> Dict[Any, Any]:
+        """Make PUT request to D2S API.
+
+        Args:
+            endpoint (str): D2S endpoint for request.
+
+        Returns:
+            Dict: JSON response from request.
+        """
+        url = self.base_url + endpoint
+        response = self.session.put(url, **kwargs)
+
+        if response.status_code != 200:
+            pretty_print_response(response)
+            response.raise_for_status()
+
+        return response.json()

d2spy-0.2.1/d2spy/auth.py

@@ -0,0 +1,127 @@
+import getpass
+import os
+import requests
+from typing import Optional
+
+from d2spy.extras.utils import pretty_print_response
+from d2spy.models.user import User
+from d2spy.schemas.session import D2SpySession
+
+
+class Auth:
+    """Authenticates with D2S."""
+
+    def __init__(self, base_url: str) -> None:
+        """Constructor for Auth class.
+
+        Args:
+            base_url (str): Base URL for D2S instance.
+
+        Raises:
+            ValueError: Raised if unable to communicate with host.
+        """
+        self.base_url: str = base_url
+
+        if is_valid_base_url(self.base_url) is False:
+            raise ValueError("unable to connect to provided host")
+
+        self.session: D2SpySession = D2SpySession()
+
+    def login(
+        self, email: Optional[str] = None, password: Optional[str] = None
+    ) -> Optional[D2SpySession]:
+        """Login to D2S platform with email and password. Alternatively, use
+        environment variables `D2S_EMAIL` and `D2S_PASSWORD` to set email and password.
+        If the password is not passed as an argument and `D2S_PASSWORD` is not set,
+        `getpass` will be used to prompt user for password.
+
+        Args:
+            email Optional[str]: Email address used to sign in to D2S.
+            password Optional[str]: Password used to sign in to D2S.
+
+        Returns:
+            Optional[D2SpySession]: Session with user access cookie.
+        """
+        # Check for email environment variable if not provided as argument
+        if not email:
+            email = os.environ.get("D2S_EMAIL")
+            if not email:
+                raise ValueError(
+                    "Must provide 'email' to login method as argument or set email "
+                    "as environment variable 'D2S_EMAIL'"
+                )
+        # Check for password environment variable if not provided as argument
+        if not password:
+            password = os.environ.get("D2S_PASSWORD")
+            # Request password from user if not set as environment variable
+            if not password:
+                password = getpass.getpass(prompt="Enter your D2S password:")
+        # Credentials that will be sent to D2S auth API
+        credentials = {"username": email, "password": password}
+        # URL for D2S access-token endpoint
+        url = f"{self.base_url}/api/v1/auth/access-token"
+        # Post credentials to access-token endpoint
+        response = requests.post(url, data=credentials)
+        # JWT access token returned for successful request
+        if response.status_code == 200 and "access_token" in response.cookies:
+            # Add JWT access token to session cookies
+            self.session.cookies.set("access_token", response.cookies["access_token"])
+            # Fetch user object associated with access token
+            user = self.get_current_user()
+            # Return dictionary of user attributes and values
+            if user:
+                # Check if user has api key and set it to session header if so
+                if hasattr(user, "api_access_token") and user.api_access_token:
+                    self.session.d2s_data = {"API_KEY": user.api_access_token}
+                return self.session
+            else:
+                return None
+        else:
+            # Print response if request fails
+            pretty_print_response(response)
+            return None
+
+    def logout(self) -> None:
+        """Logout of D2S platform."""
+        # Delete access-token cookie from session and end session
+        self.session.cookies.clear(domain="", path="/", name="access_token")
+        self.session.close()
+        print("session ended")
+
+    def get_current_user(self) -> Optional[User]:
+        """Get user object for logged in user.
+
+        Returns:
+            Optional[User]: User object or None.
+        """
+        # D2S endpoint for fetching user object for signed in user
+        url = f"{self.base_url}/api/v1/users/current"
+        # Request user object from D2S instance
+        response = self.session.get(url)
+        # Return user object if request successful
+        if response.status_code == 200:
+            return User.from_dict(response.json())
+        else:
+            # Print response if request fails
+            pretty_print_response(response)
+            return None
+
+
+def is_valid_base_url(base_url: str) -> bool:
+    """Return true if base_url returns HTTP 200 else false.
+
+    Args:
+        base_url (str): Base URL for D2S instance.
+
+    Returns:
+        bool: Returns True if D2S instance returns status OK, otherwise False
+    """
+    response: Optional[requests.Response] = None
+    try:
+        response = requests.get(f"{base_url}/api/v1/health")
+    except requests.exceptions.ConnectionError:
+        response = None
+    finally:
+        if response and response.status_code == 200:
+            return True
+    return False

d2spy-0.2.1/d2spy/extras/third_party/tusclient/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.3"

d2spy-0.2.1/d2spy/extras/third_party/tusclient/client.py

@@ -0,0 +1,77 @@
+from typing import Dict, Optional
+
+from d2spy.extras.third_party.tusclient.uploader import Uploader
+
+
+class TusClient:
+    """
+    Object representation of Tus client.
+
+    :Attributes:
+        - url (str):
+            represents the tus server's create extension url. On instantiation this argument
+            must be passed to the constructor.
+        - headers (dict):
+            This can be used to set the server specific headers. These headers would be sent
+            along with every request made by the client to the server. This may be used to set
+            authentication headers. These headers should not include headers required by tus
+            protocol. If not set this defaults to an empty dictionary.
+        - cookies (dict):
+            This can be used to set the server specific cookies. These cookies would be sent
+            along with every request made by the client to the server. This may be used to set
+            authorization cookies.
+
+    :Constructor Args:
+        - url (str)
+        - headers (Optional[dict])
+        - cookies (Optional[dict])
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        cookies: Optional[Dict[str, str]] = None,
+    ):
+        self.url = url
+        self.headers = headers or {}
+        self.cookies = cookies or {}
+
+    def set_headers(self, headers: Dict[str, str]):
+        """
+        Set tus client headers.
+
+        Update and/or set new headers that would be sent along with every request made
+        to the server.
+
+        :Args:
+            - headers (dict):
+                key, value pairs of the headers to be set. This argument is required.
+        """
+        self.headers.update(headers)
+
+    def set_cookies(self, cookies: Dict[str, str]):
+        """
+        Set tus client cookies.
+
+        Update and/or set new cookies that would be sent along with every request made
+        to the server.
+
+        :Args:
+            - cookies (dict):
+                key, value pairs of the cookies to be set. This argument is required.
+        """
+        self.cookies.update(cookies)
+
+    def uploader(self, *args, **kwargs) -> Uploader:
+        """
+        Return uploader instance pointing at current client instance.
+
+        Return uploader instance with which you can control the upload of a specific
+        file. The current instance of the tus client is passed to the uploader on creation.
+
+        :Args:
+            see tusclient.uploader.Uploader for required and optional arguments.
+        """
+        kwargs["client"] = self
+        return Uploader(*args, **kwargs)

d2spy-0.2.1/d2spy/extras/third_party/tusclient/exceptions.py

@@ -0,0 +1,35 @@
+"""
+Global Tusclient exception and warning classes.
+"""
+
+
+class TusCommunicationError(Exception):
+    """
+    Should be raised when communications with tus-server behaves
+    unexpectedly.
+
+    :Attributes:
+        - message (str):
+            Main message of the exception
+        - status_code (int):
+            Status code of response indicating an error
+        - response_content (str):
+            Content of response indicating an error
+    :Constructor Args:
+        - message (Optional[str])
+        - status_code (Optional[int])
+        - response_content (Optional[str])
+    """
+
+    def __init__(self, message, status_code=None, response_content=None):
+        default_message = "Communication with tus server failed with status {}".format(
+            status_code
+        )
+        message = message or default_message
+        super(TusCommunicationError, self).__init__(message)
+        self.status_code = status_code
+        self.response_content = response_content
+
+
+class TusUploadFailed(TusCommunicationError):
+    """Should be raised when an attempted upload fails"""

d2spy-0.2.1/d2spy/extras/third_party/tusclient/request.py

@@ -0,0 +1,96 @@
+from typing import Optional
+import base64
+from functools import wraps
+
+import requests
+
+from d2spy.extras.third_party.tusclient.exceptions import (
+    TusUploadFailed,
+    TusCommunicationError,
+)
+
+
+# Catches requests exceptions and throws custom tuspy errors.
+def catch_requests_error(func):
+    """Deocrator to catch requests exceptions"""
+
+    @wraps(func)
+    def _wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except requests.exceptions.RequestException as error:
+            raise TusCommunicationError(error)
+
+    return _wrapper
+
+
+class BaseTusRequest:
+    """
+    Http Request Abstraction.
+
+    Sets up tus custom http request on instantiation.
+
+    requires argument 'uploader' an instance of tusclient.uploader.Uploader
+    on instantiation.
+
+    :Attributes:
+        - response_headers (dict)
+        - file (file):
+            The file that is being uploaded.
+    """
+
+    def __init__(self, uploader):
+        self._url = uploader.url
+        self.response_headers = {}
+        self.status_code = None
+        self.response_content = None
+        self.verify_tls_cert = bool(uploader.verify_tls_cert)
+        self.file = uploader.get_file_stream()
+        self.file.seek(uploader.offset)
+
+        self._request_headers = {
+            "upload-offset": str(uploader.offset),
+            "Content-Type": "application/offset+octet-stream",
+        }
+        self._request_cookies = {}
+        self._request_headers.update(uploader.get_headers())
+        self._request_cookies.update(uploader.get_cookies())
+        self._content_length = uploader.get_request_length()
+        self._upload_checksum = uploader.upload_checksum
+        self._checksum_algorithm = uploader.checksum_algorithm
+        self._checksum_algorithm_name = uploader.checksum_algorithm_name
+
+    def add_checksum(self, chunk: bytes):
+        if self._upload_checksum:
+            self._request_headers["upload-checksum"] = " ".join(
+                (
+                    self._checksum_algorithm_name,
+                    base64.b64encode(self._checksum_algorithm(chunk).digest()).decode(
+                        "ascii"
+                    ),
+                )
+            )
+
+
+class TusRequest(BaseTusRequest):
+    """Class to handle async Tus upload requests"""
+
+    def perform(self):
+        """
+        Perform actual request.
+        """
+        try:
+            chunk = self.file.read(self._content_length)
+            self.add_checksum(chunk)
+            resp = requests.patch(
+                self._url,
+                data=chunk,
+                headers=self._request_headers,
+                cookies=self._request_cookies,
+                verify=self.verify_tls_cert,
+            )
+            self.status_code = resp.status_code
+            self.response_content = resp.content
+            self.response_headers = {k.lower(): v for k, v in resp.headers.items()}
+        except requests.exceptions.RequestException as error:
+            raise TusUploadFailed(error)

d2spy-0.2.1/d2spy/extras/third_party/tusclient/uploader/__init__.py

@@ -0,0 +1 @@
+from d2spy.extras.third_party.tusclient.uploader.uploader import Uploader