canvas 0.25.0__tar.gz → 0.27.0__tar.gz

{canvas-0.25.0 → canvas-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: canvas
-Version: 0.25.0
+Version: 0.27.0
 Summary: SDK to customize event-driven actions in your Canvas instance
 Author-email: Canvas Team <engineering@canvasmedical.com>
 License-Expression: MIT

{canvas-0.25.0 → canvas-0.27.0}/canvas_sdk/handlers/simple_api/api.py

@@ -5,10 +5,8 @@ from base64 import b64decode
 from collections.abc import Callable
 from functools import cached_property
 from http import HTTPStatus
-from typing import Any, TypeVar
-from urllib.parse import parse_qs
-
-from requests.structures import CaseInsensitiveDict
+from typing import Any, ClassVar, Protocol, TypeVar, cast
+from urllib.parse import parse_qsl
 
 from canvas_sdk.effects import Effect, EffectType
 from canvas_sdk.effects.simple_api import JSONResponse, Response
@@ -19,9 +17,9 @@ from plugin_runner.exceptions import PluginError
 
 from .exceptions import AuthenticationError, InvalidCredentialsError
 from .security import Credentials
+from .tools import CaseInsensitiveMultiDict, MultiDict, separate_headers
 
 # TODO: Routing by path regex?
-# TODO: Support multipart/form-data by adding helpers to the request class
 # TODO: Log requests in a format similar to other API frameworks (probably need effect metadata)
 # TODO: Support Effect metadata that is separate from payload
 # TODO: Encode event payloads with MessagePack instead of JSON
@@ -30,6 +28,137 @@ from .security import Credentials
 JSON = dict[str, "JSON"] | list["JSON"] | int | float | str | bool | None
 
 
+class FormPart(Protocol):
+    """
+    Protocol for representing a form part in the body of a multipart/form-data request.
+
+    A form part can represent a simple string value, or a file with a content type.
+    """
+
+    @staticmethod
+    def is_file() -> bool:
+        """Return True or False depending on whether the form part represents a file."""
+        ...
+
+
+class StringFormPart(FormPart):
+    """Class for representing a form part that is a simple string value."""
+
+    def __init__(self, name: str, value: str) -> None:
+        self.name = name
+        self.value = value
+
+    @staticmethod
+    def is_file() -> bool:
+        """Return True or False depending on whether the form part represents a file."""
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, FileFormPart):
+            return False
+
+        if not isinstance(other, StringFormPart):
+            return NotImplemented
+
+        return self.name == other.name and self.value == other.value
+
+
+class FileFormPart(FormPart):
+    """Class for representing a form part that is a file."""
+
+    def __init__(
+        self, name: str, filename: str, content: bytes, content_type: str | None = None
+    ) -> None:
+        self.name = name
+        self.filename = filename
+        self.content = content
+        self.content_type = content_type
+
+    @staticmethod
+    def is_file() -> bool:
+        """Return True or False depending on whether the form part represents a file."""
+        return True
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, StringFormPart):
+            return False
+
+        if not isinstance(other, FileFormPart):
+            return NotImplemented
+
+        return all(
+            (
+                self.name == other.name,
+                self.filename == other.filename,
+                self.content == other.content,
+                self.content_type == other.content_type,
+            )
+        )
+
+
+def parse_multipart_form(form: bytes, boundary: str) -> MultiDict[str, FormPart]:
+    """Parse a multipart form and return a dict of string to list of form parts."""
+    form_data: list[tuple[str, FormPart]] = []
+
+    # Split the body by the boundary value and iterate over the parts. The first and last
+    # parts can be skipped because there are delimiters on at the start and end of the body
+    parts = form.split(f"--{boundary}".encode())
+    for part in parts[1:-1]:
+        # Each part may be either a simple string value or a file. Simple string values
+        # will just have a name and a value, whereas files will have a name, content type,
+        # filename, and value.
+        name = None
+        content_type = None
+        filename = None
+
+        # Split the part into the headers and the value (i.e. the content)
+        value: str | bytes
+        headers, value = part.split(b"\r\n\r\n", maxsplit=1)
+
+        # Iterate over the headers and extract the name, filename, and content type
+        for header in headers.decode().split("\r\n"):
+            # There are only two possible headers: Content-Disposition and Content-Type
+            if header.lower().startswith("content-disposition: form-data;"):
+                # Iterate over the content disposition parameters to get the form name and
+                # filename
+                for parameter in header.split(";")[1:]:
+                    parameter_name, parameter_value = parameter.strip().split("=")
+
+                    # Strip the quotes from the value
+                    parameter_value = parameter_value[1:-1]
+
+                    if parameter_name == "name":
+                        name = parameter_value
+                    elif parameter_name == "filename":
+                        filename = parameter_value
+            elif header.lower().startswith("content-type"):
+                # Files will have a content type, so grab it
+                content_type = header.split(":")[1].strip()
+
+        if not name or not value:
+            raise RuntimeError("Invalid multipart/form-data request body")
+
+        # Strip off the trailing newline characters from the value
+        value = value[:-2]
+
+        # Now we have all the data, so append it to the list of form data
+        if filename:
+            # Because a filename was provided, we know it's a file and not a simple string value
+            form_data.append(
+                (
+                    name,
+                    FileFormPart(
+                        name=name, filename=filename, content=value, content_type=content_type
+                    ),
+                )
+            )
+        else:
+            # Decode the string before adding it
+            form_data.append((name, StringFormPart(name, value.decode())))
+
+    return MultiDict(form_data)
+
+
 class Request:
     """Request class for incoming requests to the API."""
 
