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

arkindex/client/transports.py

@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+import http
+from importlib.metadata import version
+
+import requests
+
+from arkindex import exceptions
+from arkindex.client import decoders
+
+REQUEST_TIMEOUT = (30, 60)
+
+
+class BlockAllCookies(http.cookiejar.CookiePolicy):
+    """
+    A cookie policy that rejects all cookies.
+    Used to override the default `requests` behavior.
+    """
+
+    return_ok = set_ok = domain_return_ok = path_return_ok = (
+        lambda self, *args, **kwargs: False
+    )
+    netscape = True
+    rfc2965 = hide_cookie2 = False
+
+
+class BaseTransport:
+    schemes = None
+
+    def send(self, method, url, query_params=None, content=None, encoding=None):
+        raise NotImplementedError()
+
+
+class HTTPTransport(BaseTransport):
+    schemes = ["http", "https"]
+    default_decoders = [
+        decoders.JSONDecoder(),
+        decoders.TextDecoder(),
+        decoders.DownloadDecoder(),
+    ]
+
+    def __init__(
+        self,
+        auth=None,
+        decoders=None,
+        headers=None,
+        session=None,
+        allow_cookies=True,
+        verify=True,
+    ):
+        if session is None:
+            session = requests.Session()
+        if auth is not None:
+            session.auth = auth
+        if not allow_cookies:
+            session.cookies.set_policy(BlockAllCookies())
+
+        self.session = session
+        self.verify = verify
+        self.decoders = list(decoders) if decoders else list(self.default_decoders)
+
+        client_version = version("arkindex-client")
+        self.headers = {
+            "accept": ", ".join([decoder.media_type for decoder in self.decoders]),
+            "user-agent": f"arkindex-client/{client_version}",
+        }
+        if headers:
+            self.headers.update({key.lower(): value for key, value in headers.items()})
+
+    def send(self, method, url, query_params=None, content=None, encoding=None):
+        options = self.get_request_options(query_params, content, encoding)
+        response = self.session.request(method, url, **options)
+        result = self.decode_response_content(response)
+
+        if 400 <= response.status_code <= 599:
+            title = "%d %s" % (response.status_code, response.reason)
+            raise exceptions.ErrorResponse(
+                title=title, status_code=response.status_code, content=result
+            )
+
+        return result
+
+    def get_decoder(self, content_type=None):
+        """
+        Given the value of a 'Content-Type' header, return the appropriate
+        decoder for handling the response content.
+        """
+        if content_type is None:
+            return self.decoders[0]
+
+        content_type = content_type.split(";")[0].strip().lower()
+        main_type = content_type.split("/")[0] + "/*"
+        wildcard_type = "*/*"
+
+        for codec in self.decoders:
+            if codec.media_type in (content_type, main_type, wildcard_type):
+                return codec
+
+        text = (
+            "Unsupported encoding '%s' in response Content-Type header." % content_type
+        )
+        message = exceptions.ErrorMessage(text=text, code="cannot-decode-response")
+        raise exceptions.ClientError(messages=[message])
+
+    def get_request_options(self, query_params=None, content=None, encoding=None):
+        """
+        Return the 'options' for sending the outgoing request.
+        """
+        options = {
+            "headers": dict(self.headers),
+            "params": query_params,
+            "timeout": REQUEST_TIMEOUT,
+            "verify": self.verify,
+        }
+
+        if content is not None:
+            assert (
+                encoding == "application/json"
+            ), "Only JSON request bodies are supported"
+            options["json"] = content
+
+        return options
+
+    def decode_response_content(self, response):
+        """
+        Given an HTTP response, return the decoded data.
+        """
+        if not response.content:
+            return None
+
+        content_type = response.headers.get("content-type")
+        decoder = self.get_decoder(content_type)
+        return decoder.decode(response)

arkindex/compat.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+try:
+    # Ideally we subclass `_TemporaryFileWrapper` to present a clear __repr__
+    # for downloaded files.
+    from tempfile import _TemporaryFileWrapper
+
+    class DownloadedFile(_TemporaryFileWrapper):
+        basename = None
+
+        def __repr__(self):
+            state = "closed" if self.closed else "open"
+            mode = "" if self.closed else " '%s'" % self.file.mode
+            return "<DownloadedFile '%s', %s%s>" % (self.name, state, mode)
+
+        def __str__(self):
+            return self.__repr__()
+
+except ImportError:
+    # On some platforms (eg GAE) the private _TemporaryFileWrapper may not be
+    # available, just use the standard `NamedTemporaryFile` function
+    # in this case.
+    import tempfile
+
+    DownloadedFile = tempfile.NamedTemporaryFile

