benchling-sdk 1.10.0a2__py3-none-any.whl → 1.10.0a3__py3-none-any.whl

benchling_sdk/apps/framework.py

@@ -1,44 +1,21 @@
 from __future__ import annotations
 
-import collections
-from typing import Dict, List, Optional, OrderedDict, Protocol, Tuple, TypeVar
-
-from benchling_api_client.v2.extensions import UnknownType
-from ordered_set import OrderedSet
-
-from benchling_sdk.apps import helpers
-from benchling_sdk.apps.config.errors import UnsupportedConfigItemError
-from benchling_sdk.apps.config.types import ConfigItemPath, ConfigurationReference
+from typing import Optional
+
+from benchling_sdk.apps.config.framework import BenchlingConfigProvider, ConfigItemStore
+from benchling_sdk.apps.status.framework import (
+    continue_session_context,
+    new_session_context,
+    SessionContextEnterHandler,
+    SessionContextExitHandler,
+    SessionContextManager,
+)
 from benchling_sdk.benchling import Benchling
 from benchling_sdk.helpers.logging_helpers import log_stability_warning, StabilityLevel
-from benchling_sdk.models import AppConfigItem, ListAppConfigurationItemsSort
 
 log_stability_warning(StabilityLevel.ALPHA)
 
 
-AppType = TypeVar("AppType", bound="App")
-
-
-class ConfigProvider(Protocol):
-    """
-    Config provider.
-
-    Provides a list of ConfigurationReference.
-    """
-
-    def config(self) -> List[ConfigurationReference]:
-        """Implement to provide a list of configuration items, for instance from Benchling APIs."""
-        pass
-
-
-class ConfigItemStoreProvider(Protocol):
-    """Return a config item store."""
-
-    def __call__(self, app_id: str) -> ConfigItemStore:
-        """Return a config item store."""
-        pass
-
-
 class App:
     """
     App.
@@ -88,220 +65,28 @@ class App:
         return self._config_store
 
     def create_session_context(
-        self: AppType,
+        self,
         name: str,
         timeout_seconds: int,
-        context_enter_handler: Optional[helpers.session_helpers.SessionContextEnterHandler[AppType]] = None,
-        context_exit_handler: Optional[helpers.session_helpers.SessionContextExitHandler[AppType]] = None,
-    ) -> helpers.session_helpers.SessionContextManager[AppType]:
+        context_enter_handler: Optional[SessionContextEnterHandler] = None,
+        context_exit_handler: Optional[SessionContextExitHandler] = None,
+    ) -> SessionContextManager:
         """
         Create Session Context.
 
         Create a new app session in Benchling.
         """
-        # Avoid circular import + MyPy "is not defined" if using relative like above
-        from benchling_sdk.apps.helpers.session_helpers import new_session_context
-
         return new_session_context(self, name, timeout_seconds, context_enter_handler, context_exit_handler)
 
     def continue_session_context(
-        self: AppType,
+        self,
         session_id: str,
-        context_enter_handler: Optional[helpers.session_helpers.SessionContextEnterHandler[AppType]] = None,
-        context_exit_handler: Optional[helpers.session_helpers.SessionContextExitHandler[AppType]] = None,
-    ) -> helpers.session_helpers.SessionContextManager[AppType]:
+        context_enter_handler: Optional[SessionContextEnterHandler] = None,
+        context_exit_handler: Optional[SessionContextExitHandler] = None,
+    ) -> SessionContextManager:
         """
         Continue Session Context.
 
         Fetch an existing app session from Benchling and enter a context with it.
         """
-        # Avoid circular import + MyPy "is not defined" if using relative like above
-        from benchling_sdk.apps.helpers.session_helpers import continue_session_context
-
         return continue_session_context(self, session_id, context_enter_handler, context_exit_handler)
-
-
-class BenchlingConfigProvider(ConfigProvider):
-    """
-    Benchling Config provider.
-
-    Provides a BenchlingAppConfiguration retrieved from Benchling's API.
-    """
-
-    _app_id: str
-    _benchling: Benchling
-
-    def __init__(self, benchling: Benchling, app_id: str):
-        """
-        Initialize Benchling Config Provider.
-
-        :param benchling_provider: A provider for a Benchling instance.
-        :param tenant_url_provider: A provider for a tenant url.
-        :param app_id: The app_id from which to retrieve configuration.
-        """
-        self._app_id = app_id
-        self._benchling = benchling
-
-    def config(self) -> List[ConfigurationReference]:
-        """Provide a Benchling app configuration from Benchling's APIs."""
-        app_pages = self._benchling.apps.list_app_configuration_items(
-            app_id=self._app_id,
-            page_size=100,
-            sort=ListAppConfigurationItemsSort.CREATEDATASC,
-        )
-
-        # Eager load all config items for now since we don't yet have a way of lazily querying by path
-        all_config_pages = list(app_pages)
-        # Punt on UnknownType for now as apps using manifests with new types + older client could lead to unpredictable results
-        all_config_items = [
-            _supported_config_item(config_item) for page in all_config_pages for config_item in page
-        ]
-
-        return all_config_items
-
-
-class StaticConfigProvider(ConfigProvider):
-    """
-    Static Config provider.
-
-    Provides a BenchlingAppConfiguration from a static declaration. Useful for mocking or testing.
-    """
-
-    _configuration_items: List[ConfigurationReference]
-
-    def __init__(self, configuration_items: List[ConfigurationReference]):
-        """
-        Initialize Static Config Provider.
-
-        :param configuration_items: The configuration items to return.
-        """
-        self._configuration_items = configuration_items
-
-    def config(self) -> List[ConfigurationReference]:
-        """Provide Benchling app configuration items from a static reference."""
-        return self._configuration_items
-
-
-class ConfigItemStore:
-    """
-    Dependency Link Store.
-
-    Marshalls an app configuration from the configuration provider into an indexable structure.
-    Only retrieves app configuration once unless its cache is invalidated.
-    """
-
-    _configuration_provider: ConfigProvider
-    _configuration: Optional[List[ConfigurationReference]] = None
-    _configuration_map: Optional[Dict[ConfigItemPath, ConfigurationReference]] = None
-    _array_path_row_names: Dict[Tuple[str, ...], OrderedSet[str]] = dict()
-
-    def __init__(self, configuration_provider: ConfigProvider):
-        """
-        Initialize Dependency Link Store.
-
-        :param configuration_provider: A ConfigProvider that will be invoked to provide the
-        underlying config from which to organize dependency links.
-        """
-        self._configuration_provider = configuration_provider
-        self._array_path_row_names = dict()
-
-    @property
-    def configuration(self) -> List[ConfigurationReference]:
-        """
-        Get the underlying configuration.
-
-        Return the raw, stored configuration. Can be used if the provided accessors are inadequate
-        to find particular configuration items.
-        """
-        if not self._configuration:
-            self._configuration = self._configuration_provider.config()
-        return self._configuration
-
-    @property
-    def configuration_path_map(self) -> Dict[ConfigItemPath, ConfigurationReference]:
-        """
-        Config links.
-
-        Return a map of configuration item paths to their corresponding configuration items.
-        """
-        if not self._configuration_map:
-            self._configuration_map = {tuple(item.path): item for item in self.configuration}
-        return self._configuration_map
-
-    def config_by_path(self, path: List[str]) -> Optional[ConfigurationReference]:
-        """
-        Config by path.
-
-        Find an app config item by its exact path match, if it exists. Does not search partial paths.
-        """
-        # Since we eager load all config now, we know that missing path means it's not configured in Benchling
-        # Later if we support lazy loading, we'll need to differentiate what's in our cache versus missing
-        return self.configuration_path_map.get(tuple(path))
-
-    def config_keys_by_path(self, path: List[str]) -> OrderedSet[str]:
-        """
-        Config keys by path.
-
-        Find a set of app config keys at the specified path, if any. Does not return keys that are nested
-        beyond the current level.
-
-        For instance, given paths:
-        ["One", "Two"]
-        ["One", "Two", "Three"]
-        ["One", "Two", "Four"]
-        ["One", "Two", "Three", "Five"]
-        ["Zero", "One", "Two", "Three"]
-
-        The expected return from this method when path=["One", "Two"] is a set {"Three", "Four"}.
-        """
-        # Convert path to tuple, as list is not hashable for dict keys
-        path_tuple = tuple(path)
-        if path_tuple not in self._array_path_row_names:
-            self._array_path_row_names[path_tuple] = OrderedSet(
-                [
-                    config_item.path[len(path)]
-                    # Use the list instead of configuration_map to preserve order
-                    for config_item in self.configuration
-                    # The +1 is the name of the array row
-                    if len(config_item.path) >= len(path) + 1
-                    # Ignoring flake8 error E203 because black keeps putting in whitespace padding :
-                    and config_item.path[0 : len(path_tuple)] == path  # noqa: E203
-                    and config_item.value is not None
-                ]
-            )
-        return self._array_path_row_names[path_tuple]
-
-    def array_rows_to_dict(self, path: List[str]) -> OrderedDict[str, Dict[str, ConfigurationReference]]:
-        """Given a path to the root of a config array, return each element as a named dict."""
-        # TODO BNCH-52772 Improve docstring if we keep this method
-        array_keys = self.config_keys_by_path(path)
-        # Although we don't have a way of preserving order when pulling array elements from the API right now
-        # we should intentionally order these to accommodate a potential ordered future
-        array_elements_map = collections.OrderedDict()
-        for key in array_keys:
-            # Don't care about order for the keys within a row, only the order of the rows themselves
-            array_elements_map[key] = {
-                array_element_key: self.config_by_path([*path, key, array_element_key])
-                for array_element_key in self.config_keys_by_path([*path, key])
-                if self.config_by_path([*path, key, array_element_key]) is not None
-            }
-        # TODO BNCH-52772 MyPy thinks the inner dict values can be None
-        return array_elements_map  # type: ignore
-
-    def invalidate_cache(self) -> None:
-        """
-        Invalidate Cache.
-
-        Will force retrieval of configuration from the ConfigProvider the next time the link store is accessed.
-        """
-        self._configuration = None
-        self._configuration_map = None
-        self._array_path_row_names = dict()
-
-
-def _supported_config_item(config_item: AppConfigItem) -> ConfigurationReference:
-    if isinstance(config_item, UnknownType):
-        raise UnsupportedConfigItemError(
-            f"Unable to read app configuration with unsupported type: {config_item}"
-        )
-    return config_item

