kameleoon-client-python 3.20.0__tar.gz → 3.22.1__tar.gz

{kameleoon_client_python-3.20.0 → kameleoon_client_python-3.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kameleoon-client-python
-Version: 3.20.0
+Version: 3.22.1
 Summary: Kameleoon Client Python Software Development Kit.
 Home-page: https://developers.kameleoon.com/python-sdk.html
 Author: Kameleoon
@@ -20,27 +20,27 @@ Requires-Dist: requests<3.0.0,>=2.25
 Requires-Dist: sseclient-py<1.9.0,>=1.7.0
 Requires-Dist: aiohttp<4.0.0,>=3.8.0
 Provides-Extra: test
+Requires-Dist: types-python-dateutil==2.8.2; extra == "test"
 Requires-Dist: twine==3.4.1; extra == "test"
-Requires-Dist: pytest-django==4.4.0; extra == "test"
+Requires-Dist: sseclient-py<1.9.0,>=1.7.0; extra == "test"
+Requires-Dist: types-PyYAML==5.4.3; extra == "test"
+Requires-Dist: aiohttp<4.0.0,>=3.8.0; extra == "test"
+Requires-Dist: pyyaml<6.1.0,>=5.4.0; extra == "test"
+Requires-Dist: requests<3.0.0,>=2.25; extra == "test"
+Requires-Dist: pylint==2.12.*; extra == "test"
 Requires-Dist: pytest-pythonpath==0.7.3; extra == "test"
+Requires-Dist: pytest-django==4.5.2; extra == "test"
 Requires-Dist: flake8==4.0.1; extra == "test"
+Requires-Dist: pytest-cov==2.12.1; extra == "test"
 Requires-Dist: wheel==0.36.2; extra == "test"
-Requires-Dist: pytest-asyncio==0.21.*; extra == "test"
-Requires-Dist: aioresponses==0.7.*; extra == "test"
-Requires-Dist: requests<3.0.0,>=2.25; extra == "test"
-Requires-Dist: pyyaml<6.1.0,>=5.4.0; extra == "test"
-Requires-Dist: mypy==0.991; extra == "test"
-Requires-Dist: Werkzeug==2.0.1; extra == "test"
 Requires-Dist: freezegun==1.1.0; extra == "test"
-Requires-Dist: Django==3.2.4; extra == "test"
 Requires-Dist: types-requests==2.25.0; extra == "test"
-Requires-Dist: pytest-cov==2.12.1; extra == "test"
-Requires-Dist: pylint==2.12.*; extra == "test"
-Requires-Dist: types-PyYAML==5.4.3; extra == "test"
 Requires-Dist: pytest-ordering==0.6; extra == "test"
-Requires-Dist: aiohttp<4.0.0,>=3.8.0; extra == "test"
-Requires-Dist: types-python-dateutil==2.8.2; extra == "test"
-Requires-Dist: sseclient-py<1.9.0,>=1.7.0; extra == "test"
+Requires-Dist: aioresponses==0.7.*; extra == "test"
+Requires-Dist: mypy==0.991; extra == "test"
+Requires-Dist: Werkzeug==2.0.1; extra == "test"
+Requires-Dist: pytest-asyncio==0.21.*; extra == "test"
+Requires-Dist: Django==4.2.*; extra == "test"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

kameleoon_client_python-3.22.1/kameleoon/client_readiness/async_readiness.py

@@ -0,0 +1,43 @@
+"Async Client Readiness"
+
+import asyncio
+from typing import Optional
+
+from kameleoon.exceptions import Initialization
+from kameleoon.client_readiness.threading_readiness import ThreadingClientReadiness
+
+
+class AsyncClientReadiness:
+    """
+    A class that provides an asynchronous interface for checking client readiness.
+
+    This class wraps around a `ThreadingClientReadiness` object to provide asynchronous
+    methods for waiting for the client to be ready. Blocking waits are run in the
+    event loop's default executor so the loop is never blocked.
+    """
+
+    def __init__(self, inner: ThreadingClientReadiness) -> None:
+        """
+        Initializes an AsyncClientReadiness instance.
+        """
+        super().__init__()
+        self._inner = inner
+
+    @property
+    def inner(self) -> ThreadingClientReadiness:
+        """
+        Returns the inner ThreadingClientReadiness instance.
+        """
+        return self._inner
+
+    async def wait_with_timeout(self, timeout_second: float) -> Optional[Initialization]:
+        """
+        Asynchronously waits until the readiness state is settled, but no longer than
+        `timeout_second`. See `ThreadingClientReadiness.wait_with_timeout` for the
+        detailed contract.
+        """
+        # Non-blocking paths (already settled or expired timeout) are served inline.
+        if timeout_second <= 0:
+            return self._inner.wait_with_timeout(timeout_second)
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._inner.wait_with_timeout, timeout_second)