arkindex/document.py

@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+import collections
+import re
+import typing
+
+LinkInfo = collections.namedtuple("LinkInfo", ["link", "name", "sections"])
+
+
+class Document:
+    def __init__(
+        self,
+        content: typing.Sequence[typing.Union["Section", "Link"]] = None,
+        url: str = "",
+        title: str = "",
+        description: str = "",
+        version: str = "",
+    ):
+        content = [] if (content is None) else list(content)
+
+        # Ensure all names within a document are unique.
+        seen_fields = set()
+        seen_sections = set()
+        for item in content:
+            if isinstance(item, Link):
+                msg = 'Link "%s" in Document must have a unique name.'
+                assert item.name not in seen_fields, msg % item.name
+                seen_fields.add(item.name)
+            else:
+                msg = 'Section "%s" in Document must have a unique name.'
+                assert item.name not in seen_sections, msg % item.name
+                seen_sections.add(item.name)
+
+        self.content = content
+        self.url = url
+        self.title = title
+        self.description = description
+        self.version = version
+
+    def get_links(self):
+        return [item for item in self.content if isinstance(item, Link)]
+
+    def get_sections(self):
+        return [item for item in self.content if isinstance(item, Section)]
+
+    def walk_links(self):
+        link_info_list = []
+        for item in self.content:
+            if isinstance(item, Link):
+                link_info = LinkInfo(link=item, name=item.name, sections=())
+                link_info_list.append(link_info)
+            else:
+                link_info_list.extend(item.walk_links())
+        return link_info_list
+
+
+class Section:
+    def __init__(
+        self,
+        name: str,
+        content: typing.Sequence[typing.Union["Section", "Link"]] = None,
+        title: str = "",
+        description: str = "",
+    ):
+        content = [] if (content is None) else list(content)
+
+        # Ensure all names within a section are unique.
+        seen_fields = set()
+        seen_sections = set()
+        for item in content:
+            if isinstance(item, Link):
+                msg = 'Link "%s" in Section "%s" must have a unique name.'
+                assert item.name not in seen_fields, msg % (item.name, name)
+                seen_fields.add(item.name)
+            else:
+                msg = 'Section "%s" in Section "%s" must have a unique name.'
+                assert item.name not in seen_sections, msg % (item.name, name)
+                seen_sections.add(item.name)
+
+        self.content = content
+        self.name = name
+        self.title = title
+        self.description = description
+
+    def get_links(self):
+        return [item for item in self.content if isinstance(item, Link)]
+
+    def get_sections(self):
+        return [item for item in self.content if isinstance(item, Section)]
+
+    def walk_links(self, previous_sections=()):
+        link_info_list = []
+        sections = previous_sections + (self,)
+        for item in self.content:
+            if isinstance(item, Link):
+                name = ":".join([section.name for section in sections] + [item.name])
+                link_info = LinkInfo(link=item, name=name, sections=sections)
+                link_info_list.append(link_info)
+            else:
+                link_info_list.extend(item.walk_links(previous_sections=sections))
+        return link_info_list
+
+
+class Link:
+    """
+    Links represent the actions that a client may perform.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        method: str,
+        handler: typing.Callable = None,
+        name: str = "",
+        encoding: str = "",
+        response: "Response" = None,
+        title: str = "",
+        description: str = "",
+        fields: typing.Sequence["Field"] = None,
+    ):
+        method = method.upper()
+        fields = [] if (fields is None) else list(fields)
+
+        url_path_names = set(
+            [item.strip("{}").lstrip("+") for item in re.findall("{[^}]*}", url)]
+        )
+        path_fields = [field for field in fields if field.location == "path"]
+        body_fields = [field for field in fields if field.location == "body"]
+
+        assert method in (
+            "GET",
+            "POST",
+            "PUT",
+            "PATCH",
+            "DELETE",
+            "OPTIONS",
+            "HEAD",
+            "TRACE",
+        )
+        assert len(body_fields) < 2
+        if body_fields:
+            assert encoding
+        for field in path_fields:
+            assert field.name in url_path_names
+
+        # Add in path fields for any "{param}" items that don't already have
+        # a corresponding path field.
+        for path_name in url_path_names:
+            if path_name not in [field.name for field in path_fields]:
+                fields += [Field(name=path_name, location="path", required=True)]
+
+        self.url = url
+        self.method = method
+        self.handler = handler
+        self.name = name if name else handler.__name__
+        self.encoding = encoding
+        self.response = response
+        self.title = title
+        self.description = description
+        self.fields = fields
+
+    def get_path_fields(self):
+        return [field for field in self.fields if field.location == "path"]
+
+    def get_query_fields(self):
+        return [field for field in self.fields if field.location == "query"]
+
+    def get_body_field(self):
+        for field in self.fields:
+            if field.location == "body":
+                return field
+        return None
+
+    def get_expanded_body(self):
+        field = self.get_body_field()
+        if field is None or not hasattr(field.schema, "properties"):
+            return None
+        return field.schema.properties
+
+
+class Field:
+    def __init__(
+        self,
+        name: str,
+        location: str,
+        title: str = "",
+        description: str = "",
+        required: bool = None,
+        schema: typing.Any = None,
+        example: typing.Any = None,
+    ):
+        assert location in ("path", "query", "body", "cookie", "header", "formData")
+        if required is None:
+            required = True if location in ("path", "body") else False
+        if location == "path":
+            assert required, "May not set 'required=False' on path fields."
+
+        self.name = name
+        self.title = title
+        self.description = description
+        self.location = location
+        self.required = required
+        self.schema = schema
+        self.example = example
+
+
+class Response:
+    def __init__(
+        self, encoding: str, status_code: int = 200, schema: typing.Any = None
+    ):
+        self.encoding = encoding
+        self.status_code = status_code
+        self.schema = schema

arkindex/exceptions.py

@@ -1,4 +1,77 @@
 # -*- coding: utf-8 -*-
+from collections import namedtuple
+
+Position = namedtuple("Position", ["line_no", "column_no", "index"])
+
+
+class ErrorMessage:
+    def __init__(self, text, code, index=None, position=None):
+        self.text = text
+        self.code = code
+        self.index = index
+        self.position = position
+
+    def __eq__(self, other):
+        return (
+            self.text == other.text
+            and self.code == other.code
+            and self.index == other.index
+            and self.position == other.position
+        )
+
+    def __repr__(self):
+        return "%s(%s, code=%s, index=%s, position=%s)" % (
+            self.__class__.__name__,
+            repr(self.text),
+            repr(self.code),
+            repr(self.index),
+            repr(self.position),
+        )
+
+
+class ErrorResponse(Exception):
+    """
+    Raised when a client request results in an error response being returned.
+    """
+
+    def __init__(self, title, status_code, content):
+        self.title = title
+        self.status_code = status_code
+        self.content = content
+
+    def __repr__(self):
+        return "%s(%s, status_code=%s, content=%s)" % (
+            self.__class__.__name__,
+            repr(self.title),
+            repr(self.status_code),
+            repr(self.content),
+        )
+
+    def __str__(self):
+        return repr(self.content)
+
+
+class ClientError(Exception):
+    """
+    Raised when a client is unable to fulfil an API request.
+    """
+
+    def __init__(self, messages):
+        self.messages = messages
+        super().__init__(messages)
+
+    def __repr__(self):
+        return "%s(messages=%s)" % (
+            self.__class__.__name__,
+            repr(self.messages),
+        )
+
+    def __str__(self):
+        if len(self.messages) == 1 and not self.messages[0].index:
+            return self.messages[0].text
+        return str(self.messages)
+
+
 class SchemaError(Exception):
     """
     Any error occurring during the acquisition and processing of the OpenAPI schema.