benchling_sdk/apps/status/errors.py

@@ -0,0 +1,82 @@
+from typing import List, Union
+
+from benchling_sdk.models import AppSessionMessageCreate, AppSessionMessageStyle
+
+
+class SessionClosedError(Exception):
+    """
+    Session Closed Error.
+
+    A session was inoperable because its status in Benchling was terminal.
+    """
+
+    pass
+
+
+class SessionContextClosedError(Exception):
+    """
+    Session Context Closed Error.
+
+    An operation was attempted using the session context manager after it was closed.
+    """
+
+    pass
+
+
+class InvalidSessionTimeoutError(Exception):
+    """
+    Invalid Session Timeout Error.
+
+    A session's timeout value was set to an invalid value.
+    """
+
+    pass
+
+
+class MissingAttachedCanvasError(Exception):
+    """
+    Missing Attached Canvas Error.
+
+    A canvas operation was requested, but a session context has no attached canvas.
+    """
+
+    pass
+
+
+class AppUserFacingError(Exception):
+    """
+    App User Facing Error.
+
+    Extend this class with custom exceptions you want to be written back to the user as a SessionMessage.
+
+    SessionClosingContextExitHandler will invoke messages() and write them to a user. Callers choosing to
+    write their own SessionContextExitHandler may need to replicate this behavior themselves.
+
+    This is useful for control flow where an app wants to terminate with an error state that is resolvable
+    by the user.
+
+    For example:
+
+    class InvalidUserInputError(AppUserFacingError):
+        pass
+
+    raise InvalidUserInputError("Please enter a number between 1 and 10")
+
+    This would create a message shown to the user like:
+
+    AppSessionMessageCreate("Please enter a number between 1 and 10", style=AppSessionMessageStyle.ERROR)
+    """
+
+    _messages: List[str]
+
+    def __init__(self, messages: Union[str, List[str]], *args) -> None:
+        """Initialize an AppUserFacingError with one message or a list."""
+        self._messages = [messages] if isinstance(messages, str) else messages
+        super().__init__(args)
+
+    def messages(self) -> List[AppSessionMessageCreate]:
+        """Create a series of AppSessionMessageCreate to write to a Session and displayed to the user."""
+        return [
+            AppSessionMessageCreate(content=message, style=AppSessionMessageStyle.ERROR)
+            for message in self._messages
+        ]

