api-graveyard 0.1.0__py3-none-any.whl

api_graveyard/__init__.py

@@ -0,0 +1,62 @@
+import atexit
+import signal
+import logging
+from typing import Optional
+
+from .batcher import Batcher
+from . import interceptor
+
+logger = logging.getLogger(__name__)
+
+_batcher: Optional[Batcher] = None
+
+
+def init(
+    api_key: str,
+    project_id: str,
+    base_url: str = "https://api-graveyard.com",
+    service_name: Optional[str] = None,
+    environment: Optional[str] = None,
+    flush_interval_s: float = 10.0,
+    max_batch_size: int = 100,
+    debug: bool = False,
+) -> None:
+    global _batcher
+
+    if _batcher is not None:
+        return
+
+    _batcher = Batcher(
+        api_key=api_key,
+        project_id=project_id,
+        base_url=base_url,
+        flush_interval_s=flush_interval_s,
+        max_batch_size=max_batch_size,
+        debug=debug,
+    )
+
+    options = {
+        "base_url": base_url,
+        "service_name": service_name,
+        "environment": environment or "production",
+    }
+    interceptor.patch(_batcher, options)
+
+    atexit.register(shutdown)
+
+    def _sigterm_handler(signum, frame):
+        shutdown()
+
+    try:
+        signal.signal(signal.SIGTERM, _sigterm_handler)
+    except (OSError, ValueError):
+        pass
+
+
+def shutdown() -> None:
+    global _batcher
+
+    interceptor.unpatch()
+    if _batcher is not None:
+        _batcher.shutdown()
+        _batcher = None

api_graveyard/batcher.py