arkindex/mock.py

@@ -2,7 +2,7 @@
 import collections
 import logging
 
-import apistar
+from arkindex.exceptions import ErrorResponse
 
 logger = logging.getLogger(__name__)
 
@@ -36,7 +36,7 @@ class MockApiClient(object):
     ):
         """Store a new mock error response for a request on an endpoint"""
         request = MockRequest(operation_id, body, args, kwargs)
-        error = apistar.exceptions.ErrorResponse(
+        error = ErrorResponse(
             title=title,
             status_code=status_code,
             content=content,
@@ -74,7 +74,7 @@ class MockApiClient(object):
         logger.error(
             f"No mock response found for {operation_id} with body={body} args={args} kwargs={kwargs}"
         )
-        raise apistar.exceptions.ErrorResponse(
+        raise ErrorResponse(
             title="No mock response found",
             status_code=400,
             content="No mock response found",

arkindex/pagination.py

@@ -7,9 +7,10 @@ from collections.abc import Iterator, Sized
 from enum import Enum
 from urllib.parse import parse_qs, urlsplit
 
-import apistar
 import requests
 
+from arkindex.exceptions import ErrorResponse
+
 logger = logging.getLogger(__name__)
 
 
@@ -28,12 +29,12 @@ class ResponsePaginator(Sized, Iterator):
 
     def __init__(self, client, operation_id, *request_args, **request_kwargs):
         r"""
-        :param client apistar.Client: An API client to use to perform requests for each page.
-        :param \*request_args: Arguments to send to :meth:`apistar.Client.request`.
-        :param \**request_kwargs: Keyword arguments to send to :meth:`apistar.Client.request`.
+        :param client arkindex.ArkindexClient: An API client to use to perform requests for each page.
+        :param \*request_args: Arguments to send to :meth:`arkindex.ArkindexClient.request`.
+        :param \**request_kwargs: Keyword arguments to send to :meth:`arkindex.ArkindexClient.request`.
         """
         self.client = client
-        """The APIStar client used to perform requests on each page."""
+        """The API client used to perform requests on each page."""
 
         self.data = {}
         """Stored data from the last performed request."""
@@ -45,10 +46,10 @@ class ResponsePaginator(Sized, Iterator):
         """Client operation"""
 
         self.request_args = request_args
-        """Arguments to send to :meth:`apistar.Client.request` with each request."""
+        """Arguments to send to :meth:`arkindex.ArkindexClient.request` with each request."""
 
         self.request_kwargs = request_kwargs
-        """Keyword arguments to send to :meth:`apistar.Client.request` with each request."""
+        """Keyword arguments to send to :meth:`arkindex.ArkindexClient.request` with each request."""
 
         self.mode = None
         """`page` for PageNumberPagination endpoints or `cursor` for CursorPagination endpoints."""
@@ -172,7 +173,7 @@ class ResponsePaginator(Sized, Iterator):
             self.pages_loaded += 1
             return True
 
-        except apistar.exceptions.ErrorResponse as e:
+        except ErrorResponse as e:
             logger.warning(f"API Error {e.status_code} on pagination: {e.content}")
 
             # Decrement pages counter

arkindex/schema/jsonschema.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+import typesystem
+
+definitions = typesystem.SchemaDefinitions()
+
+JSON_SCHEMA = (
+    typesystem.Object(
+        properties={
+            "$ref": typesystem.String(),
+            "type": typesystem.String() | typesystem.Array(items=typesystem.String()),
+            "enum": typesystem.Array(unique_items=True, min_items=1),
+            "definitions": typesystem.Object(
+                additional_properties=typesystem.Reference(
+                    "JSONSchema", definitions=definitions
+                )
+            ),
+            # String
+            "minLength": typesystem.Integer(minimum=0),
+            "maxLength": typesystem.Integer(minimum=0),
+            "pattern": typesystem.String(format="regex"),
+            "format": typesystem.String(),
+            # Numeric
+            "minimum": typesystem.Number(),
+            "maximum": typesystem.Number(),
+            "exclusiveMinimum": typesystem.Number(),
+            "exclusiveMaximum": typesystem.Number(),
+            "multipleOf": typesystem.Number(exclusive_minimum=0),
+            # Object
+            "properties": typesystem.Object(
+                additional_properties=typesystem.Reference(
+                    "JSONSchema", definitions=definitions
+                )
+            ),
+            "minProperties": typesystem.Integer(minimum=0),
+            "maxProperties": typesystem.Integer(minimum=0),
+            "patternProperties": typesystem.Object(
+                additional_properties=typesystem.Reference(
+                    "JSONSchema", definitions=definitions
+                )
+            ),
+            "additionalProperties": (
+                typesystem.Reference("JSONSchema", definitions=definitions)
+                | typesystem.Boolean()
+            ),
+            "required": typesystem.Array(items=typesystem.String(), unique_items=True),
+            # Array
+            "items": (
+                typesystem.Reference("JSONSchema", definitions=definitions)
+                | typesystem.Array(
+                    items=typesystem.Reference("JSONSchema", definitions=definitions),
+                    min_items=1,
+                )
+            ),
+            "additionalItems": (
+                typesystem.Reference("JSONSchema", definitions=definitions)
+                | typesystem.Boolean()
+            ),
+            "minItems": typesystem.Integer(minimum=0),
+            "maxItems": typesystem.Integer(minimum=0),
+            "uniqueItems": typesystem.Boolean(),
+        }
+    )
+    | typesystem.Boolean()
+)
+
+definitions["JSONSchema"] = JSON_SCHEMA