semetrics-sdk 0.1.0__tar.gz

semetrics_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: semetrics-sdk
+Version: 0.1.0
+Summary: Python SDK for Semetrics — AI-first product analytics platform
+License: MIT
+Project-URL: Homepage, https://semetrics.ru
+Project-URL: Repository, https://github.com/trombocit/semetrics-python
+Keywords: analytics,tracking,semetrics,product-analytics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+
+# Semetrics Python SDK
+
+Python SDK для отправки аналитических событий на платформу Semetrics.
+
+## Установка
+
+```bash
+pip install semetrics-sdk
+```
+
+## Быстрый старт
+
+```python
+from semetrics import Semetrics
+
+# Инициализация (один раз при старте приложения)
+semetrics = Semetrics(
+    api_key="sm_live_ваш_ключ",
+    endpoint="https://semetrics.ru/events",
+)
+
+# Отправка событий (не блокирует — очередь + фоновый поток)
+semetrics.track(
+    event_name="user_signed_up",
+    user_id="user_123",
+    properties={"plan": "pro", "source": "organic"},
+)
+
+semetrics.track(
+    event_name="checkout_completed",
+    user_id="user_123",
+    properties={"amount": 1990, "currency": "RUB", "items": 3},
+)
+
+# При завершении программы — отправить все накопленные события
+semetrics.shutdown()
+```
+
+## Использование через контекстный менеджер
+
+```python
+with Semetrics(api_key="sm_live_...", endpoint="https://semetrics.ru/events") as sm:
+    sm.track("page_viewed", user_id="u1", properties={"page": "/home"})
+# shutdown() вызывается автоматически при выходе из блока
+```
+
+## Параметры конструктора
+
+| Параметр | По умолчанию | Описание |
+|----------|-------------|----------|
+| `api_key` | обязательный | API-ключ проекта (`sm_live_...`) |
+| `endpoint` | `https://semetrics.ru/events` | URL сервиса |
+| `flush_interval` | `5` | Интервал фонового сброса (секунды) |
+| `batch_size` | `50` | Максимум событий в одном запросе |
+| `max_queue_size` | `10_000` | Максимум событий в памяти |
+| `max_retries` | `3` | Попыток при ошибке отправки |
+| `request_timeout` | `10` | Таймаут HTTP запроса (секунды) |
+| `persistence_path` | `None` | Путь к SQLite для персистентной очереди |
+
+## Персистентная очередь (опционально)
+
+Для серверных приложений с требованием "ни одно событие не должно потеряться":
+
+```python
+semetrics = Semetrics(
+    api_key="sm_live_...",
+    endpoint="https://semetrics.ru/events",
+    persistence_path="/var/lib/myapp/semetrics_queue.db",
+)
+```
+
+События сохраняются в SQLite и отправляются даже после перезапуска процесса.
+
+## Принудительный сброс
+
+```python
+# Отправить всё накопленное прямо сейчас (блокирует до завершения)
+semetrics.flush()
+```
+
+## Поля события
+
+| Поле | Тип | Обязательное | Описание |
+|------|-----|-------------|----------|
+| `event_name` | str | ✅ | Название события |
+| `user_id` | str | — | ID аутентифицированного пользователя |
+| `anonymous_id` | str | — | ID анонимного пользователя |
+| `session_id` | str | — | ID сессии |
+| `properties` | dict | — | Произвольные свойства события |
+| `client_ts` | datetime | — | Время события (по умолчанию — `now()`) |