@@ -38,10 +167,21 @@ class Request:
         self.path = event.context["path"]
         self.query_string = event.context["query_string"]
         self._body = event.context["body"]
-        self.headers: CaseInsensitiveDict = CaseInsensitiveDict(event.context["headers"])
-
-        self.query_params = parse_qs(self.query_string)
-        self.content_type = self.headers.get("Content-Type")
+        self.headers = CaseInsensitiveMultiDict(separate_headers(event.context["headers"]))
+
+        self.query_params = MultiDict(parse_qsl(self.query_string))
+
+        # Parse the content type and any included content type parameters
+        content_type = self.headers.get("Content-Type")
+        self._content_type_parameters = {}
+        if content_type:
+            content_type, *parameters = content_type.split(";")
+            self.content_type = content_type.strip()
+            for parameter in parameters:
+                name, value = parameter.strip().split("=")
+                self._content_type_parameters[name] = value
+        else:
+            self.content_type = None
 
     @cached_property
     def body(self) -> bytes:
@@ -49,13 +189,31 @@ class Request:
         return b64decode(self._body)
 
     def json(self) -> JSON:
-        """Return the response JSON."""
+        """Return the response body as a JSON dict."""
         return json.loads(self.body)
 
     def text(self) -> str:
         """Return the response body as plain text."""
         return self.body.decode()
 
+    def form_data(self) -> MultiDict[str, FormPart]:
+        """Return the response body as a dict of string to list of FormPart objects."""
+        form_data: MultiDict[str, FormPart]
+
+        if self.content_type == "application/x-www-form-urlencoded":
+            # For request bodies that are URL-encoded, just parse them and return them as simple
+            # form parts
+            form_data = MultiDict(
+                (name, StringFormPart(name, value)) for name, value in parse_qsl(self.body.decode())
+            )
+        elif self.content_type == "multipart/form-data":
+            # Parse request bodies that are multipart forms
+            form_data = parse_multipart_form(self.body, self._content_type_parameters["boundary"])
+        else:
+            raise RuntimeError(f"Cannot parse content type {self.content_type} as form data")
+
+        return form_data
+
 
 SimpleAPIType = TypeVar("SimpleAPIType", bound="SimpleAPIBase")
 
@@ -108,20 +266,23 @@ class SimpleAPIBase(BaseHandler, ABC):
         EventType.Name(EventType.SIMPLE_API_REQUEST),
     ]
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(*args, **kwargs)
+    _ROUTES: ClassVar[dict[tuple[str, str], RouteHandler]]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
 
         # Build the registry of routes so that requests can be routed to the correct handler. This
