@geoly-ai/social-hub-cli 0.3.14 → 0.3.16

package/skills/reddit-voc-volume/scripts/reddit_voc_volume.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Reddit VOC volume sampler — keyword / subreddit / links / stickies modes.
+Reddit VOC volume sampler — keyword / subreddit / links / comments / stickies modes.
 Strict rate limits; browser-like JSON requests; no bulk crawling.
 """
 from __future__ import annotations
@@ -42,6 +42,8 @@ RETRY_BACKOFF_SEC = (30.0, 120.0)
 ARCTIC_BASE_URL = "https://arctic-shift.photon-reddit.com"
 ARCTIC_MAX_LIMIT = 100  # 单次上限；文档另有 "auto"，但会随服务器负载浮动，不用
 ARCTIC_IDS_MAX = 500
+ARCTIC_COMMENT_TREE_MAX = 25_000
+ARCTIC_COMMENT_SEARCH_MAX = 100
 ARCTIC_DEFAULT_TIMEOUT_SEC = 60.0
 ARCTIC_MAX_RETRIES = 3
 ARCTIC_MIN_SLEEP_SEC = 2.0  # 作者要求 "a couple requests per second" 以内，取更保守值
@@ -143,7 +145,7 @@ SOCIAL_HUB_REQUIRED_SKILLS = ("social-hub-cli", "social-hub-shared")
 HUB_DEFAULT_POLL_TIMEOUT_SEC = 600.0
 HUB_POLL_BACKOFF_SEC = (5.0, 10.0, 20.0, 30.0)
 HUB_INTELLIGENCE_TIMEOUT_SEC = 30.0
-COLLECTOR_VERSION = "2.12.30"
+COLLECTOR_VERSION = "2.12.31"
 ACQUISITION_POLICIES = ("hub-first", "hub-only", "self-first")
 DEFAULT_FLAIR_FILTER_PAGES = ("", "hot", "new", "top")
 
@@ -3184,6 +3186,7 @@ def arctic_get(
     user_agent: str,
     timeout: float = ARCTIC_DEFAULT_TIMEOUT_SEC,
     tracker: "RequestTracker | None" = None,
+    keep_empty_params: set[str] | None = None,
 ) -> dict[str, Any]:
     """调用 Arctic Shift API，处理 429 限流与重查询超时。
 