semetrics_sdk-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Semetrics Python SDK
+
+Python SDK для отправки аналитических событий на платформу Semetrics.
+
+## Установка
+
+```bash
+pip install semetrics-sdk
+```
+
+## Быстрый старт
+
+```python
+from semetrics import Semetrics
+
+# Инициализация (один раз при старте приложения)
+semetrics = Semetrics(
+    api_key="sm_live_ваш_ключ",
+    endpoint="https://semetrics.ru/events",
+)
+
+# Отправка событий (не блокирует — очередь + фоновый поток)
+semetrics.track(
+    event_name="user_signed_up",
+    user_id="user_123",
+    properties={"plan": "pro", "source": "organic"},
+)
+
+semetrics.track(
+    event_name="checkout_completed",
+    user_id="user_123",
+    properties={"amount": 1990, "currency": "RUB", "items": 3},
+)
+
+# При завершении программы — отправить все накопленные события
+semetrics.shutdown()
+```
+
+## Использование через контекстный менеджер
+
+```python
+with Semetrics(api_key="sm_live_...", endpoint="https://semetrics.ru/events") as sm:
+    sm.track("page_viewed", user_id="u1", properties={"page": "/home"})
+# shutdown() вызывается автоматически при выходе из блока
+```
+
+## Параметры конструктора
+
+| Параметр | По умолчанию | Описание |
+|----------|-------------|----------|
+| `api_key` | обязательный | API-ключ проекта (`sm_live_...`) |
+| `endpoint` | `https://semetrics.ru/events` | URL сервиса |
+| `flush_interval` | `5` | Интервал фонового сброса (секунды) |
+| `batch_size` | `50` | Максимум событий в одном запросе |
+| `max_queue_size` | `10_000` | Максимум событий в памяти |
+| `max_retries` | `3` | Попыток при ошибке отправки |
+| `request_timeout` | `10` | Таймаут HTTP запроса (секунды) |
+| `persistence_path` | `None` | Путь к SQLite для персистентной очереди |
+
+## Персистентная очередь (опционально)
+
+Для серверных приложений с требованием "ни одно событие не должно потеряться":
+
+```python
+semetrics = Semetrics(
+    api_key="sm_live_...",
+    endpoint="https://semetrics.ru/events",
+    persistence_path="/var/lib/myapp/semetrics_queue.db",
+)
+```
+
+События сохраняются в SQLite и отправляются даже после перезапуска процесса.
+
+## Принудительный сброс
+
+```python
+# Отправить всё накопленное прямо сейчас (блокирует до завершения)
+semetrics.flush()
+```
+
+## Поля события
+
+| Поле | Тип | Обязательное | Описание |
+|------|-----|-------------|----------|
+| `event_name` | str | ✅ | Название события |
+| `user_id` | str | — | ID аутентифицированного пользователя |
+| `anonymous_id` | str | — | ID анонимного пользователя |
+| `session_id` | str | — | ID сессии |
+| `properties` | dict | — | Произвольные свойства события |
+| `client_ts` | datetime | — | Время события (по умолчанию — `now()`) |