-        # is done by iterating over the methods on the class instance and looking for methods that
-        # have been marked by the handler decorators (get, post, etc.).
-        self._routes: dict[tuple[str, str], Callable] = {}
-        for attr in self.__class__.__dict__.values():
+        # is done by iterating over the methods on the class and looking for methods that have been
+        # marked by the handler decorators (get, post, etc.).
+        cls._ROUTES = {}
+        for attr in cls.__dict__.values():
             if callable(attr) and (route := getattr(attr, "route", None)):
                 method, relative_path = route
-                path = f"{self._path_prefix()}{relative_path}"
-                self._routes[(method, path)] = attr
+                path = f"{cls._path_prefix()}{relative_path}"
+                cls._ROUTES[(method, path)] = attr
 
-    def _path_prefix(self) -> str:
+    @classmethod
+    def _path_prefix(cls) -> str:
         return ""
 
     @cached_property
@@ -174,7 +335,7 @@ class SimpleAPIBase(BaseHandler, ABC):
     def _handle_request(self) -> list[Effect]:
         """Route the incoming request to the handler method based on the HTTP method and path."""
         # Get the handler method
-        handler = self._routes[(self.request.method, self.request.path)]
+        handler = self._ROUTES[(self.request.method, self.request.path)]
 
         # Handle the request
         effects = handler(self)
@@ -191,7 +352,7 @@ class SimpleAPIBase(BaseHandler, ABC):
             if isinstance(effect, Response):
                 effects[index] = effect.apply()
 
-            if effects[index].type == EffectType.SIMPLE_API_RESPONSE:
+            if cast(Effect, effects[index]).type == EffectType.SIMPLE_API_RESPONSE:
                 # If a response has already been found, return an error response immediately
                 if response_found:
                     log.error(f"Multiple responses provided by {SimpleAPI.__name__} handler")
@@ -210,13 +371,13 @@ class SimpleAPIBase(BaseHandler, ABC):
                 # If the handler returned an error response, return only that response effect
                 # and omit any other included effects
                 if 400 <= status_code <= 599:
-                    return [effects[index]]
+                    return [cast(Effect, effects[index])]
 
-        return effects
+        return cast(list[Effect], effects)
 
     def accept_event(self) -> bool:
         """Ignore the event if the handler does not implement the route."""
-        return (self.request.method, self.request.path) in self._routes
+        return (self.request.method, self.request.path) in self._ROUTES
 
     def authenticate(self, credentials: Credentials) -> bool:
         """Method the user should override to authenticate requests."""
@@ -257,8 +418,12 @@ class SimpleAPI(SimpleAPIBase, ABC):
                     f"class attributes: {', '.join(f'{cls.__name__}.{name}' for name in names)}"
                 )
 
-    def _path_prefix(self) -> str:
-        return getattr(self, "PREFIX", None) or ""
+    @classmethod
+    def _path_prefix(cls) -> str:
+        # getattr needs a default else it will raise an exception. We also need to ensure that the
+        # final value is a string if the user specifies "None" as the prefix because this value gets
+        # prepended to the URL path
+        return getattr(cls, "PREFIX", "") or ""
 
 
 class SimpleAPIRoute(SimpleAPIBase, ABC):
@@ -271,8 +436,6 @@ class SimpleAPIRoute(SimpleAPIBase, ABC):
                 f"Setting a PREFIX value on a {SimpleAPIRoute.__name__} is not allowed"
             )
 
-        super().__init_subclass__(**kwargs)
-
         for attr_name, attr_value in cls.__dict__.items():
             decorator: Callable | None
             match attr_name:
@@ -307,6 +470,8 @@ class SimpleAPIRoute(SimpleAPIBase, ABC):
 
             decorator(path)(attr_value)
 
+        super().__init_subclass__(**kwargs)
+
     def get(self) -> list[Response | Effect]:
         """Stub method for GET handler."""
         return []