@@ -3191,7 +3194,12 @@ def arctic_get(
     `{"error": "Timeout. Maybe slow down a bit"}` —— 那是查询代价过高而非
     限流，同样退避重试（实测跨 15 年的 aggregate 会稳定触发）。
     """
-    clean = {k: v for k, v in params.items() if v is not None and v != ""}
+    keep_empty_params = keep_empty_params or set()
+    clean = {
+        k: v
+        for k, v in params.items()
+        if v is not None and (v != "" or k in keep_empty_params)
+    }
     url = f"{ARCTIC_BASE_URL}{path}?{urllib.parse.urlencode(clean)}"
     last_err = ""
     # 预算按**逻辑请求**计一次，不按重试次数计：重试是同一次取数的补偿，
@@ -3277,6 +3285,306 @@ def arctic_search_posts(
     return [arctic_post_item(r) for r in rows if isinstance(r, dict)]
 
 
+_ARCTIC_BASE36_ID_RE = re.compile(r"^[0-9a-z]+$", re.I)
+
+
+def normalize_reddit_post_id(target: str) -> str:
+    """Extract a bare base36 post ID from a Reddit URL, ``t3_`` ID, or bare ID."""
+    raw = str(target or "").strip()
+    if not raw:
+        raise ValueError("post URL or post ID is required (unless --ids is used)")
+
+    # Full Reddit permalinks and redd.it short links. Reject lookalike hosts rather
+    # than accepting any URL that happens to contain `/comments/<id>`.
+    if "://" in raw:
+        parsed = urllib.parse.urlparse(raw)
+        host = (parsed.hostname or "").lower().rstrip(".")
+        if host == "redd.it" or host.endswith(".redd.it"):
+            candidate = parsed.path.strip("/").split("/", 1)[0]
+        elif host == "reddit.com" or host.endswith(".reddit.com"):
+            match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", parsed.path, re.I)
+            candidate = match.group(1) if match else ""
+        else:
+            raise ValueError(f"unsupported post URL host: {host or '<missing>'}")
+    elif "/comments/" in raw:
+        match = re.search(r"/comments/([0-9a-z]+)(?:/|$)", raw, re.I)
+        candidate = match.group(1) if match else ""
+    else:
+        candidate = raw[3:] if raw.lower().startswith("t3_") else raw
+        if raw.lower().startswith("t1_"):
+            raise ValueError("expected a post ID (t3_), received a comment ID (t1_)")
+
+    candidate = candidate.strip().lower()
+    if not candidate or not _ARCTIC_BASE36_ID_RE.fullmatch(candidate):
+        raise ValueError(f"malformed Reddit post ID: {raw}")
+    return candidate
+
+
+def normalize_reddit_comment_id(raw_id: str) -> str:
+    """Normalize one comment ID to its bare base36 representation."""
+    raw = str(raw_id or "").strip()
+    if raw.lower().startswith("t3_"):
+        raise ValueError(f"expected a comment ID (t1_), received a post ID: {raw}")
+    candidate = raw[3:] if raw.lower().startswith("t1_") else raw
+    candidate = candidate.strip().lower()
+    if not candidate or not _ARCTIC_BASE36_ID_RE.fullmatch(candidate):
+        raise ValueError(f"malformed Reddit comment ID: {raw or '<empty>'}")
+    return candidate
+
+
+def parse_reddit_comment_ids(values: list[str] | None) -> list[str]:
+    """Parse comma- or whitespace-separated comment IDs, preserving first-seen order."""
+    ids: list[str] = []
+    seen: set[str] = set()
+    for value in values or []:
+        for token in str(value).split(","):
+            if not token.strip():
+                raise ValueError("malformed Reddit comment ID: empty value")
+            comment_id = normalize_reddit_comment_id(token)
+            if comment_id not in seen:
+                ids.append(comment_id)
+                seen.add(comment_id)
+    if len(ids) > ARCTIC_IDS_MAX:
+        raise ValueError(f"too many comment IDs: {len(ids)} (maximum {ARCTIC_IDS_MAX})")
+    return ids
+
+
+def normalize_comment_parent_id(parent_id: str | None, *, allow_top_level: bool = False) -> str | None:
+    """Normalize a parent comment ID; search uses an empty value for top-level comments."""
+    if parent_id is None:
+        return None
+    raw = str(parent_id).strip()
+    if raw.lower() in ("top", "root"):
+        if allow_top_level:
+            return ""
+        raise ValueError("--parent-id top/root is only valid with --source search")
+    return f"t1_{normalize_reddit_comment_id(raw)}"
+
+
+def arctic_comment_item(
+    row: dict[str, Any],
+    *,
+    depth: int | None = None,
+    tree_order: int | None = None,
+    sibling_index: int | None = None,
+    tree_path: list[int] | None = None,
+    tree_parent_id: str | None = None,
+) -> dict[str, Any]:
+    """Map an Arctic comment row without truncating its archived body."""
+    body = row.get("body")
+    body_text = body if isinstance(body, str) else ("" if body is None else str(body))
+    body_status = classify_body(body_text)
+    measurable = body_status not in ("Removed", "Deleted")
+    comment_id = str(row.get("id") or "").removeprefix("t1_").lower()
+    permalink = str(row.get("permalink") or "")
+    if permalink.startswith("/"):
+        permalink = f"https://www.reddit.com{permalink}"
+    item = {
+        "item_type": "comment",
+        "id": comment_id,
+        "name": str(row.get("name") or (f"t1_{comment_id}" if comment_id else "")),
+        "link_id": row.get("link_id"),
+        # Preserve Arctic's original edge exactly. `tree_parent_id` separately records
+        # the edge observed while traversing the nested tree, useful for consistency checks.
+        "parent_id": row.get("parent_id"),
+        "tree_parent_id": tree_parent_id,
+        "author": row.get("author"),
+        "created_utc": row.get("created_utc"),
+        "score": row.get("score"),
+        "score_status": "ArchivedSnapshot",
+        "score_realtime": False,
+        "subreddit": row.get("subreddit"),
+        "body": body_text,
+        "body_status": body_status,
+        "body_chars": len(body_text) if measurable else 0,
+        "body_words": len(re.findall(r"\S+", body_text)) if measurable else 0,
+        "body_truncated": False if measurable else None,
+        "permalink": permalink or None,
+        "retrieved_on": row.get("retrieved_on"),
+        "distinguished": row.get("distinguished"),
+        "is_submitter": row.get("is_submitter"),
+        "edited": row.get("edited"),
+        "depth": depth,
+        "tree_order": tree_order,
+        "sibling_index": sibling_index,
+        "tree_path": tree_path,
+        "source_fetch": "arctic_shift",
+    }
+    return item
+
+
+def _arctic_tree_children(replies: Any) -> list[dict[str, Any]]:
+    if replies in (None, ""):
+        return []
+    if not isinstance(replies, dict):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies must be a listing")
+    data = replies.get("data")
+    if not isinstance(data, dict):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies.data must be an object")
+    children = data.get("children")
+    if not isinstance(children, list) or any(not isinstance(child, dict) for child in children):
+        raise ArcticError("arctic_comments_tree_malformed_payload: replies.data.children must be object[]")
+    return children
+
+
+def flatten_arctic_comment_tree(payload: Any) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Flatten Arctic's Reddit-shaped comment tree while retaining exact tree coordinates."""
+    if not isinstance(payload, dict) or not isinstance(payload.get("data"), list):
+        raise ArcticError("arctic_comments_tree_malformed_payload: expected data[]")
+    roots = payload.get("data")
+    if any(not isinstance(node, dict) for node in roots):
+        raise ArcticError("arctic_comments_tree_malformed_payload: data must contain object nodes")
+    nodes = roots
+    items: list[dict[str, Any]] = []
+    collapsed: list[dict[str, Any]] = []
+    order = 0
+
+    def walk(children: list[dict[str, Any]], *, depth: int, path: list[int], parent_id: str | None) -> None:
+        nonlocal order
+        for sibling_index, node in enumerate(children):
+            kind = str(node.get("kind") or "")
+            data = node.get("data")
+            if not isinstance(data, dict):
+                raise ArcticError("arctic_comments_tree_malformed_payload: node.data must be an object")
+            node_path = [*path, sibling_index]
+            node_order = order
+            order += 1
+            if kind == "more":
+                child_ids = [
+                    normalize_reddit_comment_id(str(value))
+                    for value in (data.get("children") or [])
+                    if str(value or "").strip()
+                ]
+                collapsed.append(
+                    {
+                        "kind": "more",
+                        "id": data.get("id"),
+                        "parent_id": data.get("parent_id") or parent_id,
+                        "count": data.get("count"),
+                        "children": child_ids,
+                        "depth": depth,
+                        "tree_order": node_order,
+                        "sibling_index": sibling_index,
+                        "tree_path": node_path,
+                    }
+                )
+                continue
+            if kind != "t1":
+                raise ArcticError(f"arctic_comments_tree_malformed_payload: unexpected kind={kind or '<empty>'}")
+
+            replies = _arctic_tree_children(data.get("replies"))
+            item = arctic_comment_item(
+                data,
+                depth=depth,
+                tree_order=node_order,
+                sibling_index=sibling_index,
+                tree_path=node_path,
+                tree_parent_id=parent_id,
+            )
+            item["child_ids"] = [
+                str(child.get("data", {}).get("id") or "").removeprefix("t1_").lower()
+                for child in replies
+                if child.get("kind") == "t1" and isinstance(child.get("data"), dict)
+            ]
+            items.append(item)
+            current_parent = str(data.get("name") or (f"t1_{item['id']}" if item.get("id") else "")) or None
+            walk(replies, depth=depth + 1, path=node_path, parent_id=current_parent)
+
+    walk(nodes, depth=0, path=[], parent_id=None)
+    return items, collapsed
+
+
+def arctic_comments_tree(
+    post_id: str,
+    *,
+    parent_id: str | None = None,
+    limit: int = ARCTIC_COMMENT_TREE_MAX,
+    start_breadth: int | None = None,
+    start_depth: int | None = None,
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    payload = arctic_get(
+        "/api/comments/tree",
+        {
+            "link_id": f"t3_{post_id}",
+            "parent_id": parent_id,
+            "limit": limit,
+            "start_breadth": start_breadth,
+            "start_depth": start_depth,
+        },
+        user_agent=user_agent,
+        tracker=tracker,
+    )
+    return flatten_arctic_comment_tree(payload)
+
+
+def arctic_search_comments(
+    post_id: str,
+    *,
+    body: str | None = None,
+    author: str | None = None,
+    after: str | None = None,
+    before: str | None = None,
+    parent_id: str | None = None,
+    limit: int = ARCTIC_COMMENT_SEARCH_MAX,
+    sort: str = "asc",
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> list[dict[str, Any]]:
+    payload = arctic_get(
+        "/api/comments/search",
+        {
+            "link_id": post_id,
+            "body": body,
+            "author": author,
+            "after": after,
+            "before": before,
+            "parent_id": parent_id,
+            "limit": limit,
+            "sort": sort,
+        },
+        user_agent=user_agent,
+        tracker=tracker,
+        keep_empty_params={"parent_id"} if parent_id == "" else None,
+    )
+    rows = payload.get("data")
+    if not isinstance(rows, list):
+        return []
+    return [
+        arctic_comment_item(row, tree_order=index)
+        for index, row in enumerate(rows)
+        if isinstance(row, dict)
+    ]
+
+
+def arctic_comments_by_ids(
+    comment_ids: list[str],
+    *,
+    user_agent: str,
+    tracker: "RequestTracker | None" = None,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    payload = arctic_get(
+        "/api/comments/ids",
+        {"ids": ",".join(comment_ids)},
+        user_agent=user_agent,
+        tracker=tracker,
+    )
+    rows = payload.get("data")
+    by_id = {
+        str(row.get("id") or "").removeprefix("t1_").lower(): row
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, dict)
+    }
+    items = [
+        arctic_comment_item(by_id[comment_id], tree_order=index)
+        for index, comment_id in enumerate(comment_ids)
+        if comment_id in by_id
+    ]
+    missing = [comment_id for comment_id in comment_ids if comment_id not in by_id]
+    return items, missing
+
+
 def arctic_subreddit_rules(subreddits: list[str], *, user_agent: str) -> dict[str, list[dict[str, Any]]]:
     """替代 /about/rules.json（本机对 reddit.com 直连被拦时唯一可用途径）。"""
     names = [_clean_subreddit_name(s) for s in subreddits if s]
@@ -4571,6 +4879,43 @@ def main() -> int:
     )
     pl.add_argument("--pretty", action="store_true")
 
+    pc = sub.add_parser(
+        "comments",
+        help="读取帖子历史评论正文：默认 Arctic 评论树，也支持筛选搜索与评论 ID 批查",
+    )
+    pc.add_argument("target", nargs="?", help="Reddit post URL、t3_<post_id> 或裸 post ID；--ids 模式省略")
+    pc.add_argument(
+        "--source",
+        choices=["tree", "search"],
+        default="tree",
+        help="tree=评论树（默认，最多 25,000）；search=平面筛选（最多 100）",
+    )
+    pc.add_argument(
+        "--ids",
+        nargs="+",
+        metavar="COMMENT_ID",
+        help=f"按 t1_/裸评论 ID 批查，可用空格或逗号分隔，最多 {ARCTIC_IDS_MAX}",
+    )
+    pc.add_argument("--body", help="search only：评论正文关键词/FTS 查询")
+    pc.add_argument("--author", help="search only：作者")
+    pc.add_argument("--after", help="search only：起始时间（ISO 日期、epoch 或 Arctic offset）")
+    pc.add_argument("--before", help="search only：结束时间（ISO 日期、epoch 或 Arctic offset）")
+    pc.add_argument(
+        "--parent-id",
+        help="tree/search：父评论 ID；search 中 top/root 表示顶层评论",
+    )
+    pc.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="tree 默认/上限 25000；search 默认/上限 100；越界直接报错",
+    )
+    pc.add_argument("--sort", choices=["asc", "desc"], default=None, help="search only：按 created_utc 排序")
+    pc.add_argument("--start-breadth", type=int, default=None, help="tree only：Arctic 折叠宽度，必须 >=0")
+    pc.add_argument("--start-depth", type=int, default=None, help="tree only：Arctic 折叠深度，必须 >=0")
+    pc.add_argument("--user-agent", default=DEFAULT_UA)
+    pc.add_argument("--pretty", action="store_true")
+
     ph = sub.add_parser(
         "history",
         help="历史检索：按时间窗从 Arctic Shift 归档取帖（覆盖 2005-06 起至近实时）",
@@ -4601,6 +4946,174 @@ def main() -> int:
     psh.add_argument("--pretty", action="store_true")
 
     args = p.parse_args()
+    if args.mode == "comments":
+        try:
+            comment_ids = parse_reddit_comment_ids(args.ids) if args.ids else []
+            if comment_ids and args.target:
+                raise ValueError("provide either a post target or --ids, not both")
+            if comment_ids and args.source != "tree":
+                raise ValueError("--ids cannot be combined with --source search")
+            if not comment_ids and not args.target:
+                raise ValueError("post URL or post ID is required (unless --ids is used)")
+
+            filter_values = (args.body, args.author, args.after, args.before, args.sort)
+            if comment_ids and (any(value is not None for value in filter_values) or args.parent_id is not None):
+                raise ValueError("--ids cannot be combined with post/search/tree filters")
+            if comment_ids and (args.limit is not None or args.start_breadth is not None or args.start_depth is not None):
+                raise ValueError("--ids cannot be combined with --limit/--start-breadth/--start-depth")
+            if args.source == "tree" and any(value is not None for value in filter_values):
+                raise ValueError("--body/--author/--after/--before/--sort require --source search")
+            if args.source == "search" and (args.start_breadth is not None or args.start_depth is not None):
+                raise ValueError("--start-breadth/--start-depth are only valid with --source tree")
+            if args.start_breadth is not None and args.start_breadth < 0:
+                raise ValueError("--start-breadth must be >= 0")
+            if args.start_depth is not None and args.start_depth < 0:
+                raise ValueError("--start-depth must be >= 0")
+
+            post_id = normalize_reddit_post_id(args.target) if args.target else None
+            parent_id = (
+                normalize_comment_parent_id(args.parent_id, allow_top_level=args.source == "search")
+                if args.parent_id is not None and post_id is not None
+                else None
+            )
+            retrieval_mode = "ids" if comment_ids else args.source
+            maximum = ARCTIC_COMMENT_TREE_MAX if retrieval_mode == "tree" else ARCTIC_COMMENT_SEARCH_MAX
+            default_limit = ARCTIC_COMMENT_TREE_MAX if retrieval_mode == "tree" else ARCTIC_COMMENT_SEARCH_MAX
+            limit = default_limit if args.limit is None else args.limit
+            if retrieval_mode != "ids" and not 1 <= limit <= maximum:
+                raise ValueError(f"--limit must be between 1 and {maximum} for {retrieval_mode} mode")
+        except ValueError as exc:
+            pc.error(str(exc))
+
+        tracker = RequestTracker()
+        errors: list[str] = []
+        collapsed: list[dict[str, Any]] = []
+        missing_ids: list[str] = []
+        items: list[dict[str, Any]] = []
+        tree_fetch_succeeded = False
+        try:
+            if retrieval_mode == "ids":
+                items, missing_ids = arctic_comments_by_ids(
+                    comment_ids,
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+            elif retrieval_mode == "search":
+                items = arctic_search_comments(
+                    post_id,
+                    body=args.body,
+                    author=args.author,
+                    after=args.after,
+                    before=args.before,
+                    parent_id=parent_id,
+                    limit=limit,
+                    sort=args.sort or "asc",
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+            else:
+                items, collapsed = arctic_comments_tree(
+                    post_id,
+                    parent_id=parent_id,
+                    limit=limit,
+                    start_breadth=args.start_breadth,
+                    start_depth=args.start_depth,
+                    user_agent=args.user_agent,
+                    tracker=tracker,
+                )
+                tree_fetch_succeeded = True
+        except ArcticError as exc:
+            errors.append(f"arctic_comments_failed:{exc}"[:300])
+        if missing_ids:
+            errors.append(f"comment_ids_not_found:{','.join(missing_ids)}"[:300])
+
+        bodies = [item for item in items if item.get("body_status") == "Present"]
+        removed = [item for item in items if item.get("body_status") in ("Removed", "Deleted")]
+        notes = [
+            "Arctic Shift 是第三方历史归档源，通常滞后约 2 小时，且不保证可用性。",
+            "评论 body 适合历史 VOC；score 是归档快照而非实时值，不得用于当前热度判断。",
+        ]
+        if collapsed:
+            notes.append(
+                f"评论树含 {len(collapsed)} 个 kind=more 折叠节点；"
+                "tree_complete=false，collapsed[].children 保留尚未展开的评论 ID。"
+            )
+        fetched_at = utc_now_iso()
+        canonical_source = f"https://www.reddit.com/comments/{post_id}/" if post_id else None
+        fingerprint = hashlib.sha256(
+            json.dumps(
+                {
+                    "mode": "comments",
+                    "retrieval_mode": retrieval_mode,
+                    "post_id": post_id,
+                    "comment_ids": comment_ids,
+                    "body": args.body,
+                    "author": args.author,
+                    "after": args.after,
+                    "before": args.before,
+                    "parent_id": parent_id,
+                    "limit": None if retrieval_mode == "ids" else limit,
+                    "sort": args.sort or ("asc" if retrieval_mode == "search" else None),
+                    "start_breadth": args.start_breadth,
+                    "start_depth": args.start_depth,
+                },
+                ensure_ascii=False,
+                sort_keys=True,
+            ).encode("utf-8")
+        ).hexdigest()
+        out = {
+            "ok": not errors,
+            "mode": "comments",
+            "retrieval_mode": retrieval_mode,
+            "provenance": "arctic_shift",
+            "source_endpoint": f"/api/comments/{'ids' if retrieval_mode == 'ids' else retrieval_mode}",
+            "source_urls": [canonical_source] if canonical_source else [],
+            "post_id": post_id,
+            "link_id": f"t3_{post_id}" if post_id else None,
+            "requested_comment_ids": comment_ids,
+            "missing_comment_ids": missing_ids,
+            "filters": {
+                "body": args.body,
+                "author": args.author,
+                "after": args.after,
+                "before": args.before,
+                "parent_id": parent_id,
+                "sort": args.sort or ("asc" if retrieval_mode == "search" else None),
+            },
+            "count": len(items),
+            "tree_complete": tree_fetch_succeeded and not collapsed if retrieval_mode == "tree" else None,
+            "collapsed_count": len(collapsed),
+            "collapsed": collapsed,
+            "body_stats": {
+                "with_text": len(bodies),
+                "removed_or_deleted": len(removed),
+                "max_chars": max((int(item.get("body_chars") or 0) for item in bodies), default=0),
+            },
+            "items": items,
+            "archive_caveats": {
+                "estimated_lag": "about_2_hours",
+                "uptime_guaranteed": False,
+                "score_realtime": False,
+            },
+            "rate_limit": {
+                "requested_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
+                "effective_limit": len(comment_ids) if retrieval_mode == "ids" else limit,
+                "http_requests": tracker.count,
+                "rate_limited": tracker.rate_limited,
+            },
+            "fetched_at": fetched_at,
+            "fetchedAt": fetched_at,
+            "fingerprint": fingerprint,
+            "runId": None,
+            "hubRunId": None,
+            "fallbackReason": None,
+            "writebackStatus": "not_applicable",
+            "notes": notes,
+            "errors": errors,
+        }
+        print(json.dumps(out, ensure_ascii=False, indent=2 if args.pretty else None))
+        return 0 if out["ok"] else 1
+
     if args.mode == "history":
         subs = [_clean_subreddit_name(s) for s in (args.subreddit or [])] or [None]
         items: list[dict[str, Any]] = []