pulsegrid 0.1.0__tar.gz

pulsegrid-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pulsegrid
+Version: 0.1.0
+Summary: Official Python SDK for the PulseGrid realtime platform
+Author: Kwandile Mofokeng
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kwandiletshepo/pulsegrid-python
+Project-URL: Repository, https://github.com/Kwandiletshepo/pulsegrid-python
+Project-URL: Issues, https://github.com/Kwandiletshepo/pulsegrid-python/issues
+Keywords: pulsegrid,realtime,websocket,channels,presence,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.8.0
+
+# PulseGrid Python SDK
+
+Official Python SDK for PulseGrid.
+
+## Install
+
+```bash
+pip install pulsegrid

pulsegrid-0.1.0/README.md

@@ -0,0 +1,8 @@
+# PulseGrid Python SDK
+
+Official Python SDK for PulseGrid.
+
+## Install
+
+```bash
+pip install pulsegrid

pulsegrid-0.1.0/pulsegrid/__init__.py

@@ -0,0 +1,4 @@
+from .client import create_pulsegrid, PulseGridClient
+
+__all__ = ["create_pulsegrid", "PulseGridClient"]
+__version__ = "0.1.0"

pulsegrid-0.1.0/pulsegrid/client.py

@@ -0,0 +1,364 @@
+import json
+from typing import Any, Callable, Dict, Optional
+
+import requests
+from websocket import WebSocketApp
+
+
+def create_pulsegrid(
+    *,
+    base_url: str,
+    public_key: str,
+    secret_key: str,
+    project_id: str,
+) -> "PulseGridClient":
+    return PulseGridClient(
+        base_url=base_url,
+        public_key=public_key,
+        secret_key=secret_key,
+        project_id=project_id,
+    )
+
+
+class PulseGridClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        public_key: str,
+        secret_key: str,
+        project_id: str,
+    ) -> None:
+        self.base_url = (base_url or "").rstrip("/")
+        self.public_key = public_key or ""
+        self.secret_key = secret_key or ""
+        self.project_id = project_id or ""
+
+        if not self.base_url:
+            raise ValueError("base_url is required.")
+        if not self.public_key:
+            raise ValueError("public_key is required.")
+        if not self.secret_key:
+            raise ValueError("secret_key is required.")
+        if not self.project_id:
+            raise ValueError("project_id is required.")
+
+        self.projects = ProjectHelpers(self)
+        self.tokens = TokenHelpers(self)
+
+    def _headers(self, *, json_body: bool = False) -> Dict[str, str]:
+        headers = {
+            "X-PulseGrid-Public-Key": self.public_key,
+            "X-PulseGrid-Secret-Key": self.secret_key,
+        }
+        if json_body:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _read_json(self, response: requests.Response) -> Dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise RuntimeError(
+                f"PulseGrid returned a non-JSON response with status {response.status_code}."
+            ) from exc
+
+        if not response.ok:
+            message = (
+                data.get("error", {}).get("message")
+                or data.get("message")
+                or f"PulseGrid request failed with status {response.status_code}."
+            )
+            raise RuntimeError(message)
+
+        return data
+
+    def _ws_base(self) -> str:
+        if self.base_url.startswith("https://"):
+            return self.base_url.replace("https://", "wss://", 1)
+        if self.base_url.startswith("http://"):
+            return self.base_url.replace("http://", "ws://", 1)
+        return self.base_url
+
+    def test_auth(self) -> Dict[str, Any]:
+        response = requests.post(
+            f"{self.base_url}/api/auth/test/",
+            headers=self._headers(),
+            timeout=30,
+        )
+        return self._read_json(response)
+
+    def channel(self, channel_slug: str) -> "PulseGridChannel":
+        if not channel_slug or not channel_slug.strip():
+            raise ValueError("channel_slug is required.")
+        return PulseGridChannel(self, channel_slug.strip())
+
+
+class ProjectHelpers:
+    def __init__(self, client: PulseGridClient) -> None:
+        self.client = client
+
+    def list(self) -> Dict[str, Any]:
+        response = requests.get(
+            f"{self.client.base_url}/api/projects/",
+            headers=self.client._headers(),
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+
+class TokenHelpers:
+    def __init__(self, client: PulseGridClient) -> None:
+        self.client = client
+
+    def create(
+        self,
+        *,
+        identifier_id: str,
+        identifier_label: str = "",
+        allowed_channels: Optional[list[str]] = None,
+        expires_in: int = 3600,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        if not identifier_id or not identifier_id.strip():
+            raise ValueError("identifier_id is required.")
+
+        payload = {
+            "project_id": self.client.project_id,
+            "identifier_id": identifier_id.strip(),
+            "identifier_label": identifier_label,
+            "allowed_channels": allowed_channels or [],
+            "expires_in": expires_in,
+            "metadata": metadata or {},
+        }
+
+        response = requests.post(
+            f"{self.client.base_url}/api/client-tokens/create/",
+            headers=self.client._headers(json_body=True),
+            data=json.dumps(payload),
+            timeout=30,
+        )
+
+        result = self.client._read_json(response)
+        return result["data"]["client_token"]["token"]
+
+
+class PulseGridChannel:
+    def __init__(self, client: PulseGridClient, channel_slug: str) -> None:
+        self.client = client
+        self.channel_slug = channel_slug
+
+    def list(self) -> Dict[str, Any]:
+        response = requests.get(
+            f"{self.client.base_url}/api/channels/",
+            headers=self.client._headers(),
+            params={"project_id": self.client.project_id},
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+    def create(
+        self,
+        *,
+        name: str,
+        channel_type: str = "public",
+        description: str = "",
+        persist_events: bool = True,
+        retention_days: int = 30,
+    ) -> Dict[str, Any]:
+        if not name or not name.strip():
+            raise ValueError("name is required.")
+
+        payload = {
+            "project_id": self.client.project_id,
+            "name": name.strip(),
+            "channel_type": channel_type,
+            "description": description,
+            "persist_events": persist_events,
+            "retention_days": retention_days,
+        }
+
+        response = requests.post(
+            f"{self.client.base_url}/api/channels/create/",
+            headers=self.client._headers(json_body=True),
+            data=json.dumps(payload),
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+    def publish(
+        self,
+        text: str,
+        *,
+        identifier_id: str = "server",
+        identifier_label: str = "Server",
+        event: str = "message",
+        meta: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        if not text or not str(text).strip():
+            raise ValueError("text is required.")
+
+        payload = {
+            "project_id": self.client.project_id,
+            "channel_slug": self.channel_slug,
+            "event": event,
+            "identifier_id": identifier_id,
+            "identifier_label": identifier_label,
+            "data": {
+                "text": str(text).strip(),
+                **(data or {}),
+            },
+            "meta": meta or {},
+        }
+
+        response = requests.post(
+            f"{self.client.base_url}/api/messages/publish/",
+            headers=self.client._headers(json_body=True),
+            data=json.dumps(payload),
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+    def presence(self) -> Dict[str, Any]:
+        response = requests.get(
+            f"{self.client.base_url}/api/channels/presence/",
+            headers=self.client._headers(),
+            params={
+                "project_id": self.client.project_id,
+                "channel_slug": self.channel_slug,
+            },
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+    def online_count(self) -> int:
+        result = self.presence()
+        return result["data"]["presence"]["online_count"]
+
+    def is_online(self, identifier_id: str) -> Dict[str, Any]:
+        if not identifier_id or not identifier_id.strip():
+            raise ValueError("identifier_id is required.")
+
+        response = requests.get(
+            f"{self.client.base_url}/api/channels/presence/check/",
+            headers=self.client._headers(),
+            params={
+                "project_id": self.client.project_id,
+                "channel_slug": self.channel_slug,
+                "identifier_id": identifier_id.strip(),
+            },
+            timeout=30,
+        )
+        return self.client._read_json(response)
+
+    def connect(
+        self,
+        *,
+        client_token: str,
+        on_open: Optional[Callable[[], None]] = None,
+        on_message: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_close: Optional[Callable[[int, str], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> "PulseGridConnection":
+        if not client_token or not client_token.strip():
+            raise ValueError("client_token is required.")
+
+        ws_url = (
+            f"{self.client._ws_base()}/ws/channels/"
+            f"{self.client.project_id}/{self.channel_slug}/?token={client_token}"
+        )
+
+        return PulseGridConnection(
+            ws_url=ws_url,
+            on_open=on_open,
+            on_message=on_message,
+            on_close=on_close,
+            on_error=on_error,
+        )
+
+
+class PulseGridConnection:
+    def __init__(
+        self,
+        *,
+        ws_url: str,
+        on_open: Optional[Callable[[], None]] = None,
+        on_message: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_close: Optional[Callable[[int, str], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        self.ws_url = ws_url
+        self._user_on_open = on_open
+        self._user_on_message = on_message
+        self._user_on_close = on_close
+        self._user_on_error = on_error
+
+        self._app = WebSocketApp(
+            self.ws_url,
+            on_open=self._handle_open,
+            on_message=self._handle_message,
+            on_close=self._handle_close,
+            on_error=self._handle_error,
+        )
+
+    def _handle_open(self, ws: WebSocketApp) -> None:
+        if callable(self._user_on_open):
+            self._user_on_open()
+
+    def _handle_message(self, ws: WebSocketApp, message: str) -> None:
+        try:
+            payload = json.loads(message)
+        except ValueError:
+            payload = {"raw": message}
+
+        if callable(self._user_on_message):
+            self._user_on_message(payload)
+
+    def _handle_close(self, ws: WebSocketApp, code: int, reason: str) -> None:
+        if callable(self._user_on_close):
+            self._user_on_close(code, reason or "")
+
+    def _handle_error(self, ws: WebSocketApp, error: Exception) -> None:
+        if callable(self._user_on_error):
+            self._user_on_error(error)
+
+    def send(
+        self,
+        text: str,
+        *,
+        event: str = "message",
+        meta: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if not text or not str(text).strip():
+            raise ValueError("text is required.")
+
+        payload = {
+            "event": event,
+            "data": {
+                "text": str(text).strip(),
+                **(data or {}),
+            },
+            "meta": meta or {},
+        }
+
+        self._app.send(json.dumps(payload))
+
+    def request_presence_snapshot(self) -> None:
+        self._app.send(json.dumps({"action": "presence.snapshot"}))
+
+    def check_presence(self, identifier_id: str) -> None:
+        if not identifier_id or not identifier_id.strip():
+            raise ValueError("identifier_id is required.")
+
+        self._app.send(json.dumps({
+            "action": "presence.check",
+            "identifier_id": identifier_id.strip(),
+        }))
+
+    def run_forever(self) -> None:
+        self._app.run_forever()
+
+    def close(self) -> None:
+        self._app.close()

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

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pulsegrid
+Version: 0.1.0
+Summary: Official Python SDK for the PulseGrid realtime platform
+Author: Kwandile Mofokeng
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kwandiletshepo/pulsegrid-python
+Project-URL: Repository, https://github.com/Kwandiletshepo/pulsegrid-python
+Project-URL: Issues, https://github.com/Kwandiletshepo/pulsegrid-python/issues
+Keywords: pulsegrid,realtime,websocket,channels,presence,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.8.0
+
+# PulseGrid Python SDK
+
+Official Python SDK for PulseGrid.
+
+## Install
+
+```bash
+pip install pulsegrid

pulsegrid-0.1.0/pulsegrid.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+pulsegrid/__init__.py
+pulsegrid/client.py
+pulsegrid.egg-info/PKG-INFO
+pulsegrid.egg-info/SOURCES.txt
+pulsegrid.egg-info/dependency_links.txt
+pulsegrid.egg-info/requires.txt
+pulsegrid.egg-info/top_level.txt

pulsegrid-0.1.0/pulsegrid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pulsegrid-0.1.0/pulsegrid.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+websocket-client>=1.8.0

pulsegrid-0.1.0/pulsegrid.egg-info/top_level.txt

@@ -0,0 +1 @@
+pulsegrid

pulsegrid-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pulsegrid"
+version = "0.1.0"
+description = "Official Python SDK for the PulseGrid realtime platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Kwandile Mofokeng" }
+]
+dependencies = [
+  "requests>=2.31.0",
+  "websocket-client>=1.8.0"
+]
+keywords = ["pulsegrid", "realtime", "websocket", "channels", "presence", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["pulsegrid*"]
+
+[project.urls]
+Homepage = "https://github.com/Kwandiletshepo/pulsegrid-python"
+Repository = "https://github.com/Kwandiletshepo/pulsegrid-python"
+Issues = "https://github.com/Kwandiletshepo/pulsegrid-python/issues"

pulsegrid-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+