kameleoon_client_python-3.22.1/kameleoon/client_readiness/threading_readiness.py

@@ -0,0 +1,134 @@
+"""ThreadingClientReadiness"""
+from threading import Event, Lock
+from typing import Optional
+
+from kameleoon.exceptions import Initialization
+
+
+class _State:
+    """
+    A single settlement of the readiness state: `error` is written at most once,
+    before the event is set, and never changes afterwards, so a waiter which
+    obtained the state observes exactly the outcome it was registered for.
+    """
+
+    def __init__(self) -> None:
+        self._event = Event()
+        self.error: Optional[Initialization] = None
+
+    def settle(self) -> None:
+        """Settles the state, releasing all its waiters."""
+        self._event.set()
+
+    @property
+    def settled(self) -> bool:
+        """Returns whether the state is settled."""
+        return self._event.is_set()
+
+    def wait(self, timeout_second: float) -> bool:
+        """Returns whether the state was settled before the timeout elapsed."""
+        return self._event.wait(timeout_second)
+
+
+class ThreadingClientReadiness:
+    """
+    ThreadingClientReadiness tracks whether the SDK has successfully loaded its
+    configuration and exposes that state to `KameleoonClient.wait_init` and
+    `KameleoonClient.is_ready`:
+    - a successful fetch settles the state successfully;
+    - a failed fetch settles it with an `Initialization` error.
+
+    Readiness is monotonic: once the SDK is ready it stays ready, and a later failed
+    fetch can never revert it. A failure reported before the first success does not
+    prevent a subsequent successful retry from marking the SDK ready.
+
+    It is created on the thread that builds the client but settled from the
+    background thread(s) performing configuration fetches.
+    """
+
+    def __init__(self, site_code: str, environment: Optional[str]) -> None:
+        self._lock = Lock()
+        self._state = _State()
+        self._ready = False
+        self._site_code = site_code
+        self._environment = environment
+
+    @property
+    def ready(self) -> bool:
+        """
+        Returns `True` if the SDK has been successfully initialized, `False` otherwise
+        (including while the initialization is still pending or has failed).
+        It never blocks.
+
+        This is the per-request hot path, so it is lock-free: `_ready` is only ever
+        flipped False -> True (readiness is monotonic), making a plain attribute read
+        safe. At worst a reader briefly observes `False` while `mark_ready` is
+        completing, which is indistinguishable from calling a moment earlier.
+        """
+        return self._ready
+
+    def mark_ready(self) -> None:
+        """Marks the SDK ready and releases all waiters."""
+        with self._lock:
+            self._ready = True
+            if self._state.settled:
+                if self._state.error is not None:
+                    # Recovery after a failure: the failed state is left settled for its
+                    # waiters, and a fresh, ready state is published for the new ones.
+                    state = _State()
+                    state.settle()
+                    self._state = state
+            else:
+                self._state.settle()
+
+    def mark_not_ready(self, cause: Exception) -> None:
+        """
+        Reports a failed fetch with an `Initialization` error, but only while the SDK
+        is not yet ready. A failure never reverts an already-ready client and is
+        reported at most once, so the first reported cause is the one waiters observe.
+
+        :param cause: the failure which prevented the SDK from loading its configuration.
+        :type cause: Exception
+        """
+        with self._lock:
+            if not self._state.settled:
+                self._state.error = Initialization(self._site_code, self._environment, cause)
+                self._state.settle()
+            # else: already ready, or the failure was already reported
+
+    def wait_with_timeout(self, timeout_second: float) -> Optional[Initialization]:
+        """
+        Blocks until the readiness state is settled, but no longer than `timeout_second`.
+        Returns the result of the configuration fetch: `None` once the SDK is ready, or
+        the `Initialization` error the fetch failure was reported with (fail-fast - it
+        does not wait for background retries). If no fetch result is available within
+        the timeout, returns an `Initialization` error caused by the expired timeout.
+        A non-positive timeout expires immediately unless a result is already available.
+        An expired timeout does not settle the readiness state: once the SDK becomes
+        ready, a subsequent call returns `None`.
+
+        :param timeout_second: maximum number of seconds to wait.
+        :type timeout_second: float
+        :return: `None` if the SDK is ready, otherwise an `Initialization` error.
+        :rtype: Optional[Initialization]
+        """
+        state = self._current_state()
+        if state.settled:
+            return state.error
+        if timeout_second <= 0:
+            return self._timeout_failure(timeout_second)
+        if state.wait(timeout_second):
+            return state.error
+        return self._timeout_failure(timeout_second)
+
+    def _timeout_failure(self, timeout_second: float) -> Initialization:
+        # The timeout failure wraps a `TimeoutError` cause (the counterpart of the
+        # timeout error types the other SDKs report), so a caller can distinguish an
+        # expired timeout from a failed fetch.
+        cause = TimeoutError(f"initialization did not complete within {round(timeout_second * 1000)} ms")
+        return Initialization(self._site_code, self._environment, cause)
+
+    def _current_state(self) -> _State:
+        # Synchronized for safe publication of the state swapped in by a recovery.
+        with self._lock:
+            return self._state

