trismik 0.9.0__py3-none-any.whl

trismik/__init__.py

@@ -0,0 +1,20 @@
+from .client import TrismikClient
+from .client_async import TrismikAsyncClient
+from .exceptions import (
+    TrismikError,
+    TrismikApiError
+)
+from .runner import TrismikRunner
+from .runner_async import TrismikAsyncRunner
+from .types import (
+    TrismikTest,
+    TrismikAuth,
+    TrismikSession,
+    TrismikItem,
+    TrismikMultipleChoiceTextItem,
+    TrismikChoice,
+    TrismikTextChoice,
+    TrismikResult,
+    TrismikResponse,
+    TrismikResultsAndResponses,
+)

trismik/_mapper.py

@@ -0,0 +1,79 @@
+from typing import List, Any
+
+from dateutil.parser import parse as parse_date
+
+from .exceptions import TrismikApiError
+from .types import (
+    TrismikItem,
+    TrismikResult,
+    TrismikMultipleChoiceTextItem,
+    TrismikTextChoice,
+    TrismikAuth,
+    TrismikTest,
+    TrismikSession,
+    TrismikResponse,
+)
+
+
+class TrismikResponseMapper:
+
+    @staticmethod
+    def to_auth(json: dict[str, Any]) -> TrismikAuth:
+        return TrismikAuth(
+                token=json["token"],
+                expires=parse_date(json["expires"]),
+        )
+
+    @staticmethod
+    def to_tests(json: List[dict[str, Any]]) -> List[TrismikTest]:
+        return [
+            TrismikTest(
+                    id=item["id"],
+                    name=item["name"],
+            ) for item in json
+        ]
+
+    @staticmethod
+    def to_session(json: dict[str, Any]) -> TrismikSession:
+        return TrismikSession(
+                id=json["id"],
+                url=json["url"],
+                status=json["status"],
+        )
+
+    @staticmethod
+    def to_item(json: dict[str, Any]) -> TrismikItem:
+        if json["type"] == "multiple_choice_text":
+            return TrismikMultipleChoiceTextItem(
+                    id=json["id"],
+                    question=json["question"],
+                    choices=[
+                        TrismikTextChoice(
+                                id=choice["id"],
+                                text=choice["text"],
+                        ) for choice in json["choices"]
+                    ]
+            )
+        else:
+            raise TrismikApiError(
+                    f"API has returned unrecognized item type: {json['type']}")
+
+    @staticmethod
+    def to_results(json: List[dict[str, Any]]) -> List[TrismikResult]:
+        return [
+            TrismikResult(
+                    trait=item["trait"],
+                    name=item["name"],
+                    value=item["value"],
+            ) for item in json
+        ]
+
+    @staticmethod
+    def to_responses(json: List[dict[str, Any]]) -> List[TrismikResponse]:
+        return [
+            TrismikResponse(
+                    item_id=response["itemId"],
+                    value=response["value"],
+                    score=response["score"],
+            ) for response in json
+        ]

trismik/_utils.py

@@ -0,0 +1,44 @@
+import os
+
+import httpx
+
+from .exceptions import TrismikError
+
+
+class TrismikUtils:
+
+    @staticmethod
+    def get_error_message(response: httpx.Response) -> str:
+        try:
+            return (response.json()).get("message", "Unknown error")
+        except (httpx.RequestError, ValueError):
+            error_message = response.content.decode("utf-8", errors="ignore")
+        return error_message
+
+    @staticmethod
+    def required_option(
+            value: str | None,
+            name: str,
+            env: str
+    ) -> str:
+        if value is None:
+            value = os.environ.get(env)
+        if value is None:
+            raise TrismikError(
+                    f"The {name} client option must be set either by passing "
+                    f"{env} to the client or by setting the {env} "
+                    "environment variable"
+            )
+        return value
+
+    @staticmethod
+    def option(
+            value: str | None,
+            default: str,
+            env: str,
+    ) -> str:
+        if value is None:
+            value = os.environ.get(env)
+        if value is None:
+            return default
+        return value

