Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)`)
Expand Down
25 changes: 20 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
77 changes: 61 additions & 16 deletions src/altissimo/mixpanel/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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:
Expand All @@ -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(
Expand All @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -123,6 +149,7 @@ def from_env(
token=token or "disabled",
enabled=enabled,
consumer=consumer,
consumer_factory=consumer_factory,
on_error=on_error,
)

Expand All @@ -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."""
Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion tests/test_disabled.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion tests/test_flush.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading