d2spy 0.0.1__py3-none-any.whl

d2spy/api_client.py

@@ -0,0 +1,64 @@
+import requests
+
+
+class APIClient:
+    """Makes API requests to D2S API."""
+
+    def __init__(self, base_url: str, session: requests.Session):
+        """Constructor for APIClient class.
+
+        Args:
+            base_url (str): Base URL for D2S instance.
+            session (requests.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) -> requests.Response:
+        """Makes GET request to D2S API.
+
+        Args:
+            endpoint (str): D2S endpoint for request.
+
+        Returns:
+            requests.Response: Response from D2S API to request.
+        """
+        url = self.base_url + endpoint
+        response = self.session.get(url)
+
+        return response
+
+    def make_post_request(self, endpoint: str, **kwargs) -> requests.Response:
+        """Make POST request to D2S API.
+
+        Args:
+            endpoint (str): D2S endpoint for request.
+
+        Returns:
+            requests.Response: Response from D2S API to request.
+        """
+        url = self.base_url + endpoint
+        response = self.session.post(url, **kwargs)
+
+        return response
+
+    def make_put_request(self, endpoint: str, **kwargs) -> requests.Response:
+        """Make PUT request to D2S API.
+
+        Args:
+            endpoint (str): _description_
+
+        Returns:
+            requests.Response: _description_
+        """
+        url = self.base_url + endpoint
+        response = self.session.put(url, **kwargs)
+
+        return response

d2spy/auth.py

@@ -0,0 +1,108 @@
+import getpass
+import json
+import requests
+from typing import Dict, Union
+from urllib.parse import urlparse
+
+from .extras.utils import pretty_print_response
+from .models.user import User
+
+
+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 test_base_url(self.base_url) is False:
+            raise ValueError("unable to connect to provided host")
+
+        self.session: requests.Session = requests.session()
+
+    def login(self, email: str) -> Union[User, None]:
+        """Login to D2S platform with email and password.
+
+        Args:
+            email (str): Email address used to sign in to D2S.
+
+        Returns:
+            Union[User, None]: User object or None.
+        """
+        # Request password from user
+        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.get("access_token")
+            )
+            # Fetch user object associated with access token
+            user = self.get_current_user()
+            # Return dictionary of user attributes and values
+            if user:
+                return User.from_dict(user)
+            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) -> Union[User, None]:
+        """Get user object for logged in user.
+
+        Returns:
+            Union[User, None]: 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 response.json()
+        else:
+            # Print response if request fails
+            pretty_print_response(response)
+            return None
+
+
+def test_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: Union[requests.Response, None] = None
+    try:
+        response = requests.get(base_url)
+    except requests.exceptions.ConnectionError:
+        response = None
+    finally:
+        if response and response.status_code == 200:
+            return True
+    return False

d2spy/extras/third_party/tusclient/__init__.py

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

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/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/extras/third_party/tusclient/request.py

@@ -0,0 +1,93 @@
+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/extras/third_party/tusclient/uploader/__init__.py

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

d2spy/extras/third_party/tusclient/uploader/baseuploader.py

