arkindex-client 1.0.15__py3-none-any.whl → 1.1.0__py3-none-any.whl

apistar/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+import warnings
+
+warnings.warn(
+    "The Arkindex API client no longer depends on APIStar. "
+    "Please update your `apistar` imports to use the `arkindex` package.",
+    FutureWarning,
+    stacklevel=2,
+)

apistar/exceptions.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+import warnings
+
+from arkindex.exceptions import ErrorResponse
+
+__all__ = ["ErrorResponse"]
+
+warnings.warn(
+    "The Arkindex API client no longer depends on APIStar. "
+    "Please update your `apistar.exceptions` imports to use the `arkindex.exceptions` module.",
+    FutureWarning,
+    stacklevel=2,
+)

arkindex/auth.py

@@ -1,11 +1,10 @@
 # -*- coding: utf-8 -*-
-from apistar.client.auth import SessionAuthentication, TokenAuthentication
+from requests.auth import AuthBase
 
 
-class TokenSessionAuthentication(TokenAuthentication):
-    """
-    A token authentication that takes care of CSRF tokens.
-    """
+class TokenSessionAuthentication(AuthBase):
+
+    safe_methods = ("GET", "HEAD", "OPTIONS", "TRACE")
 
     def __init__(
         self,
@@ -20,14 +19,30 @@ class TokenSessionAuthentication(TokenAuthentication):
         :param str csrf_cookie_name: Name of the CSRF token cookie.
         :param str csrf_header_name: Name of the CSRF request header.
         """
-        self.session_auth = SessionAuthentication(
-            csrf_cookie_name=csrf_cookie_name,
-            csrf_header_name=csrf_header_name,
-        )
-        super().__init__(token, scheme=scheme)
+        self.token = token
+        self.scheme = scheme
+        self.csrf_cookie_name = csrf_cookie_name
+        self.csrf_header_name = csrf_header_name
+        self.csrf_token = None
+
+    def store_csrf_token(self, response, **kwargs):
+        if self.csrf_cookie_name in response.cookies:
+            self.csrf_token = response.cookies[self.csrf_cookie_name]
 
     def __call__(self, request):
-        request = self.session_auth(request)
-        if self.token is None:
-            return request
-        return super().__call__(request)
+        # Add CSRF token
+        if (
+            self.csrf_token
+            and self.csrf_header_name is not None
+            and (request.method not in self.safe_methods)
+        ):
+            request.headers[self.csrf_header_name] = self.csrf_token
+
+        if self.csrf_cookie_name is not None:
+            request.register_hook("response", self.store_csrf_token)
+
+        # Add API token
+        if self.token is not None:
+            request.headers["Authorization"] = f"{self.scheme} {self.token}"
+
+        return request

arkindex/client/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from arkindex.client.client import ArkindexClient, options_from_env
+
+__all__ = ["ArkindexClient", "options_from_env"]

arkindex/client/base.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+from urllib.parse import quote, urljoin, urlparse
+
+import typesystem
+
+from arkindex import exceptions
+from arkindex.client.transports import HTTPTransport
+from arkindex.schema.validator import validate
+
+
+class BaseClient:
+    def __init__(
+        self,
+        schema,
+        encoding=None,
+        auth=None,
+        decoders=None,
+        headers=None,
+        session=None,
+        allow_cookies=True,
+        verify=True,
+    ):
+        self.document = validate(schema, encoding=encoding)
+        self.transport = HTTPTransport(
+            auth=auth,
+            decoders=decoders,
+            headers=headers,
+            session=session,
+            allow_cookies=allow_cookies,
+            verify=verify,
+        )
+
+    def lookup_operation(self, operation_id: str):
+        for item in self.document.walk_links():
+            if item.link.name == operation_id:
+                return item.link
+        text = 'Operation ID "%s" not found in schema.' % operation_id
+        message = exceptions.ErrorMessage(text=text, code="invalid-operation")
+        raise exceptions.ClientError(messages=[message])
+
+    def get_url(self, link, params):
+        url = urljoin(self.document.url, link.url)
+
+        scheme = urlparse(url).scheme.lower()
+
+        if not scheme:
+            text = "URL missing scheme '%s'." % url
+            message = exceptions.ErrorMessage(text=text, code="invalid-url")
+            raise exceptions.ClientError(messages=[message])
+
+        if scheme not in self.transport.schemes:
+            text = "Unsupported URL scheme '%s'." % scheme
+            message = exceptions.ErrorMessage(text=text, code="invalid-url")
+            raise exceptions.ClientError(messages=[message])
+
+        for field in link.get_path_fields():
+            value = str(params[field.name])
+            if "{%s}" % field.name in url:
+                url = url.replace("{%s}" % field.name, quote(value, safe=""))
+            elif "{+%s}" % field.name in url:
+                url = url.replace("{+%s}" % field.name, quote(value, safe="/"))
+
+        return url
+
+    def get_query_params(self, link, params):
+        return {
+            field.name: params[field.name]
+            for field in link.get_query_fields()
+            if field.name in params
+        }
+
+    def get_content_and_encoding(self, link, params):
+        body_field = link.get_body_field()
+        if body_field and body_field.name in params:
+            return (params[body_field.name], link.encoding)
+        return (None, None)
+
+    def request(self, operation_id: str, **params):
+        link = self.lookup_operation(operation_id)
+
+        validator = typesystem.Object(
+            properties={field.name: typesystem.Any() for field in link.fields},
+            required=[field.name for field in link.fields if field.required],
+            additional_properties=False,
+        )
+        try:
+            validator.validate(params)
+        except typesystem.ValidationError as exc:
+            raise exceptions.ClientError(messages=exc.messages()) from None
+
+        method = link.method
+        url = self.get_url(link, params)
+        query_params = self.get_query_params(link, params)
+        (content, encoding) = self.get_content_and_encoding(link, params)
+
+        return self.transport.send(
+            method, url, query_params=query_params, content=content, encoding=encoding
+        )

arkindex/{client.py → client/client.py}

@@ -8,14 +8,31 @@ import warnings
 from time import sleep
 from urllib.parse import urljoin, urlsplit, urlunsplit
 
-import apistar
 import requests
 import yaml
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
 
 from arkindex.auth import TokenSessionAuthentication
-from arkindex.exceptions import SchemaError
+from arkindex.client.base import BaseClient
+from arkindex.exceptions import ErrorResponse, SchemaError
 from arkindex.pagination import ResponsePaginator
-from arkindex.transports import ArkindexHTTPTransport
+
+logger = logging.getLogger(__name__)
+
+try:
+    from yaml import CSafeLoader as SafeLoader
+
+    logger.debug("Using LibYAML-based parser")
+except ImportError:
+    from yaml import SafeLoader
+
+    logger.debug("Using default PyYAML parser")
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 
@@ -24,7 +41,16 @@ DEFAULT_BASE_URL = "https://arkindex.teklia.com/"
 # Endpoint accessed by the client on instantiation to retrieve the OpenAPI schema
 SCHEMA_ENDPOINT = "/api/v1/openapi/?format=json"
 
-logger = logging.getLogger(__name__)
+
+def _is_500_error(exc: Exception) -> bool:
+    """
+    Check if an Arkindex API error is a 50x
+    This is used to retry most API calls implemented here
+    """
+    if not isinstance(exc, ErrorResponse):
+        return False
+
+    return 500 <= exc.status_code < 600
 
 
 def options_from_env():
@@ -71,7 +97,7 @@ def _find_param(operation, param_name):
     raise KeyError("Parameter '{}' not found".format(param_name))
 
 
-class ArkindexClient(apistar.Client):
+class ArkindexClient(BaseClient):
     """
     An Arkindex API client.
     """
@@ -99,7 +125,7 @@ class ArkindexClient(apistar.Client):
         :type csrf_cookie: str or None
         :param float sleep: Number of seconds to wait before sending each API request,
            as a simple means of throttling.
-        :param \**kwargs: Keyword arguments to send to ``apistar.Client``.
+        :param \**kwargs: Keyword arguments to send to ``arkindex.client.base.BaseClient``.
         """
         if not schema_url:
             schema_url = urljoin(base_url, SCHEMA_ENDPOINT)
@@ -110,11 +136,11 @@ class ArkindexClient(apistar.Client):
             if split.scheme == "file" or not (split.scheme or split.netloc):
                 # This is a local path
                 with open(schema_url) as f:
-                    schema = yaml.safe_load(f)
+                    schema = yaml.load(f, Loader=SafeLoader)
             else:
                 resp = requests.get(schema_url, verify=self.verify)
                 resp.raise_for_status()
-                schema = yaml.safe_load(resp.content)
+                schema = yaml.load(resp.content, Loader=SafeLoader)
         except Exception as e:
             raise SchemaError(
                 f"Could not retrieve a proper OpenAPI schema from {schema_url}"
@@ -122,7 +148,7 @@ class ArkindexClient(apistar.Client):
 
         super().__init__(schema, **kwargs)
 
-        # APIStar will treat a schema as valid even when there are no endpoints, making the client completely useless.
+        # An OpenAPI schema is considered valid even when there are no endpoints, making the client completely useless.
         if not len(self.document.walk_links()):
             raise SchemaError(
                 f"The OpenAPI schema from {base_url} has no defined endpoints"
@@ -142,7 +168,7 @@ class ArkindexClient(apistar.Client):
             if "x-paginated" in operation:
                 link_info.link._paginated = operation["x-paginated"]
 
-            # Remove domains from each endpoint; allows APIStar to properly handle our base URL
+            # Remove domains from each endpoint; allows to properly handle our base URL
             # https://github.com/encode/apistar/issues/657
             original_url = urlsplit(link_info.link.url)
             # Removes the scheme and netloc
@@ -174,9 +200,6 @@ class ArkindexClient(apistar.Client):
             self.document.url if hasattr(self, "document") else "",
         )
 
-    def init_transport(self, *args, **kwargs):
-        return ArkindexHTTPTransport(self.verify, *args, **kwargs)
-
     def configure(
         self,
         token=None,
@@ -223,7 +246,7 @@ class ArkindexClient(apistar.Client):
 
     def paginate(self, operation_id, *args, **kwargs):
         """
-        Perform a usual request as done by APIStar, but handle paginated endpoints.
+        Perform a usual API request, but handle paginated endpoints.
 
         :return: An iterator for a paginated endpoint.
         :rtype: Union[arkindex.pagination.ResponsePaginator, dict, list]
@@ -245,11 +268,11 @@ class ArkindexClient(apistar.Client):
             self.transport.session.auth.token = resp["auth_token"]
         return resp
 
-    def request(self, operation_id, *args, **kwargs):
+    def single_request(self, operation_id, *args, **kwargs):
         """
         Perform an API request.
-        :param args: Arguments passed to the APIStar client.
-        :param kwargs: Keyword arguments passed to the APIStar client.
+        :param args: Arguments passed to the BaseClient.
+        :param kwargs: Keyword arguments passed to the BaseClient.
         """
         link = self.lookup_operation(operation_id)
         if link.deprecated:
@@ -274,3 +297,23 @@ class ArkindexClient(apistar.Client):
             )
             sleep(self.sleep_duration)
         return super().request(operation_id, *args, **kwargs)
+
+    @retry(
+        retry=retry_if_exception(_is_500_error),
+        wait=wait_exponential(multiplier=2, min=3),
+        reraise=True,
+        stop=stop_after_attempt(5),
+        before_sleep=before_sleep_log(logger, logging.INFO),
+    )
+    def request(self, operation_id, *args, **kwargs):
+        """
+        Proxy all Arkindex API requests with a retry mechanism in case of 50X errors.
+        The same API call will be retried 5 times, with an exponential sleep time
+        going through 3, 4, 8 and 16 seconds of wait between call.
+        If the 5th call still gives a 50x, the exception is re-raised and the caller should catch it.
+        Log messages are displayed before sleeping (when at least one exception occurred).
+
+        :param args: Arguments passed to the BaseClient.
+        :param kwargs: Keyword arguments passed to the BaseClient.
+        """
+        return self.single_request(operation_id, *args, **kwargs)

arkindex/client/decoders.py

@@ -0,0 +1,252 @@
+# -*- coding: utf-8 -*-
+import cgi
+import json
+import os
+import posixpath
+import shutil
+import tempfile
+from urllib.parse import urlparse
+
+from arkindex.compat import DownloadedFile
+
+
+class BaseDecoder:
+    media_type = None
+
+    def decode(self, bytestring, **options):
+        raise NotImplementedError()
+
+
+class JSONDecoder(BaseDecoder):
+    media_type = "application/json"
+
+    def decode(self, response):
+        """
+        Return raw JSON data.
+        """
+        content = response.content.decode("utf-8")
+        return json.loads(content)
+
+
+class TextDecoder(BaseDecoder):
+    media_type = "text/*"
+
+    def decode(self, response):
+        return response.text
+
+
+class DownloadDecoder(BaseDecoder):
+    """
+    A codec to handle raw file downloads, such as images and other media.
+    """
+
+    media_type = "*/*"
+
+    def __init__(self, download_dir=None):
+        """
+        `download_dir` - If `None` then downloaded files will be temporary files
+        that are deleted on close. If set to a value, then downloaded files
+        will be saved to this directory, and will not be automatically deleted.
+        """
+        self._delete_on_close = download_dir is None
+        self.download_dir = download_dir
+
+    def decode(self, response):
+        base_url = response.url
+        content_type = response.headers.get("content-type")
+        content_disposition = response.headers.get("content-disposition")
+
+        # Write the download to a temporary .download file.
+        fd, temp_path = tempfile.mkstemp(suffix=".download")
+        with os.fdopen(fd, "wb") as file_handle:
+            for chunk in response.iter_content(chunk_size=4096):
+                file_handle.write(chunk)
+
+        # Determine the output filename.
+        output_filename = _get_filename(base_url, content_type, content_disposition)
+
+        # Determine the output directory.
+        output_dir = self.download_dir
+        if output_dir is None:
+            output_dir = os.path.dirname(temp_path)
+
+        # Determine the full output path.
+        output_path = os.path.join(output_dir, output_filename)
+
+        # Move the temporary download file to the final location.
+        if output_path != temp_path:
+            output_path = _unique_output_path(output_path)
+            shutil.move(temp_path, output_path)
+
+        # Open the file and return the file object.
+        output_file = open(output_path, "rb")
+        downloaded = DownloadedFile(
+            output_file, output_path, delete=self._delete_on_close
+        )
+        downloaded.basename = output_filename
+        return downloaded
+
+
+def _guess_extension(content_type):
+    """
+    Python's `mimetypes.guess_extension` is no use because it simply returns
+    the first of an unordered set. We use the same set of media types here,
+    but take a reasonable preference on what extension to map to.
+    """
+    return {
+        "application/javascript": ".js",
+        "application/msword": ".doc",
+        "application/octet-stream": ".bin",
+        "application/oda": ".oda",
+        "application/pdf": ".pdf",
+        "application/pkcs7-mime": ".p7c",
+        "application/postscript": ".ps",
+        "application/vnd.apple.mpegurl": ".m3u",
+        "application/vnd.ms-excel": ".xls",
+        "application/vnd.ms-powerpoint": ".ppt",
+        "application/x-bcpio": ".bcpio",
+        "application/x-cpio": ".cpio",
+        "application/x-csh": ".csh",
+        "application/x-dvi": ".dvi",
+        "application/x-gtar": ".gtar",
+        "application/x-hdf": ".hdf",
+        "application/x-latex": ".latex",
+        "application/x-mif": ".mif",
+        "application/x-netcdf": ".nc",
+        "application/x-pkcs12": ".p12",
+        "application/x-pn-realaudio": ".ram",
+        "application/x-python-code": ".pyc",
+        "application/x-sh": ".sh",
+        "application/x-shar": ".shar",
+        "application/x-shockwave-flash": ".swf",
+        "application/x-sv4cpio": ".sv4cpio",
+        "application/x-sv4crc": ".sv4crc",
+        "application/x-tar": ".tar",
+        "application/x-tcl": ".tcl",
+        "application/x-tex": ".tex",
+        "application/x-texinfo": ".texinfo",
+        "application/x-troff": ".tr",
+        "application/x-troff-man": ".man",
+        "application/x-troff-me": ".me",
+        "application/x-troff-ms": ".ms",
+        "application/x-ustar": ".ustar",
+        "application/x-wais-source": ".src",
+        "application/xml": ".xml",
+        "application/zip": ".zip",
+        "audio/basic": ".au",
+        "audio/mpeg": ".mp3",
+        "audio/x-aiff": ".aif",
+        "audio/x-pn-realaudio": ".ra",
+        "audio/x-wav": ".wav",
+        "image/gif": ".gif",
+        "image/ief": ".ief",
+        "image/jpeg": ".jpe",
+        "image/png": ".png",
+        "image/svg+xml": ".svg",
+        "image/tiff": ".tiff",
+        "image/vnd.microsoft.icon": ".ico",
+        "image/x-cmu-raster": ".ras",
+        "image/x-ms-bmp": ".bmp",
+        "image/x-portable-anymap": ".pnm",
+        "image/x-portable-bitmap": ".pbm",
+        "image/x-portable-graymap": ".pgm",
+        "image/x-portable-pixmap": ".ppm",
+        "image/x-rgb": ".rgb",
+        "image/x-xbitmap": ".xbm",
+        "image/x-xpixmap": ".xpm",
+        "image/x-xwindowdump": ".xwd",
+        "message/rfc822": ".eml",
+        "text/css": ".css",
+        "text/csv": ".csv",
+        "text/html": ".html",
+        "text/plain": ".txt",
+        "text/richtext": ".rtx",
+        "text/tab-separated-values": ".tsv",
+        "text/x-python": ".py",
+        "text/x-setext": ".etx",
+        "text/x-sgml": ".sgml",
+        "text/x-vcard": ".vcf",
+        "text/xml": ".xml",
+        "video/mp4": ".mp4",
+        "video/mpeg": ".mpeg",
+        "video/quicktime": ".mov",
+        "video/webm": ".webm",
+        "video/x-msvideo": ".avi",
+        "video/x-sgi-movie": ".movie",
+    }.get(content_type, "")
+
+
+def _unique_output_path(path):
+    """
+    Given a path like '/a/b/c.txt'
+
+    Return the first available filename that doesn't already exist,
+    using an incrementing suffix if needed.
+
+    For example: '/a/b/c.txt' or '/a/b/c (1).txt' or '/a/b/c (2).txt'...
+    """
+    basename, ext = os.path.splitext(path)
+    idx = 0
+    while os.path.exists(path):
+        idx += 1
+        path = "%s (%d)%s" % (basename, idx, ext)
+    return path
+
+
+def _safe_filename(filename):
+    """
+    Sanitize output filenames, to remove any potentially unsafe characters.
+    """
+    filename = os.path.basename(filename)
+
+    keepcharacters = (" ", ".", "_", "-")
+    filename = (
+        "".join(char for char in filename if char.isalnum() or char in keepcharacters)
+        .strip()
+        .strip(".")
+    )
+
+    return filename
+
+
+def _get_filename_from_content_disposition(content_disposition):
+    """
+    Determine an output filename based on the `Content-Disposition` header.
+    """
+    params = value, params = cgi.parse_header(content_disposition)
+
+    if "filename" in params:
+        filename = params["filename"]
+        return _safe_filename(filename)
+
+    return None
+
+
+def _get_filename_from_url(url, content_type=None):
+    """
+    Determine an output filename based on the download URL.
+    """
+    parsed = urlparse(url)
+    final_path_component = posixpath.basename(parsed.path.rstrip("/"))
+    filename = _safe_filename(final_path_component)
+    suffix = _guess_extension(content_type or "")
+
+    if filename:
+        if "." not in filename:
+            return filename + suffix
+        return filename
+
+    return "download" + suffix
+
+
+def _get_filename(base_url, content_type=None, content_disposition=None):
+    """
+    Determine an output filename to use for the download.
+    """
+    filename = None
+    if content_disposition:
+        filename = _get_filename_from_content_disposition(content_disposition)
+        if filename is not None:
+            return filename
+
+    return _get_filename_from_url(base_url, content_type)