measurement-api 0.1.0__py3-none-any.whl

measurement_api/__init__.py

@@ -0,0 +1,3 @@
+from .main import MeasurementAPI
+
+__all__ = ["MeasurementAPI"]

measurement_api/main.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+
+import logging
+from types import TracebackType
+from typing import Self
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class MeasurementAPI:
+    """A client for interacting with the Google Analytics 4 Measurement Protocol."""
+
+    def __init__(
+        self,
+        m10t_id: str,
+        secret_key: str,
+        *,
+        debug: bool = False,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Initialize the client for sending events to Google Analytics.
+
+        Args:
+            m10t_id: Measurement ID (GA4 data stream measurement ID).
+            secret_key: API Secret Key.
+            debug: Debug mode (sends validation requests to the GA4 validation server).
+            client: External AsyncClient for connection sharing and pooling.
+        """
+        self.id = m10t_id
+        self.secret_key = secret_key
+        self.debug = debug
+        self.client = client
+        self._owns_client = client is None
+
+    async def __aenter__(self) -> Self:
+        if self.client is None:
+            self.client = httpx.AsyncClient()
+            self._owns_client = True
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the httpx client if it was created internally within the class."""
+        if self._owns_client and self.client is not None:
+            await self.client.aclose()
+            self.client = None
+
+    async def log_event(self, client_id: str, event_name: str, **kwargs) -> bool:
+        """Log an event in Google Analytics.
+
+        Args:
+            client_id: A unique identifier for the client.
+            event_name: The name of the event.
+            **kwargs: Event parameters (supports primitives, lists, and dicts).
+
+        Returns:
+            bool: True if the event was successfully sent/validated, False otherwise.
+        """
+        suffix = "debug/" if self.debug else ""
+        base_url = f"https://www.google-analytics.com/{suffix}mp/collect"
+        query_params = {"measurement_id": self.id, "api_secret": self.secret_key}
+
+        valid_params = {
+            k: v
+            for k, v in kwargs.items()
+            if isinstance(v, (str, int, float, bool, list, dict, tuple))
+        }
+
+        payload = {
+            "client_id": client_id,
+            "events": [
+                {
+                    "name": event_name,
+                    "params": valid_params,
+                }
+            ],
+        }
+
+        client = self.client
+        own_client = False
+        if client is None:
+            client = httpx.AsyncClient()
+            own_client = True
+
+        try:
+            logger.debug(
+                f"Sending GA event '{event_name}' to {base_url} with payload {payload}"
+            )
+            response = await client.post(
+                base_url, params=query_params, json=payload, timeout=5.0
+            )
+
+            if self.debug:
+                if response.status_code != 200:
+                    logger.warning(
+                        f"GA debug unexpected status: {response.status_code}"
+                    )
+                    return False
+
+                debug_result = response.json()
+                validation_messages = debug_result.get("validationMessages", [])
+
+                if validation_messages:
+                    logger.warning(f"GA validation issues: {validation_messages}")
+                    return False
+                else:
+                    logger.debug(f"GA event '{event_name}' validated successfully")
+                    return True
+            else:
+                if response.status_code == 204:
+                    logger.info(f"GA event '{event_name}' sent successfully")
+                    return True
+                else:
+                    logger.warning(
+                        f"GA unexpected status {response.status_code} "
+                        f"for event '{event_name}'"
+                    )
+                    return False
+
+        except httpx.TimeoutException:
+            logger.error("Analytics request timeout")
+            return False
+
+        except httpx.RequestError as e:
+            logger.error(f"Analytics request failed: {e}")
+            return False
+
+        except Exception as e:
+            logger.exception(f"Unexpected analytics error: {e}")
+            return False
+
+        finally:
+            if own_client:
+                await client.aclose()

measurement_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: measurement-api
+Version: 0.1.0
+Summary: A lightweight asynchronous Python client for the Google Analytics 4 Measurement Protocol
+Author-email: Andrii Bogdanovych <a@bogdanovych.org>
+License-Expression: MIT
+Project-URL: Homepage, https://www.bogdanovych.org
+Project-URL: Repository, https://github.com/BogdanovychA/measurement-api
+Project-URL: Bug Tracker, https://github.com/BogdanovychA/measurement-api/issues
+Project-URL: AI Agent Skill, https://skills.sh/bogdanovycha/measurement-api/measurement-api
+Keywords: google-analytics,ga4,measurement-protocol,async,asyncio,httpx,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# measurement-api
+
+A lightweight asynchronous Python client for the Google Analytics 4 (GA4) Measurement Protocol.
+
+[![PyPI version](https://img.shields.io/pypi/v/measurement-api.svg)](https://pypi.org/project/measurement-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/measurement-api.svg)](https://pypi.org/project/measurement-api/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ⚡ **Asynchronous**: Built on top of `httpx` for efficient, non-blocking requests.
+- 🔄 **Connection Pooling**: Supports async context manager syntax and custom `httpx.AsyncClient` injection to share/reuse TCP connections.
+- 🐛 **Validation Mode**: Integrates with GA4's validation server `/debug/mp/collect` to verify your payloads without logging dummy events in production.
+- 📦 **Complex Event Parameters**: Supports nested structures like lists (e.g. for E-commerce tracking `items`), dictionaries, and primitives.
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install measurement-api
+```
+
+Or using `uv`:
+
+```bash
+uv add measurement-api
+```
+
+## Quickstart
+
+### Basic Async Usage
+
+```python
+import asyncio
+from measurement_api import MeasurementAPI
+
+async def main():
+    # Initialize the client
+    api = MeasurementAPI(
+        m10t_id="G-XXXXXXXXXX",
+        secret_key="your_api_secret_key"
+    )
+
+    # Log an event
+    success = await api.log_event(
+        client_id="user_12345",
+        event_name="button_click",
+        button_id="submit_form",
+        page_url="https://example.com"
+    )
+
+    if success:
+        print("Event sent successfully!")
+    else:
+        print("Failed to send event.")
+
+asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Context Manager (Connection Reuse)
+
+When sending multiple events, use the async context manager to reuse the HTTP client's connection pool. This avoids the overhead of establishing a new TCP/TLS connection for every single event.
+
+```python
+import asyncio
+from measurement_api import MeasurementAPI
+
+async def main():
+    async with MeasurementAPI("G-XXXXXXXXXX", "your_secret") as api:
+        # Both events share the same connection pool
+        await api.log_event("user_1", "view_item", item_name="T-Shirt")
+        await api.log_event("user_1", "add_to_cart", item_name="T-Shirt")
+
+asyncio.run(main())
+```
+
+### Passing a Custom `httpx.AsyncClient`
+
+If your application already manages a global HTTP client (e.g. in FastAPI or Sanic), you can inject it directly:
+
+```python
+import httpx
+from measurement_api import MeasurementAPI
+
+async def send_analytics():
+    # Inject your own shared client
+    async with httpx.AsyncClient() as shared_client:
+        api = MeasurementAPI(
+            "G-XXXXXXXXXX",
+            "your_secret",
+            client=shared_client
+        )
+
+        # This will not close the injected client on exit or completion
+        await api.log_event("user_1", "purchase", value=99.99)
+```
+
+### Debug & Validation Mode
+
+To validate your event structure against Google's GA4 validation server, initialize the client with `debug=True`.
+*Note: Events sent to the validation server do not show up in GA4 reports.*
+
+```python
+from measurement_api import MeasurementAPI
+
+api = MeasurementAPI("G-XXXXXXXXXX", "your_secret", debug=True)
+
+# This request goes to https://www.google-analytics.com/debug/mp/collect
+# Returns True if validation passes, False if there are validation warnings/errors
+success = await api.log_event("user_1", "purchase", items=[{"item_id": "SKU_123"}])
+```
+
+## Development & Testing
+
+### Running Tests
+
+We use `pytest` and `respx` to test the client offline without sending actual requests to Google Analytics.
+
+1. Install dependencies:
+   ```bash
+   uv sync --group dev
+   ```
+
+2. Run the test suite:
+   ```bash
+   uv run pytest
+   ```
+
+3. Run linting checks:
+   ```bash
+   uv run ruff check
+   ```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

measurement_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+measurement_api/__init__.py,sha256=w3Sz6ofFgSuHtLcca0-sPz5irZmAxjifLH5yFvCJ7GE,63
+measurement_api/main.py,sha256=MwsPvHPVLZvHxMcLVqBKQnzImCuncGUN11AUclpKEXc,4604
+measurement_api-0.1.0.dist-info/licenses/AUTHORS.md,sha256=tUUQeXubDx91l_FJTpY6CGc-34Ri6Y497kM-GBbFhUs,182
+measurement_api-0.1.0.dist-info/licenses/LICENSE,sha256=uZ9Mr4r9lJayvgB_hif-TnHqCN8hVudeMB2oXwOOUms,1062
+measurement_api-0.1.0.dist-info/METADATA,sha256=SP2Tnunq7VL_f0zQRwF7_HHnZmkjAyQ7liLQY32bPjs,5171
+measurement_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+measurement_api-0.1.0.dist-info/top_level.txt,sha256=RdyN-gxcV0IDBmQ-ai_jv7EkIb6VYo5U19S7oA6pvnI,16
+measurement_api-0.1.0.dist-info/RECORD,,

measurement_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

measurement_api-0.1.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,6 @@
+# Authors
+
+## Lead Developer
+* **Andrii Bogdanovych**
+    * [bogdanovych.org](https://www.bogdanovych.org/)
+    * ORCID: [0009-0006-9045-5675](https://orcid.org/0009-0006-9045-5675)

measurement_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Andrii Bogdanovych
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

measurement_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+measurement_api