{kameleoon_client_python-3.20.0 → kameleoon_client_python-3.22.1}/kameleoon/data/manager/visitor_manager.py

@@ -67,17 +67,15 @@ class VisitorManager:
             KameleoonLogger.debug("RETURN: VisitorManager.get_or_create_visitor(visitor_code: %s)", visitor_code)
 
     def peek_visitor(self, visitor_code: str) -> Optional[Visitor]:
-        """Retrieves a visitor by their code if it exists, otherwise returns `None`."""
-        KameleoonLogger.debug(f"CALL: VisitorManager.peekVisitor(visitor_code: {visitor_code})")
-        if (slot := self.__try_acquire_slot(visitor_code)) is None:
-            visitor = None
-        else:
-            try:
-                visitor = slot.visitor
-            finally:
-                slot.lock.release()
+        """
+        Retrieves a visitor by their code if it exists, otherwise returns `None`. Unlike `get_visitor`, does not
+        count as visitor activity and takes no lock: a plain read needs no protection against the purge.
+        """
+        KameleoonLogger.debug("CALL: VisitorManager.peek_visitor(visitor_code: %s)", visitor_code)
+        slot = self._slots.get(visitor_code)
+        visitor = slot.visitor if slot is not None else None
         KameleoonLogger.debug(
-            f"RETURN: VisitorManager.peekVisitor(visitor_code: {visitor_code}) -> " f"(visitor: {visitor})"
+            "RETURN: VisitorManager.peek_visitor(visitor_code: %s) -> (visitor: %s)", visitor_code, visitor
         )
         return visitor
 
@@ -180,7 +178,7 @@ class VisitorManager:
         while True:
             slot = self._slots[visitor_code]
             slot.lock.acquire()
-            if slot == self._slots.get(visitor_code):
+            if slot is self._slots.get(visitor_code):
                 return slot
             slot.lock.release()
 
@@ -190,7 +188,7 @@ class VisitorManager:
             if slot is None:
                 return None
             slot.lock.acquire()
-            if slot == self._slots.get(visitor_code):
+            if slot is self._slots.get(visitor_code):
                 return slot
             slot.lock.release()
 
