canvas 0.35.1__py3-none-any.whl → 0.36.0__py3-none-any.whl

canvas_sdk/caching/base.py

@@ -0,0 +1,127 @@
+from collections.abc import Iterable
+from typing import Any
+
+from django.core.cache import BaseCache
+
+from canvas_sdk.caching.exceptions import CachingException
+from canvas_sdk.caching.utils import WriteOnceProperty
+
+
+class Cache:
+    """A Class wrapper for interacting with cache."""
+
+    _connection = WriteOnceProperty[BaseCache]()
+    _prefix = WriteOnceProperty[str]()
+    _max_timeout_seconds = WriteOnceProperty[int | None]()
+
+    def __init__(
+        self, connection: BaseCache, prefix: str = "", max_timeout_seconds: int | None = None
+    ) -> None:
+        self._connection = connection
+        self._prefix = prefix
+        self._max_timeout_seconds = max_timeout_seconds
+
+    def _make_key(self, key: str) -> str:
+        return f"{self._prefix}:{key}" if self._prefix else key
+
+    def _get_timeout(self, timeout_seconds: int | None) -> int | None:
+        if timeout_seconds is None:
+            return self._max_timeout_seconds
+
+        if self._max_timeout_seconds is not None and timeout_seconds > self._max_timeout_seconds:
+            raise CachingException(
+                f"Timeout of {timeout_seconds} seconds exceeds the max timeout of {self._max_timeout_seconds} seconds."
+            )
+
+        return timeout_seconds
+
+    def set(self, key: str, value: Any, timeout_seconds: int | None = None) -> None:
+        """Set a value in the cache.
+
+        Args:
+            key: The cache key.
+            value: The value to cache.
+            timeout_seconds: The number of seconds for which the value should be cached.
+        """
+        key = self._make_key(key)
+        self._connection.set(key, value, self._get_timeout(timeout_seconds))
+
+    def set_many(self, data: dict[str, Any], timeout_seconds: int | None = None) -> list[str]:
+        """Set multiple values in the cache simultaneously.
+
+        Args:
+            data: A dict of cache keys and their values.
+            timeout_seconds: The number of seconds for which to cache the data.
+
+        Returns:
+            Returns a list of cache keys that failed insertion if supported by
+            the backend. Otherwise, an empty list is returned.
+        """
+        data = {self._make_key(key): value for key, value in data.items()}
+        return self._connection.set_many(data, self._get_timeout(timeout_seconds))
+
+    def get(self, key: str, default: Any | None = None) -> Any:
+        """Fetch a given key from the cache.
+
+        Args:
+            key: The cache key.
+            default: The value to return if the key does not exist.
+
+        Returns:
+            The cached value, or the default if the key does not exist.
+        """
+        key = self._make_key(key)
+        return self._connection.get(key, default)
+
+    def get_or_set(
+        self, key: str, default: Any | None = None, timeout_seconds: int | None = None
+    ) -> Any:
+        """Fetch a given key from the cache, or set it to the given default.
+
+        If the key does not exist, it will be created with the given default as
+        its value. If the default is a callable, it will be called with no
+        arguments and the return value will be used.
+
+        Args:
+            key: The key to retrieve.
+            default: The default value to set if the key does not exist. May be
+                     a callable with no arguments.
+            timeout_seconds: The number of seconds for which to cache the key.
+
+        Returns:
+            The cached value.
+        """
+        key = self._make_key(key)
+        return self._connection.get_or_set(key, default, self._get_timeout(timeout_seconds))
+
+    def get_many(self, keys: Iterable[str]) -> Any:
+        """Fetch multiple values from the cache.
+
+        This is often much faster than retrieving cached values individually,
+        and its use is encouraged where possible.
+
+        Args:
+            keys: The cache keys to retrieve.
+
+        Returns:
+            A dict mapping each key in 'keys' to its cached value.
+        """
+        keys = {self._make_key(key) for key in keys}
+        return self._connection.get_many(keys)
+
+    def delete(self, key: str) -> None:
+        """Delete a key from the cache.
+
+        Args:
+            key: The key to be removed from the cache.
+        """
+        key = self._make_key(key)
+        self._connection.delete(key)
+
+    def __contains__(self, key: str) -> bool:
+        """Return True if the key is in the cache and has not expired."""
+        key = self._make_key(key)
+        return self._connection.__contains__(key)
+
+
+__exports__ = ()

canvas_sdk/caching/client.py

