diff --git a/CHANGELOG.md b/CHANGELOG.md index 12751f1..6263e0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `MixpanelClient` with typed wrappers for `track`, `people_set`, `people_set_once`, `people_increment`, `people_union`, `people_unset`, and `alias` - `MixpanelClient.from_env()` factory. A missing token disables tracking with a warning naming the variable, raises `ValueError` when `enabled=True` was passed, and is silent when tracking was turned off - ([#10](https://github.com/altissimo-hq/mixpanel-python/issues/10)). It takes a `consumer`, like the constructor + ([#10](https://github.com/altissimo-hq/mixpanel-python/issues/10)). It takes a `consumer` or `consumer_factory`, like + the constructor +- One client can be shared across threads: each thread gets its own Mixpanel SDK instance (and HTTP session). + `consumer_factory` makes one consumer per thread; `flush()` flushes all of them + ([#12](https://github.com/altissimo-hq/mixpanel-python/issues/12)) - Configurable error handling via `on_error` parameter (`log`, `raise`, `ignore`). A missing `mixpanel` SDK is logged once and disables the client, instead of logging a traceback on every call (raised with `"raise"`) - `MixpanelConsumer` protocol describing what a custom consumer needs (`send(endpoint, json_message)`) diff --git a/README.md b/README.md index 4d79ef9..0ea6d12 100644 --- a/README.md +++ b/README.md @@ -119,16 +119,31 @@ with MixpanelClient(token="...", consumer=BufferedConsumer()) as client: With the default consumer, which sends each message immediately, `flush()` does nothing. A failing flush follows `on_error` like every other call. -`from_env()` takes a consumer too, for example to shorten the request timeout: +Any object with `send(endpoint, json_message)` works as a consumer; the +`MixpanelConsumer` protocol describes it for type checking. + +### Threads + +One `MixpanelClient` can be shared across threads, such as a module-level +client in a web app. Each thread gets its own Mixpanel SDK instance and, with +the default consumer, its own HTTP session: the SDK's `Consumer` and +`BufferedConsumer` aren't safe to share between threads. + +A `consumer=` is a single object every thread shares, so in a threaded app pass +a `consumer_factory` instead; it's called once per thread: ```python -from mixpanel import Consumer +from mixpanel import BufferedConsumer, Consumer + +# A shorter request timeout, one consumer per thread +client = MixpanelClient.from_env(consumer_factory=lambda: Consumer(request_timeout=5)) -client = MixpanelClient.from_env(consumer=Consumer(request_timeout=5)) +# Buffered, one buffer per thread +client = MixpanelClient(token="...", consumer_factory=BufferedConsumer) ``` -Any object with `send(endpoint, json_message)` works as a consumer; the -`MixpanelConsumer` protocol describes it for type checking. +`flush()` flushes every thread's consumer. Call it when no other thread is +tracking, such as at shutdown. ### Testing with `FakeMixpanelClient` diff --git a/src/altissimo/mixpanel/client.py b/src/altissimo/mixpanel/client.py index 4fb11f3..cd588f9 100644 --- a/src/altissimo/mixpanel/client.py +++ b/src/altissimo/mixpanel/client.py @@ -4,11 +4,13 @@ import logging import os +import threading from typing import TYPE_CHECKING, Any, Literal from altissimo.mixpanel.exceptions import MixpanelImportError if TYPE_CHECKING: + from collections.abc import Callable from types import TracebackType from altissimo.mixpanel.protocol import MixpanelConsumer @@ -28,6 +30,11 @@ class MixpanelClient: The underlying ``Mixpanel`` instance is lazily initialized on the first API call, so constructing a ``MixpanelClient`` is side-effect-free. + One client can be shared across threads: each thread gets its own + ``Mixpanel`` instance, and so its own consumer and HTTP session, since + neither the SDK's ``Consumer`` (one ``requests.Session``) nor its + ``BufferedConsumer`` (unlocked buffers) is safe to share. + When ``enabled=False``, all tracking calls silently no-op without making any network requests or importing the SDK. @@ -36,8 +43,16 @@ class MixpanelClient: enabled: When ``False``, all calls silently no-op. consumer: Optional custom consumer for the Mixpanel SDK, such as ``BufferedConsumer`` or anything matching - :class:`~altissimo.mixpanel.protocol.MixpanelConsumer`. A - consumer that buffers must be flushed with :meth:`flush` (or by + :class:`~altissimo.mixpanel.protocol.MixpanelConsumer`. This one + object is shared by every thread, so it must be thread-safe if + the client is used from more than one; otherwise pass + ``consumer_factory``. + consumer_factory: Optional callable returning a new consumer, called + once per thread that uses the client. Use it instead of + ``consumer`` in threaded apps, e.g. + ``consumer_factory=lambda: Consumer(request_timeout=5)``. + + A consumer that buffers must be flushed with :meth:`flush` (or by using the client as a context manager) before the process exits, or the buffered messages are lost. on_error: Error handling strategy: @@ -56,13 +71,21 @@ def __init__( *, enabled: bool = True, consumer: MixpanelConsumer | None = None, + consumer_factory: Callable[[], MixpanelConsumer] | None = None, on_error: Literal["log", "raise", "ignore"] = "log", ) -> None: + if consumer is not None and consumer_factory is not None: + raise ValueError("Pass consumer or consumer_factory, not both") self._token = token self._enabled = enabled self._consumer = consumer + self._consumer_factory = consumer_factory self._on_error = on_error - self._mp: Mixpanel | None = None + # One Mixpanel instance per thread (see class docstring) + self._local = threading.local() + # Every consumer consumer_factory made, so flush() reaches all threads' + self._factory_consumers: list[MixpanelConsumer] = [] + self._factory_consumers_lock = threading.Lock() @classmethod def from_env( @@ -71,6 +94,7 @@ def from_env( token_var: str = "MIXPANEL_TOKEN", # noqa: S107 enabled: bool | None = None, consumer: MixpanelConsumer | None = None, + consumer_factory: Callable[[], MixpanelConsumer] | None = None, on_error: Literal["log", "raise", "ignore"] = "log", ) -> MixpanelClient: """Create a client using environment variables. @@ -95,6 +119,8 @@ def from_env( (truthy values: ``1``, ``true``, ``yes``; defaults to ``True`` when the variable is not set). consumer: Optional custom consumer (see class docstring). + consumer_factory: Optional per-thread consumer factory (see + class docstring). on_error: Error handling strategy (see class docstring). Returns: @@ -123,6 +149,7 @@ def from_env( token=token or "disabled", enabled=enabled, consumer=consumer, + consumer_factory=consumer_factory, on_error=on_error, ) @@ -132,23 +159,30 @@ def enabled(self) -> bool: return self._enabled def _get_mp(self) -> Mixpanel: - """Return the lazily-initialized ``Mixpanel`` instance. + """Return this thread's ``Mixpanel`` instance, creating it on first use. Raises: MixpanelImportError: If the ``mixpanel`` package is not installed. """ - if self._mp is None: + mp: Mixpanel | None = getattr(self._local, "mp", None) + if mp is None: try: from mixpanel import Mixpanel as _Mixpanel except ImportError: raise MixpanelImportError from None kwargs: dict[str, Any] = {} - if self._consumer is not None: + if self._consumer_factory is not None: + consumer = self._consumer_factory() + with self._factory_consumers_lock: + self._factory_consumers.append(consumer) + kwargs["consumer"] = consumer + elif self._consumer is not None: kwargs["consumer"] = self._consumer - self._mp = _Mixpanel(self._token, **kwargs) - return self._mp + mp = _Mixpanel(self._token, **kwargs) + self._local.mp = mp + return mp def _handle_error(self, exc: Exception, operation: str, **context: Any) -> None: """Handle an exception according to the configured error strategy.""" @@ -331,22 +365,33 @@ def alias( # ------------------------------------------------------------------ def flush(self) -> None: - """Send any messages the consumer is still holding. + """Send any messages the consumers are still holding. Only a buffering consumer such as ``BufferedConsumer`` holds messages; it sends them when its buffer fills, so whatever is buffered when the process exits is lost unless flushed. With the default consumer, which sends each message as it is made, this does nothing. + + With ``consumer_factory`` this flushes the consumer of every thread + that has used the client, so call it when no other thread is tracking, + such as at shutdown: a buffering consumer isn't safe to flush while + its own thread is adding to it. """ if not self._enabled: return - flush = getattr(self._consumer, "flush", None) - if flush is None: - return - try: - flush() - except Exception as exc: - self._handle_error(exc, "flush") + if self._consumer_factory is not None: + with self._factory_consumers_lock: + consumers = list(self._factory_consumers) + else: + consumers = [self._consumer] if self._consumer is not None else [] + for consumer in consumers: + flush = getattr(consumer, "flush", None) + if flush is None: + continue + try: + flush() + except Exception as exc: + self._handle_error(exc, "flush") def __enter__(self) -> MixpanelClient: return self diff --git a/tests/test_client.py b/tests/test_client.py index e62063f..4674093 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -131,14 +131,14 @@ class TestLazyInit: def test_mp_is_none_initially(self) -> None: client = MixpanelClient(token="test-token") - assert client._mp is None + assert getattr(client._local, "mp", None) is None def test_mp_is_cached(self, client: MixpanelClient) -> None: - """The Mixpanel instance is created once and reused.""" + """The Mixpanel instance is created once per thread and reused.""" client.track("user-123", "Event 1") - mp_first = client._mp + mp_first = client._local.mp client.track("user-123", "Event 2") - mp_second = client._mp + mp_second = client._local.mp assert mp_first is mp_second def test_custom_consumer_is_used(self, recording_consumer: RecordingConsumer) -> None: diff --git a/tests/test_disabled.py b/tests/test_disabled.py index b1e2e0f..f83b917 100644 --- a/tests/test_disabled.py +++ b/tests/test_disabled.py @@ -37,4 +37,4 @@ def test_mp_stays_none(self, disabled_client: MixpanelClient) -> None: disabled_client.track("user-123", "Event") disabled_client.people_set("user-123", {"key": "val"}) disabled_client.alias("a", "b") - assert disabled_client._mp is None + assert getattr(disabled_client._local, "mp", None) is None diff --git a/tests/test_flush.py b/tests/test_flush.py index 7217ba3..139a253 100644 --- a/tests/test_flush.py +++ b/tests/test_flush.py @@ -35,7 +35,7 @@ def test_buffered_events_sent_on_flush(self) -> None: def test_flush_with_default_consumer_is_noop(self) -> None: client = MixpanelClient(token="test-token") client.flush() # should not raise or build the SDK client - assert client._mp is None + assert getattr(client._local, "mp", None) is None def test_flush_with_consumer_without_flush_is_noop(self, client: MixpanelClient) -> None: client.flush() # RecordingConsumer has no flush method diff --git a/tests/test_threads.py b/tests/test_threads.py new file mode 100644 index 0000000..4b26ec3 --- /dev/null +++ b/tests/test_threads.py @@ -0,0 +1,153 @@ +"""Tests for sharing one MixpanelClient across threads.""" + +from __future__ import annotations + +import threading +from typing import TYPE_CHECKING +from unittest.mock import MagicMock + +import pytest + +from altissimo.mixpanel import MixpanelClient + +from .conftest import RecordingConsumer + +if TYPE_CHECKING: + from collections.abc import Callable + + from mixpanel import Mixpanel + +THREADS = 8 + + +def _run_in_threads(target: Callable[[], None], count: int = THREADS) -> None: + """Run ``target`` in ``count`` threads that all start together.""" + barrier = threading.Barrier(count) + + def run() -> None: + barrier.wait() + target() + + threads = [threading.Thread(target=run) for _ in range(count)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + + +class TestPerThreadSdkClient: + """Each thread gets its own Mixpanel instance.""" + + def test_default_consumer_one_instance_per_thread(self) -> None: + client = MixpanelClient(token="test-token") + instances: list[Mixpanel] = [] + lock = threading.Lock() + + def get() -> None: + first = client._get_mp() + assert client._get_mp() is first # reused within the thread + with lock: + instances.append(first) + + _run_in_threads(get) + + assert len({id(mp) for mp in instances}) == THREADS + # The SDK's default Consumer, and with it the HTTP session, isn't shared either + assert len({id(mp._consumer) for mp in instances}) == THREADS + + def test_consumer_factory_called_once_per_thread(self) -> None: + made: list[RecordingConsumer] = [] + lock = threading.Lock() + + def factory() -> RecordingConsumer: + consumer = RecordingConsumer() + with lock: + made.append(consumer) + return consumer + + client = MixpanelClient(token="test-token", consumer_factory=factory) + + def track_twice() -> None: + client.track("user-123", "Event A") + client.track("user-123", "Event B") + + _run_in_threads(track_twice) + + assert len(made) == THREADS + assert all(len(consumer.sent) == 2 for consumer in made) + + def test_shared_consumer_used_by_every_thread(self) -> None: + consumer = RecordingConsumer() + client = MixpanelClient(token="test-token", consumer=consumer) + consumers: list[object] = [] + lock = threading.Lock() + + def get() -> None: + mp = client._get_mp() + with lock: + consumers.append(mp._consumer) + + _run_in_threads(get) + + assert all(c is consumer for c in consumers) + + +class TestFlushAcrossThreads: + """flush() reaches the consumer of every thread that used the client.""" + + def test_flushes_every_factory_consumer(self) -> None: + made: list[MagicMock] = [] + lock = threading.Lock() + + def factory() -> MagicMock: + consumer = MagicMock() + with lock: + made.append(consumer) + return consumer + + client = MixpanelClient(token="test-token", consumer_factory=factory) + _run_in_threads(lambda: client.track("user-123", "Event")) + + client.flush() + + assert len(made) == THREADS + for consumer in made: + consumer.flush.assert_called_once_with() + + def test_flush_before_any_thread_tracked_is_noop(self) -> None: + factory = MagicMock() + client = MixpanelClient(token="test-token", consumer_factory=factory) + + client.flush() + + factory.assert_not_called() + + def test_one_failing_flush_doesnt_stop_the_rest_when_logging(self) -> None: + failing = MagicMock() + failing.flush.side_effect = RuntimeError("Flush failed") + ok = MagicMock() + consumers = iter([failing, ok]) + client = MixpanelClient(token="test-token", consumer_factory=lambda: next(consumers), on_error="log") + _run_in_threads(lambda: client.track("user-123", "Event"), count=2) + + client.flush() + + failing.flush.assert_called_once_with() + ok.flush.assert_called_once_with() + + +class TestConsumerArguments: + """consumer and consumer_factory are alternatives.""" + + def test_both_raises(self) -> None: + with pytest.raises(ValueError, match="not both"): + MixpanelClient(token="test-token", consumer=RecordingConsumer(), consumer_factory=RecordingConsumer) + + def test_from_env_forwards_factory(self, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("MIXPANEL_TOKEN", "my-token") + consumer = RecordingConsumer() + client = MixpanelClient.from_env(consumer_factory=lambda: consumer) + + client.track("user-123", "Event") + + assert len(consumer.sent) == 1