syncforge 1.0.0__tar.gz

syncforge-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SyncForge
+
+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.

syncforge-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: syncforge
+Version: 1.0.0
+Summary: Official Python SDK for SyncForge — control exactly when data syncs between your database and clients.
+Author-email: SyncForge <sureshdulupolai@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sureshdulupolai/syncforge
+Project-URL: Documentation, https://syncforge.dev/docs/
+Project-URL: Repository, https://github.com/sureshdulupolai/syncforge
+Project-URL: Bug Tracker, https://github.com/sureshdulupolai/syncforge/issues
+Keywords: syncforge,sync,database,cache,invalidation,django,fastapi
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# SyncForge Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/syncforge)](https://pypi.org/project/syncforge/)
+[![Python](https://img.shields.io/pypi/pyversions/syncforge)](https://pypi.org/project/syncforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [SyncForge](https://syncforge.dev) data sync platform.  
+Control exactly when data syncs between your database and client applications — no polling, no wasted DB calls.
+
+---
+
+## Installation
+
+```bash
+pip install syncforge
+```
+
+**Zero external dependencies.** Uses only Python stdlib (`urllib`, `json`, `threading`).
+
+---
+
+## Quick Start
+
+```python
+from syncforge import SyncForge
+
+sf = SyncForge(api_key='sf_live_YOUR_KEY')
+
+# After any DB write — notify all connected clients
+sf.refresh('products')
+```
+
+---
+
+## The `syncforge.py` Pattern (Recommended)
+
+Place a `syncforge.py` file at your project root — same level as `manage.py` or `main.py`.  
+This mirrors the Celery pattern and gives you a single shared instance.
+
+```python
+# syncforge.py (project root)
+import os
+from syncforge import SyncForge
+
+sf = SyncForge(
+    api_key=os.environ.get('SYNCFORGE_API_KEY', 'sf_live_YOUR_KEY')
+)
+```
+
+Then import `sf` anywhere:
+
+```python
+# views.py / routes.py
+from syncforge import sf
+
+def create_product(request):
+    Product.objects.create(name='New Item', price=99.99)
+    sf.refresh('products')           # one line — all clients updated
+    return JsonResponse({'status': 'created'})
+```
+
+---
+
+## API Reference
+
+### `SyncForge(api_key, base_url, timeout, silent, async_mode)`
+
+| Parameter    | Default                        | Description                                          |
+|--------------|-------------------------------|------------------------------------------------------|
+| `api_key`    | required                       | Your API key (`sf_live_...`)                         |
+| `base_url`   | `https://syncforge.dev/api`   | Override for local dev / self-hosted                 |
+| `timeout`    | `10`                           | HTTP timeout in seconds                              |
+| `silent`     | `False`                        | Suppress errors — logs warnings instead of raising   |
+| `async_mode` | `False`                        | Fire-and-forget — refresh runs in a background thread|
+
+### `sf.refresh(*tables)` → `SyncResult | list[SyncResult]`
+
+```python
+sf.refresh('products')                         # single table
+sf.refresh('products', 'categories', 'orders') # multiple at once
+
+result = sf.refresh('products')
+print(result.ok)           # True
+print(result.calls_saved)  # 1854211
+print(result.sync_mode)    # 'Event — On INSERT / UPDATE / DELETE'
+```
+
+### `sf.ping()` → `bool`
+Health check — returns `True` if SyncForge is reachable.
+
+### `sf.project_info()` → `dict`
+Returns project metadata and all registered tables.
+
+### `sf.list_tables()` → `list`
+Lists all tables with their sync mode and stats.
+
+---
+
+## Django Integration
+
+```python
+# syncforge.py (next to manage.py)
+import os
+from syncforge import SyncForge
+sf = SyncForge(api_key=os.environ.get('SYNCFORGE_API_KEY'))
+
+# myapp/views.py
+from syncforge import sf
+
+def update_products(request):
+    Product.objects.filter(on_sale=True).update(price=F('price') * 0.9)
+    sf.refresh('products')
+    return JsonResponse({'status': 'updated'})
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from syncforge import sf
+
+app = FastAPI()
+
+@app.post("/products/")
+async def create_product(name: str, price: float):
+    db.execute("INSERT INTO products ...")
+    sf.refresh('products')
+    return {"status": "ok"}
+```
+
+---
+
+## Production Tips
+
+```python
+# Silent mode — SyncForge errors never crash your app
+sf = SyncForge(api_key='sf_live_...', silent=True)
+
+# Async mode — fire-and-forget, returns immediately
+sf = SyncForge(api_key='sf_live_...', async_mode=True)
+sf.refresh('products')  # returns None, syncs in background
+
+# Override base URL for local development
+sf = SyncForge(api_key='sf_live_...', base_url='http://localhost:8000/api')
+```
+
+---
+
+## Error Handling
+
+```python
+from syncforge import SyncForge, AuthError, TableNotFoundError, NetworkError
+
+sf = SyncForge(api_key='sf_live_...')
+try:
+    sf.refresh('products')
+except AuthError:
+    print("Invalid API key")
+except TableNotFoundError:
+    print("Register the table in your SyncForge dashboard first")
+except NetworkError:
+    print("Could not reach SyncForge — check your internet connection")
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

syncforge-1.0.0/README.md

@@ -0,0 +1,169 @@
+# SyncForge Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/syncforge)](https://pypi.org/project/syncforge/)
+[![Python](https://img.shields.io/pypi/pyversions/syncforge)](https://pypi.org/project/syncforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [SyncForge](https://syncforge.dev) data sync platform.  
+Control exactly when data syncs between your database and client applications — no polling, no wasted DB calls.
+
+---
+
+## Installation
+
+```bash
+pip install syncforge
+```
+
+**Zero external dependencies.** Uses only Python stdlib (`urllib`, `json`, `threading`).
+
+---
+
+## Quick Start
+
+```python
+from syncforge import SyncForge
+
+sf = SyncForge(api_key='sf_live_YOUR_KEY')
+
+# After any DB write — notify all connected clients
+sf.refresh('products')
+```
+
+---
+
+## The `syncforge.py` Pattern (Recommended)
+
+Place a `syncforge.py` file at your project root — same level as `manage.py` or `main.py`.  
+This mirrors the Celery pattern and gives you a single shared instance.
+
+```python
+# syncforge.py (project root)
+import os
+from syncforge import SyncForge
+
+sf = SyncForge(
+    api_key=os.environ.get('SYNCFORGE_API_KEY', 'sf_live_YOUR_KEY')
+)
+```
+
+Then import `sf` anywhere:
+
+```python
+# views.py / routes.py
+from syncforge import sf
+
+def create_product(request):
+    Product.objects.create(name='New Item', price=99.99)
+    sf.refresh('products')           # one line — all clients updated
+    return JsonResponse({'status': 'created'})
+```
+
+---
+
+## API Reference
+
+### `SyncForge(api_key, base_url, timeout, silent, async_mode)`
+
+| Parameter    | Default                        | Description                                          |
+|--------------|-------------------------------|------------------------------------------------------|
+| `api_key`    | required                       | Your API key (`sf_live_...`)                         |
+| `base_url`   | `https://syncforge.dev/api`   | Override for local dev / self-hosted                 |
+| `timeout`    | `10`                           | HTTP timeout in seconds                              |
+| `silent`     | `False`                        | Suppress errors — logs warnings instead of raising   |
+| `async_mode` | `False`                        | Fire-and-forget — refresh runs in a background thread|
+
+### `sf.refresh(*tables)` → `SyncResult | list[SyncResult]`
+
+```python
+sf.refresh('products')                         # single table
+sf.refresh('products', 'categories', 'orders') # multiple at once
+
+result = sf.refresh('products')
+print(result.ok)           # True
+print(result.calls_saved)  # 1854211
+print(result.sync_mode)    # 'Event — On INSERT / UPDATE / DELETE'
+```
+
+### `sf.ping()` → `bool`
+Health check — returns `True` if SyncForge is reachable.
+
+### `sf.project_info()` → `dict`
+Returns project metadata and all registered tables.
+
+### `sf.list_tables()` → `list`
+Lists all tables with their sync mode and stats.
+
+---
+
+## Django Integration
+
+```python
+# syncforge.py (next to manage.py)
+import os
+from syncforge import SyncForge
+sf = SyncForge(api_key=os.environ.get('SYNCFORGE_API_KEY'))
+
+# myapp/views.py
+from syncforge import sf
+
+def update_products(request):
+    Product.objects.filter(on_sale=True).update(price=F('price') * 0.9)
+    sf.refresh('products')
+    return JsonResponse({'status': 'updated'})
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from syncforge import sf
+
+app = FastAPI()
+
+@app.post("/products/")
+async def create_product(name: str, price: float):
+    db.execute("INSERT INTO products ...")
+    sf.refresh('products')
+    return {"status": "ok"}
+```
+
+---
+
+## Production Tips
+
+```python
+# Silent mode — SyncForge errors never crash your app
+sf = SyncForge(api_key='sf_live_...', silent=True)
+
+# Async mode — fire-and-forget, returns immediately
+sf = SyncForge(api_key='sf_live_...', async_mode=True)
+sf.refresh('products')  # returns None, syncs in background
+
+# Override base URL for local development
+sf = SyncForge(api_key='sf_live_...', base_url='http://localhost:8000/api')
+```
+
+---
+
+## Error Handling
+
+```python
+from syncforge import SyncForge, AuthError, TableNotFoundError, NetworkError
+
+sf = SyncForge(api_key='sf_live_...')
+try:
+    sf.refresh('products')
+except AuthError:
+    print("Invalid API key")
+except TableNotFoundError:
+    print("Register the table in your SyncForge dashboard first")
+except NetworkError:
+    print("Could not reach SyncForge — check your internet connection")
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

syncforge-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syncforge"
+version = "1.0.0"
+description = "Official Python SDK for SyncForge — control exactly when data syncs between your database and clients."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "SyncForge", email = "sureshdulupolai@gmail.com" }
+]
+keywords = ["syncforge", "sync", "database", "cache", "invalidation", "django", "fastapi"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Database",
+]
+requires-python = ">=3.8"
+dependencies = []   # zero external dependencies — only stdlib
+
+[project.urls]
+Homepage = "https://github.com/sureshdulupolai/syncforge"
+Documentation = "https://syncforge.dev/docs/"
+Repository = "https://github.com/sureshdulupolai/syncforge"
+"Bug Tracker" = "https://github.com/sureshdulupolai/syncforge/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["syncforge*"]

syncforge-1.0.0/setup.cfg

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

syncforge-1.0.0/syncforge/__init__.py

@@ -0,0 +1,30 @@
+"""
+SyncForge Python SDK
+~~~~~~~~~~~~~~~~~~~~
+Official Python client for the SyncForge data sync platform.
+
+Usage::
+
+    from syncforge import SyncForge
+    sf = SyncForge(api_key='sf_live_YOUR_KEY')
+    sf.refresh('products')
+
+Or use a project-level syncforge.py file (like Celery pattern)::
+
+    # syncforge.py
+    import os
+    from syncforge import SyncForge
+    sf = SyncForge(api_key=os.environ.get('SYNCFORGE_API_KEY'))
+
+    # In your views / handlers:
+    from syncforge import sf
+    sf.refresh('products')
+"""
+
+from .client import SyncForge
+from .result import SyncResult
+from .exceptions import SyncForgeError, AuthError, TableNotFoundError
+
+__version__ = "1.0.0"
+__author__ = "SyncForge"
+__all__ = ["SyncForge", "SyncResult", "SyncForgeError", "AuthError", "TableNotFoundError"]

syncforge-1.0.0/syncforge/client.py

@@ -0,0 +1,244 @@
+"""
+SyncForge Python SDK — Client
+"""
+from __future__ import annotations
+
+import threading
+import urllib.request
+import urllib.error
+import json
+import time
+from typing import Optional, Union, List
+
+from .result import SyncResult
+from .exceptions import (
+    SyncForgeError, AuthError, TableNotFoundError,
+    RateLimitError, NetworkError,
+)
+
+# Default production base URL — override for self-hosted or local dev
+DEFAULT_BASE_URL = "https://syncforge.dev/api"
+
+# Per-request timeout (seconds)
+DEFAULT_TIMEOUT = 10
+
+
+class SyncForge:
+    """
+    Official Python client for the SyncForge data sync platform.
+
+    Create one instance per project (API key) — typically in a
+    ``syncforge.py`` file at your project root, then import it
+    wherever needed::
+
+        # syncforge.py (project root)
+        import os
+        from syncforge import SyncForge
+
+        sf = SyncForge(api_key=os.environ.get('SYNCFORGE_API_KEY', 'sf_live_...'))
+
+        # views.py / routes.py / any handler
+        from syncforge import sf
+        sf.refresh('products')
+
+    Args:
+        api_key:    Your SyncForge API key (starts with ``sf_live_``).
+        base_url:   Override the base URL (useful for local dev / self-hosted).
+        timeout:    HTTP timeout in seconds (default: 10).
+        silent:     If ``True``, all errors are suppressed and logged instead
+                    of raised. Use this in production so a SyncForge outage
+                    never breaks your app flow. Default: ``False``.
+        async_mode: If ``True``, every ``refresh()`` call runs in a background
+                    thread and returns immediately. Default: ``False``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        silent: bool = False,
+        async_mode: bool = False,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required.")
+
+        self._api_key   = api_key.strip()
+        self._base_url  = base_url.rstrip("/")
+        self._timeout   = timeout
+        self._silent    = silent
+        self._async     = async_mode
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def refresh(self, *tables: str) -> Union[SyncResult, List[SyncResult], None]:
+        """
+        Trigger a data sync for one or more tables.
+
+        After any database write, call this to tell SyncForge to
+        broadcast the change to all connected clients.
+
+        Args:
+            *tables: One or more table names registered in your SyncForge
+                     dashboard (e.g. ``'products'``, ``'orders'``).
+
+        Returns:
+            A :class:`SyncResult` for a single table, or a list of
+            :class:`SyncResult` objects when multiple tables are passed.
+            Returns ``None`` when ``async_mode=True`` (fire-and-forget).
+
+        Raises:
+            :class:`AuthError`:           Invalid or missing API key.
+            :class:`TableNotFoundError`:  Table not registered in dashboard.
+            :class:`NetworkError`:        Connection / timeout failure.
+            :class:`SyncForgeError`:      Any other server-side error.
+
+        Examples::
+
+            # Single table
+            sf.refresh('products')
+
+            # Multiple tables at once
+            sf.refresh('products', 'categories', 'inventory')
+
+            # With result inspection
+            result = sf.refresh('products')
+            if result.ok:
+                print(f"{result.calls_saved} DB calls saved!")
+        """
+        if not tables:
+            raise ValueError("At least one table name is required.")
+
+        if self._async:
+            t = threading.Thread(
+                target=self._refresh_all,
+                args=(tables,),
+                daemon=True,
+            )
+            t.start()
+            return None
+
+        results = self._refresh_all(tables)
+        return results[0] if len(results) == 1 else results
+
+    def ping(self) -> bool:
+        """
+        Check that your API key is valid and SyncForge is reachable.
+
+        Returns:
+            ``True`` if the health endpoint responds, ``False`` otherwise.
+        """
+        try:
+            url = f"{self._base_url}/v1/health/"
+            self._request("GET", url)
+            return True
+        except Exception:
+            return False
+
+    def project_info(self) -> dict:
+        """
+        Fetch project metadata and registered tables for this API key.
+
+        Returns:
+            dict with ``project``, ``slug``, ``tables``, ``active_keys``.
+        """
+        url = f"{self._base_url}/v1/project/"
+        return self._request("GET", url)
+
+    def list_tables(self) -> list:
+        """
+        Return all tables registered in this project.
+
+        Returns:
+            List of dicts with ``table_name``, ``sync_mode``, ``rows_count``,
+            ``database_calls_saved``.
+        """
+        url = f"{self._base_url}/v1/tables/"
+        data = self._request("GET", url)
+        return data.get("tables", [])
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _refresh_all(self, tables: tuple) -> List[SyncResult]:
+        results = []
+        for table in tables:
+            try:
+                result = self._sync_one(table)
+                results.append(result)
+            except SyncForgeError as exc:
+                if self._silent:
+                    import warnings
+                    warnings.warn(f"[SyncForge] {exc} (table={table!r})", stacklevel=4)
+                    results.append(SyncResult(
+                        ok=False, table=table, message=str(exc),
+                        status_code=getattr(exc, 'status_code', None) or 0,
+                    ))
+                else:
+                    raise
+        return results
+
+    def _sync_one(self, table: str) -> SyncResult:
+        table = table.strip().lower()
+        if not table:
+            raise ValueError("Table name cannot be empty.")
+
+        url  = f"{self._base_url}/v1/sync/{table}/"
+        data = self._request("POST", url)
+
+        return SyncResult(
+            ok          = data.get("status") == "ok",
+            table       = data.get("table", table),
+            project     = data.get("project"),
+            sync_mode   = data.get("sync_mode"),
+            calls_saved = data.get("database_calls_saved", 0),
+            message     = data.get("message", ""),
+            raw         = data,
+            status_code = 200,
+        )
+
+    def _request(self, method: str, url: str) -> dict:
+        headers = {
+            "X-API-Key":    self._api_key,
+            "Content-Type": "application/json",
+            "Accept":       "application/json",
+            "User-Agent":   "syncforge-python/1.0.0",
+        }
+        body = b"" if method == "GET" else b"{}"
+        req  = urllib.request.Request(url, data=body, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw) if raw else {}
+
+        except urllib.error.HTTPError as exc:
+            raw  = exc.read().decode("utf-8", errors="replace")
+            data = {}
+            try:
+                data = json.loads(raw)
+            except Exception:
+                pass
+
+            error_msg = data.get("error", raw or exc.reason)
+            code      = exc.code
+
+            if code == 401:
+                raise AuthError(f"Invalid API key: {error_msg}", status_code=code)
+            if code == 404:
+                raise TableNotFoundError(
+                    f"Table not found — register it in your SyncForge dashboard. {error_msg}",
+                    status_code=code,
+                )
+            if code == 429:
+                raise RateLimitError(f"Rate limit exceeded: {error_msg}", status_code=code)
+            raise SyncForgeError(f"Server error {code}: {error_msg}", status_code=code)
+
+        except urllib.error.URLError as exc:
+            raise NetworkError(
+                f"Could not connect to SyncForge ({url}): {exc.reason}"
+            ) from exc
+
+        except TimeoutError:
+            raise NetworkError(
+                f"Request to SyncForge timed out after {self._timeout}s."
+            )

syncforge-1.0.0/syncforge/exceptions.py

@@ -0,0 +1,21 @@
+class SyncForgeError(Exception):
+    """Base exception for all SyncForge SDK errors."""
+    def __init__(self, message: str, status_code: int = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(SyncForgeError):
+    """Raised when the API key is missing, invalid, or revoked."""
+
+
+class TableNotFoundError(SyncForgeError):
+    """Raised when the table is not registered in the SyncForge dashboard."""
+
+
+class RateLimitError(SyncForgeError):
+    """Raised when the API rate limit is exceeded."""
+
+
+class NetworkError(SyncForgeError):
+    """Raised when the HTTP request fails (timeout, DNS, etc.)."""

syncforge-1.0.0/syncforge/result.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any
+
+
+@dataclass
+class SyncResult:
+    """
+    Returned by SyncForge.refresh().
+
+    Attributes:
+        ok              True if the sync was accepted by the server.
+        table           The table name that was synced.
+        project         The project name associated with the API key.
+        sync_mode       Human-readable sync mode label.
+        calls_saved     Cumulative database calls saved for this table.
+        message         Server response message.
+        raw             Full raw JSON response from the server.
+        status_code     HTTP status code.
+    """
+    ok: bool
+    table: str
+    project: Optional[str] = None
+    sync_mode: Optional[str] = None
+    calls_saved: int = 0
+    message: str = ""
+    raw: Dict[str, Any] = field(default_factory=dict)
+    status_code: int = 200
+
+    def __repr__(self):
+        status = "✓" if self.ok else "✗"
+        return f"<SyncResult {status} table={self.table!r} calls_saved={self.calls_saved}>"

syncforge-1.0.0/syncforge.egg-info/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: syncforge
+Version: 1.0.0
+Summary: Official Python SDK for SyncForge — control exactly when data syncs between your database and clients.
+Author-email: SyncForge <sureshdulupolai@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sureshdulupolai/syncforge
+Project-URL: Documentation, https://syncforge.dev/docs/
+Project-URL: Repository, https://github.com/sureshdulupolai/syncforge
+Project-URL: Bug Tracker, https://github.com/sureshdulupolai/syncforge/issues
+Keywords: syncforge,sync,database,cache,invalidation,django,fastapi
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# SyncForge Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/syncforge)](https://pypi.org/project/syncforge/)
+[![Python](https://img.shields.io/pypi/pyversions/syncforge)](https://pypi.org/project/syncforge/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official Python SDK for the [SyncForge](https://syncforge.dev) data sync platform.  
+Control exactly when data syncs between your database and client applications — no polling, no wasted DB calls.
+
+---
+
+## Installation
+
+```bash
+pip install syncforge
+```
+
+**Zero external dependencies.** Uses only Python stdlib (`urllib`, `json`, `threading`).
+
+---
+
+## Quick Start
+
+```python
+from syncforge import SyncForge
+
+sf = SyncForge(api_key='sf_live_YOUR_KEY')
+
+# After any DB write — notify all connected clients
+sf.refresh('products')
+```
+
+---
+
+## The `syncforge.py` Pattern (Recommended)
+
+Place a `syncforge.py` file at your project root — same level as `manage.py` or `main.py`.  
+This mirrors the Celery pattern and gives you a single shared instance.
+
+```python
+# syncforge.py (project root)
+import os
+from syncforge import SyncForge
+
+sf = SyncForge(
+    api_key=os.environ.get('SYNCFORGE_API_KEY', 'sf_live_YOUR_KEY')
+)
+```
+
+Then import `sf` anywhere:
+
+```python
+# views.py / routes.py
+from syncforge import sf
+
+def create_product(request):
+    Product.objects.create(name='New Item', price=99.99)
+    sf.refresh('products')           # one line — all clients updated
+    return JsonResponse({'status': 'created'})
+```
+
+---
+
+## API Reference
+
+### `SyncForge(api_key, base_url, timeout, silent, async_mode)`
+
+| Parameter    | Default                        | Description                                          |
+|--------------|-------------------------------|------------------------------------------------------|
+| `api_key`    | required                       | Your API key (`sf_live_...`)                         |
+| `base_url`   | `https://syncforge.dev/api`   | Override for local dev / self-hosted                 |
+| `timeout`    | `10`                           | HTTP timeout in seconds                              |
+| `silent`     | `False`                        | Suppress errors — logs warnings instead of raising   |
+| `async_mode` | `False`                        | Fire-and-forget — refresh runs in a background thread|
+
+### `sf.refresh(*tables)` → `SyncResult | list[SyncResult]`
+
+```python
+sf.refresh('products')                         # single table
+sf.refresh('products', 'categories', 'orders') # multiple at once
+
+result = sf.refresh('products')
+print(result.ok)           # True
+print(result.calls_saved)  # 1854211
+print(result.sync_mode)    # 'Event — On INSERT / UPDATE / DELETE'
+```
+
+### `sf.ping()` → `bool`
+Health check — returns `True` if SyncForge is reachable.
+
+### `sf.project_info()` → `dict`
+Returns project metadata and all registered tables.
+
+### `sf.list_tables()` → `list`
+Lists all tables with their sync mode and stats.
+
+---
+
+## Django Integration
+
+```python
+# syncforge.py (next to manage.py)
+import os
+from syncforge import SyncForge
+sf = SyncForge(api_key=os.environ.get('SYNCFORGE_API_KEY'))
+
+# myapp/views.py
+from syncforge import sf
+
+def update_products(request):
+    Product.objects.filter(on_sale=True).update(price=F('price') * 0.9)
+    sf.refresh('products')
+    return JsonResponse({'status': 'updated'})
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from syncforge import sf
+
+app = FastAPI()
+
+@app.post("/products/")
+async def create_product(name: str, price: float):
+    db.execute("INSERT INTO products ...")
+    sf.refresh('products')
+    return {"status": "ok"}
+```
+
+---
+
+## Production Tips
+
+```python
+# Silent mode — SyncForge errors never crash your app
+sf = SyncForge(api_key='sf_live_...', silent=True)
+
+# Async mode — fire-and-forget, returns immediately
+sf = SyncForge(api_key='sf_live_...', async_mode=True)
+sf.refresh('products')  # returns None, syncs in background
+
+# Override base URL for local development
+sf = SyncForge(api_key='sf_live_...', base_url='http://localhost:8000/api')
+```
+
+---
+
+## Error Handling
+
+```python
+from syncforge import SyncForge, AuthError, TableNotFoundError, NetworkError
+
+sf = SyncForge(api_key='sf_live_...')
+try:
+    sf.refresh('products')
+except AuthError:
+    print("Invalid API key")
+except TableNotFoundError:
+    print("Register the table in your SyncForge dashboard first")
+except NetworkError:
+    print("Could not reach SyncForge — check your internet connection")
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

syncforge-1.0.0/syncforge.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+syncforge/__init__.py
+syncforge/client.py
+syncforge/exceptions.py
+syncforge/result.py
+syncforge.egg-info/PKG-INFO
+syncforge.egg-info/SOURCES.txt
+syncforge.egg-info/dependency_links.txt
+syncforge.egg-info/top_level.txt

syncforge-1.0.0/syncforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

syncforge-1.0.0/syncforge.egg-info/top_level.txt

@@ -0,0 +1 @@
+syncforge