benchling_sdk/apps/{helpers/session_helpers.py → status/framework.py}

@@ -3,15 +3,21 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from contextlib import AbstractContextManager
 from types import TracebackType
-from typing import cast, Generic, Iterable, List, Optional, Protocol, Type, Union
+from typing import cast, Iterable, List, Optional, Protocol, Type, TYPE_CHECKING, Union
 
 from benchling_api_client.v2.stable.types import Unset, UNSET
 
-from benchling_sdk.apps.framework import AppType
+from benchling_sdk.apps.status.errors import (
+    AppUserFacingError,
+    InvalidSessionTimeoutError,
+    MissingAttachedCanvasError,
+    SessionClosedError,
+    SessionContextClosedError,
+)
+from benchling_sdk.apps.status.types import _ReferencedSessionLinkType
 from benchling_sdk.errors import BenchlingError
 from benchling_sdk.helpers.logging_helpers import log_stability_warning, sdk_logger, StabilityLevel
 from benchling_sdk.models import (
-    AaSequence,
     AppCanvasUpdate,
     AppSession,
     AppSessionCreate,
@@ -22,132 +28,16 @@ from benchling_sdk.models import (
     AppSessionUpdateStatus,
     BadRequestError,
     BadRequestErrorBulkError,
-    Blob,
-    Box,
-    Container,
-    CustomEntity,
-    DnaOligo,
-    DnaSequence,
-    Entry,
-    Folder,
-    Location,
-    Mixture,
-    Molecule,
-    Plate,
-    Request,
-    RnaOligo,
-    RnaSequence,
-    WorkflowOutput,
-    WorkflowTask,
 )
 
-# Taken from CHIP_SUPPORTED_COLUMN_TYPES in Benchling server
-# Anything we miss, they can still embed the ID themselves in a message
-_ReferencedSessionLinkType = Union[
-    AaSequence,
-    Blob,
-    Box,
-    Container,
-    CustomEntity,
-    DnaSequence,
-    DnaOligo,
-    Entry,
-    Folder,
-    Location,
-    Mixture,
-    Plate,
-    RnaOligo,
-    Molecule,
-    RnaSequence,
-    Request,
-    WorkflowOutput,
-    WorkflowTask,
-]
+if TYPE_CHECKING:
+    from benchling_sdk.apps.framework import App
 
 _DEFAULT_APP_ERROR_MESSAGE = "An unexpected error occurred in the app"
 
 log_stability_warning(StabilityLevel.BETA)
 
 
-class SessionClosedError(Exception):
-    """
-    Session Closed Error.
-
-    A session was inoperable because its status in Benchling was terminal.
-    """
-
-    pass
-
-
-class SessionContextClosedError(Exception):
-    """
-    Session Context Closed Error.
-
-    An operation was attempted using the session context manager after it was closed.
-    """
-
-    pass
-
-
-class InvalidSessionTimeoutError(Exception):
-    """
-    Invalid Session Timeout Error.
-
-    A session's timeout value was set to an invalid value.
-    """
-
-    pass
-
-
-class MissingAttachedCanvasError(Exception):
-    """
-    Missing Attached Canvas Error.
-
-    A canvas operation was requested, but a session context has no attached canvas.
-    """
-
-    pass
-
-
-class AppUserFacingError(Exception):
-    """
-    App User Facing Error.
-
-    Extend this class with custom exceptions you want to be written back to the user as a SessionMessage.
-
-    SessionClosingContextExitHandler will invoke messages() and write them to a user. Callers choosing to
-    write their own SessionContextExitHandler may need to replicate this behavior themselves.
-
-    This is useful for control flow where an app wants to terminate with an error state that is resolvable
-    by the user.
-
-    For example:
-
-    class InvalidUserInputError(AppUserFacingError):
-        pass
-
-    raise InvalidUserInputError("Please enter a number between 1 and 10")
-
-    This would create a message shown to the user like:
-
-    AppSessionMessageCreate("Please enter a number between 1 and 10", style=AppSessionMessageStyle.ERROR)
-    """
-
-    _messages: List[str]
-
-    def __init__(self, messages: Union[str, List[str]], *args) -> None:
-        """Initialize an AppUserFacingError with one message or a list."""
-        self._messages = [messages] if isinstance(messages, str) else messages
-        super().__init__(args)
-
-    def messages(self) -> List[AppSessionMessageCreate]:
-        """Create a series of AppSessionMessageCreate to write to a Session and displayed to the user."""
-        return [
-            AppSessionMessageCreate(content=message, style=AppSessionMessageStyle.ERROR)
-            for message in self._messages
-        ]
-
-
 class SessionProvider(Protocol):
     """Provide a Benchling App Session to convey app status."""
 
@@ -181,7 +71,7 @@ class SessionContextErrorProcessor(ABC):
     @abstractmethod
     def process_error(
         cls,
-        context: SessionContextManager[AppType],
+        context: SessionContextManager,
         exc_type: Type[BaseException],
         exc_value: BaseException,
         exc_traceback: TracebackType,
@@ -220,7 +110,7 @@ class AppUserFacingErrorProcessor(SessionContextErrorProcessor):
     @classmethod
     def process_error(
         cls,
-        context: SessionContextManager[AppType],
+        context: SessionContextManager,
         exc_type: Type[BaseException],
         exc_value: BaseException,
         exc_traceback: TracebackType,
@@ -269,7 +159,7 @@ class BenchlingBadRequestErrorProcessor(AppUserFacingErrorProcessor):
     @classmethod
     def process_error(
         cls,
-        context: SessionContextManager[AppType],
+        context: SessionContextManager,
         exc_type: Type[BaseException],
         exc_value: BaseException,
         exc_traceback: TracebackType,
@@ -318,7 +208,7 @@ class BenchlingBadRequestErrorProcessor(AppUserFacingErrorProcessor):
         return messages
 
 
-class SessionContextEnterHandler(ABC, Generic[AppType]):
+class SessionContextEnterHandler(ABC):
     """
     Session Context Enter Handler.
 
@@ -326,12 +216,12 @@ class SessionContextEnterHandler(ABC, Generic[AppType]):
     """
 
     @abstractmethod
-    def on_enter(self, context: SessionContextManager[AppType]) -> None:
+    def on_enter(self, context: SessionContextManager) -> None:
         """Perform on session context enter after a Session has been started with Benchling."""
         pass
 
 
-class SessionContextExitHandler(ABC, Generic[AppType]):
+class SessionContextExitHandler(ABC):
     """
     Session Context Exit Handler.
 
@@ -339,7 +229,7 @@ class SessionContextExitHandler(ABC, Generic[AppType]):
     """
 
     @abstractmethod
-    def on_success(self, context: SessionContextManager[AppType]) -> bool:
+    def on_success(self, context: SessionContextManager) -> bool:
         """
         Perform on session context exit when no errors are present.
 
@@ -354,7 +244,7 @@ class SessionContextExitHandler(ABC, Generic[AppType]):
     @abstractmethod
     def on_error(
         self,
-        context: SessionContextManager[AppType],
+        context: SessionContextManager,
         exc_type: Type[BaseException],
         exc_value: BaseException,
         exc_traceback: TracebackType,
@@ -412,7 +302,7 @@ class SessionClosingContextExitHandler(SessionContextExitHandler):
         self._error_messages = error_messages
         self._error_processors = error_processors
 
-    def on_success(self, context: SessionContextManager[AppType]) -> bool:
+    def on_success(self, context: SessionContextManager) -> bool:
         """
         Close Active Session on Success.
 
@@ -443,7 +333,7 @@ class SessionClosingContextExitHandler(SessionContextExitHandler):
 
     def on_error(
         self,
-        context: SessionContextManager[AppType],
+        context: SessionContextManager,
         exc_type: Type[BaseException],
         exc_value: BaseException,
         exc_traceback: TracebackType,
@@ -497,7 +387,7 @@ class SessionClosingContextExitHandler(SessionContextExitHandler):
         return None
 
 
-def create_session_provider(app: AppType, name: str, timeout_seconds: int) -> SessionProvider:
+def create_session_provider(app: App, name: str, timeout_seconds: int) -> SessionProvider:
     """
     Create Session Provider.
 
@@ -512,7 +402,7 @@ def create_session_provider(app: AppType, name: str, timeout_seconds: int) -> Se
     return _new_session
 
 
-def existing_session_provider(app: AppType, session_id: str) -> SessionProvider:
+def existing_session_provider(app: App, session_id: str) -> SessionProvider:
     """
     Existing Session Provider.
 
@@ -537,7 +427,7 @@ def _ordered_messages(messages: Iterable[AppSessionMessageCreate]) -> List[AppSe
     return list(messages)
 
 
-class SessionContextManager(AbstractContextManager, Generic[AppType]):
+class SessionContextManager(AbstractContextManager):
     """
     Manage Benchling App Session.
 
@@ -546,19 +436,19 @@ class SessionContextManager(AbstractContextManager, Generic[AppType]):
     success_exit_handler.
     """
 
-    _app: AppType
+    _app: App
     _session_provider: SessionProvider
-    _context_enter_handler: Optional[SessionContextEnterHandler[AppType]]
-    _context_exit_handler: SessionContextExitHandler[AppType]
+    _context_enter_handler: Optional[SessionContextEnterHandler]
+    _context_exit_handler: SessionContextExitHandler
     _session: Optional[AppSession]
     _attached_canvas_id: Optional[str]
 
     def __init__(
         self,
-        app: AppType,
+        app: App,
         session_provider: SessionProvider,
-        context_enter_handler: Optional[SessionContextEnterHandler[AppType]] = None,
-        context_exit_handler: Optional[SessionContextExitHandler[AppType]] = None,
+        context_enter_handler: Optional[SessionContextEnterHandler] = None,
+        context_exit_handler: Optional[SessionContextExitHandler] = None,
     ):
         """
         Initialize SessionContextManager.
@@ -595,7 +485,7 @@ class SessionContextManager(AbstractContextManager, Generic[AppType]):
         return self._context_exit_handler.on_success(self)
 
     @property
-    def app(self) -> AppType:
+    def app(self) -> App:
         """Return the app for the session."""
         return self._app
 
@@ -759,12 +649,12 @@ class SessionContextManager(AbstractContextManager, Generic[AppType]):
 
 
 def new_session_context(
-    app: AppType,
+    app: App,
     name: str,
     timeout_seconds: int,
     context_enter_handler: Optional[SessionContextEnterHandler] = None,
     context_exit_handler: Optional[SessionContextExitHandler] = None,
-) -> SessionContextManager[AppType]:
+) -> SessionContextManager:
     """
     Create New Session Context.
 
@@ -779,11 +669,11 @@ def new_session_context(
 
 
 def continue_session_context(
-    app: AppType,
+    app: App,
     session_id: str,
     context_enter_handler: Optional[SessionContextEnterHandler] = None,
     context_exit_handler: Optional[SessionContextExitHandler] = None,
-) -> SessionContextManager[AppType]:
+) -> SessionContextManager:
     """
     Continue Session Context.