cloudflare-analytics 0.1.1__py3-none-any.whl

cloudflare_analytics/__init__.py

@@ -0,0 +1,26 @@
+"""
+Cloudflare Analytics GraphQL API client.
+
+API docs: https://developers.cloudflare.com/analytics/graphql-api/
+"""
+
+import logging
+import os
+
+from .client import CloudflareAnalyticsClient, GraphQLResponse, get_analytics_client
+
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "CloudflareAnalyticsClient",
+    "GraphQLResponse",
+    "get_analytics_client",
+]
+
+
+def main():
+    logger.info("Cloudflare Analytics Client - use as a library")

cloudflare_analytics/client.py

@@ -0,0 +1,157 @@
+"""
+Cloudflare Analytics GraphQL API client.
+
+API docs: https://developers.cloudflare.com/analytics/graphql-api/
+"""
+
+import logging
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+logger = logging.getLogger(__name__)
+
+_analytics_client: "CloudflareAnalyticsClient | None" = None
+
+
+class GraphQLResponse(BaseModel):
+    data: dict[str, Any] | None = None
+    errors: list[dict[str, Any]] | None = None
+
+
+class CloudflareAnalyticsClient:
+    """
+    Client for interacting with the Cloudflare GraphQL Analytics API using httpx.
+
+    Example usage:
+
+        from cloudflare_analytics import CloudflareAnalyticsClient
+
+        client = CloudflareAnalyticsClient(api_token="your_token")
+
+        query = '''
+        query GetStreamMinutes($accountTag: string!, $start: Date, $end: Date) {
+          viewer {
+            accounts(filter: { accountTag: $accountTag }) {
+              streamMinutesViewedAdaptiveGroups(
+                filter: { date_geq: $start, date_lt: $end }
+                orderBy: [date_ASC]
+              ) {
+                dimensions { date }
+                sum { minutesViewed }
+              }
+            }
+          }
+        }
+        '''
+
+        response = client.query(
+            query,
+            variables={
+                "accountTag": "your_account_id",
+                "start": "2025-10-01",
+                "end": "2025-10-28"
+            }
+        )
+
+        if response.errors:
+            logger.error("graphql errors", extra={"errors": response.errors})
+        elif response.data:
+            groups = response.data["viewer"]["accounts"][0]["streamMinutesViewedAdaptiveGroups"]
+            for group in groups:
+                minutes = group["sum"]["minutesViewed"]
+                date = group["dimensions"]["date"]
+                logger.info("stream data", extra={"date": date, "minutes": minutes})
+    """
+
+    def __init__(self, api_token: str):
+        if not api_token:
+            raise ValueError("API token must be provided.")
+
+        self.api_token = api_token
+        self.base_url = "https://api.cloudflare.com/client/v4"
+
+    @retry(
+        stop=stop_after_attempt(6),
+        wait=wait_exponential(multiplier=1, min=0, max=32),
+        retry=retry_if_exception_type(httpx.HTTPError),
+        before_sleep=before_sleep_log(logger, logging.INFO),
+        reraise=True,
+    )
+    def _make_request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """
+        Internal method to make the HTTP POST request to the GraphQL endpoint.
+
+        Args:
+            payload: Dictionary containing query and optional variables
+
+        Returns:
+            The JSON response as a dictionary
+        """
+        url = f"{self.base_url}/graphql"
+        headers = {"Authorization": f"Bearer {self.api_token}"}
+
+        logger.debug(
+            "cloudflare graphql request", extra={"url": url, "payload": payload}
+        )
+
+        response = httpx.post(url, json=payload, headers=headers)
+        response.raise_for_status()
+
+        json_data = response.json()
+        logger.info(
+            "cloudflare graphql response", extra={"status": response.status_code}
+        )
+
+        return json_data
+
+    def query(
+        self, query: str, variables: dict[str, Any] | None = None
+    ) -> GraphQLResponse:
+        """Execute a GraphQL query against the Cloudflare Analytics API.
+
+        Args:
+            query: GraphQL query string
+            variables: Optional variables for the query
+
+        Returns:
+            GraphQLResponse containing data or errors
+
+        Raises:
+            httpx.HTTPError: If the request fails after retries
+        """
+        payload: dict[str, Any] = {"query": query}
+        if variables:
+            payload["variables"] = variables
+
+        json_data = self._make_request(payload)
+
+        return GraphQLResponse(
+            data=json_data.get("data"), errors=json_data.get("errors")
+        )
+
+
+def get_analytics_client(api_token: str) -> CloudflareAnalyticsClient:
+    """
+    Get or create the global Cloudflare Analytics client instance.
+
+    Args:
+        api_token: Cloudflare API token
+
+    Returns:
+        CloudflareAnalyticsClient: The configured analytics client instance
+    """
+    global _analytics_client
+
+    if _analytics_client is None:
+        _analytics_client = CloudflareAnalyticsClient(api_token=api_token)
+
+    return _analytics_client