@@ -0,0 +1,246 @@
+from typing import Optional, IO, Dict, TYPE_CHECKING
+import os
+import re
+from base64 import b64encode
+from sys import maxsize as MAXSIZE
+import hashlib
+
+import requests
+
+from d2spy.extras.third_party.tusclient.exceptions import TusCommunicationError
+from d2spy.extras.third_party.tusclient.request import TusRequest, catch_requests_error
+
+if TYPE_CHECKING:
+    from d2spy.extras.third_party.tusclient.client import TusClient
+
+
+class BaseUploader:
+    """
+    Object to control upload related functions.
+
+    :Attributes:
+        - file_path (str):
+            This is the path(absolute/relative) to the file that is intended for upload
+            to the tus server. On instantiation this attribute is required.
+        - file_stream (file):
+            As an alternative to the `file_path`, an instance of the file to be uploaded
+            can be passed to the constructor as `file_stream`. Do note that either the
+            `file_stream` or the `file_path` must be passed on instantiation.
+        -  url (str):
+            If the upload url for the file is known, it can be passed to the constructor.
+            This may happen when you resume an upload.
+        - client (<tusclient.client.TusClient>):
+            An instance of `tusclient.client.TusClient`. This would tell the uploader instance
+            what client it is operating with. Although this argument is optional, it is only
+            optional if the 'url' argument is specified.
+        - chunk_size (int):
+            This tells the uploader what chunk size(in bytes) should be uploaded when the
+            method `upload_chunk` is called. This defaults to the maximum possible integer if not
+            specified.
+        - metadata (dict):
+            A dictionary containing the upload-metadata. This would be encoded internally
+            by the method `encode_metadata` to conform with the tus protocol.
+        - metadata_encoding (str):
+            Encoding used for each upload-metadata value. This defaults to 'utf-8'.
+        - offset (int):
+            The offset value of the upload indicates the current position of the file upload.
+        - stop_at (int):
+            At what offset value the upload should stop.
+        - request (<tusclient.request.TusRequest>):
+            A http Request instance of the last chunk uploaded.
+        - retries (int):
+            The number of attempts the uploader should make in the case of a failed upload.
+            If not specified, it defaults to 0.
+        - retry_delay (int):
+            How long (in seconds) the uploader should wait before retrying a failed upload attempt.
+            If not specified, it defaults to 30.
+        - verify_tls_cert (bool):
+            Whether or not to verify the TLS certificate of the server.
+            If not specified, it defaults to True.
+        - upload_checksum (bool):
+            Whether or not to supply the Upload-Checksum header along with each
+            chunk. Defaults to False.
+
+    :Constructor Args:
+        - file_path (str)
+        - file_stream (Optional[file])
+        - url (Optional[str])
+        - client (Optional [<tusclient.client.TusClient>])
+        - chunk_size (Optional[int])
+        - metadata (Optional[dict])
+        - metadata_encoding (Optional[str])
+        - retries (Optional[int])
+        - retry_delay (Optional[int])
+        - verify_tls_cert (Optional[bool])
+        - upload_checksum (Optional[bool])
+    """
+
+    DEFAULT_HEADERS = {"Tus-Resumable": "1.0.0"}
+    DEFAULT_CHUNK_SIZE = MAXSIZE
+    CHECKSUM_ALGORITHM_PAIR = (
+        "sha1",
+        hashlib.sha1,
+    )
+
+    def __init__(
+        self,
+        file_path: Optional[str] = None,
+        file_stream: Optional[IO] = None,
+        url: Optional[str] = None,
+        client: Optional["TusClient"] = None,
+        chunk_size: int = MAXSIZE,
+        metadata: Optional[Dict] = None,
+        metadata_encoding: Optional[str] = "utf-8",
+        retries: int = 0,
+        retry_delay: int = 30,
+        verify_tls_cert: bool = True,
+        upload_checksum=False,
+    ):
+        if file_path is None and file_stream is None:
+            raise ValueError("Either 'file_path' or 'file_stream' cannot be None.")
+
+        if url is None and client is None:
+            raise ValueError("Either 'url' or 'client' cannot be None.")
+
+        self.verify_tls_cert = verify_tls_cert
+        self.file_path = file_path
+        self.file_stream = file_stream
+        self.stop_at = self.get_file_size()
+        self.client = client
+        self.metadata = metadata or {}
+        self.metadata_encoding = metadata_encoding
+        self.offset = 0
+        self.url = None
+        self.__init_url_and_offset(url)
+        self.chunk_size = chunk_size
+        self.retries = retries
+        self.request = None
+        self._retried = 0
+        self.retry_delay = retry_delay
+        self.upload_checksum = upload_checksum
+        (
+            self.__checksum_algorithm_name,
+            self.__checksum_algorithm,
+        ) = self.CHECKSUM_ALGORITHM_PAIR
+
+    def get_cookies(self):
+        """
+        Return cookies of the uploader instance. This would include the cookies of the
+        client instance.
+        """
+        client_cookies = getattr(self.client, "cookies", {})
+        return dict(**client_cookies)
+
+    def get_headers(self):
+        """
+        Return headers of the uploader instance. This would include the headers of the
+        client instance.
+        """
+        client_headers = getattr(self.client, "headers", {})
+        return dict(self.DEFAULT_HEADERS, **client_headers)
+
+    def get_url_creation_headers(self):
+        """Return headers required to create upload url"""
+        headers = self.get_headers()
+        headers["upload-length"] = str(self.get_file_size())
+        headers["upload-metadata"] = ",".join(self.encode_metadata())
+        return headers
+
+    def get_url_creation_cookies(self):
+        """Return cookies required to create upload url"""
+        cookies = self.get_cookies()
+        return cookies
+
+    @property
+    def checksum_algorithm(self):
+        """The checksum algorithm to be used for the Upload-Checksum extension."""
+        return self.__checksum_algorithm
+
+    @property
+    def checksum_algorithm_name(self):
+        """The name of the checksum algorithm to be used for the Upload-Checksum
+        extension.
+        """
+        return self.__checksum_algorithm_name
+
+    @catch_requests_error
+    def get_offset(self):
+        """
+        Return offset from tus server.
+
+        This is different from the instance attribute 'offset' because this makes an
+        http request to the tus server to retrieve the offset.
+        """
+        resp = requests.head(
+            self.url, headers=self.get_headers(), verify=self.verify_tls_cert
+        )
+        offset = resp.headers.get("upload-offset")
+        if offset is None:
+            msg = "Attempt to retrieve offset fails with status {}".format(
+                resp.status_code
+            )
+            raise TusCommunicationError(msg, resp.status_code, resp.content)
+        return int(offset)
+
+    def encode_metadata(self):
+        """
+        Return list of encoded metadata as defined by the Tus protocol.
+        """
+        encoded_list = []
+        for key, value in self.metadata.items():
+            key_str = str(key)  # dict keys may be of any object type.
+
+            # confirm that the key does not contain unwanted characters.
+            if re.search(r"^$|[\s,]+", key_str):
+                msg = 'Upload-metadata key "{}" cannot be empty nor contain spaces or commas.'
+                raise ValueError(msg.format(key_str))
+
+            value_bytes = value.encode(self.metadata_encoding)
+            encoded_list.append(
+                "{} {}".format(key_str, b64encode(value_bytes).decode("ascii"))
+            )
+        return encoded_list
+
+    def __init_url_and_offset(self, url: Optional[str] = None):
+        """
+        Return the tus upload url.
+
+        If resumability is enabled, this would try to get the url from storage if available,
+        otherwise it would request a new upload url from the tus server.
+        """
+        if url:
+            self.set_url(url)
+
+        if self.url:
+            self.offset = self.get_offset()
+
+    def set_url(self, url: str):
+        """Set the upload URL"""
+        self.url = url
+
+    def get_request_length(self):
+        """
+        Return length of next chunk upload.
+        """
+        remainder = self.stop_at - self.offset
+        return self.chunk_size if remainder > self.chunk_size else remainder
+
+    def get_file_stream(self):
+        """
+        Return a file stream instance of the upload.
+        """
+        if self.file_stream:
+            self.file_stream.seek(0)
+            return self.file_stream
+        elif os.path.isfile(self.file_path):
+            return open(self.file_path, "rb")
+        else:
+            raise ValueError("invalid file {}".format(self.file_path))
+
+    def get_file_size(self):
+        """
+        Return size of the file.
+        """
+        stream = self.get_file_stream()
+        stream.seek(0, os.SEEK_END)
+        return stream.tell()