canvas-0.27.0/canvas_sdk/handlers/simple_api/tools.py

@@ -0,0 +1,115 @@
+from collections.abc import ItemsView, Iterable, Iterator, KeysView, Mapping, ValuesView
+from typing import Any, TypeVar, overload
+
+KeyType = TypeVar("KeyType")
+ValueType = TypeVar("ValueType", covariant=True)
+
+
+class MultiDict(Mapping[KeyType, ValueType]):
+    """Immutable key-value data structure that can store multiple values per key."""
+
+    def __init__(self, items: Iterable[tuple[KeyType, ValueType]] | None = None) -> None:
+        self._dict: dict[KeyType, ValueType] = {}
+        self._items = []
+        for key, value in items or ():
+            if key not in self._dict:
+                self._dict[key] = value
+            self._items.append((key, value))
+
+    def __len__(self) -> int:
+        return len(self._dict)
+
+    def __iter__(self) -> Iterator[KeyType]:
+        return iter(self.keys())
+
+    def __getitem__(self, key: KeyType, /) -> ValueType:
+        return self._dict[key]
+
+    def __contains__(self, x: object, /) -> bool:
+        return x in self._dict
+
+    @overload
+    def get(self, __key: KeyType, /) -> Any: ...
+
+    @overload
+    def get(self, __key: KeyType, /, __default: Any = None) -> Any: ...
+
+    def get(self, __key: KeyType, __default: Any | None = None) -> Any:
+        """Get a value for a key if present, and if not, return the default value."""
+        return self._dict.get(__key, __default)
+
+    def get_list(self, __key: KeyType) -> list[ValueType]:
+        """Get the values for a key if present, and if not, return an empty list."""
+        return [value for key, value in self._items if key == __key]
+
+    def items(self) -> ItemsView[KeyType, ValueType]:
+        """Return an items view of the dict."""
+        return self._dict.items()
+
+    def multi_items(self) -> Iterable[tuple[KeyType, ValueType]]:
+        """Return an iterable of tuples of the keys and values in the dict."""
+        yield from self._items
+
+    def keys(self) -> KeysView[KeyType]:
+        """Return a keys view of the dict."""
+        return self._dict.keys()
+
+    def __reversed__(self) -> Iterator[KeyType]:
+        return iter(reversed(list(self.keys())))
+
+    def values(self) -> ValuesView[ValueType]:
+        """Return a values view of the dict."""
+        return self._dict.values()
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, MultiDict):
+            return NotImplemented
+
+        return other._items == self._items
+
+
+class CaseInsensitiveMultiDict(MultiDict[str, ValueType]):
+    """
+    Case-insensitive immutable key-value data structure that can store multiple values per key.
+
+    Keys in the dict are interpreted in a case-insensitive manner.
+    """
+
+    def __init__(self, items: Iterable[tuple[str, ValueType]] | None = None) -> None:
+        super().__init__(((key.lower(), value) for key, value in items or ()))
+
+    def __getitem__(self, key: str, /) -> ValueType:
+        return super().__getitem__(key.lower())
+
+    def __contains__(self, x: object, /) -> bool:
+        if not isinstance(x, str):
+            return False
+
+        return super().__contains__(x.lower())
+
+    def get(self, __key: KeyType, __default: Any | None = None) -> Any:
+        """Get a value for a key if present, and if not, return the default value."""
+        if not isinstance(__key, str):
+            return __default
+
+        return super().get(__key.lower(), __default)
+
+    def get_list(self, __key: KeyType) -> list[ValueType]:
+        """Get the values for a key if present, and if not, return an empty list."""
+        if not isinstance(__key, str):
+            return []
+
+        return super().get_list(__key.lower())
+
+
+def separate_headers(headers: Mapping[str, str]) -> list[tuple[str, str]]:
+    """
+    Break apart header values containing comma-separated lists into discrete key-value pairs.
+    """
+    headers_list = []
+
+    for key, values in headers.items():
+        for value in values.split(","):
+            headers_list.append((key, value.strip()))
+
+    return headers_list