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 +50 -0
- rrss/adapters/base.py +80 -0
- rrss/adapters/instagram.py +123 -0
- rrss/adapters/threads.py +62 -0
- rrss/adapters/tiktok.py +76 -0
- rrss/adapters/x.py +224 -0
- rrss/adapters/x_stub.py +5 -0
- rrss/auth/__init__.py +19 -0
- rrss/cache.py +209 -0
- rrss/cli.py +78 -0
- rrss/client.py +35 -0
- rrss/errors.py +31 -0
- rrss/gateway.py +306 -0
- rrss/models.py +61 -0
- rrss/normalize/__init__.py +1 -0
- rrss/normalize/instagram.py +82 -0
- rrss/normalize/threads.py +82 -0
- rrss/normalize/tiktok.py +51 -0
- rrss/normalize/x.py +192 -0
- rrss/ratelimit.py +30 -0
- rrss/serialize.py +216 -0
- rrss/stream.py +198 -0
- rrss_sdk_wrapper-0.2.0.dist-info/METADATA +173 -0
- rrss_sdk_wrapper-0.2.0.dist-info/RECORD +26 -0
- rrss_sdk_wrapper-0.2.0.dist-info/WHEEL +4 -0
- rrss_sdk_wrapper-0.2.0.dist-info/entry_points.txt +2 -0
rrss/serialize.py
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
"""JSON helpers for canonical models.
|
|
2
|
+
|
|
3
|
+
Nullable fields are always present. ``raw`` is included only when set, matching
|
|
4
|
+
the schema (object, not null).
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
from datetime import UTC, datetime
|
|
11
|
+
from typing import Any, Literal, cast
|
|
12
|
+
|
|
13
|
+
from rrss.models import Comment, CursorPage, MediaItem, Platform, Post, User
|
|
14
|
+
|
|
15
|
+
_PLATFORMS = ("instagram", "threads", "tiktok", "facebook", "x")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def model_to_dict(model: User | Post | Comment | MediaItem | CursorPage[Any]) -> dict[str, Any]:
|
|
19
|
+
if isinstance(model, User):
|
|
20
|
+
data: dict[str, Any] = {
|
|
21
|
+
"id": model.id,
|
|
22
|
+
"username": model.username,
|
|
23
|
+
"display_name": model.display_name,
|
|
24
|
+
"bio": model.bio,
|
|
25
|
+
"profile_url": model.profile_url,
|
|
26
|
+
"avatar_url": model.avatar_url,
|
|
27
|
+
"follower_count": model.follower_count,
|
|
28
|
+
"following_count": model.following_count,
|
|
29
|
+
"is_verified": model.is_verified,
|
|
30
|
+
"platform": model.platform,
|
|
31
|
+
}
|
|
32
|
+
if model.raw is not None:
|
|
33
|
+
data["raw"] = model.raw
|
|
34
|
+
return data
|
|
35
|
+
if isinstance(model, Post):
|
|
36
|
+
data = {
|
|
37
|
+
"id": model.id,
|
|
38
|
+
"author_id": model.author_id,
|
|
39
|
+
"text": model.text,
|
|
40
|
+
"created_at": _dt_to_str(model.created_at),
|
|
41
|
+
"url": model.url,
|
|
42
|
+
"media": [model_to_dict(item) for item in model.media],
|
|
43
|
+
"like_count": model.like_count,
|
|
44
|
+
"comment_count": model.comment_count,
|
|
45
|
+
"platform": model.platform,
|
|
46
|
+
}
|
|
47
|
+
if model.raw is not None:
|
|
48
|
+
data["raw"] = model.raw
|
|
49
|
+
return data
|
|
50
|
+
if isinstance(model, Comment):
|
|
51
|
+
return {
|
|
52
|
+
"id": model.id,
|
|
53
|
+
"post_id": model.post_id,
|
|
54
|
+
"author_id": model.author_id,
|
|
55
|
+
"text": model.text,
|
|
56
|
+
"created_at": _dt_to_str(model.created_at),
|
|
57
|
+
"platform": model.platform,
|
|
58
|
+
}
|
|
59
|
+
if isinstance(model, MediaItem):
|
|
60
|
+
return {"type": model.type, "url": model.url}
|
|
61
|
+
items = [model_to_dict(item) for item in model.items]
|
|
62
|
+
return {
|
|
63
|
+
"items": items,
|
|
64
|
+
"next_cursor": model.next_cursor,
|
|
65
|
+
"has_more": model.has_more,
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def dumps_model(
|
|
70
|
+
model: User | Post | Comment | MediaItem | CursorPage[Any],
|
|
71
|
+
*,
|
|
72
|
+
pretty: bool = False,
|
|
73
|
+
) -> str:
|
|
74
|
+
payload = model_to_dict(model)
|
|
75
|
+
if pretty:
|
|
76
|
+
return json.dumps(payload, indent=2, ensure_ascii=False)
|
|
77
|
+
return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def user_from_dict(data: dict[str, Any]) -> User:
|
|
81
|
+
return User(
|
|
82
|
+
id=str(data["id"]),
|
|
83
|
+
platform=_as_platform(data.get("platform")),
|
|
84
|
+
username=_as_optional_str(data.get("username")),
|
|
85
|
+
display_name=_as_optional_str(data.get("display_name")),
|
|
86
|
+
bio=_as_optional_str(data.get("bio")),
|
|
87
|
+
profile_url=_as_optional_str(data.get("profile_url")),
|
|
88
|
+
avatar_url=_as_optional_str(data.get("avatar_url")),
|
|
89
|
+
follower_count=_as_int(data.get("follower_count")),
|
|
90
|
+
following_count=_as_int(data.get("following_count")),
|
|
91
|
+
is_verified=_as_bool(data.get("is_verified")),
|
|
92
|
+
raw=_as_raw(data.get("raw")),
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def post_from_dict(data: dict[str, Any]) -> Post:
|
|
97
|
+
return Post(
|
|
98
|
+
id=str(data["id"]),
|
|
99
|
+
author_id=str(data.get("author_id") or ""),
|
|
100
|
+
platform=_as_platform(data.get("platform")),
|
|
101
|
+
text=_as_optional_str(data.get("text")),
|
|
102
|
+
created_at=_as_datetime(data.get("created_at")),
|
|
103
|
+
url=_as_optional_str(data.get("url")),
|
|
104
|
+
media=_as_media(data.get("media")),
|
|
105
|
+
like_count=_as_int(data.get("like_count")),
|
|
106
|
+
comment_count=_as_int(data.get("comment_count")),
|
|
107
|
+
raw=_as_raw(data.get("raw")),
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def comment_from_dict(data: dict[str, Any]) -> Comment:
|
|
112
|
+
return Comment(
|
|
113
|
+
id=str(data["id"]),
|
|
114
|
+
post_id=str(data.get("post_id") or ""),
|
|
115
|
+
text=str(data.get("text") or ""),
|
|
116
|
+
platform=_as_platform(data.get("platform")),
|
|
117
|
+
author_id=_as_optional_str(data.get("author_id")),
|
|
118
|
+
created_at=_as_datetime(data.get("created_at")),
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def posts_page_from_dict(data: dict[str, Any]) -> CursorPage[Post]:
|
|
123
|
+
return CursorPage(
|
|
124
|
+
items=[post_from_dict(item) for item in _as_dict_list(data.get("items"))],
|
|
125
|
+
has_more=bool(data.get("has_more")),
|
|
126
|
+
next_cursor=_as_optional_str(data.get("next_cursor")),
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def comments_page_from_dict(data: dict[str, Any]) -> CursorPage[Comment]:
|
|
131
|
+
return CursorPage(
|
|
132
|
+
items=[comment_from_dict(item) for item in _as_dict_list(data.get("items"))],
|
|
133
|
+
has_more=bool(data.get("has_more")),
|
|
134
|
+
next_cursor=_as_optional_str(data.get("next_cursor")),
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def _dt_to_str(value: datetime | None) -> str | None:
|
|
139
|
+
if value is None:
|
|
140
|
+
return None
|
|
141
|
+
if value.tzinfo is None:
|
|
142
|
+
value = value.replace(tzinfo=UTC)
|
|
143
|
+
else:
|
|
144
|
+
value = value.astimezone(UTC)
|
|
145
|
+
return value.isoformat().replace("+00:00", "Z")
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _as_platform(value: object) -> Platform:
|
|
149
|
+
if not isinstance(value, str) or value not in _PLATFORMS:
|
|
150
|
+
raise ValueError(f"invalid platform: {value!r}")
|
|
151
|
+
return cast(Platform, value)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _as_optional_str(value: object) -> str | None:
|
|
155
|
+
if value is None:
|
|
156
|
+
return None
|
|
157
|
+
return str(value)
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def _as_int(value: object) -> int | None:
|
|
161
|
+
if value is None:
|
|
162
|
+
return None
|
|
163
|
+
if isinstance(value, bool) or not isinstance(value, int):
|
|
164
|
+
raise ValueError(f"expected integer, got {value!r}")
|
|
165
|
+
return value
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _as_bool(value: object) -> bool | None:
|
|
169
|
+
if value is None:
|
|
170
|
+
return None
|
|
171
|
+
if not isinstance(value, bool):
|
|
172
|
+
raise ValueError(f"expected boolean, got {value!r}")
|
|
173
|
+
return value
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _as_datetime(value: object) -> datetime | None:
|
|
177
|
+
if value is None:
|
|
178
|
+
return None
|
|
179
|
+
if isinstance(value, datetime):
|
|
180
|
+
return value
|
|
181
|
+
if isinstance(value, str):
|
|
182
|
+
return datetime.fromisoformat(value.replace("Z", "+00:00"))
|
|
183
|
+
raise ValueError("created_at must be an ISO-8601 string")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def _as_raw(value: object) -> dict[str, object] | None:
|
|
187
|
+
if value is None:
|
|
188
|
+
return None
|
|
189
|
+
if not isinstance(value, dict):
|
|
190
|
+
raise ValueError("raw must be an object")
|
|
191
|
+
return cast(dict[str, object], value)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _as_media(value: object) -> list[MediaItem]:
|
|
195
|
+
items: list[MediaItem] = []
|
|
196
|
+
for entry in _as_dict_list(value):
|
|
197
|
+
kind = entry.get("type")
|
|
198
|
+
url = entry.get("url")
|
|
199
|
+
if kind not in ("image", "video") or not isinstance(url, str):
|
|
200
|
+
raise ValueError("invalid media item")
|
|
201
|
+
media_type: Literal["image", "video"] = "video" if kind == "video" else "image"
|
|
202
|
+
items.append(MediaItem(type=media_type, url=url))
|
|
203
|
+
return items
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _as_dict_list(value: object) -> list[dict[str, Any]]:
|
|
207
|
+
if value is None:
|
|
208
|
+
return []
|
|
209
|
+
if not isinstance(value, list):
|
|
210
|
+
raise ValueError("expected a list")
|
|
211
|
+
rows: list[dict[str, Any]] = []
|
|
212
|
+
for entry in value:
|
|
213
|
+
if not isinstance(entry, dict):
|
|
214
|
+
raise ValueError("expected a list of objects")
|
|
215
|
+
rows.append(cast(dict[str, Any], entry))
|
|
216
|
+
return rows
|
rrss/stream.py
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
"""Polling and webhook stubs for canonical reads.
|
|
2
|
+
|
|
3
|
+
``iter_user_posts`` walks cursor pages once. ``poll`` / ``poll_user`` re-fetch
|
|
4
|
+
on an interval. ``WebhookStub`` records push events in memory so tests never
|
|
5
|
+
open a public callback URL.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import threading
|
|
11
|
+
import time
|
|
12
|
+
from collections.abc import Callable, Iterator
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from datetime import UTC, datetime
|
|
15
|
+
from typing import Any, TypeVar
|
|
16
|
+
|
|
17
|
+
from rrss.adapters.base import BaseAdapter
|
|
18
|
+
from rrss.models import CursorPage, Post, User
|
|
19
|
+
|
|
20
|
+
T = TypeVar("T")
|
|
21
|
+
|
|
22
|
+
_MISSING = object()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def iter_user_posts(
|
|
26
|
+
adapter: BaseAdapter,
|
|
27
|
+
user_ref: str,
|
|
28
|
+
*,
|
|
29
|
+
limit: int = 25,
|
|
30
|
+
max_pages: int | None = None,
|
|
31
|
+
) -> Iterator[CursorPage[Post]]:
|
|
32
|
+
"""Yield post pages until the cursor is exhausted or ``max_pages`` is hit."""
|
|
33
|
+
cursor: str | None = None
|
|
34
|
+
pages = 0
|
|
35
|
+
while True:
|
|
36
|
+
page = adapter.list_user_posts(user_ref, cursor=cursor, limit=limit)
|
|
37
|
+
yield page
|
|
38
|
+
pages += 1
|
|
39
|
+
if not page.has_more or page.next_cursor is None:
|
|
40
|
+
break
|
|
41
|
+
if max_pages is not None and pages >= max_pages:
|
|
42
|
+
break
|
|
43
|
+
cursor = page.next_cursor
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def poll(
|
|
47
|
+
fetch: Callable[[], T],
|
|
48
|
+
*,
|
|
49
|
+
interval: float = 0.0,
|
|
50
|
+
max_polls: int | None = None,
|
|
51
|
+
sleeper: Callable[[float], None] = time.sleep,
|
|
52
|
+
distinct: Callable[[T], object] | None = None,
|
|
53
|
+
) -> Iterator[T]:
|
|
54
|
+
"""Call ``fetch`` repeatedly and yield each result.
|
|
55
|
+
|
|
56
|
+
``interval`` is the delay in seconds between polls. Tests pass ``interval=0``
|
|
57
|
+
with ``max_polls`` and a no-op ``sleeper``. When ``distinct`` is set, a result
|
|
58
|
+
whose key matches the previous key is skipped.
|
|
59
|
+
|
|
60
|
+
An unbounded poll with a zero interval is rejected so a forgotten ``max_polls``
|
|
61
|
+
cannot busy-spin.
|
|
62
|
+
"""
|
|
63
|
+
if max_polls is not None and max_polls < 1:
|
|
64
|
+
raise ValueError("max_polls must be >= 1")
|
|
65
|
+
if max_polls is None and interval <= 0:
|
|
66
|
+
raise ValueError("poll requires max_polls or a positive interval")
|
|
67
|
+
|
|
68
|
+
previous: object = _MISSING
|
|
69
|
+
calls = 0
|
|
70
|
+
while True:
|
|
71
|
+
if max_polls is not None and calls >= max_polls:
|
|
72
|
+
return
|
|
73
|
+
value = fetch()
|
|
74
|
+
calls += 1
|
|
75
|
+
emit = True
|
|
76
|
+
if distinct is not None:
|
|
77
|
+
key = distinct(value)
|
|
78
|
+
if previous is not _MISSING and key == previous:
|
|
79
|
+
emit = False
|
|
80
|
+
previous = key
|
|
81
|
+
if emit:
|
|
82
|
+
yield value
|
|
83
|
+
if max_polls is not None and calls >= max_polls:
|
|
84
|
+
return
|
|
85
|
+
sleeper(interval)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def poll_user(
|
|
89
|
+
adapter: BaseAdapter,
|
|
90
|
+
user_ref: str,
|
|
91
|
+
*,
|
|
92
|
+
interval: float = 0.0,
|
|
93
|
+
max_polls: int | None = None,
|
|
94
|
+
sleeper: Callable[[float], None] = time.sleep,
|
|
95
|
+
) -> Iterator[User]:
|
|
96
|
+
"""Re-fetch a profile until it changes or ``max_polls`` calls complete."""
|
|
97
|
+
return poll(
|
|
98
|
+
lambda: adapter.get_user(user_ref),
|
|
99
|
+
interval=interval,
|
|
100
|
+
max_polls=max_polls,
|
|
101
|
+
sleeper=sleeper,
|
|
102
|
+
distinct=_user_fingerprint,
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def poll_user_posts(
|
|
107
|
+
adapter: BaseAdapter,
|
|
108
|
+
user_ref: str,
|
|
109
|
+
*,
|
|
110
|
+
limit: int = 25,
|
|
111
|
+
interval: float = 0.0,
|
|
112
|
+
max_polls: int | None = None,
|
|
113
|
+
sleeper: Callable[[float], None] = time.sleep,
|
|
114
|
+
) -> Iterator[CursorPage[Post]]:
|
|
115
|
+
"""Re-fetch the first post page until its ids change or polls run out."""
|
|
116
|
+
return poll(
|
|
117
|
+
lambda: adapter.list_user_posts(user_ref, limit=limit),
|
|
118
|
+
interval=interval,
|
|
119
|
+
max_polls=max_polls,
|
|
120
|
+
sleeper=sleeper,
|
|
121
|
+
distinct=_posts_fingerprint,
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _user_fingerprint(user: User) -> tuple[object, ...]:
|
|
126
|
+
return (
|
|
127
|
+
user.id,
|
|
128
|
+
user.username,
|
|
129
|
+
user.display_name,
|
|
130
|
+
user.bio,
|
|
131
|
+
user.follower_count,
|
|
132
|
+
user.following_count,
|
|
133
|
+
user.is_verified,
|
|
134
|
+
user.avatar_url,
|
|
135
|
+
user.profile_url,
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _posts_fingerprint(page: CursorPage[Post]) -> tuple[object, ...]:
|
|
140
|
+
return (
|
|
141
|
+
tuple((post.id, post.text, post.like_count, post.comment_count) for post in page.items),
|
|
142
|
+
page.next_cursor,
|
|
143
|
+
page.has_more,
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
@dataclass(frozen=True)
|
|
148
|
+
class WebhookEvent:
|
|
149
|
+
"""One accepted webhook payload."""
|
|
150
|
+
|
|
151
|
+
platform: str
|
|
152
|
+
event: str
|
|
153
|
+
data: dict[str, Any]
|
|
154
|
+
received_at: str
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class WebhookStub:
|
|
158
|
+
"""In-memory webhook receiver.
|
|
159
|
+
|
|
160
|
+
Production platforms would POST to a public URL. This stub records those
|
|
161
|
+
bodies so callers can iterate events without credentials or DNS.
|
|
162
|
+
"""
|
|
163
|
+
|
|
164
|
+
def __init__(self) -> None:
|
|
165
|
+
self._events: list[WebhookEvent] = []
|
|
166
|
+
self._lock = threading.Lock()
|
|
167
|
+
|
|
168
|
+
def accept(self, body: dict[str, Any], *, received_at: str | None = None) -> WebhookEvent:
|
|
169
|
+
if not isinstance(body, dict):
|
|
170
|
+
raise TypeError("webhook body must be a JSON object")
|
|
171
|
+
raw_data = body.get("data")
|
|
172
|
+
if raw_data is None:
|
|
173
|
+
payload: dict[str, Any] = {}
|
|
174
|
+
elif isinstance(raw_data, dict):
|
|
175
|
+
payload = dict(raw_data)
|
|
176
|
+
else:
|
|
177
|
+
raise TypeError("webhook data must be an object")
|
|
178
|
+
stamp = received_at or datetime.now(UTC).isoformat().replace("+00:00", "Z")
|
|
179
|
+
event = WebhookEvent(
|
|
180
|
+
platform=str(body.get("platform") or ""),
|
|
181
|
+
event=str(body.get("event") or "unknown"),
|
|
182
|
+
data=payload,
|
|
183
|
+
received_at=stamp,
|
|
184
|
+
)
|
|
185
|
+
with self._lock:
|
|
186
|
+
self._events.append(event)
|
|
187
|
+
return event
|
|
188
|
+
|
|
189
|
+
def __iter__(self) -> Iterator[WebhookEvent]:
|
|
190
|
+
with self._lock:
|
|
191
|
+
snapshot = list(self._events)
|
|
192
|
+
yield from snapshot
|
|
193
|
+
|
|
194
|
+
def drain(self) -> list[WebhookEvent]:
|
|
195
|
+
with self._lock:
|
|
196
|
+
snapshot = list(self._events)
|
|
197
|
+
self._events.clear()
|
|
198
|
+
return snapshot
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: rrss-sdk-wrapper
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Unified social media data client (Instagram, Threads, TikTok)
|
|
5
|
+
Author: Ferran Suils
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Provides-Extra: all
|
|
9
|
+
Requires-Dist: httpx>=0.27; extra == 'all'
|
|
10
|
+
Requires-Dist: tweepy>=4.14; extra == 'all'
|
|
11
|
+
Provides-Extra: cache
|
|
12
|
+
Requires-Dist: redis>=5; extra == 'cache'
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: httpx>=0.27; extra == 'dev'
|
|
15
|
+
Requires-Dist: mypy>=1.11; extra == 'dev'
|
|
16
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
17
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
18
|
+
Provides-Extra: docs
|
|
19
|
+
Requires-Dist: mkdocs>=1.6; extra == 'docs'
|
|
20
|
+
Provides-Extra: instagram
|
|
21
|
+
Provides-Extra: threads
|
|
22
|
+
Requires-Dist: httpx>=0.27; extra == 'threads'
|
|
23
|
+
Provides-Extra: tiktok
|
|
24
|
+
Provides-Extra: x
|
|
25
|
+
Requires-Dist: tweepy>=4.14; extra == 'x'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# rrss
|
|
29
|
+
|
|
30
|
+
Python meta-package for normalized social profile and post data across Instagram, Threads, and TikTok.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
Version 0.2.0 in this tree is not published. PyPI still serves 0.1.0 until a tagged release.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install rrss-sdk-wrapper
|
|
38
|
+
# optional extras
|
|
39
|
+
pip install "rrss-sdk-wrapper[threads]"
|
|
40
|
+
pip install "rrss-sdk-wrapper[x]" # tweepy; live X calls only
|
|
41
|
+
pip install "rrss-sdk-wrapper[cache]" # redis; tests use the in-memory cache
|
|
42
|
+
pip install "rrss-sdk-wrapper[docs]" # mkdocs
|
|
43
|
+
pip install "rrss-sdk-wrapper[all]"
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
From this repository:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
cd python
|
|
50
|
+
pip install -e .
|
|
51
|
+
pip install -e ".[dev]" # ruff, mypy, pytest
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick start
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from rrss import Client
|
|
58
|
+
|
|
59
|
+
# Adapters accept injectable upstream clients for testing; optional deps for live usage.
|
|
60
|
+
ig = Client("instagram", username="u", password="p")
|
|
61
|
+
user = ig.get_user("someone")
|
|
62
|
+
for page in ig.iter_user_posts("someone", limit=50):
|
|
63
|
+
for post in page.items:
|
|
64
|
+
print(post.text)
|
|
65
|
+
|
|
66
|
+
# Re-fetch until the profile changes. Pass max_polls in tests (interval may be 0).
|
|
67
|
+
for profile in ig.poll_user("someone", interval=60, max_polls=5):
|
|
68
|
+
print(profile.follower_count)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`WebhookStub` records push payloads in memory (`accept`, then iterate). The gateway also accepts `POST /v1/webhooks` into that stub. Neither path needs a public callback URL.
|
|
72
|
+
|
|
73
|
+
## Cache
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from rrss import CachingAdapter, Client, MemoryCache
|
|
77
|
+
|
|
78
|
+
cached = CachingAdapter(Client("threads"), MemoryCache())
|
|
79
|
+
cached.get_user("someone") # second call is served from memory
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Set `RRSS_REDIS_URL` and install `rrss-sdk-wrapper[cache]` to use `RedisCache`. The same `get` / `set` interface backs both. Default TTLs follow the lower bound in the plan: users 15 minutes, post lists 5 minutes, comments 1 minute.
|
|
83
|
+
|
|
84
|
+
## CLI
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
rrss pull user threads some_username
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The command prints canonical user JSON. Credentials come from the environment (see `.env.example`), never from flags.
|
|
91
|
+
|
|
92
|
+
## HTTP gateway
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
RRSS_GATEWAY_API_KEY=dev python -m rrss.gateway
|
|
96
|
+
# GET /v1/{platform}/users/{user_ref}
|
|
97
|
+
# GET /v1/{platform}/users/{user_ref}/posts
|
|
98
|
+
# GET /openapi.yaml
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The server is stdlib `http.server` with an injectable client factory, so tests run without live platform credentials. Spec: `schemas/openapi.yaml`.
|
|
102
|
+
|
|
103
|
+
Generated clients (Python, Go, and a Rust URL stub) are described in `docs/generated-clients.md`.
|
|
104
|
+
|
|
105
|
+
Copy `python/.env.example` to `.env` for local credentials (never commit secrets).
|
|
106
|
+
|
|
107
|
+
## Threads sidecar (Node)
|
|
108
|
+
|
|
109
|
+
The Threads adapter calls a small **Node sidecar** that wraps `threads-wrapper` over HTTP.
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
cd sidecar/threads
|
|
113
|
+
npm install
|
|
114
|
+
npm start # listens on 127.0.0.1:1877
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Set `RRSS_THREADS_SIDECAR_URL` if the sidecar is not on the default URL. Contract: `GET /health`, `GET /users/:username`, `GET /users/:username/threads` (see api-wrapper plan §19).
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from rrss import Client
|
|
121
|
+
|
|
122
|
+
th = Client("threads") # uses http://127.0.0.1:1877 by default
|
|
123
|
+
user = th.get_user("threader")
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
The sidecar is **not** published to npm; run it from this repo.
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
cd python
|
|
130
|
+
docker compose up --build threads-sidecar
|
|
131
|
+
curl http://127.0.0.1:1877/health
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Compose publishes `127.0.0.1:1877` only. See `docs/platforms/threads.md`.
|
|
135
|
+
|
|
136
|
+
## Errors and retries
|
|
137
|
+
|
|
138
|
+
Shared exceptions live in `rrss.errors`. Rate-limited upstream responses can be retried with `rrss.ratelimit.with_retries` (default: 3 attempts, exponential backoff with jitter). Instagram `get_user` uses this policy when the upstream raises `RateLimited`.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
cd python
|
|
144
|
+
pip install -e ".[dev]"
|
|
145
|
+
ruff check .
|
|
146
|
+
mypy rrss
|
|
147
|
+
pytest -m "not integration"
|
|
148
|
+
pytest -m integration # optional: requires local Threads sidecar for health check
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
CI on pull requests runs `pytest -m "not integration"`. Nightly/workflow-dispatch jobs may run integration markers separately.
|
|
152
|
+
|
|
153
|
+
Optional docs site (not published with the package):
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
pip install -e ".[docs]"
|
|
157
|
+
mkdocs build # writes ./site
|
|
158
|
+
mkdocs serve # http://127.0.0.1:8000
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
See `docs/index.md`.
|
|
162
|
+
|
|
163
|
+
## Platforms
|
|
164
|
+
|
|
165
|
+
| Platform | Auth | Read / write | API | Guide |
|
|
166
|
+
|-----------|------------------------------|--------------|-----|-------|
|
|
167
|
+
| Instagram | Username/password session | Read only | Unofficial (`instagrapi`) | [docs/platforms/instagram.md](docs/platforms/instagram.md) |
|
|
168
|
+
| Threads | None (sidecar) | Read only | Unofficial | [docs/platforms/threads.md](docs/platforms/threads.md) |
|
|
169
|
+
| TikTok | `ms_token` | Read only | Unofficial | [docs/platforms/tiktok.md](docs/platforms/tiktok.md) |
|
|
170
|
+
| X | `X_BEARER_TOKEN` (inert if unset) | Read only | Official v2 | [docs/platforms/x.md](docs/platforms/x.md) |
|
|
171
|
+
| Facebook | — | Deferred | — | [docs/platforms/facebook-v1-deferral.md](docs/platforms/facebook-v1-deferral.md) |
|
|
172
|
+
|
|
173
|
+
Project specification: see the workspace `docs/api-wrapper-plan.md` for the full contract.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
rrss/__init__.py,sha256=C5p5Pn-3cMLfrHUUsdSswq4cmJxC9xEvwZzOfpPae4E,942
|
|
2
|
+
rrss/cache.py,sha256=NhwdkLzZ9Nq0fnEyWo32RvsaHoO2YTVQ6e9oiyFNj8Y,6406
|
|
3
|
+
rrss/cli.py,sha256=HuymHwLFJ6mpmymTyItIIcVkGDJwik0YctdwSTorP-A,2417
|
|
4
|
+
rrss/client.py,sha256=5AXhuvIYbhJ7PNMYWvLdX0kTZy4vqJMwTzxCR_5oybs,1247
|
|
5
|
+
rrss/errors.py,sha256=rRfOlZDw4iseea1_P7R7NMOAnxuNcVkv3puuN40KVmw,572
|
|
6
|
+
rrss/gateway.py,sha256=RQ2ZrpYhU2-uGZ1-ES-a3zZWJFr2ZpZIC-RhzPKbKNc,11375
|
|
7
|
+
rrss/models.py,sha256=3Kea_LypgWqDi8rFermJhRggC3Yu9glHWQdPJc7MTHI,1321
|
|
8
|
+
rrss/ratelimit.py,sha256=yor8vPg3HlXU_5rFRQF2aTBcx4lNOrVLXQYgaWx1jKs,694
|
|
9
|
+
rrss/serialize.py,sha256=EzujXWYnc7rOtdhN5IAX35oTM8281eXiLi65F4_Am0w,7141
|
|
10
|
+
rrss/stream.py,sha256=FvL-i13gEigRV7sNtcOe_jkGOHSuO0MackwE5uuORR4,5720
|
|
11
|
+
rrss/adapters/base.py,sha256=IHzefLA5CaYZXEI1xbwWNvu57mk9UXZl1y2Bi3G6sFs,2003
|
|
12
|
+
rrss/adapters/instagram.py,sha256=r2YAAAOw2H6qHQh_HobIPAmWqzITTJq9MIuRvBmo3TQ,4289
|
|
13
|
+
rrss/adapters/threads.py,sha256=cAmylyt14iZ9Ns_fetc9O67Qrji6Qte-lhbE4bfNGyA,2172
|
|
14
|
+
rrss/adapters/tiktok.py,sha256=p7mIHLh1Rn1X9JFuwyuF-D77IoEof_euOXGhc9jhoUA,2441
|
|
15
|
+
rrss/adapters/x.py,sha256=dTxr95LQRnOUzdgwECHTpHYshpCoSM-KKJ5uNPyldKg,7348
|
|
16
|
+
rrss/adapters/x_stub.py,sha256=jHSq_5OEv9Vg9vM-rLC-oIp3as5I4zL0Jn0HfClHTFk,157
|
|
17
|
+
rrss/auth/__init__.py,sha256=B65BM3-H1qXOveqGMQqypn2lCdTqQLZofwdiAiNTITE,468
|
|
18
|
+
rrss/normalize/__init__.py,sha256=DfJYiceeR_PXMGeV-OAckUxlPhdwjVkwk3T1h1Et-_Y,46
|
|
19
|
+
rrss/normalize/instagram.py,sha256=d9E1valIKd5lE3XlxXbCjaU5kMeE4xZP3B1490aD5Zc,2806
|
|
20
|
+
rrss/normalize/threads.py,sha256=GgfeVcixpUPtisoCnMVm0mtjRqVrRoPe26h9l9YrbSw,3141
|
|
21
|
+
rrss/normalize/tiktok.py,sha256=Iml8xUt_XulOusODDgzcVdDloiI8CeVvZxOcxXlCt-U,1980
|
|
22
|
+
rrss/normalize/x.py,sha256=rHIN4bgXpxRUpAlslioZM8hIqWJ2YNf1tTjcblqfHXg,6694
|
|
23
|
+
rrss_sdk_wrapper-0.2.0.dist-info/METADATA,sha256=gmN9xSp_O2ja5KgZ7Iwi-Rg158Bggy50cgoilNCt0sQ,5809
|
|
24
|
+
rrss_sdk_wrapper-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
25
|
+
rrss_sdk_wrapper-0.2.0.dist-info/entry_points.txt,sha256=LPq9wf7x__q6igHz_UmCQNfy1nIdFtvNL-17SNIF--A,39
|
|
26
|
+
rrss_sdk_wrapper-0.2.0.dist-info/RECORD,,
|