cloudflare_analytics-0.1.1.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: cloudflare-analytics
+Version: 0.1.1
+Summary: Cloudflare Analytics GraphQL API client
+Keywords: cloudflare,analytics,graphql
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/iloveitaly/cloudflare-analytics
+Description-Content-Type: text/markdown
+
+# Python Cloudflare Analytics Client
+
+A Python client for interacting with the [Cloudflare GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/).
+
+> **Note:** The official Cloudflare Python library does not support the GraphQL Analytics API endpoints. This library provides dedicated support for querying Cloudflare analytics data.
+
+## Installation
+
+```bash
+uv add cloudflare-analytics
+```
+
+## Usage
+
+```python
+from cloudflare_analytics import client
+
+# Execute a GraphQL query
+query = '''
+query GetStreamMinutes($accountTag: string!, $start: Date, $end: Date) {
+  viewer {
+    accounts(filter: { accountTag: $accountTag }) {
+      streamMinutesViewedAdaptiveGroups(
+        filter: { date_geq: $start, date_lt: $end }
+        orderBy: [date_ASC]
+      ) {
+        dimensions { date }
+        sum { minutesViewed }
+      }
+    }
+  }
+}
+'''
+
+response = client.query(
+    query,
+    variables={
+        "accountTag": "your_account_id",
+        "start": "2025-10-01",
+        "end": "2025-10-28"
+    },
+    api_token="your_cloudflare_api_token"
+)
+
+if response.errors:
+    print(f"Errors: {response.errors}")
+elif response.data:
+    groups = response.data["viewer"]["accounts"][0]["streamMinutesViewedAdaptiveGroups"]
+    for group in groups:
+        minutes = group["sum"]["minutesViewed"]
+        date = group["dimensions"]["date"]
+        print(f"Date: {date}, Minutes: {minutes}")
+```
+
+## Features
+
+- Simple, clean API for Cloudflare GraphQL Analytics
+- Built-in retry logic with exponential backoff
+- Type-safe responses using Pydantic models
+- Comprehensive error handling
+
+## [MIT License](LICENSE.md)

cloudflare_analytics-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+cloudflare_analytics/__init__.py,sha256=YjAPfeP55HEhOmpQfevStNG1svRvgJ6k7ScTr7kOoDQ,525
+cloudflare_analytics/client.py,sha256=GGcl7fZtCJMKldi91AMxe1jOlh6G6I_ni4KC-2VASys,4517
+cloudflare_analytics-0.1.1.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+cloudflare_analytics-0.1.1.dist-info/entry_points.txt,sha256=GHeI44VGvKgmiH2T36QidTL4bZDbkcCqjPUi0FYOEdk,68
+cloudflare_analytics-0.1.1.dist-info/METADATA,sha256=HlgNWdQDxYIvDy8K2svZgEtXamvq7OAB8GYdXZ13l0o,2086
+cloudflare_analytics-0.1.1.dist-info/RECORD,,

cloudflare_analytics-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.17
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudflare_analytics-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cloudflare-analytics = cloudflare_analytics:main
+