@@ -0,0 +1,89 @@
+import json
+import logging
+import threading
+import urllib.request
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from .types import HttpEvent
+
+logger = logging.getLogger(__name__)
+
+_SELF_HOSTNAMES = {"api-graveyard.com", "www.api-graveyard.com"}
+
+
+class Batcher:
+    def __init__(
+        self,
+        api_key: str,
+        project_id: str,
+        base_url: str = "https://api-graveyard.com",
+        flush_interval_s: float = 10.0,
+        max_batch_size: int = 100,
+        debug: bool = False,
+    ) -> None:
+        self._api_key = api_key
+        self._project_id = project_id
+        self._endpoint = f"{base_url}/api/v1/projects/{project_id}/ingest/events/"
+        self._max_batch_size = max_batch_size
+        self._debug = debug
+        self._queue: List[HttpEvent] = []
+        self._lock = threading.Lock()
+        self._shutdown = False
+        self._timer: Optional[threading.Timer] = None
+        self._start_timer(flush_interval_s)
+        self._flush_interval_s = flush_interval_s
+
+    def _start_timer(self, interval: float) -> None:
+        self._timer = threading.Timer(interval, self._timer_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _timer_flush(self) -> None:
+        if self._shutdown:
+            return
+        self.flush()
+        self._start_timer(self._flush_interval_s)
+
+    def push(self, event: HttpEvent) -> None:
+        with self._lock:
+            self._queue.append(event)
+            should_flush = len(self._queue) >= self._max_batch_size
+
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._queue:
+                return
+            batch = self._queue[:]
+            self._queue.clear()
+
+        self._send(batch)
+
+    def shutdown(self) -> None:
+        self._shutdown = True
+        if self._timer:
+            self._timer.cancel()
+        self.flush()
+
+    def _send(self, events: List[HttpEvent]) -> None:
+        try:
+            body = json.dumps(events).encode("utf-8")
+            req = urllib.request.Request(
+                self._endpoint,
+                data=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "X-API-Key": self._api_key,
+                    "User-Agent": "api-graveyard-python/0.1.0",
+                },
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                if self._debug:
+                    logger.debug(f"[api-graveyard] flushed {len(events)} events → {resp.status}")
+        except Exception as e:
+            if self._debug:
+                logger.debug(f"[api-graveyard] flush failed: {e}")

api_graveyard/interceptor.py

@@ -0,0 +1,93 @@
+import time
+import logging
+from datetime import datetime, timezone
+from typing import Optional, Set
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+_SELF_HOSTNAMES: Set[str] = {"api-graveyard.com", "www.api-graveyard.com"}
+_IGNORED_HOSTNAMES: Set[str] = set()
+_patched = False
+_original_urlopen = None
+_batcher = None
+_service_name: Optional[str] = None
+_environment: Optional[str] = None
+
+
+def patch(batcher, options: dict) -> None:
+    global _patched, _original_urlopen, _batcher, _service_name, _environment, _IGNORED_HOSTNAMES
+
+    if _patched:
+        return
+
+    try:
+        import urllib3
+    except ImportError:
+        logger.warning("[api-graveyard] urllib3 not found — HTTP interception disabled")
+        return
+
+    _batcher = batcher
+    _service_name = options.get("service_name")
+    _environment = options.get("environment", "production")
+
+    from urllib.parse import urlparse as _up
+    base_url = options.get("base_url", "https://api-graveyard.com")
+    base_host = _up(base_url).hostname or "api-graveyard.com"
+    _IGNORED_HOSTNAMES = _SELF_HOSTNAMES | {base_host, "localhost", "127.0.0.1", "::1"}
+
+    _original_urlopen = urllib3.HTTPConnectionPool.urlopen
+
+    def patched_urlopen(pool, method, url, **kwargs):
+        scheme = "https" if isinstance(pool, urllib3.HTTPSConnectionPool) else "http"
+        port = pool.port
+        default_port = 443 if scheme == "https" else 80
+        port_str = f":{port}" if port and port != default_port else ""
+        full_url = f"{scheme}://{pool.host}{port_str}{url}"
+
+        if pool.host in _IGNORED_HOSTNAMES:
+            return _original_urlopen(pool, method, url, **kwargs)
+
+        start = time.monotonic()
+        status: Optional[int] = None
+        try:
+            response = _original_urlopen(pool, method, url, **kwargs)
+            status = response.status
+            return response
+        except Exception:
+            raise
+        finally:
+            event = {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "method": method.upper(),
+                "url": full_url,
+                "duration_ms": int((time.monotonic() - start) * 1000),
+            }
+            if status is not None:
+                event["status"] = status
+            if _service_name:
+                event["service_name"] = _service_name
+            if _environment:
+                event["environment"] = _environment
+            try:
+                _batcher.push(event)
+            except Exception:
+                pass
+
+    urllib3.HTTPConnectionPool.urlopen = patched_urlopen
+    _patched = True
+
+
+def unpatch() -> None:
+    global _patched
+
+    if not _patched or _original_urlopen is None:
+        return
+
+    try:
+        import urllib3
+        urllib3.HTTPConnectionPool.urlopen = _original_urlopen
+    except ImportError:
+        pass
+
+    _patched = False

api_graveyard/types.py

@@ -0,0 +1,11 @@
+from typing import Optional, TypedDict
+
+
+class HttpEvent(TypedDict, total=False):
+    ts: str
+    method: str
+    url: str
+    status: Optional[int]
+    duration_ms: Optional[int]
+    service_name: Optional[str]
+    environment: Optional[str]

api_graveyard-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: api-graveyard
+Version: 0.1.0
+Summary: Official Python collector for API Graveyard — automatically tracks your outgoing HTTP dependencies
+License: MIT
+Project-URL: Homepage, https://api-graveyard.com
+Project-URL: Repository, https://github.com/Shakargy/api-graveyard-python
+Keywords: api,monitoring,dependency,tracking,http,observability
+Classifier: Development Status :: 4 - Beta
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: urllib3>=2; extra == "dev"
+
+# api-graveyard
+
+Official Python collector for [API Graveyard](https://api-graveyard.com) — automatically tracks your outgoing HTTP dependencies, detects risk events, and surfaces zombie APIs before they take down your product.
+
+## Install
+
+```bash
+pip install api-graveyard
+```
+
+## Quick start
+
+Add one call to the top of your app entry point:
+
+```python
+import api_graveyard
+
+api_graveyard.init(
+    api_key="agk_your_key_here",
+    project_id="your-project-id",
+)
+
+# ... rest of your app
+```
+
+That's it. Every outgoing HTTP/HTTPS request your app makes is now automatically captured, batched, and sent to API Graveyard in the background.
+
+## Works with
+
+- `requests`
+- `httpx` (sync mode)
+- `urllib3` directly
+- Any library that uses `urllib3` under the hood
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | `str` | **required** | Your `agk_...` API key from the dashboard |
+| `project_id` | `str` | **required** | Your project ID from the dashboard |
+| `base_url` | `str` | `https://api-graveyard.com` | Override for self-hosted |
+| `service_name` | `str` | `None` | Tag events with a service name |
+| `environment` | `str` | `"production"` | Tag events with an environment |
+| `flush_interval_s` | `float` | `10.0` | How often to flush the event buffer (seconds) |
+| `max_batch_size` | `int` | `100` | Max events per batch before forcing a flush |
+| `debug` | `bool` | `False` | Log flush activity |
+
+## Django / Flask example
+
+```python
+# manage.py or wsgi.py / app factory
+import api_graveyard
+
+api_graveyard.init(
+    api_key=os.environ["API_GRAVEYARD_KEY"],
+    project_id=os.environ["API_GRAVEYARD_PROJECT_ID"],
+    service_name="django-backend",
+    environment=os.environ.get("DJANGO_ENV", "production"),
+)
+```
+
+## Graceful shutdown
+
+The collector automatically flushes on process exit. For manual control:
+
+```python
+import api_graveyard
+
+api_graveyard.shutdown()
+```
+
+## What gets captured
+
+- Method, URL, HTTP status code, response time
+- Timestamp of each request
+- Service name and environment (if configured)
+
+Requests to `api-graveyard.com` itself are never captured to avoid infinite loops.
+Localhost and `127.0.0.1` requests are ignored by default.
+
+## Get your API key
+
+1. Sign up at [api-graveyard.com](https://api-graveyard.com)
+2. Create a project
+3. Go to **Settings → Integrations** and create an API key
+
+## License
+
+MIT

api_graveyard-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+api_graveyard/__init__.py,sha256=YDVxmCaYvjnQeazkGTYr9V14NdDsrukkBmRR534ASUc,1308
+api_graveyard/batcher.py,sha256=mwWSyzt62WjtYrvDwySQeq8oNDApfJ-4ajWyBqYE3aw,2744
+api_graveyard/interceptor.py,sha256=TWS6TWnzm-nW0QdbBKt_CiU1pfmJ01PINcqmoA9akpQ,2887
+api_graveyard/types.py,sha256=_OzrA7XbQXXTHRqcKcnEfIMyIiTedDsO9r_6-yz7mOo,243
+api_graveyard-0.1.0.dist-info/METADATA,sha256=hwS-U7tLc78dqKGxV5T87QQHuQgrdWVWw_9ND9WFST4,3586
+api_graveyard-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+api_graveyard-0.1.0.dist-info/top_level.txt,sha256=-FfW1IBmQxzShMo6b09NB7C7TBbFjjz3MOfkjauDazU,14
+api_graveyard-0.1.0.dist-info/RECORD,,

api_graveyard-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
+

api_graveyard-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+api_graveyard