trismik/client.py

@@ -0,0 +1,274 @@
+from typing import List, Any, Optional
+
+import httpx
+
+from ._mapper import TrismikResponseMapper
+from ._utils import TrismikUtils
+from .exceptions import TrismikApiError
+from .types import (
+    TrismikTest,
+    TrismikAuth,
+    TrismikSession,
+    TrismikItem,
+    TrismikResult,
+    TrismikResponse,
+)
+
+
+class TrismikClient:
+    _serviceUrl: str = "https://trismik.e-psychometrics.com/api"
+
+    def __init__(
+            self,
+            service_url: Optional[str] = None,
+            api_key: Optional[str] = None,
+            http_client: Optional[httpx.Client] | None = None,
+    ) -> None:
+        """
+        Initializes a new Trismik client.
+
+        Args:
+            service_url (Optional[str]): URL of the Trismik service.
+            api_key (Optional[str]): API key for the Trismik service.
+            http_client (Optional[httpx.Client]): HTTP client to use for requests.
+
+        Raises:
+            TrismikError: If service_url or api_key are not provided and not found in environment.
+            TrismikApiError: If API request fails.
+        """
+        self._service_url = TrismikUtils.option(
+                service_url, self._serviceUrl, "TRISMIK_SERVICE_URL"
+        )
+        self._api_key = TrismikUtils.required_option(
+                api_key, "api_key", "TRISMIK_API_KEY"
+        )
+        self._http_client = http_client or httpx.Client(
+                base_url=self._service_url)
+
+    def authenticate(self) -> TrismikAuth:
+        """
+        Authenticates with the Trismik service.
+
+        Returns:
+            TrismikAuth: Authentication token.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/auth"
+            body = {"apiKey": self._api_key}
+            response = self._http_client.post(url, json=body)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_auth(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def refresh_token(self, token: str) -> TrismikAuth:
+        """
+        Refreshes the authentication token.
+
+        Args:
+            token (str): Current authentication token.
+
+        Returns:
+            TrismikAuth: New authentication token.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/token"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_auth(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def available_tests(self, token: str) -> List[TrismikTest]:
+        """
+        Retrieves a list of available tests.
+
+        Args:
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikTest]: List of available tests.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/tests"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_tests(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def create_session(self, test_id: str, token: str) -> TrismikSession:
+        """
+        Creates a new session for a test.
+
+        Args:
+            test_id (str): ID of the test.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikSession: New session
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/sessions"
+            headers = {"Authorization": f"Bearer {token}"}
+            body = {"testId": test_id, }
+            response = self._http_client.post(url, headers=headers, json=body)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_session(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def current_item(
+            self,
+            session_url: str,
+            token: str
+    ) -> TrismikItem:
+        """
+        Retrieves the current test item.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikItem: Current test item.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/item"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_item(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def respond_to_current_item(
+            self,
+            session_url: str,
+            value: Any,
+            token: str
+    ) -> TrismikItem | None:
+        """
+        Responds to the current test item.
+
+        Args:
+            session_url (str): URL of the session.
+            value (Any): Response value.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikItem | None: Next test item or None if session is finished.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/item"
+            body = {"value": value}
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.post(url, headers=headers, json=body)
+            response.raise_for_status()
+            if response.status_code == 204:
+                return None
+            else:
+                json = response.json()
+                return TrismikResponseMapper.to_item(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def results(self, session_url: str, token: str) -> List[TrismikResult]:
+        """
+        Retrieves the results of a session.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikResult]: Results of the session.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/results"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_results(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    def responses(self,
+            session_url: str,
+            token: str
+    ) -> List[TrismikResponse]:
+        """
+        Retrieves responses to session items.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikResponse]: Responses of the session.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/responses"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_responses(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e

trismik/client_async.py

@@ -0,0 +1,280 @@
+from typing import List, Any, Optional
+
+import httpx
+
+from ._mapper import TrismikResponseMapper
+from ._utils import TrismikUtils
+from .exceptions import TrismikApiError
+from .types import (
+    TrismikTest,
+    TrismikAuth,
+    TrismikSession,
+    TrismikItem,
+    TrismikResult,
+    TrismikResponse,
+)
+
+
+class TrismikAsyncClient:
+    _serviceUrl: str = "https://trismik.e-psychometrics.com/api"
+
+    def __init__(
+            self,
+            service_url: Optional[str] = None,
+            api_key: Optional[str] = None,
+            http_client: Optional[httpx.AsyncClient] | None = None,
+    ) -> None:
+        """
+        Initializes a new Trismik client (async version).
+
+        Args:
+            service_url (Optional[str]): URL of the Trismik service.
+            api_key (Optional[str]): API key for the Trismik service.
+            http_client (Optional[httpx.Client]): HTTP client to use for requests.
+
+        Raises:
+            TrismikError: If service_url or api_key are not provided and not found in environment.
+            TrismikApiError: If API request fails.
+        """
+        self._service_url = TrismikUtils.option(
+                service_url, self._serviceUrl, "TRISMIK_SERVICE_URL"
+        )
+        self._api_key = TrismikUtils.required_option(
+                api_key, "api_key", "TRISMIK_API_KEY"
+        )
+        self._http_client = http_client or httpx.AsyncClient(
+                base_url=self._service_url)
+
+    async def authenticate(self) -> TrismikAuth:
+        """
+        Authenticates with the Trismik service.
+
+        Returns:
+            TrismikAuth: Authentication token.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/auth"
+            body = {"apiKey": self._api_key}
+            response = await self._http_client.post(url, json=body)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_auth(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def refresh_token(self, token: str) -> TrismikAuth:
+        """
+        Refreshes the authentication token.
+
+        Args:
+            token (str): Current authentication token.
+
+        Returns:
+            TrismikAuth: New authentication token.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/token"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_auth(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def available_tests(self, token: str) -> List[TrismikTest]:
+        """
+        Retrieves a list of available tests.
+
+        Args:
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikTest]: List of available tests.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/tests"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_tests(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def create_session(self, test_id: str, token: str) -> TrismikSession:
+        """
+        Creates a new session for a test.
+
+        Args:
+            test_id (str): ID of the test.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikSession: New session
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = "/client/sessions"
+            headers = {"Authorization": f"Bearer {token}"}
+            body = {"testId": test_id}
+            response = await self._http_client.post(url, headers=headers,
+                                                    json=body)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_session(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def current_item(
+            self,
+            session_url: str,
+            token: str
+    ) -> TrismikItem:
+        """
+        Retrieves the current test item.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikItem: Current test item.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/item"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_item(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def respond_to_current_item(
+            self,
+            session_url: str,
+            value: Any,
+            token: str
+    ) -> TrismikItem | None:
+        """
+        Responds to the current test item.
+
+        Args:
+            session_url (str): URL of the session.
+            value (Any): Response value.
+            token (str): Authentication token.
+
+        Returns:
+            TrismikItem | None: Next test item or None if session is finished.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/item"
+            body = {"value": value}
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.post(
+                    url, headers=headers, json=body
+            )
+            response.raise_for_status()
+            if response.status_code == 204:
+                return None
+            else:
+                json = response.json()
+                return TrismikResponseMapper.to_item(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def results(self,
+            session_url: str,
+            token: str
+    ) -> List[TrismikResult]:
+        """
+        Retrieves the results of a session.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikResult]: Results of the session.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/results"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_results(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e
+
+    async def responses(self,
+            session_url: str,
+            token: str
+    ) -> List[TrismikResponse]:
+        """
+        Retrieves responses to session items.
+
+        Args:
+            session_url (str): URL of the session.
+            token (str): Authentication token.
+
+        Returns:
+            List[TrismikResponse]: Responses of the session.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        try:
+            url = f"{session_url}/responses"
+            headers = {"Authorization": f"Bearer {token}"}
+            response = await self._http_client.get(url, headers=headers)
+            response.raise_for_status()
+            json = response.json()
+            return TrismikResponseMapper.to_responses(json)
+        except httpx.HTTPStatusError as e:
+            raise TrismikApiError(
+                    TrismikUtils.get_error_message(e.response)) from e
+        except httpx.HTTPError as e:
+            raise TrismikApiError(str(e)) from e

trismik/exceptions.py

@@ -0,0 +1,13 @@
+class TrismikError(Exception):
+    """
+    Base class for all exceptions raised.
+    Raised when an error occurs in the Trismik package, i.e. configuration.
+    """
+    pass
+
+
+class TrismikApiError(TrismikError):
+    """
+    Raised when an error occurs while interacting with the Trismik API
+    """
+    pass

trismik/runner.py

@@ -0,0 +1,85 @@
+from datetime import datetime, timedelta
+from typing import List, Callable, Any, Optional
+
+from .client import TrismikClient
+from .types import (
+    TrismikAuth,
+    TrismikItem,
+    TrismikResult,
+    TrismikResultsAndResponses,
+)
+
+
+class TrismikRunner:
+    def __init__(
+            self,
+            item_processor: Callable[[TrismikItem], Any],
+            client: Optional[TrismikClient] = None,
+            auth: Optional[TrismikAuth] = None,
+    ) -> None:
+        """
+        Initializes a new Trismik runner.
+
+        Args:
+            item_processor (Callable[[TrismikItem], Any]): Function to process test items.
+            client (Optional[TrismikClient]): Trismik client to use for requests.
+            auth (Optional[TrismikAuth]): Authentication token to use for requests
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        self._item_processor = item_processor
+        self._client = client
+        self._auth = auth
+
+    def run(self,
+            test_id: str,
+            with_responses: bool = False,
+    ) -> List[TrismikResult] | TrismikResultsAndResponses:
+        """
+        Runs a test.
+
+        Args:
+            test_id (str): ID of the test to run.
+            with_responses (bool): If True, responses will be included with the results.
+
+        Returns:
+            List[TrismikResult] | TrismikResultsAndResponses: Either just test results, or with responses.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        self._init()
+        self._refresh_token_if_needed()
+        session = self._client.create_session(test_id, self._auth.token)
+        self._run_session(session.url)
+        results = self._client.results(session.url, self._auth.token)
+
+        if with_responses:
+            responses = self._client.responses(session.url, self._auth.token)
+            return TrismikResultsAndResponses(results, responses)
+        else:
+            return results
+
+    def _run_session(self, session_url: str) -> None:
+        item = self._client.current_item(session_url, self._auth.token)
+        while item is not None:
+            self._refresh_token_if_needed()
+            response = self._item_processor(item)
+            item = self._client.respond_to_current_item(
+                    session_url, response, self._auth.token
+            )
+
+    def _init(self) -> None:
+        if self._client is None:
+            self._client = TrismikClient()
+
+        if self._auth is None:
+            self._auth = self._client.authenticate()
+
+    def _refresh_token_if_needed(self) -> None:
+        if self._token_needs_refresh():
+            self._auth = self._client.refresh_token(self._auth.token)
+
+    def _token_needs_refresh(self) -> bool:
+        return self._auth.expires < (datetime.now() + timedelta(minutes=5))

trismik/runner_async.py

@@ -0,0 +1,87 @@
+from datetime import datetime, timedelta
+from typing import List, Callable, Any, Awaitable, Optional
+
+from .client_async import TrismikAsyncClient
+from .types import (
+    TrismikAuth,
+    TrismikItem,
+    TrismikResult,
+    TrismikResultsAndResponses,
+)
+
+
+class TrismikAsyncRunner:
+    def __init__(
+            self,
+            item_processor: Callable[[TrismikItem], Awaitable[Any]],
+            client: Optional[TrismikAsyncClient] = None,
+            auth: Optional[TrismikAuth] = None,
+    ) -> None:
+        """
+        Initializes a new Trismik runner (async version).
+
+        Args:
+            item_processor (Callable[[TrismikItem], Any]): Function to process test items.
+            client (Optional[TrismikClient]): Trismik client to use for requests.
+            auth (Optional[TrismikAuth]): Authentication token to use for requests
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        self._item_processor = item_processor
+        self._client = client
+        self._auth = auth
+
+    async def run(self,
+            test_id: str,
+            with_responses: bool = False,
+    ) -> List[TrismikResult] | TrismikResultsAndResponses:
+        """
+        Runs a test.
+
+        Args:
+            test_id (str): ID of the test to run.
+            with_responses (bool): If True, responses will be included with the results.
+
+        Returns:
+            List[TrismikResult] | TrismikResultsAndResponses: Either just test results, or with responses.
+
+        Raises:
+            TrismikApiError: If API request fails.
+        """
+        await self._init()
+        await self._refresh_token_if_needed()
+        session = await self._client.create_session(test_id, self._auth.token)
+        await self._run_session(session.url)
+        results = await self._client.results(session.url, self._auth.token)
+
+        if with_responses:
+            responses = await self._client.responses(session.url,
+                                                     self._auth.token)
+            return TrismikResultsAndResponses(results, responses)
+        else:
+            return results
+
+    async def _run_session(self, session_url: str) -> None:
+        await self._init()
+        await self._refresh_token_if_needed()
+        item = await self._client.current_item(session_url, self._auth.token)
+        while item is not None:
+            await self._refresh_token_if_needed()
+            response = await self._item_processor(item)
+            item = await self._client.respond_to_current_item(
+                    session_url, response, self._auth.token)
+
+    async def _init(self) -> None:
+        if self._client is None:
+            self._client = TrismikAsyncClient()
+
+        if self._auth is None:
+            self._auth = await self._client.authenticate()
+
+    async def _refresh_token_if_needed(self) -> None:
+        if self._token_needs_refresh():
+            self._auth = await self._client.refresh_token(self._auth.token)
+
+    def _token_needs_refresh(self) -> bool:
+        return self._auth.expires < (datetime.now() + timedelta(minutes=5))

trismik/types.py

@@ -0,0 +1,133 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List, Any
+
+
+@dataclass
+class TrismikAuth:
+    """
+    Authentication token.
+
+    Attributes:
+        token (str): Authentication token value.
+        expires (datetime): Expiration date.
+    """
+    token: str
+    expires: datetime
+
+
+@dataclass
+class TrismikTest:
+    """
+    Available test.
+
+    Attributes:
+        id (str): Test ID.
+        name (str): Test name.
+    """
+    id: str
+    name: str
+
+
+@dataclass
+class TrismikSession:
+    """
+    Test session.
+
+    Attributes:
+        id (str): Session ID.
+        url (str): Session URL.
+        status (str): Session status
+    """
+    id: str
+    url: str
+    status: str
+
+
+@dataclass
+class TrismikItem:
+    """
+    Base class for test items.
+
+    Attributes:
+        id (str): Item ID.
+    """
+    id: str
+
+
+@dataclass
+class TrismikChoice:
+    """
+    Base class for choices in items that use them.
+
+    Attributes:
+        id (str): Choice ID.
+    """
+    id: str
+
+
+@dataclass
+class TrismikTextChoice(TrismikChoice):
+    """
+    Text choice.
+
+    Attributes:
+        text (str): Choice text.
+    """
+    text: str
+
+
+@dataclass
+class TrismikMultipleChoiceTextItem(TrismikItem):
+    """
+    Multiple choice text item.
+
+    Attributes:
+        question (str): Question text.
+        choices (List[TrismikTextChoice]): List of choices.
+    """
+    question: str
+    choices: List[TrismikTextChoice]
+
+
+@dataclass
+class TrismikResult:
+    """
+    Test result.
+
+    Attributes:
+        trait (str): Trait name.
+        name (str): Result name/type.
+        value (Any): Result value.
+    """
+    trait: str
+    name: str
+    value: Any
+
+
+@dataclass
+class TrismikResponse:
+    """
+    Test result.
+
+    Attributes:
+        item_id (str): Item ID.
+        value (Any): Result value.
+        score (float): Score.
+    """
+    item_id: str
+    value: Any
+    score: float
+
+
+@dataclass
+class TrismikResultsAndResponses:
+    """
+    Test results and responses.
+
+    Attributes:
+        results (List[TrismikResult]): Results.
+        responses (List[TrismikResponse]): Responses.
+    """
+    results: List[TrismikResult]
+    responses: List[TrismikResponse]

trismik-0.9.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cambridge Enterprise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trismik-0.9.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: trismik
+Version: 0.9.0
+Summary: 
+Author: Bartosz Kielczewski
+Author-email: bk352@cam.ac.uk
+Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Description-Content-Type: text/markdown
+
+Trismik Python SDK
+==================
+
+This is the official Python SDK for Trismik. It provides a simple way to interact with the Trismik
+API.
+
+Usage
+-----
+
+1. ```pip install trismik```
+2. Set the following environment variable. Alternatively, put it into `.env` file
+   in the root of your project, and load them using `python-dotenv` package:
+
+   ```
+   TRISMIK_API_KEY=<api_key>
+   ```
+
+3. Refer to examples:
+   * [example_runner.py](./examples/example_runner.py) - run test using high-level `TrismikRunner`
+     class
+   * [example_runner_async.py](./examples/example_runner_async.py) - like above, but with async
+     support
+   * [example_client.py](./examples/example_client.py) - run test using `TrismikClient` directly
+   * [example_client_async.py](./examples/example_client_async.py) - like above, but with async
+     support
+
+Contributing
+------------
+
+1. Install [Python Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer)
+2. ```git clone https://github.com/trismik/trismik-python.git```, or if cloned previously:
+   ```git pull``` to update
+3. ```cd ./trismik-python```
+4. ```poetry install```
+5. ```poetry run pytest```
+
+Publishing to TestPyPi
+----------------------
+
+1. ```poetry config repositories.testpypi https://test.pypi.org/legacy/```
+2. ```poetry config pypi-token.testpypi <token>```
+3. ```poetry publish --build --repository testpypi```
+

trismik-0.9.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+trismik/__init__.py,sha256=DoKoJyAtB8C8La-Jjn8PS7uqIpGutWxeI48dIjhywPY,487
+trismik/_mapper.py,sha256=HX4pQw3pZKsiOwuIebLbDP9_aTO8E9tlsSjUhU9dQTQ,2359
+trismik/_utils.py,sha256=5_zRwgfF7flfU0shQm2BzT5A-coIV7MWeq_MoRmsoQc,1195
+trismik/client.py,sha256=nsYdMHtELlBiwzfh-ameSwlPd-4-vQPg9eP-gYxu5gA,9318
+trismik/client_async.py,sha256=vAByw1ZvxtrzQx-IQ9K-k71RimvceH6POiSJpSPZKB4,9564
+trismik/exceptions.py,sha256=QcAH95FeZNXl4eDTCvqq3OhHrK976de1wd7bNEIfa88,322
+trismik/runner.py,sha256=VwkNKVA9On8zqEclALR_ffkSSiyNfYHCmtgGm1ASMl4,2906
+trismik/runner_async.py,sha256=sXHyMrUHmJ5bsDUz3KpTIPEFQpWSTj0YpqRv8Qs9FuE,3181
+trismik/types.py,sha256=1oDZ5pIoDr8WvY0LquChiPbcdqMvFt4CfS5rZAR66EM,2318
+trismik-0.9.0.dist-info/LICENSE,sha256=EbaNeGU9EYIF6mQ0iI3nnJ9UwEMghRj8sRNdjNTq96g,1098
+trismik-0.9.0.dist-info/METADATA,sha256=32QHAFdQx8L3IG3PNjoojYtwJpINrlITkBKguhZDVFE,1970
+trismik-0.9.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+trismik-0.9.0.dist-info/RECORD,,

trismik-0.9.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any