@@ -199,7 +197,7 @@ class VisitorManager:
         if slot is None:
             return None
         slot.lock.acquire()
-        if slot == self._slots.get(visitor_code):
+        if slot is self._slots.get(visitor_code):
             return slot
         slot.lock.release()
         return None

kameleoon_client_python-3.22.1/kameleoon/events/__init__.py

@@ -0,0 +1,19 @@
+"""Kameleoon SDK events"""
+
+from kameleoon.events.data_file_update_event import DataFileUpdateEvent  # noqa: F401
+from kameleoon.events.data_file_update_handler import DataFileUpdateHandler  # noqa: F401
+from kameleoon.events.event_handler import EventHandler  # noqa: F401
+from kameleoon.events.event_type import EventType  # noqa: F401
+from kameleoon.events.http_request_failure import HttpRequestFailure  # noqa: F401
+from kameleoon.events.http_request_handler import HttpRequestHandler  # noqa: F401
+from kameleoon.events.request_type import RequestType  # noqa: F401
+
+__all__ = [
+    "DataFileUpdateEvent",
+    "DataFileUpdateHandler",
+    "EventHandler",
+    "EventType",
+    "HttpRequestFailure",
+    "HttpRequestHandler",
+    "RequestType",
+]

kameleoon_client_python-3.22.1/kameleoon/events/data_file_update_event.py

@@ -0,0 +1,33 @@
+"""Events"""
+from enum import Enum
+
+
+class DataFileUpdateEvent:
+    """Describes an update of the SDK data file (configuration) reported to `DataFileUpdateHandler`."""
+
+    class Source(Enum):
+        """Represents the source of a data file update."""
+
+        POLLING = "POLLING"
+        """The data file was updated by periodic polling."""
+
+        STREAMING = "STREAMING"
+        """The data file was updated by a real-time (streaming) notification."""
+
+    def __init__(self, source: "DataFileUpdateEvent.Source", date_modified: int) -> None:
+        """For internal use only."""
+        self.__source = source
+        self.__date_modified = date_modified
+
+    @property
+    def source(self) -> "DataFileUpdateEvent.Source":
+        """Returns the source of the data file update."""
+        return self.__source
+
+    @property
+    def date_modified(self) -> int:
+        """Returns the date of the last modification of the data file, in Unix time milliseconds."""
+        return self.__date_modified
+
+    def __str__(self) -> str:
+        return f"DataFileUpdateEvent{{Source:{self.__source.value},DateModified:{self.__date_modified}}}"

kameleoon_client_python-3.22.1/kameleoon/events/data_file_update_handler.py

@@ -0,0 +1,23 @@
+"""Events"""
+from typing import Protocol
+
+from kameleoon.events.data_file_update_event import DataFileUpdateEvent
+from kameleoon.events.event_handler import EventHandler
+
+
+class DataFileUpdateHandler(EventHandler, Protocol):
+    """
+    Handles `EventType.DATAFILE_UPDATE` SDK events.
+
+    Subclassing this protocol is optional: any object which provides the `on_update` method
+    is accepted by `KameleoonClient.set_event_handler`.
+    Static type checkers (e.g. mypy) verify such handlers structurally.
+    """
+
+    def on_update(self, update_event: DataFileUpdateEvent) -> None:
+        """
+        Called when the SDK data file (configuration) is updated.
+        :param update_event: The data file update details.
+        :type update_event: DataFileUpdateEvent
+        """
+        raise NotImplementedError()

kameleoon_client_python-3.22.1/kameleoon/events/event_handler.py

@@ -0,0 +1,13 @@
+"""Events"""
+from typing import Protocol
+
+
+class EventHandler(Protocol):  # pylint: disable=R0903
+    """
+    Base protocol for all SDK event handlers. See `EventType` for the supported
+    event types and their corresponding handler protocols.
+
+    Subclassing the handler protocols is optional: any object which provides the methods
+    required by the selected event type is accepted by `KameleoonClient.set_event_handler`.
+    Static type checkers (e.g. mypy) verify such handlers structurally.
+    """