semetrics_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semetrics-sdk"
+version = "0.1.0"
+description = "Python SDK for Semetrics — AI-first product analytics platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["analytics", "tracking", "semetrics", "product-analytics"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://semetrics.ru"
+Repository = "https://github.com/trombocit/semetrics-python"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-mock>=3", "respx>=0.21"]
+
+[tool.pytest.ini_options]
+markers = ["integration: требует локального docker-compose (запускать вручную)"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["semetrics*"]

semetrics_sdk-0.1.0/semetrics/__init__.py

@@ -0,0 +1,3 @@
+from .client import Semetrics
+
+__all__ = ["Semetrics"]

semetrics_sdk-0.1.0/semetrics/client.py

@@ -0,0 +1,84 @@
+import logging
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from .models import Event
+from .queue import EventQueue
+from .transport import HttpTransport
+from .worker import BackgroundWorker
+
+logger = logging.getLogger(__name__)
+
+SDK_VERSION = "0.1.0"
+
+
+class Semetrics:
+    """
+    Клиент Semetrics для Python.
+
+    Пример использования:
+        semetrics = Semetrics(api_key="sm_live_...", endpoint="https://semetrics.ru/events")
+        semetrics.track("user_signed_up", user_id="u123", properties={"plan": "pro"})
+        semetrics.shutdown()  # при завершении программы
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = "https://semetrics.ru/events",
+        flush_interval: int = 5,
+        batch_size: int = 50,
+        max_queue_size: int = 10_000,
+        max_retries: int = 3,
+        request_timeout: int = 10,
+        persistence_path: Optional[str] = None,
+    ):
+        self._queue = EventQueue(max_size=max_queue_size, persistence_path=persistence_path)
+        self._transport = HttpTransport(api_key=api_key, endpoint=endpoint, timeout=request_timeout)
+        self._worker = BackgroundWorker(
+            queue=self._queue,
+            transport=self._transport,
+            flush_interval=flush_interval,
+            batch_size=batch_size,
+            max_retries=max_retries,
+        )
+        self._worker.start()
+
+    def track(
+        self,
+        event_name: str,
+        user_id: Optional[str] = None,
+        anonymous_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        properties: Optional[dict[str, Any]] = None,
+        client_ts: Optional[datetime] = None,
+    ) -> None:
+        """
+        Добавить событие в очередь.
+        Не блокирует вызывающий код — отправка происходит в фоне.
+        """
+        event = Event(
+            event_name=event_name,
+            user_id=user_id,
+            anonymous_id=anonymous_id,
+            session_id=session_id,
+            platform="python",
+            sdk_version=SDK_VERSION,
+            properties=properties,
+            client_ts=client_ts or datetime.now(timezone.utc),
+        )
+        self._queue.enqueue(event)
+
+    def flush(self) -> None:
+        """Синхронно отправить все накопленные события прямо сейчас."""
+        self._worker.flush_sync()
+
+    def shutdown(self) -> None:
+        """Остановить фоновый worker и отправить всё накопленное перед выходом."""
+        self._worker.stop()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.shutdown()

semetrics_sdk-0.1.0/semetrics/models.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Optional
+import uuid
+
+
+@dataclass
+class Event:
+    event_name: str
+    client_ts: datetime
+    user_id: Optional[str] = None
+    anonymous_id: Optional[str] = None
+    session_id: Optional[str] = None
+    platform: str = "python"
+    sdk_version: str = "0.1.0"
+    properties: Optional[dict[str, Any]] = None
+    db_id: Optional[int] = None  # SQLite rowid, None для in-memory событий
+
+    def to_dict(self) -> dict:
+        return {
+            "event_name": self.event_name,
+            "user_id": self.user_id,
+            "anonymous_id": self.anonymous_id,
+            "session_id": self.session_id,
+            "platform": self.platform,
+            "sdk_version": self.sdk_version,
+            "client_ts": self.client_ts.isoformat(),
+            "properties": self.properties or {},
+        }

semetrics_sdk-0.1.0/semetrics/queue.py

@@ -0,0 +1,104 @@
+import json
+import logging
+import sqlite3
+import threading
+from collections import deque
+from typing import Optional
+
+from .models import Event
+
+logger = logging.getLogger(__name__)
+
+
+class EventQueue:
+    """
+    Thread-safe очередь событий.
+    По умолчанию — in-memory.
+    При указании persistence_path — дополнительно сохраняет в SQLite
+    (события переживают перезапуск процесса).
+    """
+
+    def __init__(self, max_size: int = 10_000, persistence_path: Optional[str] = None):
+        self._max_size = max_size
+        self._queue: deque[Event] = deque()
+        self._lock = threading.Lock()
+        self._db: Optional[sqlite3.Connection] = None
+
+        if persistence_path:
+            self._init_db(persistence_path)
+
+    def _init_db(self, path: str) -> None:
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.execute("""
+            CREATE TABLE IF NOT EXISTS queued_events (
+                id        INTEGER PRIMARY KEY AUTOINCREMENT,
+                payload   TEXT NOT NULL,
+                created_at REAL DEFAULT (unixepoch('now', 'subsec'))
+            )
+        """)
+        self._db.commit()
+        self._restore_from_db()
+
+    def _restore_from_db(self) -> None:
+        """Загрузить непереданные события из SQLite при старте."""
+        rows = self._db.execute("SELECT id, payload FROM queued_events ORDER BY id").fetchall()
+        for row_id, payload in rows:
+            try:
+                data = json.loads(payload)
+                from datetime import datetime
+                data["client_ts"] = datetime.fromisoformat(data["client_ts"])
+                event = Event(**data)
+                event.db_id = row_id
+                self._queue.append(event)
+            except Exception as exc:
+                logger.warning(f"Не удалось восстановить событие {row_id}: {exc}")
+        if rows:
+            logger.info(f"Восстановлено {len(rows)} событий из SQLite.")
+
+    def enqueue(self, event: Event) -> bool:
+        """Добавить событие в очередь. Возвращает False если очередь переполнена."""
+        with self._lock:
+            if len(self._queue) >= self._max_size:
+                logger.warning("Очередь переполнена, событие отброшено.")
+                return False
+            if self._db:
+                cursor = self._db.execute(
+                    "INSERT INTO queued_events (payload) VALUES (?)",
+                    (json.dumps(event.to_dict()),),
+                )
+                self._db.commit()
+                event.db_id = cursor.lastrowid
+            self._queue.append(event)
+            return True
+
+    def dequeue_batch(self, size: int) -> list[Event]:
+        """Извлечь до `size` событий из начала очереди."""
+        with self._lock:
+            batch = []
+            for _ in range(min(size, len(self._queue))):
+                batch.append(self._queue.popleft())
+            return batch
+
+    def requeue_batch(self, events: list[Event]) -> None:
+        """Вернуть события в начало очереди (после неудачной отправки)."""
+        with self._lock:
+            for event in reversed(events):
+                self._queue.appendleft(event)
+
+    def delete_from_db(self, events: list[Event]) -> None:
+        """Удалить отправленные события из SQLite по db_id."""
+        if not self._db:
+            return
+        ids = [e.db_id for e in events if e.db_id is not None]
+        if not ids:
+            return
+        with self._lock:
+            self._db.execute(
+                f"DELETE FROM queued_events WHERE id IN ({','.join('?' * len(ids))})",
+                ids,
+            )
+            self._db.commit()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._queue)

semetrics_sdk-0.1.0/semetrics/transport.py

@@ -0,0 +1,35 @@
+import logging
+
+import httpx
+
+from .models import Event
+
+logger = logging.getLogger(__name__)
+
+
+class HttpTransport:
+    def __init__(self, api_key: str, endpoint: str, timeout: int = 10):
+        self._api_key = api_key
+        self._batch_url = endpoint.rstrip("/") + "/ingest/batch"
+        self._timeout = timeout
+
+    def send_batch(self, events: list[Event]) -> None:
+        """
+        Отправить батч событий на сервер.
+        Поднимает исключение при ошибке (для retry-логики в worker'е).
+        """
+        payload = {"events": [e.to_dict() for e in events]}
+
+        with httpx.Client(timeout=self._timeout) as client:
+            response = client.post(
+                self._batch_url,
+                json=payload,
+                headers={"X-API-Key": self._api_key},
+            )
+            response.raise_for_status()
+
+            data = response.json()
+            if data.get("status", {}).get("code") not in ("", None):
+                raise RuntimeError(
+                    f"Сервер вернул ошибку: {data['status'].get('message')}"
+                )

semetrics_sdk-0.1.0/semetrics/worker.py

@@ -0,0 +1,69 @@
+import logging
+import threading
+import time
+
+from .queue import EventQueue
+from .transport import HttpTransport
+
+logger = logging.getLogger(__name__)
+
+
+class BackgroundWorker(threading.Thread):
+    """
+    Daemon thread, который периодически отправляет события из очереди.
+    Запускается при создании клиента, останавливается при shutdown().
+    """
+
+    def __init__(
+        self,
+        queue: EventQueue,
+        transport: HttpTransport,
+        flush_interval: int = 5,
+        batch_size: int = 50,
+        max_retries: int = 3,
+    ):
+        super().__init__(daemon=True, name="semetrics-worker")
+        self._queue = queue
+        self._transport = transport
+        self._flush_interval = flush_interval
+        self._batch_size = batch_size
+        self._max_retries = max_retries
+        self._stop_event = threading.Event()
+
+    def run(self) -> None:
+        while not self._stop_event.is_set():
+            self._stop_event.wait(timeout=self._flush_interval)
+            self._flush()
+
+    def flush_sync(self) -> None:
+        """Отправить всё что есть прямо сейчас (вызывается из основного потока)."""
+        while len(self._queue) > 0:
+            self._flush()
+
+    def stop(self) -> None:
+        """Остановить worker и отправить оставшиеся события."""
+        self._stop_event.set()
+        self.flush_sync()
+
+    def _flush(self) -> None:
+        batch = self._queue.dequeue_batch(self._batch_size)
+        if not batch:
+            return
+
+        for attempt in range(self._max_retries):
+            try:
+                self._transport.send_batch(batch)
+                self._queue.delete_from_db(batch)
+                logger.debug(f"Отправлено {len(batch)} событий.")
+                return
+            except Exception as exc:
+                wait = 2 ** attempt  # 1s, 2s, 4s
+                logger.warning(
+                    f"Ошибка отправки (попытка {attempt + 1}/{self._max_retries}): {exc}. "
+                    f"Повтор через {wait}с."
+                )
+                if attempt < self._max_retries - 1:
+                    time.sleep(wait)
+
+        # После всех попыток — логируем потерю батча
+        logger.error(f"Батч из {len(batch)} событий потерян после {self._max_retries} попыток.")

semetrics_sdk-0.1.0/semetrics_sdk.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: semetrics-sdk
+Version: 0.1.0
+Summary: Python SDK for Semetrics — AI-first product analytics platform
+License: MIT
+Project-URL: Homepage, https://semetrics.ru
+Project-URL: Repository, https://github.com/trombocit/semetrics-python
+Keywords: analytics,tracking,semetrics,product-analytics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+
+# Semetrics Python SDK
+
+Python SDK для отправки аналитических событий на платформу Semetrics.
+
+## Установка
+
+```bash
+pip install semetrics-sdk
+```
+
+## Быстрый старт
+
+```python
+from semetrics import Semetrics
+
+# Инициализация (один раз при старте приложения)
+semetrics = Semetrics(
+    api_key="sm_live_ваш_ключ",
+    endpoint="https://semetrics.ru/events",
+)
+
+# Отправка событий (не блокирует — очередь + фоновый поток)
+semetrics.track(
+    event_name="user_signed_up",
+    user_id="user_123",
+    properties={"plan": "pro", "source": "organic"},
+)
+
+semetrics.track(
+    event_name="checkout_completed",
+    user_id="user_123",
+    properties={"amount": 1990, "currency": "RUB", "items": 3},
+)
+
+# При завершении программы — отправить все накопленные события
+semetrics.shutdown()
+```
+
+## Использование через контекстный менеджер
+
+```python
+with Semetrics(api_key="sm_live_...", endpoint="https://semetrics.ru/events") as sm:
+    sm.track("page_viewed", user_id="u1", properties={"page": "/home"})
+# shutdown() вызывается автоматически при выходе из блока
+```
+
+## Параметры конструктора
+
+| Параметр | По умолчанию | Описание |
+|----------|-------------|----------|
+| `api_key` | обязательный | API-ключ проекта (`sm_live_...`) |
+| `endpoint` | `https://semetrics.ru/events` | URL сервиса |
+| `flush_interval` | `5` | Интервал фонового сброса (секунды) |
+| `batch_size` | `50` | Максимум событий в одном запросе |
+| `max_queue_size` | `10_000` | Максимум событий в памяти |
+| `max_retries` | `3` | Попыток при ошибке отправки |
+| `request_timeout` | `10` | Таймаут HTTP запроса (секунды) |
+| `persistence_path` | `None` | Путь к SQLite для персистентной очереди |
+
+## Персистентная очередь (опционально)
+
+Для серверных приложений с требованием "ни одно событие не должно потеряться":
+
+```python
+semetrics = Semetrics(
+    api_key="sm_live_...",
+    endpoint="https://semetrics.ru/events",
+    persistence_path="/var/lib/myapp/semetrics_queue.db",
+)
+```
+
+События сохраняются в SQLite и отправляются даже после перезапуска процесса.
+
+## Принудительный сброс
+
+```python
+# Отправить всё накопленное прямо сейчас (блокирует до завершения)
+semetrics.flush()
+```
+
+## Поля события
+
+| Поле | Тип | Обязательное | Описание |
+|------|-----|-------------|----------|
+| `event_name` | str | ✅ | Название события |
+| `user_id` | str | — | ID аутентифицированного пользователя |
+| `anonymous_id` | str | — | ID анонимного пользователя |
+| `session_id` | str | — | ID сессии |
+| `properties` | dict | — | Произвольные свойства события |
+| `client_ts` | datetime | — | Время события (по умолчанию — `now()`) |