sylvia-api 1.0.0__py3-none-any.whl

sylvia/__init__.py

@@ -0,0 +1,22 @@
+"""
+Sylvia Reddit API Client — fastest way to access Reddit data at scale.
+No OAuth. No rate limit headaches. Just an API key.
+
+    pip install sylvia-api
+    export SYLVIA_API_KEY=syl_xxx
+
+    from sylvia import Sylvia
+    s = Sylvia()
+    python = s.subreddit("python")
+    print(f"{python['name']}: {python['members']:,} members")
+    for post in s.subreddit_posts("python", sort="hot", limit=5):
+        print(f"  {post['score']} — {post['title']}")
+
+License: MIT
+"""
+
+from .client import Sylvia
+from .exceptions import SylviaError, AuthenticationError, RateLimitError, InsufficientCreditsError
+
+__version__ = "1.0.0"
+__all__ = ["Sylvia", "SylviaError", "AuthenticationError", "RateLimitError", "InsufficientCreditsError"]

sylvia/client.py

@@ -0,0 +1,117 @@
+import os
+import time
+from typing import Optional, Iterator, Dict, Any, List
+
+import requests
+
+
+class Sylvia:
+    """Reddit data API client. No OAuth. Just works."""
+
+    BASE_URL = "https://api.sylvia-api.com/v1/reddit/"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        max_retries: int = 3,
+        timeout: int = 60,
+    ):
+        self.api_key = api_key or os.environ.get("SYLVIA_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key required. Set SYLVIA_API_KEY env var or pass api_key=..."
+            )
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({"X-API-KEY": self.api_key})
+
+    def _request(self, path: str, params: Optional[Dict] = None) -> Dict[str, Any]:
+        url = f"{self.BASE_URL}{path}"
+        for attempt in range(self.max_retries + 1):
+            resp = self._session.get(url, params=params, timeout=self.timeout)
+            if resp.status_code == 200:
+                return resp.json()
+            if resp.status_code == 401:
+                raise AuthenticationError("Invalid API key. Get one at https://sylvia-api.com")
+            if resp.status_code == 429:
+                retry = int(resp.headers.get("Retry-After", 5))
+                if attempt < self.max_retries:
+                    time.sleep(retry)
+                    continue
+                raise RateLimitError(retry)
+            if resp.status_code == 402:
+                raise InsufficientCreditsError("Add credits at https://sylvia-api.com/dashboard")
+            resp.raise_for_status()
+        raise SylviaError("Max retries exceeded")
+
+    def subreddit(self, name: str) -> Dict[str, Any]:
+        data = self._request(f"r/{name}/about")
+        return data.get("data", data)
+
+    def subreddit_posts(
+        self, name: str, sort: str = "hot", limit: int = 25, after: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        params = {"limit": min(limit, 100)}
+        if after:
+            params["after"] = after
+        data = self._request(f"r/{name}/{sort}", params=params)
+        return data.get("data", {}).get("posts", [])
+
+    def subreddit_posts_iter(
+        self, name: str, sort: str = "hot", limit: int = 100,
+    ) -> Iterator[Dict[str, Any]]:
+        yielded = 0
+        after = None
+        while yielded < limit:
+            batch = self.subreddit_posts(name, sort=sort, limit=min(limit - yielded, 100), after=after)
+            if not batch:
+                break
+            for post in batch:
+                yield post
+                yielded += 1
+                if yielded >= limit:
+                    return
+            after = batch[-1].get("name")
+
+    def user(self, username: str) -> Dict[str, Any]:
+        data = self._request(f"u/{username}/about")
+        return data.get("data", data)
+
+    def user_posts(self, username: str, where: str = "submitted", limit: int = 25) -> List[Dict[str, Any]]:
+        params = {"limit": min(limit, 100)}
+        data = self._request(f"u/{username}/{where}", params=params)
+        return data.get("data", {}).get("children", [])
+
+    def search(
+        self, query: str, sort: str = "relevance", limit: int = 25,
+        subreddit: Optional[str] = None, include_over_18: bool = False,
+    ) -> List[Dict[str, Any]]:
+        params = {"q": query, "sort": sort, "limit": min(limit, 100)}
+        if subreddit:
+            params["subreddit"] = subreddit
+        if include_over_18:
+            params["include_over_18"] = "true"
+        data = self._request("search", params=params)
+        return data.get("data", {}).get("results", [])
+
+    def post(self, url: str) -> Dict[str, Any]:
+        data = self._request("submission", params={"url": url})
+        return data.get("data", data)
+
+    def comment(self, url: str) -> Dict[str, Any]:
+        data = self._request("comment", params={"url": url})
+        return data.get("data", data)
+
+    def thread(self, post_id: str) -> Dict[str, Any]:
+        data = self._request(f"submission/{post_id}/full")
+        return data.get("data", data)
+
+    def live_comments(self, limit: int = 25) -> List[Dict[str, Any]]:
+        data = self._request("comments/live", params={"limit": min(limit, 100)})
+        return data.get("data", {}).get("comments", [])
+
+    def domain(self, domain: str, sort: str = "hot", limit: int = 25) -> List[Dict[str, Any]]:
+        params = {"domain": domain, "sort": sort, "limit": min(limit, 100)}
+        data = self._request("domain", params=params)
+        return data.get("data", {}).get("posts", [])

sylvia/exceptions.py

@@ -0,0 +1,13 @@
+class SylviaError(Exception):
+    pass
+
+class AuthenticationError(SylviaError):
+    pass
+
+class RateLimitError(SylviaError):
+    def __init__(self, retry_after: int = 0):
+        self.retry_after = retry_after
+        super().__init__(f"Rate limited. Retry after {retry_after}s")
+
+class InsufficientCreditsError(SylviaError):
+    pass

sylvia_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: sylvia-api
+Version: 1.0.0
+Summary: Reddit data API client — no OAuth, no rate limits. Subreddits, users, search, live comments.
+License-Expression: MIT
+Project-URL: Homepage, https://sylvia-api.com
+Project-URL: Documentation, https://sylvia-api.com/docs
+Project-URL: Repository, https://github.com/emraan-harshme/sylvia-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25
+
+# Sylvia Reddit API
+
+**The fastest way to access Reddit data at scale.** No OAuth. No rate limit headaches. No browser automation. Just an API key.
+
+```bash
+pip install sylvia-api
+```
+
+## Quickstart
+
+```python
+from sylvia import Sylvia
+
+# Sign up at https://sylvia-api.com to get your key
+sylvia = Sylvia(api_key="syl_...")
+
+# Subreddit info
+python_sub = sylvia.subreddit("python")
+print(f"r/{python_sub['name']}: {python_sub['members']:,} members")
+
+# Get top posts
+for post in sylvia.subreddit_posts("programming", sort="hot", limit=5):
+    print(f"🔥 {post['score']} — {post['title']}")
+
+# User profile
+spez = sylvia.user("spez")
+print(f"u/spez: {spez['comment_karma']:,} comment karma")
+
+# Global search (not available in Reddit's own API!)
+results = sylvia.search("llama 4 model", limit=10)
+for post in results:
+    print(f"r/{post['subreddit']} — {post['title']}")
+
+# Live comment firehose
+for comment in sylvia.live_comments(limit=10):
+    print(f"u/{comment['author']}: {comment['body'][:100]}")
+
+# Thread with ALL nested comments expanded
+thread = sylvia.thread("1tlh5aj")
+```
+
+## How It Works
+
+Sylvia operates a fleet of real residential proxy engines that fetch Reddit data through actual browsers. This means:
+- **No OAuth** needed — just an API key
+- **480 req/min free** (with free tier API key)
+- **Global search** across all of Reddit
+- **Live comment firehose** in real-time
+- **Automatic IP rotation** — Reddit never blocks you
+
+## Pricing
+
+| Tier | Rate Limit | Price |
+|------|-----------|-------|
+| Free | 8 req/s (480/min) | $0 |
+| Strela | 20 req/s | $50/mo |
+| Svetka | 40 req/s | $200/mo |
+| Enterprise | 60+ req/s | Custom |
+
+Per-request billing: **$0.0005/request** ($0.50 per 1,000 requests). Failed requests are not charged.
+
+[Sign up free →](https://sylvia-api.com)
+
+## Comparison
+
+| | Sylvia | Reddit API | Bright Data | Apify |
+|---|---|---|---|---|
+| OAuth required | ❌ No | ✅ Yes | ❌ No | ❌ No |
+| Global search | ✅ Yes | ❌ No | ❌ No | Limited |
+| Live comments | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
+| Auto IP rotation | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
+| Free tier | 480 req/min | 60 req/min | None | 100 req/mo |
+| Per-1K cost | $0.50 | Free (limited) | $8.40/GB | ~$5/1K |
+
+## License
+
+MIT

sylvia_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sylvia/__init__.py,sha256=xN_-CJNjzsPYFn9k-Ceq02SjhOhX-Lfwqr-zuCOTXps,731
+sylvia/client.py,sha256=JOFeVn8or-WCOAcz_m5SKelvskDYaBX9DcrGm5ktkKA,4631
+sylvia/exceptions.py,sha256=YPgZyRBGcPBQyxlcYsa-j8jo4-MKsDMiboae7IB42FU,335
+sylvia_api-1.0.0.dist-info/METADATA,sha256=PQv3gzg4gw_nblDrBdpNgbmmFvhfoH1T4KWlQiLrteg,2872
+sylvia_api-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sylvia_api-1.0.0.dist-info/top_level.txt,sha256=BuiI5LL-PXD444cHUXAFgxx-fDpUjvU_-KXq4w9K1L4,7
+sylvia_api-1.0.0.dist-info/RECORD,,

sylvia_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sylvia_api-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sylvia