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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.1] - 2026-10-26

### Fixed

- With `consumer_factory`, a thread's consumer is now flushed and released when the thread exits. Before, the client
held every consumer it had made, and events buffered by exited threads (such as idle workers a thread pool retires)
waited until the next `flush()`. `flush()` also releases any exited thread's consumer still held
- Leaving a `with` block that raised no longer replaces its exception with a flush error under `on_error="raise"`;
the flush error is logged instead
- The `mixpanel` extra is limited to `mixpanel>=4.0,<6`
- `__version__` falls back to `0.0.0` instead of a stale hardcoded version when package metadata is missing

## [0.1.0] - 2026-10-26

First release, published to PyPI as `altissimo-mixpanel`. The import name is
Expand Down
17 changes: 2 additions & 15 deletions poetry.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "altissimo-mixpanel"
version = "0.1.0"
version = "0.1.1"
description = "Reusable Mixpanel analytics client for Altissimo projects"
readme = "README.md"
license = "Apache-2.0"
Expand All @@ -22,7 +22,7 @@ classifiers = [
dependencies = []

[project.optional-dependencies]
mixpanel = ["mixpanel>=4.0"]
mixpanel = ["mixpanel>=4.0,<6"]

[project.urls]
Homepage = "https://github.com/altissimo-hq/mixpanel-python"
Expand All @@ -47,7 +47,7 @@ ruff = ">=0.11"
pre-commit = ">=4.0"

# Include mixpanel in dev for testing
mixpanel = ">=4.0"
mixpanel = ">=4.0,<6"

[tool.ruff]
target-version = "py311"
Expand Down
2 changes: 1 addition & 1 deletion src/altissimo/mixpanel/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
try:
__version__ = version("altissimo-mixpanel")
except PackageNotFoundError:
__version__ = "0.1.0"
__version__ = "0.0.0"

__all__ = [
"FakeMixpanelClient",
Expand Down
84 changes: 70 additions & 14 deletions src/altissimo/mixpanel/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
import logging
import os
import threading
import weakref
from typing import TYPE_CHECKING, Any, Literal

from altissimo.mixpanel.exceptions import MixpanelImportError
Expand Down Expand Up @@ -52,9 +53,13 @@ class MixpanelClient:
``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.
When a thread that used the client exits, its consumer is
flushed and released, so short-lived threads, such as an idle
worker a thread pool retires, don't leave buffered messages
behind. A consumer that buffers must still be flushed with
:meth:`flush` (or by using the client as a context manager)
before the process exits, or the buffered messages of threads
still running are lost.
on_error: Error handling strategy:
- ``"log"`` (default): Catch exceptions and log them.
- ``"raise"``: Re-raise exceptions to the caller.
Expand Down Expand Up @@ -83,8 +88,9 @@ def __init__(
self._on_error = on_error
# 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] = []
# The consumer consumer_factory made for each thread still using the
# client, with its thread, so flush() reaches all threads' consumers
self._factory_consumers: list[tuple[threading.Thread, MixpanelConsumer]] = []
self._factory_consumers_lock = threading.Lock()

@classmethod
Expand Down Expand Up @@ -172,18 +178,57 @@ def _get_mp(self) -> Mixpanel:
raise MixpanelImportError from None

kwargs: dict[str, Any] = {}
entry: tuple[threading.Thread, MixpanelConsumer] | None = None
if self._consumer_factory is not None:
consumer = self._consumer_factory()
entry = (threading.current_thread(), consumer)
with self._factory_consumers_lock:
self._factory_consumers.append(consumer)
self._factory_consumers.append(entry)
kwargs["consumer"] = consumer
elif self._consumer is not None:
kwargs["consumer"] = self._consumer

mp = _Mixpanel(self._token, **kwargs)
self._local.mp = mp
if entry is not None:
# The thread's Mixpanel instance is released when the thread
# exits; flush and release its consumer then. A weak reference
# to the client, so a live thread doesn't keep the client alive.
finalizer = weakref.finalize(mp, MixpanelClient._retire_consumer, weakref.ref(self), entry)
finalizer.atexit = False # type: ignore[misc] # documented, but missing from typeshed's __slots__
return mp

@staticmethod
def _retire_consumer(
client_ref: weakref.ref[MixpanelClient],
entry: tuple[threading.Thread, MixpanelConsumer],
) -> None:
"""Flush and release the consumer of a thread that has exited.

No caller is left to raise to, so a flush error is logged (not with
``on_error="ignore"``) instead of raised.
"""
client = client_ref()
if client is None:
return
with client._factory_consumers_lock:
if not any(e is entry for e in client._factory_consumers):
return # flush() already released it
client._factory_consumers = [e for e in client._factory_consumers if e is not entry]
if not client._enabled:
return
try:
client._flush_consumer(entry[1])
except Exception:
if client._on_error != "ignore":
logger.exception("Mixpanel flush error for exited thread %s", entry[0].name)

@staticmethod
def _flush_consumer(consumer: MixpanelConsumer) -> None:
flush = getattr(consumer, "flush", None)
if flush is not None:
flush()

def _handle_error(self, exc: Exception, operation: str, **context: Any) -> None:
"""Handle an exception according to the configured error strategy."""
if self._on_error == "raise":
Expand Down Expand Up @@ -375,21 +420,22 @@ def flush(self) -> None:
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.
its own thread is adding to it. It also releases the consumers of
threads that have exited, if any are still held.
"""
if not self._enabled:
return
if self._consumer_factory is not None:
with self._factory_consumers_lock:
consumers = list(self._factory_consumers)
entries = self._factory_consumers
# Flush exited threads' consumers one last time, then release them
self._factory_consumers = [e for e in entries if e[0].is_alive()]
consumers = [consumer for _, consumer in entries]
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()
self._flush_consumer(consumer)
except Exception as exc:
self._handle_error(exc, "flush")

Expand All @@ -402,5 +448,15 @@ def __exit__(
exc: BaseException | None,
tb: TracebackType | None,
) -> None:
"""Flush on leaving the ``with`` block, including when it raised."""
self.flush()
"""Flush on leaving the ``with`` block, including when it raised.

If the block raised, a flush error is logged rather than raised, so
it doesn't replace the block's own exception.
"""
if exc is None:
self.flush()
return
try:
self.flush()
except Exception:
logger.exception("Mixpanel flush error while leaving a with block that raised")
17 changes: 17 additions & 0 deletions tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,23 @@ def send(self, endpoint: str, json_message: str, api_key: str | None = None) ->
raise self.error


@dataclass
class BufferingConsumer:
"""A consumer that holds messages until flushed, then records them as sent."""

buffer: list[tuple[str, str]] = field(default_factory=list)
sent: list[tuple[str, str]] = field(default_factory=list)

def send(self, endpoint: str, json_message: str, api_key: str | None = None) -> None:
"""Hold the message until the next flush."""
self.buffer.append((endpoint, json_message))

def flush(self) -> None:
"""Record every held message as sent."""
self.sent.extend(self.buffer)
self.buffer.clear()


@dataclass
class FailingFlushConsumer:
"""A buffering consumer whose flush always raises an exception."""
Expand Down
15 changes: 15 additions & 0 deletions tests/test_flush.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,21 @@ def test_flushes_when_block_raises(self) -> None:

consumer.flush.assert_called_once_with()

def test_flush_error_doesnt_replace_block_exception(self, caplog: pytest.LogCaptureFixture) -> None:
client = MixpanelClient(token="test-token", consumer=FailingFlushConsumer(), on_error="raise")

with caplog.at_level(logging.ERROR), pytest.raises(ValueError, match="boom"), client:
raise ValueError("boom")

assert "Mixpanel flush error while leaving a with block that raised" in caplog.text
assert "Flush failed" in caplog.text

def test_flush_error_raised_when_block_succeeds(self) -> None:
client = MixpanelClient(token="test-token", consumer=FailingFlushConsumer(), on_error="raise")

with pytest.raises(RuntimeError, match="Flush failed"), client:
pass

def test_track_then_exit_sends_buffered_events(self) -> None:
with patch("mixpanel.Consumer.send") as send:
with MixpanelClient(token="test-token", consumer=BufferedConsumer()) as client:
Expand Down
96 changes: 95 additions & 1 deletion tests/test_threads.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@

from __future__ import annotations

import gc
import logging
import threading
import weakref
from typing import TYPE_CHECKING
from unittest.mock import MagicMock

import pytest

from altissimo.mixpanel import MixpanelClient

from .conftest import RecordingConsumer
from .conftest import BufferingConsumer, FailingFlushConsumer, RecordingConsumer

if TYPE_CHECKING:
from collections.abc import Callable
Expand Down Expand Up @@ -136,6 +139,97 @@ def test_one_failing_flush_doesnt_stop_the_rest_when_logging(self) -> None:
ok.flush.assert_called_once_with()


class TestExitedThreads:
"""A thread's factory consumer is flushed and released when the thread exits."""

def test_short_lived_threads_leave_nothing_behind(self) -> None:
# Like a thread pool retiring idle workers in a long-running service
made: list[BufferingConsumer] = []
lock = threading.Lock()

def factory() -> BufferingConsumer:
consumer = BufferingConsumer()
with lock:
made.append(consumer)
return consumer

client = MixpanelClient(token="test-token", consumer_factory=factory)
for _ in range(200):
thread = threading.Thread(target=lambda: client.track("user-123", "Event"))
thread.start()
thread.join()

assert len(made) == 200
assert client._factory_consumers == []
assert all(consumer.buffer == [] and len(consumer.sent) == 1 for consumer in made)

def test_flush_error_in_exited_thread_is_logged(self, caplog: pytest.LogCaptureFixture) -> None:
client = MixpanelClient(token="test-token", consumer_factory=FailingFlushConsumer, on_error="raise")

with caplog.at_level(logging.ERROR):
_run_in_threads(lambda: client.track("user-123", "Event"), count=1)

assert "Mixpanel flush error for exited thread" in caplog.text
assert client._factory_consumers == []

def test_flush_error_in_exited_thread_ignored(self, caplog: pytest.LogCaptureFixture) -> None:
client = MixpanelClient(token="test-token", consumer_factory=FailingFlushConsumer, on_error="ignore")

with caplog.at_level(logging.ERROR):
_run_in_threads(lambda: client.track("user-123", "Event"), count=1)

assert "Mixpanel" not in caplog.text

def test_exited_thread_not_flushed_when_disabled(self) -> None:
consumer = MagicMock()
client = MixpanelClient(token="test-token", consumer_factory=lambda: consumer)

def track_then_disable() -> None:
client.track("user-123", "Event")
client._enabled = False

_run_in_threads(track_then_disable, count=1)

consumer.flush.assert_not_called()
assert client._factory_consumers == []

def test_flush_releases_exited_threads_still_held(self) -> None:
# If an exited thread's Mixpanel instance is still referenced, its
# consumer isn't released at exit; flush() sends and releases it
consumer = MagicMock()
client = MixpanelClient(token="test-token", consumer_factory=lambda: consumer)
kept: list[Mixpanel] = []
_run_in_threads(lambda: kept.append(client._get_mp()), count=1)
assert len(client._factory_consumers) == 1

client.flush()
client.flush()

consumer.flush.assert_called_once_with()
assert client._factory_consumers == []

def test_flush_keeps_live_threads_consumers(self) -> None:
consumer = MagicMock()
client = MixpanelClient(token="test-token", consumer_factory=lambda: consumer)
client.track("user-123", "Event") # the main thread stays alive

client.flush()
client.flush()

assert consumer.flush.call_count == 2
assert len(client._factory_consumers) == 1

def test_live_thread_doesnt_keep_client_alive(self) -> None:
client = MixpanelClient(token="test-token", consumer_factory=MagicMock)
client.track("user-123", "Event")
client_ref = weakref.ref(client)

del client
gc.collect()

assert client_ref() is None


class TestConsumerArguments:
"""consumer and consumer_factory are alternatives."""

Expand Down
Loading