@@ -0,0 +1,24 @@
+from django.core.cache import InvalidCacheBackendError
+from django.core.cache import caches as django_caches
+
+from canvas_sdk.caching.base import Cache
+from canvas_sdk.caching.exceptions import CacheConfigurationError
+
+caches: dict[tuple[str, str], Cache] = {}
+
+
+def get_cache(
+    driver: str = "default", prefix: str = "", max_timeout_seconds: int | None = None
+) -> Cache:
+    """Get the cache client based on the specified driver."""
+    try:
+        key = (driver, prefix)
+        connection = django_caches[driver]
+        if key not in caches:
+            caches[key] = Cache(connection, prefix, max_timeout_seconds)
+        return caches[key]
+    except InvalidCacheBackendError as error:
+        raise CacheConfigurationError(driver) from error
+
+
+__exports__ = ()

canvas_sdk/caching/exceptions.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+
+class CachingException(Exception):
+    """A Generic Exception for the module."""
+
+
+class CacheConfigurationError(CachingException):
+    """An Exception raised when cache driver doesn't exist."""
+
+    driver: str
+
+    def __init__(self, driver: str, *args: Any):
+        super().__init__(args)
+        self.driver = driver
+
+    def __str__(self) -> str:
+        return f"The cache driver {self.driver} does not exist"
+
+
+__exports__ = ("CachingException", "CacheConfigurationError")

canvas_sdk/caching/plugins.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from canvas_sdk.caching.client import get_cache as get_cache_client
+from canvas_sdk.utils.plugins import plugin_only
+from settings import CANVAS_SDK_CACHE_TIMEOUT_SECONDS
+
+if TYPE_CHECKING:
+    from canvas_sdk.caching.base import Cache
+
+
+@plugin_only
+def get_cache(**kwargs: Any) -> Cache:
+    """Get the cache client for plugins."""
+    prefix = kwargs["plugin_name"]
+    return get_cache_client("plugins", prefix, CANVAS_SDK_CACHE_TIMEOUT_SECONDS)
+
+
+__exports__ = ("get_cache",)

canvas_sdk/caching/utils.py

@@ -0,0 +1,28 @@
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class WriteOnceProperty(Generic[T]):
+    """A descriptor for write-once values."""
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        """Set the name of the property so that the descriptor can access it."""
+        self.public_name = name
+        self.private_name = f"_{name}"
+
+    def __get__(self, obj: Any, objtype: Any = None) -> T:
+        """Retrieve the value of the property."""
+        return getattr(obj, self.private_name)
+
+    def __set__(self, obj: Any, value: T) -> None:
+        """Set the value of the property.
+
+        Throws an AttributeError if the property already has a value.
+        """
+        if hasattr(obj, self.private_name):
+            raise AttributeError(f"{self.public_name} cannot be changed.")
+        setattr(obj, self.private_name, value)
+
+
+__exports__ = ()

canvas_sdk/commands/__init__.py

@@ -1,6 +1,7 @@
 from canvas_sdk.commands.commands.adjust_prescription import AdjustPrescriptionCommand
 from canvas_sdk.commands.commands.allergy import AllergyCommand
 from canvas_sdk.commands.commands.assess import AssessCommand
+from canvas_sdk.commands.commands.chart_section_review import ChartSectionReviewCommand
 from canvas_sdk.commands.commands.close_goal import CloseGoalCommand
 from canvas_sdk.commands.commands.diagnose import DiagnoseCommand
 from canvas_sdk.commands.commands.exam import PhysicalExamCommand
@@ -39,6 +40,7 @@ __all__ = __exports__ = (
     "AdjustPrescriptionCommand",
     "AllergyCommand",
     "AssessCommand",
+    "ChartSectionReviewCommand",
     "CloseGoalCommand",
     "DiagnoseCommand",
     "FamilyHistoryCommand",

canvas_sdk/commands/commands/chart_section_review.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+from canvas_sdk.commands.base import _BaseCommand
+
+
+class ChartSectionReviewCommand(_BaseCommand):
+    """A class for managing a Chart Section Review command within a specific note."""
+
+    class Meta:
+        key = "chartSectionReview"
+
+    class Sections(Enum):
+        CONDITIONS = "conditions"
+        SURGICAL_HISTORY = "surgical_history"
+        MEDICATIONS = "medications"
+        FAMILY_HISTORY = "family_histories"
+        ALLERGIES = "allergies"
+        IMMUNIZATIONS = "immunizations"
+
+    section: Sections
+
+
+__exports__ = ("ChartSectionReviewCommand",)

canvas_sdk/effects/launch_modal.py

@@ -17,6 +17,7 @@ class LaunchModalEffect(_BaseEffect):
         NEW_WINDOW = "new_window"
         RIGHT_CHART_PANE = "right_chart_pane"
         RIGHT_CHART_PANE_LARGE = "right_chart_pane_large"
+        PAGE = "page"
 
     url: str | None = None
     content: str | None = None

canvas_sdk/effects/simple_api.py

@@ -1,11 +1,13 @@
 import json
+import re
 from base64 import b64encode
 from collections.abc import Mapping, Sequence
 from http import HTTPStatus
 from typing import Any
 
-from canvas_generated.messages.effects_pb2 import EffectType
-from canvas_sdk.effects import Effect, _BaseEffect
+from pydantic_core import InitErrorDetails
+
+from canvas_sdk.effects import Effect, EffectType, _BaseEffect
 
 JSON = Mapping[str, "JSON"] | Sequence["JSON"] | int | float | str | bool | None
 
@@ -83,10 +85,67 @@ class HTMLResponse(Response):
         super().__init__(content.encode(), status_code, headers, content_type="text/html")
 
 
+class AcceptConnection(_BaseEffect):
+    """AcceptConnection effect."""
+
+    class Meta:
+        effect_type = EffectType.SIMPLE_API_WEBSOCKET_ACCEPT
+
+
+class DenyConnection(_BaseEffect):
+    """DenyConnection effect."""
+
+    message: str | None = None
+
+    class Meta:
+        effect_type = EffectType.SIMPLE_API_WEBSOCKET_DENY
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Make the payload."""
+        return {"message": self.message} if self.message else {}
+
+
+class Broadcast(_BaseEffect):
+    """Broadcast effect."""
+
+    class Meta:
+        effect_type = EffectType.SIMPLE_API_WEBSOCKET_BROADCAST
+
+    channel: str
+    message: dict[str, Any]
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """Make the payload."""
+        return {"channel": self.channel, "message": self.message}
+
+    def is_valid_channel_name(self) -> bool:
+        """Check if the channel name is valid."""
+        return re.fullmatch(r"\w+", self.channel) is not None
+
+    def _get_error_details(self, method: Any) -> list[InitErrorDetails]:
+        errors = super()._get_error_details(method)
+
+        if not self.is_valid_channel_name():
+            errors.append(
+                self._create_error_detail(
+                    "value",
+                    "Invalid channel name. Channel name must be alphanumeric and can contain underscores.",
+                    self.channel,
+                )
+            )
+
+        return errors
+
+
 __exports__ = (
     "JSON",
     "Response",
     "JSONResponse",
     "PlainTextResponse",
     "HTMLResponse",
+    "AcceptConnection",
+    "DenyConnection",
+    "Broadcast",
 )

canvas_sdk/handlers/simple_api/websocket.py

@@ -0,0 +1,79 @@
+import traceback
+from abc import ABC
+from functools import cached_property
+from typing import ClassVar
+
+import sentry_sdk
+
+from canvas_sdk.effects import Effect
+from canvas_sdk.effects.simple_api import AcceptConnection, DenyConnection
+from canvas_sdk.events import Event, EventType
+from canvas_sdk.handlers.base import BaseHandler
+from logger import log
+
+from .exceptions import AuthenticationError, InvalidCredentialsError
+from .tools import CaseInsensitiveMultiDict, separate_headers
+
+
+class WebSocket:
+    """WebSocket class for incoming requests to the WebSocketAPI."""
+
+    def __init__(self, event: Event) -> None:
+        self.channel = event.context["channel_name"]
+        self.headers = CaseInsensitiveMultiDict(separate_headers(event.context["headers"]))
+        self.api_key = self.headers.get("authorization")
+        self.logged_in_user = (
+            {
+                "id": self.headers.get("canvas-logged-in-user-id", ""),
+                "type": self.headers.get("canvas-logged-in-user-type", ""),
+            }
+            if "canvas-logged-in-user-id" in self.headers
+            else None
+        )
+
+
+class WebSocketAPI(BaseHandler, ABC):
+    """Abstract base class for WebSocket APIs."""
+
+    RESPONDS_TO: ClassVar[list[str]] = [
+        EventType.Name(EventType.SIMPLE_API_WEBSOCKET_AUTHENTICATE),
+    ]
+
+    @cached_property
+    def websocket(self) -> WebSocket:
+        """Return the WebSocket object for the event."""
+        return WebSocket(self.event)
+
+    def compute(self) -> list[Effect]:
+        """Handle WebSocket authenticate event."""
+        try:
+            if self.event.type == EventType.SIMPLE_API_WEBSOCKET_AUTHENTICATE:
+                return self._authenticate()
+            else:
+                raise AssertionError(f"Cannot handle event type {EventType.Name(self.event.type)}")
+        except Exception as exception:
+            for error_line_with_newlines in traceback.format_exception(exception):
+                for error_line in error_line_with_newlines.split("\n"):
+                    log.error(error_line)
+
+            sentry_sdk.capture_exception(exception)
+
+            return [DenyConnection(message="Internal server error").apply()]
+
+    def _authenticate(self) -> list[Effect]:
+        """Authenticate the WebSocket request."""
+        try:
+            if self.authenticate():
+                return [AcceptConnection().apply()]
+            else:
+                raise InvalidCredentialsError
+
+        except AuthenticationError:
+            return [DenyConnection(message="Unauthorized").apply()]
+
+    def authenticate(self) -> bool:
+        """Override to implement authentication."""
+        return False
+
+
+__exports__ = ("WebSocketAPI", "WebSocket")

canvas_sdk/value_set/custom.py

@@ -1058,4 +1058,4 @@ class DiabetesOtherClassConditionSuspect(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/allergy.py

@@ -234,4 +234,4 @@ class StatinAllergen(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/assessment.py

@@ -217,4 +217,4 @@ class HistoryOfHipFractureInParent(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/communication.py

@@ -327,4 +327,4 @@ class ConsultantReport(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/condition.py

@@ -40656,4 +40656,4 @@ class UrinaryRetention(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/device.py

@@ -176,4 +176,4 @@ class CardiacPacer(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/diagnostic_study.py

@@ -4969,4 +4969,4 @@ class DexaDualEnergyXrayAbsorptiometry_BoneDensityForUrologyCare(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/encounter.py

@@ -2566,4 +2566,4 @@ class HospitalServicesForUrologyCare(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/immunization.py

@@ -343,4 +343,4 @@ class PneumococcalPolysaccharide23Vaccine(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/individual_characteristic.py

@@ -315,4 +315,4 @@ class White(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/intervention.py

@@ -1334,4 +1334,4 @@ class ReferralsWhereWeightAssessmentMayOccur(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/laboratory_test.py

@@ -1252,4 +1252,4 @@ class HumanImmunodeficiencyVirusHivLaboratoryTestCodesAbAndAg(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/medication.py

@@ -5132,4 +5132,4 @@ class MedicationsForBelowNormalBmi(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/physical_exam.py

@@ -203,4 +203,4 @@ class BmiRatio(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

canvas_sdk/value_set/v2022/procedure.py

@@ -4041,4 +4041,4 @@ class FluorideVarnishApplicationForChildren(ValueSet):
     }
 
 
-__exports__ = get_overrides(locals().copy())
+__exports__ = get_overrides(locals())

plugin_runner/plugin_runner.py

@@ -32,6 +32,7 @@ from canvas_generated.services.plugin_runner_pb2_grpc import (
 from canvas_sdk.effects import Effect
 from canvas_sdk.effects.simple_api import Response
 from canvas_sdk.events import Event, EventRequest, EventResponse, EventType
+from canvas_sdk.handlers.simple_api.websocket import DenyConnection
 from canvas_sdk.protocols import ClinicalQualityMeasure
 from canvas_sdk.utils import metrics
 from canvas_sdk.utils.metrics import measured
@@ -180,7 +181,11 @@ class PluginRunner(PluginRunnerServicer):
                 plugin_name = event.target.id
                 # filter only for the plugin(s) that were created/updated
                 relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
-            elif event_type in {EventType.SIMPLE_API_AUTHENTICATE, EventType.SIMPLE_API_REQUEST}:
+            elif event_type in {
+                EventType.SIMPLE_API_AUTHENTICATE,
+                EventType.SIMPLE_API_REQUEST,
+                EventType.SIMPLE_API_WEBSOCKET_AUTHENTICATE,
+            }:
                 # The target plugin's name will be part of the home-app URL path, so other plugins that
                 # respond to SimpleAPI request events are not relevant
                 plugin_name = event.context["plugin_name"]
@@ -267,6 +272,15 @@ class PluginRunner(PluginRunnerServicer):
                         f" {event.context['path']}"
                     )
                     effect_list = [Response(status_code=HTTPStatus.INTERNAL_SERVER_ERROR).apply()]
+            if event.type == EventType.SIMPLE_API_WEBSOCKET_AUTHENTICATE:
+                if len(relevant_plugin_handlers) == 0:
+                    effect_list = [DenyConnection().apply()]
+                elif len(relevant_plugin_handlers) > 1:
+                    log.error(
+                        f"Multiple handlers responded to {EventType.Name(EventType.SIMPLE_API_WEBSOCKET_AUTHENTICATE)}"
+                        f" {event.context['channel']}"
+                    )
+                    effect_list = [DenyConnection().apply()]
 
             # Don't log anything if a plugin handler didn't actually run.
             if relevant_plugins:

plugin_runner/sandbox.py

@@ -81,6 +81,7 @@ SAFE_EXTERNAL_DUNDER_READ_ATTRIBUTES = {
 }
 
 CANVAS_TOP_LEVEL_MODULES = (
+    "canvas_sdk.caching",
     "canvas_sdk.commands",
     "canvas_sdk.effects",
     "canvas_sdk.events",

protobufs/canvas_generated/messages/effects.proto

@@ -233,6 +233,8 @@ enum EffectType {
   COMMIT_ADJUST_PRESCRIPTION_COMMAND = 1303;
   ENTER_IN_ERROR_ADJUST_PRESCRIPTION_COMMAND = 1304;
 
+  ORIGINATE_CHART_SECTION_REVIEW_COMMAND = 1400;
+
   SHOW_ACTION_BUTTON = 1000;
 
   PATIENT_PORTAL__FORM_RESULT = 2000;
@@ -260,6 +262,9 @@ enum EffectType {
   LAUNCH_MODAL = 3000;
 
   SIMPLE_API_RESPONSE = 4000;
+  SIMPLE_API_WEBSOCKET_ACCEPT = 4001;
+  SIMPLE_API_WEBSOCKET_DENY = 4002;
+  SIMPLE_API_WEBSOCKET_BROADCAST = 4003;
 
   UPDATE_USER = 5000;
 
@@ -268,6 +273,7 @@ enum EffectType {
   CREATE_SCHEDULE_EVENT = 6002;
 
   CREATE_PATIENT = 6003;
+
 }
 
 message Effect {

protobufs/canvas_generated/messages/events.proto

@@ -244,18 +244,12 @@ enum EventType {
   CANCEL_PRESCRIPTION__SELECTED_PRESCRIPTION__PRE_SEARCH = 8012;
   CANCEL_PRESCRIPTION__SELECTED_PRESCRIPTION__POST_SEARCH = 8013;
 
-  // CHART_SECTION_REVIEW_COMMAND__PRE_ORIGINATE = 9000;
-  // CHART_SECTION_REVIEW_COMMAND__POST_ORIGINATE = 9001;
-  // CHART_SECTION_REVIEW_COMMAND__PRE_UPDATE = 9002;
-  // CHART_SECTION_REVIEW_COMMAND__POST_UPDATE = 9003;
-  // CHART_SECTION_REVIEW_COMMAND__PRE_COMMIT = 9004;
-  // CHART_SECTION_REVIEW_COMMAND__POST_COMMIT = 9005;
-  // CHART_SECTION_REVIEW_COMMAND__PRE_DELETE = 9006;
-  // CHART_SECTION_REVIEW_COMMAND__POST_DELETE = 9007;
-  // CHART_SECTION_REVIEW_COMMAND__PRE_ENTER_IN_ERROR = 9008;
-  // CHART_SECTION_REVIEW_COMMAND__POST_ENTER_IN_ERROR = 9009;
-  // CHART_SECTION_REVIEW_COMMAND__PRE_EXECUTE_ACTION = 9010;
-  // CHART_SECTION_REVIEW_COMMAND__POST_EXECUTE_ACTION = 9011;
+  CHART_SECTION_REVIEW_COMMAND__PRE_ORIGINATE = 9000;
+  CHART_SECTION_REVIEW_COMMAND__POST_ORIGINATE = 9001;
+  CHART_SECTION_REVIEW_COMMAND__PRE_ENTER_IN_ERROR = 9002;
+  CHART_SECTION_REVIEW_COMMAND__POST_ENTER_IN_ERROR = 9003;
+  CHART_SECTION_REVIEW_COMMAND__PRE_EXECUTE_ACTION = 9004;
+  CHART_SECTION_REVIEW_COMMAND__POST_EXECUTE_ACTION = 9005;
 
 
   CLIPBOARD_COMMAND__PRE_ORIGINATE = 53000;
@@ -1093,6 +1087,8 @@ enum EventType {
 
   SIMPLE_API_AUTHENTICATE = 130000;
   SIMPLE_API_REQUEST = 130001;
+  SIMPLE_API_WEBSOCKET_AUTHENTICATE = 130002;
+
 }
 
 message Event {