rrss-sdk-wrapper 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
rrss/__init__.py ADDED
@@ -0,0 +1,50 @@
1
+ """Unified social media data client."""
2
+
3
+ from rrss.cache import CachingAdapter, MemoryCache, RedisCache
4
+ from rrss.client import Client
5
+ from rrss.errors import (
6
+ AuthFailed,
7
+ NotFound,
8
+ NotSupported,
9
+ PlatformError,
10
+ RateLimited,
11
+ RRSSError,
12
+ )
13
+ from rrss.gateway import Gateway
14
+ from rrss.models import Comment, CursorPage, MediaItem, Platform, Post, User
15
+ from rrss.stream import (
16
+ WebhookEvent,
17
+ WebhookStub,
18
+ iter_user_posts,
19
+ poll,
20
+ poll_user,
21
+ poll_user_posts,
22
+ )
23
+
24
+ __all__ = [
25
+ "AuthFailed",
26
+ "CachingAdapter",
27
+ "Client",
28
+ "Comment",
29
+ "CursorPage",
30
+ "Gateway",
31
+ "MediaItem",
32
+ "MemoryCache",
33
+ "NotFound",
34
+ "NotSupported",
35
+ "Platform",
36
+ "PlatformError",
37
+ "Post",
38
+ "RRSSError",
39
+ "RateLimited",
40
+ "RedisCache",
41
+ "User",
42
+ "WebhookEvent",
43
+ "WebhookStub",
44
+ "iter_user_posts",
45
+ "poll",
46
+ "poll_user",
47
+ "poll_user_posts",
48
+ ]
49
+
50
+ __version__ = "0.2.0"
rrss/adapters/base.py ADDED
@@ -0,0 +1,80 @@
1
+ from __future__ import annotations
2
+
3
+ from abc import ABC, abstractmethod
4
+ from collections.abc import Iterator
5
+
6
+ from rrss.models import Comment, CursorPage, Post, User
7
+
8
+
9
+ class BaseAdapter(ABC):
10
+ platform: str
11
+
12
+ @abstractmethod
13
+ def get_user(self, user_ref: str) -> User:
14
+ ...
15
+
16
+ @abstractmethod
17
+ def list_user_posts(
18
+ self,
19
+ user_ref: str,
20
+ *,
21
+ cursor: str | None = None,
22
+ limit: int = 25,
23
+ ) -> CursorPage[Post]:
24
+ ...
25
+
26
+ def get_post(self, post_id: str) -> Post:
27
+ from rrss.errors import NotSupported
28
+
29
+ raise NotSupported(f"get_post is not supported for {self.platform}")
30
+
31
+ def list_post_comments(
32
+ self,
33
+ post_id: str,
34
+ *,
35
+ cursor: str | None = None,
36
+ limit: int = 25,
37
+ ) -> CursorPage[Comment]:
38
+ from rrss.errors import NotSupported
39
+
40
+ raise NotSupported(f"list_post_comments is not supported for {self.platform}")
41
+
42
+ def iter_user_posts(
43
+ self,
44
+ user_ref: str,
45
+ *,
46
+ limit: int = 25,
47
+ max_pages: int | None = None,
48
+ ) -> Iterator[CursorPage[Post]]:
49
+ from rrss.stream import iter_user_posts as walk_pages
50
+
51
+ return walk_pages(self, user_ref, limit=limit, max_pages=max_pages)
52
+
53
+ def poll_user(
54
+ self,
55
+ user_ref: str,
56
+ *,
57
+ interval: float = 0.0,
58
+ max_polls: int | None = None,
59
+ ) -> Iterator[User]:
60
+ from rrss.stream import poll_user as poll_profile
61
+
62
+ return poll_profile(self, user_ref, interval=interval, max_polls=max_polls)
63
+
64
+ def poll_user_posts(
65
+ self,
66
+ user_ref: str,
67
+ *,
68
+ limit: int = 25,
69
+ interval: float = 0.0,
70
+ max_polls: int | None = None,
71
+ ) -> Iterator[CursorPage[Post]]:
72
+ from rrss.stream import poll_user_posts as poll_posts
73
+
74
+ return poll_posts(
75
+ self,
76
+ user_ref,
77
+ limit=limit,
78
+ interval=interval,
79
+ max_polls=max_polls,
80
+ )
@@ -0,0 +1,123 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Protocol
4
+
5
+ from rrss.adapters.base import BaseAdapter
6
+ from rrss.errors import AuthFailed, NotFound, PlatformError, RateLimited
7
+ from rrss.models import Comment, CursorPage, Post, User
8
+ from rrss.normalize import instagram as normalize
9
+ from rrss.ratelimit import with_retries
10
+
11
+
12
+ class InstagramUpstream(Protocol):
13
+ def user_info_by_username(self, username: str) -> Any: ...
14
+
15
+ def user_medias(
16
+ self,
17
+ user_id: str,
18
+ amount: int,
19
+ end_cursor: str | None = ...,
20
+ ) -> tuple[list[Any], str | None]: ...
21
+
22
+ def media_info(self, media_id: str) -> Any: ...
23
+
24
+ def media_comments(self, media_id: str, amount: int) -> list[Any]: ...
25
+
26
+
27
+ class InstagramAdapter(BaseAdapter):
28
+ platform = "instagram"
29
+
30
+ def __init__(
31
+ self,
32
+ *,
33
+ username: str | None = None,
34
+ password: str | None = None,
35
+ client: InstagramUpstream | None = None,
36
+ include_raw: bool = False,
37
+ ) -> None:
38
+ self._username = username
39
+ self._password = password
40
+ self._client = client
41
+ self._include_raw = include_raw
42
+
43
+ def _ensure_client(self) -> InstagramUpstream:
44
+ if self._client is not None:
45
+ return self._client
46
+ if not self._username or not self._password:
47
+ raise AuthFailed("Instagram requires username/password or an injected client")
48
+ try:
49
+ from instagrapi import Client as IgClient # type: ignore[import-not-found]
50
+
51
+ ig = IgClient()
52
+ ig.login(self._username, self._password)
53
+ self._client = ig
54
+ return self._client
55
+ except ImportError as exc:
56
+ raise PlatformError(
57
+ "instagrapi is not installed; inject a mock client or install optional deps",
58
+ detail=str(exc),
59
+ ) from exc
60
+ except Exception as exc:
61
+ raise AuthFailed("Instagram login failed", detail=str(exc)) from exc
62
+
63
+ def get_user(self, user_ref: str) -> User:
64
+ client = self._ensure_client()
65
+
66
+ def _fetch() -> Any:
67
+ try:
68
+ return client.user_info_by_username(user_ref)
69
+ except RateLimited:
70
+ raise
71
+ except Exception as exc:
72
+ raise PlatformError(
73
+ "Instagram user_info_by_username failed",
74
+ detail=str(exc),
75
+ ) from exc
76
+
77
+ raw = with_retries(_fetch)
78
+ if raw is None:
79
+ raise NotFound(f"User not found: {user_ref}")
80
+ return normalize.user_from_instagrapi(raw, include_raw=self._include_raw)
81
+
82
+ def list_user_posts(
83
+ self,
84
+ user_ref: str,
85
+ *,
86
+ cursor: str | None = None,
87
+ limit: int = 25,
88
+ ) -> CursorPage[Post]:
89
+ client = self._ensure_client()
90
+ user = self.get_user(user_ref)
91
+ try:
92
+ medias, next_cursor = client.user_medias(user.id, limit, end_cursor=cursor)
93
+ except Exception as exc:
94
+ raise PlatformError("Instagram user_medias failed", detail=str(exc)) from exc
95
+ posts = [normalize.post_from_instagrapi(m, include_raw=self._include_raw) for m in medias]
96
+ return CursorPage(items=posts, has_more=next_cursor is not None, next_cursor=next_cursor)
97
+
98
+ def get_post(self, post_id: str) -> Post:
99
+ client = self._ensure_client()
100
+ try:
101
+ raw = client.media_info(post_id)
102
+ except Exception as exc:
103
+ raise PlatformError("Instagram media_info failed", detail=str(exc)) from exc
104
+ return normalize.post_from_instagrapi(raw, include_raw=self._include_raw)
105
+
106
+ def list_post_comments(
107
+ self,
108
+ post_id: str,
109
+ *,
110
+ cursor: str | None = None,
111
+ limit: int = 25,
112
+ ) -> CursorPage[Comment]:
113
+ del cursor
114
+ client = self._ensure_client()
115
+ try:
116
+ raw_comments = client.media_comments(post_id, limit)
117
+ except Exception as exc:
118
+ raise PlatformError("Instagram media_comments failed", detail=str(exc)) from exc
119
+ items = [
120
+ normalize.comment_from_instagrapi(c, post_id=post_id, include_raw=False)
121
+ for c in raw_comments
122
+ ]
123
+ return CursorPage(items=items, has_more=False, next_cursor=None)
@@ -0,0 +1,62 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import os
5
+ import urllib.error
6
+ import urllib.request
7
+ from typing import Any, cast
8
+
9
+ from rrss.adapters.base import BaseAdapter
10
+ from rrss.errors import PlatformError
11
+ from rrss.models import CursorPage, Post, User
12
+ from rrss.normalize import threads as normalize
13
+
14
+ DEFAULT_SIDECAR = "http://127.0.0.1:1877"
15
+
16
+
17
+ class ThreadsAdapter(BaseAdapter):
18
+ platform = "threads"
19
+
20
+ def __init__(
21
+ self,
22
+ *,
23
+ sidecar_url: str | None = None,
24
+ http_get: Any | None = None,
25
+ include_raw: bool = False,
26
+ ) -> None:
27
+ base = sidecar_url or os.environ.get("RRSS_THREADS_SIDECAR_URL") or DEFAULT_SIDECAR
28
+ self._base = base.rstrip("/")
29
+ self._http_get = http_get or self._default_http_get
30
+ self._include_raw = include_raw
31
+
32
+ def _default_http_get(self, url: str) -> dict[str, Any]:
33
+ try:
34
+ with urllib.request.urlopen(url, timeout=30) as resp:
35
+ body = resp.read().decode("utf-8")
36
+ except urllib.error.HTTPError as exc:
37
+ payload = exc.read().decode("utf-8", errors="replace")
38
+ raise PlatformError(
39
+ f"Threads sidecar HTTP {exc.code}",
40
+ detail=payload,
41
+ ) from exc
42
+ except urllib.error.URLError as exc:
43
+ raise PlatformError("Threads sidecar unreachable", detail=str(exc.reason)) from exc
44
+ try:
45
+ return cast(dict[str, Any], json.loads(body))
46
+ except json.JSONDecodeError as exc:
47
+ raise PlatformError("Threads sidecar returned invalid JSON", detail=body[:200]) from exc
48
+
49
+ def get_user(self, user_ref: str) -> User:
50
+ data = self._http_get(f"{self._base}/users/{user_ref}")
51
+ return normalize.user_from_sidecar(user_ref, data, include_raw=self._include_raw)
52
+
53
+ def list_user_posts(
54
+ self,
55
+ user_ref: str,
56
+ *,
57
+ cursor: str | None = None,
58
+ limit: int = 25,
59
+ ) -> CursorPage[Post]:
60
+ del cursor, limit
61
+ data = self._http_get(f"{self._base}/users/{user_ref}/threads")
62
+ return normalize.threads_page_from_sidecar(user_ref, data, include_raw=self._include_raw)
@@ -0,0 +1,76 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Protocol
4
+
5
+ from rrss.adapters.base import BaseAdapter
6
+ from rrss.errors import AuthFailed, PlatformError
7
+ from rrss.models import CursorPage, Post, User
8
+ from rrss.normalize import tiktok as normalize
9
+
10
+
11
+ class TikTokUpstream(Protocol):
12
+ def user(self, username: str) -> dict[str, Any]: ...
13
+
14
+ def user_videos(
15
+ self,
16
+ username: str,
17
+ count: int,
18
+ cursor: str | None,
19
+ ) -> tuple[list[dict[str, Any]], str | None]: ...
20
+
21
+
22
+ class TikTokAdapter(BaseAdapter):
23
+ platform = "tiktok"
24
+
25
+ def __init__(
26
+ self,
27
+ *,
28
+ ms_token: str | None = None,
29
+ proxy: str | None = None,
30
+ client: TikTokUpstream | None = None,
31
+ include_raw: bool = False,
32
+ ) -> None:
33
+ self._ms_token = ms_token
34
+ self._proxy = proxy
35
+ self._client = client
36
+ self._include_raw = include_raw
37
+
38
+ def _ensure_client(self) -> TikTokUpstream:
39
+ if self._client is not None:
40
+ return self._client
41
+ if not self._ms_token:
42
+ raise AuthFailed("TikTok requires ms_token or an injected client")
43
+ raise PlatformError(
44
+ "TikTokApi is not bundled in minimal install; inject a mock/live client",
45
+ )
46
+
47
+ def get_user(self, user_ref: str) -> User:
48
+ client = self._ensure_client()
49
+ try:
50
+ raw = client.user(user_ref)
51
+ except Exception as exc:
52
+ raise PlatformError("TikTok user() failed", detail=str(exc)) from exc
53
+ return normalize.user_from_tiktok(raw, include_raw=self._include_raw)
54
+
55
+ def list_user_posts(
56
+ self,
57
+ user_ref: str,
58
+ *,
59
+ cursor: str | None = None,
60
+ limit: int = 25,
61
+ ) -> CursorPage[Post]:
62
+ client = self._ensure_client()
63
+ try:
64
+ videos, next_cursor = client.user_videos(user_ref, limit, cursor)
65
+ except Exception as exc:
66
+ raise PlatformError("TikTok user_videos() failed", detail=str(exc)) from exc
67
+ posts = [normalize.post_from_tiktok(v, include_raw=self._include_raw) for v in videos]
68
+ return CursorPage(items=posts, has_more=next_cursor is not None, next_cursor=next_cursor)
69
+
70
+ def get_post(self, post_id: str) -> Post:
71
+ from rrss.errors import NotSupported
72
+
73
+ del post_id
74
+ raise NotSupported(
75
+ "TikTok get_post not implemented in minimal adapter; use list_user_posts",
76
+ )
rrss/adapters/x.py ADDED
@@ -0,0 +1,224 @@
1
+ """Read-only X API v2 adapter.
2
+
3
+ The client is tweepy-shaped (`get_user`, `get_users_tweets`, `get_tweet`,
4
+ `search_recent_tweets`). Without `X_BEARER_TOKEN` and without an injected
5
+ client, every method raises `NotSupported` and does not import tweepy or
6
+ open a socket.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from typing import Any, NoReturn, Protocol, cast
13
+
14
+ from rrss.adapters.base import BaseAdapter
15
+ from rrss.errors import AuthFailed, NotFound, NotSupported, PlatformError, RateLimited, RRSSError
16
+ from rrss.models import Comment, CursorPage, Post, User
17
+ from rrss.normalize import x as normalize
18
+
19
+ _USER_FIELDS = ["description", "profile_image_url", "public_metrics", "verified"]
20
+ _TWEET_FIELDS = ["attachments", "author_id", "conversation_id", "created_at", "public_metrics"]
21
+ _EXPANSIONS = ["attachments.media_keys", "author_id"]
22
+ _MEDIA_FIELDS = ["media_key", "preview_image_url", "type", "url"]
23
+ _REPLY_FIELDS = ["author_id", "conversation_id", "created_at", "public_metrics"]
24
+
25
+
26
+ class XUpstream(Protocol):
27
+ def get_user(
28
+ self,
29
+ *,
30
+ id: str | None = None,
31
+ username: str | None = None,
32
+ user_fields: list[str] | None = None,
33
+ ) -> Any: ...
34
+
35
+ def get_users_tweets(
36
+ self,
37
+ id: str,
38
+ *,
39
+ max_results: int = 10,
40
+ pagination_token: str | None = None,
41
+ tweet_fields: list[str] | None = None,
42
+ expansions: list[str] | None = None,
43
+ media_fields: list[str] | None = None,
44
+ ) -> Any: ...
45
+
46
+ def get_tweet(
47
+ self,
48
+ id: str,
49
+ *,
50
+ tweet_fields: list[str] | None = None,
51
+ expansions: list[str] | None = None,
52
+ media_fields: list[str] | None = None,
53
+ ) -> Any: ...
54
+
55
+ def search_recent_tweets(
56
+ self,
57
+ query: str,
58
+ *,
59
+ max_results: int = 10,
60
+ next_token: str | None = None,
61
+ tweet_fields: list[str] | None = None,
62
+ ) -> Any: ...
63
+
64
+
65
+ def _clamp(limit: int, *, minimum: int) -> int:
66
+ if limit < minimum:
67
+ return minimum
68
+ if limit > 100:
69
+ return 100
70
+ return limit
71
+
72
+
73
+ def _error_text(raw: Any) -> str:
74
+ errors = raw.get("errors") if isinstance(raw, dict) else getattr(raw, "errors", None)
75
+ if not errors:
76
+ return ""
77
+ first = errors[0]
78
+ if isinstance(first, dict):
79
+ return str(first.get("detail") or first.get("title") or first)
80
+ return str(getattr(first, "detail", None) or getattr(first, "title", None) or first)
81
+
82
+
83
+ class XAdapter(BaseAdapter):
84
+ """Official X API v2 reads. No post, like, or follow methods."""
85
+
86
+ platform = "x"
87
+
88
+ def __init__(
89
+ self,
90
+ *,
91
+ bearer_token: str | None = None,
92
+ client: XUpstream | None = None,
93
+ include_raw: bool = False,
94
+ ) -> None:
95
+ if bearer_token is None:
96
+ bearer_token = os.environ.get("X_BEARER_TOKEN")
97
+ token = (bearer_token or "").strip()
98
+ self._token = token or None
99
+ self._client = client
100
+ self._include_raw = include_raw
101
+
102
+ def _ensure_client(self) -> XUpstream:
103
+ if self._client is not None:
104
+ return self._client
105
+ if not self._token:
106
+ raise NotSupported(
107
+ "X read adapter is inert without X_BEARER_TOKEN; no request was sent",
108
+ )
109
+ try:
110
+ import tweepy # type: ignore[import-not-found]
111
+ except ImportError as exc:
112
+ raise PlatformError(
113
+ "tweepy is not installed; pip install 'rrss[x]' or inject a client",
114
+ detail=str(exc),
115
+ ) from exc
116
+ built = tweepy.Client(bearer_token=self._token)
117
+ self._client = cast(XUpstream, built)
118
+ return self._client
119
+
120
+ def _reraise(self, exc: Exception) -> NoReturn:
121
+ mapped = _map_upstream(exc)
122
+ if mapped is exc:
123
+ raise exc
124
+ raise mapped from exc
125
+
126
+ def _require_entity(self, raw: Any, message: str) -> None:
127
+ data = raw.get("data") if isinstance(raw, dict) else getattr(raw, "data", raw)
128
+ if data is not None:
129
+ return
130
+ detail = _error_text(raw)
131
+ if detail and "not found" in detail.lower():
132
+ raise NotFound(message, detail=detail)
133
+ if detail:
134
+ raise PlatformError(message, detail=detail)
135
+ raise NotFound(message)
136
+
137
+ def get_user(self, user_ref: str) -> User:
138
+ client = self._ensure_client()
139
+ ref = user_ref.strip().lstrip("@")
140
+ try:
141
+ if ref.isdigit():
142
+ raw = client.get_user(id=ref, user_fields=_USER_FIELDS)
143
+ else:
144
+ raw = client.get_user(username=ref, user_fields=_USER_FIELDS)
145
+ except Exception as exc:
146
+ self._reraise(exc)
147
+ self._require_entity(raw, f"X user not found: {ref}")
148
+ return normalize.user_from_x(raw, include_raw=self._include_raw)
149
+
150
+ def list_user_posts(
151
+ self,
152
+ user_ref: str,
153
+ *,
154
+ cursor: str | None = None,
155
+ limit: int = 25,
156
+ ) -> CursorPage[Post]:
157
+ client = self._ensure_client()
158
+ ref = user_ref.strip().lstrip("@")
159
+ user_id = ref if ref.isdigit() else self.get_user(ref).id
160
+ try:
161
+ raw = client.get_users_tweets(
162
+ user_id,
163
+ max_results=_clamp(limit, minimum=5),
164
+ pagination_token=cursor,
165
+ tweet_fields=_TWEET_FIELDS,
166
+ expansions=_EXPANSIONS,
167
+ media_fields=_MEDIA_FIELDS,
168
+ )
169
+ except Exception as exc:
170
+ self._reraise(exc)
171
+ return normalize.posts_page_from_x(raw, include_raw=self._include_raw)
172
+
173
+ def get_post(self, post_id: str) -> Post:
174
+ client = self._ensure_client()
175
+ try:
176
+ raw = client.get_tweet(
177
+ post_id,
178
+ tweet_fields=_TWEET_FIELDS,
179
+ expansions=_EXPANSIONS,
180
+ media_fields=_MEDIA_FIELDS,
181
+ )
182
+ except Exception as exc:
183
+ self._reraise(exc)
184
+ self._require_entity(raw, f"X post not found: {post_id}")
185
+ return normalize.post_from_x(raw, include_raw=self._include_raw)
186
+
187
+ def list_post_comments(
188
+ self,
189
+ post_id: str,
190
+ *,
191
+ cursor: str | None = None,
192
+ limit: int = 25,
193
+ ) -> CursorPage[Comment]:
194
+ client = self._ensure_client()
195
+ if not post_id.isdigit():
196
+ raise NotFound(f"X post id must be numeric: {post_id}")
197
+ try:
198
+ raw = client.search_recent_tweets(
199
+ f"conversation_id:{post_id} is:reply",
200
+ max_results=_clamp(limit, minimum=10),
201
+ next_token=cursor,
202
+ tweet_fields=_REPLY_FIELDS,
203
+ )
204
+ except Exception as exc:
205
+ self._reraise(exc)
206
+ return normalize.comments_page_from_x(
207
+ raw,
208
+ post_id=post_id,
209
+ include_raw=self._include_raw,
210
+ )
211
+
212
+
213
+ def _map_upstream(exc: Exception) -> RRSSError:
214
+ if isinstance(exc, RRSSError):
215
+ return exc
216
+ name = type(exc).__name__
217
+ message = str(exc) or name
218
+ if name in {"Unauthorized", "Forbidden"}:
219
+ return AuthFailed(message, detail=name)
220
+ if name == "TooManyRequests":
221
+ return RateLimited(message, detail=name)
222
+ if name == "NotFound":
223
+ return NotFound(message, detail=name)
224
+ return PlatformError(message, detail=name)
@@ -0,0 +1,5 @@
1
+ """Compatibility import. The read adapter lives in ``rrss.adapters.x``."""
2
+
3
+ from rrss.adapters.x import XAdapter as XStubAdapter
4
+
5
+ __all__ = ["XStubAdapter"]
rrss/auth/__init__.py ADDED
@@ -0,0 +1,19 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+ from dataclasses import dataclass
5
+
6
+
7
+ @dataclass
8
+ class InstagramCredentials:
9
+ username: str | None
10
+ password: str | None
11
+ session_path: str | None
12
+
13
+
14
+ def load_instagram_from_env() -> InstagramCredentials:
15
+ return InstagramCredentials(
16
+ username=os.environ.get("INSTAGRAM_USERNAME"),
17
+ password=os.environ.get("INSTAGRAM_PASSWORD"),
18
+ session_path=os.environ.get("INSTAGRAM_SESSION_PATH"),
19
+ )