api-graveyard 0.1.0__tar.gz

api_graveyard-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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/api_graveyard.egg-info/PKG-INFO

@@ -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/api_graveyard.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+api_graveyard/__init__.py
+api_graveyard/batcher.py
+api_graveyard/interceptor.py
+api_graveyard/types.py
+api_graveyard.egg-info/PKG-INFO
+api_graveyard.egg-info/SOURCES.txt
+api_graveyard.egg-info/dependency_links.txt
+api_graveyard.egg-info/requires.txt
+api_graveyard.egg-info/top_level.txt
+tests/test_batcher.py
+tests/test_interceptor.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,5 @@
+urllib3>=1.26
+
+[dev]
+pytest>=7
+urllib3>=2

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

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

api_graveyard-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "api-graveyard"
+version = "0.1.0"
+description = "Official Python collector for API Graveyard — automatically tracks your outgoing HTTP dependencies"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "urllib3>=1.26",
+]
+keywords = ["api", "monitoring", "dependency", "tracking", "http", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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",
+]
+
+[project.urls]
+Homepage = "https://api-graveyard.com"
+Repository = "https://github.com/Shakargy/api-graveyard-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "urllib3>=2"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["api_graveyard*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

api_graveyard-0.1.0/setup.cfg

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

api_graveyard-0.1.0/tests/test_batcher.py

@@ -0,0 +1,54 @@
+from unittest.mock import patch, MagicMock
+from api_graveyard.batcher import Batcher
+
+
+def make_batcher(**kwargs):
+    defaults = dict(api_key="agk_test", project_id="proj-123", flush_interval_s=9999, max_batch_size=5, debug=False)
+    defaults.update(kwargs)
+    return Batcher(**defaults)
+
+
+def test_queues_without_sending():
+    b = make_batcher()
+    with patch.object(b, "_send") as mock_send:
+        b.push({"ts": "2026-01-01T00:00:00Z", "method": "GET", "url": "https://api.stripe.com"})
+        assert len(b._queue) == 1
+        mock_send.assert_not_called()
+    b.shutdown()
+
+
+def test_auto_flush_on_max_batch_size():
+    b = make_batcher(max_batch_size=3)
+    with patch.object(b, "_send") as mock_send:
+        for i in range(3):
+            b.push({"ts": "2026-01-01T00:00:00Z", "method": "GET", "url": f"https://api.example.com/{i}"})
+        mock_send.assert_called_once()
+        assert len(b._queue) == 0
+    b.shutdown()
+
+
+def test_flush_sends_correct_payload():
+    b = make_batcher()
+    event = {"ts": "2026-01-01T00:00:00Z", "method": "POST", "url": "https://api.sendgrid.com", "status": 200, "duration_ms": 42}
+    with patch.object(b, "_send") as mock_send:
+        b.push(event)
+        b.flush()
+        mock_send.assert_called_once_with([event])
+    b.shutdown()
+
+
+def test_shutdown_flushes_queue():
+    b = make_batcher()
+    with patch.object(b, "_send") as mock_send:
+        b.push({"ts": "2026-01-01T00:00:00Z", "method": "GET", "url": "https://api.example.com"})
+        b.shutdown()
+        mock_send.assert_called_once()
+        assert len(b._queue) == 0
+
+
+def test_flush_noop_on_empty_queue():
+    b = make_batcher()
+    with patch.object(b, "_send") as mock_send:
+        b.flush()
+        mock_send.assert_not_called()
+    b.shutdown()

api_graveyard-0.1.0/tests/test_interceptor.py

@@ -0,0 +1,39 @@
+import pytest
+import urllib3
+from unittest.mock import MagicMock
+from api_graveyard import interceptor
+
+
+@pytest.fixture(autouse=True)
+def reset_interceptor():
+    yield
+    interceptor.unpatch()
+
+
+def make_batcher():
+    b = MagicMock()
+    b.push = MagicMock()
+    return b
+
+
+def test_patches_urllib3():
+    original = urllib3.HTTPConnectionPool.urlopen
+    batcher = make_batcher()
+    interceptor.patch(batcher, {"api_key": "agk_test", "project_id": "proj-123"})
+    assert urllib3.HTTPConnectionPool.urlopen is not original
+
+
+def test_restores_after_unpatch():
+    original = urllib3.HTTPConnectionPool.urlopen
+    batcher = make_batcher()
+    interceptor.patch(batcher, {"api_key": "agk_test", "project_id": "proj-123"})
+    interceptor.unpatch()
+    assert urllib3.HTTPConnectionPool.urlopen is original
+
+
+def test_does_not_patch_twice():
+    batcher = make_batcher()
+    interceptor.patch(batcher, {"api_key": "agk_test", "project_id": "proj-123"})
+    first_patched = urllib3.HTTPConnectionPool.urlopen
+    interceptor.patch(batcher, {"api_key": "agk_test", "project_id": "proj-123"})
+    assert urllib3.HTTPConnectionPool.urlopen is first_patched