kameleoon_client_python-3.22.1/kameleoon/events/event_manager.py

@@ -0,0 +1,62 @@
+"""Events"""
+from typing import Any, Dict, Optional
+
+from kameleoon.events.data_file_update_event import DataFileUpdateEvent
+from kameleoon.events.event_type import EventType, T
+from kameleoon.events.http_request_failure import HttpRequestFailure
+from kameleoon.events.request_type import RequestType
+from kameleoon.logging.kameleoon_logger import KameleoonLogger
+
+
+class EventManager:
+    """For internal use only. Stores SDK event handlers and fires SDK events."""
+
+    def __init__(self) -> None:
+        self.__event_handlers: Dict[EventType[Any], Any] = {}
+
+    def set_event_handler(self, event_type: EventType[T], handler: Optional[T]) -> None:
+        """Sets the SDK event handler for the specified event type. `None` clears the handler."""
+        if not isinstance(event_type, EventType):  # runtime guard for untyped callers
+            KameleoonLogger.error("Unknown event type '%s'", event_type)  # type: ignore[unreachable]
+            return
+        if (handler is not None) and (
+            not all(callable(getattr(handler, method, None)) for method in event_type.required_methods)
+        ):
+            KameleoonLogger.error(
+                "Handler for event type '%s' must provide the following methods: %s",
+                event_type, ", ".join(event_type.required_methods),
+            )
+            return
+        if handler is None:
+            self.__event_handlers.pop(event_type, None)
+        else:
+            self.__event_handlers[event_type] = handler
+
+    def fire_http_request_succeeded(self, request_type: RequestType, http_status: int, duration_millis: int) -> None:
+        """Fires the HTTP request event for a succeeded HTTP request attempt."""
+        handler = self.__event_handlers.get(EventType.HTTP_REQUEST)
+        if handler is not None:
+            try:
+                handler.on_request_succeeded(request_type, http_status, duration_millis)
+            except Exception as ex:  # pylint: disable=W0703
+                KameleoonLogger.warning("HTTP request event handler failed: %s", ex)
+
+    def fire_http_request_failed(
+        self, request_type: RequestType, failure: HttpRequestFailure, duration_millis: int
+    ) -> None:
+        """Fires the HTTP request event for a failed HTTP request attempt."""
+        handler = self.__event_handlers.get(EventType.HTTP_REQUEST)
+        if handler is not None:
+            try:
+                handler.on_request_failed(request_type, failure, duration_millis)
+            except Exception as ex:  # pylint: disable=W0703
+                KameleoonLogger.warning("HTTP request event handler failed: %s", ex)
+
+    def fire_data_file_update(self, update_event: DataFileUpdateEvent) -> None:
+        """Fires the data file update event."""
+        handler = self.__event_handlers.get(EventType.DATAFILE_UPDATE)
+        if handler is not None:
+            try:
+                handler.on_update(update_event)
+            except Exception as ex:  # pylint: disable=W0703
+                KameleoonLogger.warning("Data file update event handler failed: %s", ex)

kameleoon_client_python-3.22.1/kameleoon/events/event_type.py

