diff --git a/CHANGELOG.md b/CHANGELOG.md index b2a8514..b6167e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/poetry.lock b/poetry.lock index 613ffd6..b581609 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1210,19 +1210,6 @@ files = [ ] markers = {main = "extra == \"mixpanel\""} -[[package]] -name = "typing-extensions" -version = "4.15.0" -description = "Backported and Experimental Type Hints for Python 3.9+" -optional = false -python-versions = ">=3.9" -groups = ["main", "dev"] -files = [ - {file = "typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548"}, - {file = "typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466"}, -] -markers = {main = "python_version >= \"3.15\" and extra == \"mixpanel\"", dev = "python_version >= \"3.15\""} - [[package]] name = "typing-extensions" version = "4.16.0" @@ -1234,7 +1221,7 @@ files = [ {file = "typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8"}, {file = "typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5"}, ] -markers = {main = "python_version < \"3.15\" and extra == \"mixpanel\"", dev = "python_version < \"3.15\""} +markers = {main = "extra == \"mixpanel\""} [[package]] name = "typing-inspection" @@ -1296,4 +1283,4 @@ mixpanel = ["mixpanel"] [metadata] lock-version = "2.1" python-versions = ">=3.11" -content-hash = "df80dba9cb1ee2241adbdcfc9aa6696e62a9facdcf9e4f491d18cc0cd09830de" +content-hash = "417816fa91c8bd75c8bab2d7ca92b66c4712830a82c466b138f29fc9490e9cb8" diff --git a/pyproject.toml b/pyproject.toml index 3229cd1..5d9cad9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" @@ -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" @@ -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" diff --git a/src/altissimo/mixpanel/__init__.py b/src/altissimo/mixpanel/__init__.py index 7834c02..72099e0 100644 --- a/src/altissimo/mixpanel/__init__.py +++ b/src/altissimo/mixpanel/__init__.py @@ -12,7 +12,7 @@ try: __version__ = version("altissimo-mixpanel") except PackageNotFoundError: - __version__ = "0.1.0" + __version__ = "0.0.0" __all__ = [ "FakeMixpanelClient", diff --git a/src/altissimo/mixpanel/client.py b/src/altissimo/mixpanel/client.py index cd588f9..d7cc9c8 100644 --- a/src/altissimo/mixpanel/client.py +++ b/src/altissimo/mixpanel/client.py @@ -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 @@ -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. @@ -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 @@ -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": @@ -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") @@ -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") diff --git a/tests/conftest.py b/tests/conftest.py index 4a9bdbc..f9a6fcb 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -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.""" diff --git a/tests/test_flush.py b/tests/test_flush.py index 139a253..249dc41 100644 --- a/tests/test_flush.py +++ b/tests/test_flush.py @@ -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: diff --git a/tests/test_threads.py b/tests/test_threads.py index 4b26ec3..aa5a459 100644 --- a/tests/test_threads.py +++ b/tests/test_threads.py @@ -2,7 +2,10 @@ from __future__ import annotations +import gc +import logging import threading +import weakref from typing import TYPE_CHECKING from unittest.mock import MagicMock @@ -10,7 +13,7 @@ from altissimo.mixpanel import MixpanelClient -from .conftest import RecordingConsumer +from .conftest import BufferingConsumer, FailingFlushConsumer, RecordingConsumer if TYPE_CHECKING: from collections.abc import Callable @@ -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."""