@@ -0,0 +1,70 @@
+"""Events"""
+from typing import cast, Generic, Tuple, Type, TypeVar
+
+from kameleoon.events.data_file_update_handler import DataFileUpdateHandler
+from kameleoon.events.event_handler import EventHandler
+from kameleoon.events.http_request_handler import HttpRequestHandler
+
+T = TypeVar("T", bound=EventHandler)
+
+
+def _handler_methods(handler_type: type) -> Tuple[str, ...]:
+    """Collects the public methods of the handler type."""
+    return tuple(
+        name for name, member in vars(handler_type).items()
+        if not name.startswith("_") and callable(member)
+    )
+
+
+class EventType(Generic[T]):
+    """
+    Represents an SDK event type available for `KameleoonClient.set_event_handler`.
+    The type parameter defines the handler protocol accepted by the event type.
+
+    Subclassing the handler protocols is optional: any object which provides the methods
+    required by the selected event type is accepted by `KameleoonClient.set_event_handler`.
+    Static type checkers (e.g. mypy) verify such handlers structurally.
+    """
+
+    HTTP_REQUEST: "EventType[HttpRequestHandler]"
+    """
+    Notifies when an SDK HTTP request completes successfully or fails.
+    Handled by `HttpRequestHandler`.
+    """
+
+    DATAFILE_UPDATE: "EventType[DataFileUpdateHandler]"
+    """
+    Notifies when the SDK data file (configuration) is updated.
+    Handled by `DataFileUpdateHandler`.
+    """
+
+    def __init__(self, name: str, handler_type: type) -> None:
+        """For internal use only. Use the predefined event type constants instead."""
+        self.__name = name
+        self.__handler_type = handler_type
+        self.__required_methods = _handler_methods(handler_type)
+        if not self.__required_methods:
+            # Guards against an event type accepting any object: `all(())` is `True`.
+            raise ValueError(f"Event handler type '{handler_type.__name__}' declares no handler methods")
+
+    @property
+    def name(self) -> str:
+        """Returns the name of the event type."""
+        return self.__name
+
+    @property
+    def handler_type(self) -> Type[T]:
+        """Returns the event handler protocol accepted by the event type."""
+        return cast(Type[T], self.__handler_type)
+
+    @property
+    def required_methods(self) -> Tuple[str, ...]:
+        """Returns the names of the methods a handler of the event type must provide."""
+        return self.__required_methods
+
+    def __str__(self) -> str:
+        return self.__name
+
+
+EventType.HTTP_REQUEST = EventType("HTTP_REQUEST", HttpRequestHandler)
+EventType.DATAFILE_UPDATE = EventType("DATAFILE_UPDATE", DataFileUpdateHandler)

kameleoon_client_python-3.22.1/kameleoon/events/http_request_failure.py

@@ -0,0 +1,70 @@
+"""Events"""
+from enum import Enum
+from typing import Optional
+
+
+class HttpRequestFailure:
+    """Describes the failure of an SDK HTTP request reported to `HttpRequestHandler`."""
+
+    class Reason(Enum):
+        """Represents the reason of an SDK HTTP request failure."""
+
+        HTTP_STATUS = "HTTP_STATUS"
+        """The request completed with an unexpected HTTP status code."""
+
+        EXCEPTION = "EXCEPTION"
+        """The request failed with an exception."""
+
+        CANCELLED = "CANCELLED"
+        """The request was cancelled (for example, due to a timeout)."""
+
+    def __init__(
+        self, reason: "HttpRequestFailure.Reason", http_status: Optional[int], cause: Optional[Exception]
+    ) -> None:
+        """
+        For internal use only. Use the `from_http_status`, `from_exception`,
+        `of_cancellation` factory methods instead.
+        """
+        self.__reason = reason
+        self.__http_status = http_status
+        self.__cause = cause
+
+    @staticmethod
+    def from_http_status(http_status: int) -> "HttpRequestFailure":
+        """For internal use only. Creates a failure with the `HTTP_STATUS` reason."""
+        return HttpRequestFailure(HttpRequestFailure.Reason.HTTP_STATUS, http_status, None)
+
+    @staticmethod
+    def from_exception(cause: Exception) -> "HttpRequestFailure":
+        """For internal use only. Creates a failure with the `EXCEPTION` reason."""
+        return HttpRequestFailure(HttpRequestFailure.Reason.EXCEPTION, None, cause)
+
+    @staticmethod
+    def of_cancellation() -> "HttpRequestFailure":
+        """For internal use only. Creates a failure with the `CANCELLED` reason."""
+        return HttpRequestFailure(HttpRequestFailure.Reason.CANCELLED, None, None)
+
+    @property
+    def reason(self) -> "HttpRequestFailure.Reason":
+        """Returns the reason of the failure."""
+        return self.__reason
+
+    @property
+    def http_status(self) -> Optional[int]:
+        """
+        Returns the HTTP status code of the response. Has a value only if `reason` is
+        `Reason.HTTP_STATUS`.
+        """
+        return self.__http_status
+
+    @property
+    def cause(self) -> Optional[Exception]:
+        """
+        Returns the exception caused the failure. Not `None` only if `reason` is
+        `Reason.EXCEPTION`.
+        """
+        return self.__cause
+
+    def __str__(self) -> str:
+        cause = type(self.__cause).__name__ if self.__cause is not None else None
+        return f"HttpRequestFailure{{Reason:{self.__reason.value},HttpStatus:{self.__http_status},Cause:{cause}}}"

kameleoon_client_python-3.22.1/kameleoon/events/http_request_handler.py

@@ -0,0 +1,43 @@
+"""Events"""
+from typing import Protocol
+
+from kameleoon.events.event_handler import EventHandler
+from kameleoon.events.http_request_failure import HttpRequestFailure
+from kameleoon.events.request_type import RequestType
+
+
+class HttpRequestHandler(EventHandler, Protocol):
+    """
+    Handles `EventType.HTTP_REQUEST` SDK events. The handler is called once per each
+    actual HTTP request attempt, including retries.
+
+    Subclassing this protocol is optional: any object which provides the `on_request_succeeded`
+    and `on_request_failed` methods is accepted by `KameleoonClient.set_event_handler`.
+    Static type checkers (e.g. mypy) verify such handlers structurally.
+    """
+
+    def on_request_succeeded(self, request_type: RequestType, http_status: int, duration_millis: int) -> None:
+        """
+        Called when an SDK HTTP request completes successfully.
+        :param request_type: The type of the request.
+        :type request_type: RequestType
+        :param http_status: The HTTP status code of the response.
+        :type http_status: int
+        :param duration_millis: The duration of the request in milliseconds.
+        :type duration_millis: int
+        """
+        raise NotImplementedError()
+
+    def on_request_failed(
+        self, request_type: RequestType, failure: HttpRequestFailure, duration_millis: int
+    ) -> None:
+        """
+        Called when an SDK HTTP request fails.
+        :param request_type: The type of the request.
+        :type request_type: RequestType
+        :param failure: The failure details.
+        :type failure: HttpRequestFailure
+        :param duration_millis: The duration of the request in milliseconds.
+        :type duration_millis: int
+        """
+        raise NotImplementedError()

kameleoon_client_python-3.22.1/kameleoon/events/request_type.py

@@ -0,0 +1,21 @@
+"""Events"""
+from enum import Enum
+
+
+class RequestType(Enum):
+    """Represents the type of an SDK HTTP request reported to `HttpRequestHandler`."""
+
+    DATAFILE = "DATAFILE"
+    """Fetching of the SDK data file (configuration)."""
+
+    TRACKING = "TRACKING"
+    """Sending of tracking data."""
+
+    REMOTE_VISITOR_DATA = "REMOTE_VISITOR_DATA"
+    """Fetching of remote visitor data."""
+
+    REMOTE_DATA = "REMOTE_DATA"
+    """Fetching of remote data."""
+
+    ACCESS_TOKEN = "ACCESS_TOKEN"
+    """Fetching of the Kameleoon API access token."""

{kameleoon_client_python-3.20.0 → kameleoon_client_python-3.22.1}/kameleoon/exceptions.py

@@ -25,6 +25,24 @@ class SiteCodeIsEmpty(KameleoonError):
     """Site Code is Empty"""
 
 
+class Initialization(KameleoonError):
+    """
+    SDK could not be initialized: its configuration failed to load or no
+    initialization result was available within the requested timeout.
+    The failure which prevented the initialization is available via `cause`;
+    it is also reported in the message so a caller which only logs the
+    message still learns why the SDK is not initialized.
+    """
+
+    def __init__(self, site_code: str, environment, cause: Exception) -> None:
+        # The failure which prevented the SDK from loading its configuration.
+        self.cause = cause
+        reason = "unknown" if cause is None else str(cause)
+        super().__init__(
+            f"SDK is not initialized for siteCode: '{site_code}', environment: '{environment}'. Reason: {reason}"
+        )
+
+
 class NotFoundError(KameleoonError):
     """Base not found error"""