twitter-cli 0.1.0__tar.gz

twitter_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -q

twitter_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

twitter_cli-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.json
+!config.yaml

twitter_cli-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: twitter-cli
+Version: 0.1.0
+Summary: A CLI for Twitter/X — feed, bookmarks, and user timeline in terminal
+Project-URL: Homepage, https://github.com/jackwener/twitter-cli
+Project-URL: Repository, https://github.com/jackwener/twitter-cli
+Project-URL: Issues, https://github.com/jackwener/twitter-cli/issues
+Author-email: jackwener <jakevingoo@gmail.com>
+License-Expression: Apache-2.0
+Keywords: cli,feed,timeline,twitter,x
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: browser-cookie3>=0.19
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Twitter CLI
+
+Twitter/X 命令行工具 — 读取 Timeline、书签和用户信息。
+
+**零 API Key** — 使用浏览器 Cookie 认证，免费访问 Twitter。
+
+## 安装
+
+```bash
+# 推荐：uv tool（更快，隔离环境）
+uv tool install twitter-cli
+
+# 其次：pipx
+pipx install twitter-cli
+```
+
+从源码安装：
+
+```bash
+git clone git@github.com:jackwener/twitter-cli.git
+cd twitter-cli
+uv sync
+```
+
+## Quick Start
+
+```bash
+# 运行（自动从 Chrome 提取 Cookie）
+twitter feed
+```
+
+首次运行确保 Chrome 已登录 x.com。
+
+## 使用方式
+
+### 读取
+
+```bash
+# 抓取首页 timeline（For You 算法推荐）
+twitter feed
+
+# 抓取关注的人的 timeline（Following 时间线）
+twitter feed -t following
+
+# 自定义抓取条数
+twitter feed --max 50
+
+# 开启筛选（按 score 排序过滤）
+twitter feed --filter
+
+# JSON 输出
+twitter feed --json > tweets.json
+
+# 从已有数据加载
+twitter feed --input tweets.json
+
+
+# 抓取收藏
+twitter favorite
+twitter favorite --max 30 --json
+```
+
+### 用户
+
+```bash
+# 查看用户资料
+twitter user elonmusk
+
+# 列出用户推文
+twitter user-posts elonmusk --max 20
+```
+
+## Pipeline
+
+```
+抓取 (GraphQL API)  →  筛选 (Engagement Score)
+      50 条               top 20
+```
+
+### 筛选算法
+
+加权评分公式，收藏权重最高（代表"值得回看"）：
+
+```
+score = 1.0 × likes + 3.0 × retweets + 2.0 × replies
+      + 5.0 × bookmarks + 0.5 × log10(views)
+```
+
+## 配置
+
+编辑 `config.yaml`：
+
+```yaml
+fetch:
+  count: 50
+
+filter:
+  mode: "topN"          # "topN" | "score" | "all"
+  topN: 20
+  weights:
+    likes: 1.0
+    retweets: 3.0
+    replies: 2.0
+    bookmarks: 5.0
+    views_log: 0.5
+```
+
+### Cookie 配置
+
+**方式 1：自动提取**（推荐） — 确保浏览器已登录 x.com，程序自动通过 `browser-cookie3` 按 Chrome → Edge → Firefox → Brave 顺序尝试读取。
+
+**方式 2：环境变量** — 设置：
+
+```bash
+export TWITTER_AUTH_TOKEN=your_auth_token
+export TWITTER_CT0=your_ct0
+```
+
+可通过 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 浏览器插件导出。
+
+## 项目结构
+
+```
+twitter_cli/
+├── __init__.py     # 版本信息
+├── cli.py          # CLI 入口 (click)
+├── client.py       # Twitter GraphQL API Client (GET)
+├── auth.py         # Cookie 提取 (env / browser-cookie3)
+├── filter.py       # Engagement scoring + 筛选
+├── formatter.py    # Rich 终端输出 + JSON
+├── config.py       # YAML 配置加载
+├── serialization.py # Tweet JSON <-> dataclass
+└── models.py       # 数据模型 (dataclass)
+```
+
+## Development
+
+```bash
+# Install development tools
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+```
+
+## 注意事项
+
+- 使用 Cookie 登录存在被平台检测的风险，建议使用**专用小号**
+- Cookie 只存在本地，不上传不外传
+- GraphQL `queryId` 会从 Twitter 前端 JS 自动检测，无需手动维护

twitter_cli-0.1.0/README.md

@@ -0,0 +1,153 @@
+# Twitter CLI
+
+Twitter/X 命令行工具 — 读取 Timeline、书签和用户信息。
+
+**零 API Key** — 使用浏览器 Cookie 认证，免费访问 Twitter。
+
+## 安装
+
+```bash
+# 推荐：uv tool（更快，隔离环境）
+uv tool install twitter-cli
+
+# 其次：pipx
+pipx install twitter-cli
+```
+
+从源码安装：
+
+```bash
+git clone git@github.com:jackwener/twitter-cli.git
+cd twitter-cli
+uv sync
+```
+
+## Quick Start
+
+```bash
+# 运行（自动从 Chrome 提取 Cookie）
+twitter feed
+```
+
+首次运行确保 Chrome 已登录 x.com。
+
+## 使用方式
+
+### 读取
+
+```bash
+# 抓取首页 timeline（For You 算法推荐）
+twitter feed
+
+# 抓取关注的人的 timeline（Following 时间线）
+twitter feed -t following
+
+# 自定义抓取条数
+twitter feed --max 50
+
+# 开启筛选（按 score 排序过滤）
+twitter feed --filter
+
+# JSON 输出
+twitter feed --json > tweets.json
+
+# 从已有数据加载
+twitter feed --input tweets.json
+
+
+# 抓取收藏
+twitter favorite
+twitter favorite --max 30 --json
+```
+
+### 用户
+
+```bash
+# 查看用户资料
+twitter user elonmusk
+
+# 列出用户推文
+twitter user-posts elonmusk --max 20
+```
+
+## Pipeline
+
+```
+抓取 (GraphQL API)  →  筛选 (Engagement Score)
+      50 条               top 20
+```
+
+### 筛选算法
+
+加权评分公式，收藏权重最高（代表"值得回看"）：
+
+```
+score = 1.0 × likes + 3.0 × retweets + 2.0 × replies
+      + 5.0 × bookmarks + 0.5 × log10(views)
+```
+
+## 配置
+
+编辑 `config.yaml`：
+
+```yaml
+fetch:
+  count: 50
+
+filter:
+  mode: "topN"          # "topN" | "score" | "all"
+  topN: 20
+  weights:
+    likes: 1.0
+    retweets: 3.0
+    replies: 2.0
+    bookmarks: 5.0
+    views_log: 0.5
+```
+
+### Cookie 配置
+
+**方式 1：自动提取**（推荐） — 确保浏览器已登录 x.com，程序自动通过 `browser-cookie3` 按 Chrome → Edge → Firefox → Brave 顺序尝试读取。
+
+**方式 2：环境变量** — 设置：
+
+```bash
+export TWITTER_AUTH_TOKEN=your_auth_token
+export TWITTER_CT0=your_ct0
+```
+
+可通过 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 浏览器插件导出。
+
+## 项目结构
+
+```
+twitter_cli/
+├── __init__.py     # 版本信息
+├── cli.py          # CLI 入口 (click)
+├── client.py       # Twitter GraphQL API Client (GET)
+├── auth.py         # Cookie 提取 (env / browser-cookie3)
+├── filter.py       # Engagement scoring + 筛选
+├── formatter.py    # Rich 终端输出 + JSON
+├── config.py       # YAML 配置加载
+├── serialization.py # Tweet JSON <-> dataclass
+└── models.py       # 数据模型 (dataclass)
+```
+
+## Development
+
+```bash
+# Install development tools
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+```
+
+## 注意事项
+
+- 使用 Cookie 登录存在被平台检测的风险，建议使用**专用小号**
+- Cookie 只存在本地，不上传不外传
+- GraphQL `queryId` 会从 Twitter 前端 JS 自动检测，无需手动维护

twitter_cli-0.1.0/config.yaml

@@ -0,0 +1,15 @@
+fetch:
+  count: 50
+
+filter:
+  mode: "topN"
+  topN: 20
+  minScore: 50
+  lang: []
+  excludeRetweets: false
+  weights:
+    likes: 1.0
+    retweets: 3.0
+    replies: 2.0
+    bookmarks: 5.0
+    views_log: 0.5

twitter_cli-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "twitter-cli"
+version = "0.1.0"
+description = "A CLI for Twitter/X — feed, bookmarks, and user timeline in terminal"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.8"
+authors = [{ name = "jackwener", email = "jakevingoo@gmail.com" }]
+keywords = ["twitter", "x", "cli", "feed", "timeline"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software 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",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "browser-cookie3>=0.19",
+    "click>=8.0",
+    "rich>=13.0",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/jackwener/twitter-cli"
+Repository = "https://github.com/jackwener/twitter-cli"
+Issues = "https://github.com/jackwener/twitter-cli/issues"
+
+[project.scripts]
+twitter = "twitter_cli.cli:cli"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.hatch.build.targets.wheel]
+packages = ["twitter_cli"]

twitter_cli-0.1.0/tests/conftest.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from twitter_cli.models import Author, Metrics, Tweet
+
+
+@pytest.fixture()
+def tweet_factory():
+    def _make_tweet(tweet_id: str = "1", **overrides: Any) -> Tweet:
+        metrics = overrides.pop(
+            "metrics",
+            Metrics(likes=10, retweets=2, replies=1, quotes=0, views=120, bookmarks=3),
+        )
+        author = overrides.pop(
+            "author",
+            Author(id="u1", name="Alice", screen_name="alice", verified=False),
+        )
+        return Tweet(
+            id=tweet_id,
+            text=overrides.pop("text", "hello"),
+            author=author,
+            metrics=metrics,
+            created_at=overrides.pop("created_at", "2025-01-01"),
+            media=overrides.pop("media", []),
+            urls=overrides.pop("urls", []),
+            is_retweet=overrides.pop("is_retweet", False),
+            lang=overrides.pop("lang", "en"),
+            retweeted_by=overrides.pop("retweeted_by", None),
+            quoted_tweet=overrides.pop("quoted_tweet", None),
+            score=overrides.pop("score", 0.0),
+        )
+
+    return _make_tweet

twitter_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from click.testing import CliRunner
+
+from twitter_cli.cli import cli
+from twitter_cli.models import UserProfile
+from twitter_cli.serialization import tweets_to_json
+
+
+def test_cli_user_command_works_with_client_factory(monkeypatch) -> None:
+    class FakeClient:
+        def fetch_user(self, screen_name: str) -> UserProfile:
+            return UserProfile(id="1", name="Alice", screen_name=screen_name)
+
+    monkeypatch.setattr("twitter_cli.cli._get_client", lambda: FakeClient())
+    runner = CliRunner()
+    result = runner.invoke(cli, ["user", "alice"])
+    assert result.exit_code == 0
+
+
+def test_cli_feed_json_input_path(tmp_path, tweet_factory) -> None:
+    json_path = tmp_path / "tweets.json"
+    json_path.write_text(tweets_to_json([tweet_factory("1")]), encoding="utf-8")
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["feed", "--input", str(json_path), "--json"])
+    assert result.exit_code == 0
+    assert '"id": "1"' in result.output

twitter_cli-0.1.0/tests/test_config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from twitter_cli.config import DEFAULT_CONFIG, load_config
+
+
+def test_load_config_supports_block_list_yaml(tmp_path: Path) -> None:
+    config_file = tmp_path / "config.yaml"
+    config_file.write_text(
+        "\n".join(
+            [
+                "fetch:",
+                "  count: 25",
+                "filter:",
+                "  mode: score",
+                "  lang:",
+                "    - en",
+                "    - zh",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    config = load_config(str(config_file))
+    assert config["fetch"]["count"] == 25
+    assert config["filter"]["mode"] == "score"
+    assert config["filter"]["lang"] == ["en", "zh"]
+
+
+def test_load_config_invalid_yaml_falls_back_to_defaults(tmp_path: Path) -> None:
+    config_file = tmp_path / "config.yaml"
+    config_file.write_text("fetch: [", encoding="utf-8")
+
+    config = load_config(str(config_file))
+    assert config["fetch"]["count"] == DEFAULT_CONFIG["fetch"]["count"]
+    assert config["filter"]["mode"] == DEFAULT_CONFIG["filter"]["mode"]
+
+
+def test_load_config_does_not_mutate_defaults(tmp_path: Path) -> None:
+    config = load_config(str(tmp_path / "missing-config.yaml"))
+    config["filter"]["weights"]["likes"] = 999
+    assert DEFAULT_CONFIG["filter"]["weights"]["likes"] == 1.0

twitter_cli-0.1.0/tests/test_config_normalization.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from twitter_cli.config import load_config
+
+
+def test_filter_normalization_for_invalid_values(tmp_path: Path) -> None:
+    config_file = tmp_path / "config.yaml"
+    config_file.write_text(
+        "\n".join(
+            [
+                "fetch:",
+                "  count: -5",
+                "filter:",
+                "  mode: unknown",
+                "  topN: -1",
+                "  minScore: abc",
+                "  lang: zh",
+                "  weights:",
+                "    likes: bad",
+                "    retweets: 4",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    config = load_config(str(config_file))
+    assert config["fetch"]["count"] == 1
+    assert config["filter"]["mode"] == "topN"
+    assert config["filter"]["topN"] == 1
+    assert config["filter"]["minScore"] == 50.0
+    assert config["filter"]["lang"] == []
+    assert config["filter"]["weights"]["likes"] == 1.0
+    assert config["filter"]["weights"]["retweets"] == 4.0

twitter_cli-0.1.0/tests/test_filter.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from twitter_cli.filter import filter_tweets
+
+
+def test_filter_tweets_does_not_mutate_input(tweet_factory) -> None:
+    tweet = tweet_factory("1", score=0.0)
+    output = filter_tweets([tweet], {"mode": "all", "weights": {}})
+
+    assert tweet.score == 0.0
+    assert output[0].score > 0.0
+    assert output[0] is not tweet
+
+
+def test_filter_tweets_applies_language_and_retweet_filters(tweet_factory) -> None:
+    tweets = [
+        tweet_factory("1", lang="en", is_retweet=False),
+        tweet_factory("2", lang="zh", is_retweet=False),
+        tweet_factory("3", lang="en", is_retweet=True),
+    ]
+    output = filter_tweets(
+        tweets,
+        {
+            "mode": "all",
+            "lang": ["en"],
+            "excludeRetweets": True,
+            "weights": {},
+        },
+    )
+
+    assert [tweet.id for tweet in output] == ["1"]

twitter_cli-0.1.0/tests/test_serialization.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from twitter_cli.serialization import tweet_from_dict, tweet_to_dict, tweets_from_json, tweets_to_json
+
+
+def test_tweet_roundtrip_dict(tweet_factory) -> None:
+    tweet = tweet_factory("42")
+    payload = tweet_to_dict(tweet)
+    restored = tweet_from_dict(payload)
+
+    assert restored.id == tweet.id
+    assert restored.author.screen_name == tweet.author.screen_name
+    assert restored.metrics.likes == tweet.metrics.likes
+
+
+def test_tweets_json_roundtrip(tweet_factory) -> None:
+    tweets = [tweet_factory("1"), tweet_factory("2", lang="zh")]
+    raw = tweets_to_json(tweets)
+    restored = tweets_from_json(raw)
+
+    assert [tweet.id for tweet in restored] == ["1", "2"]
+    assert restored[1].lang == "zh"

twitter_cli-0.1.0/twitter_cli/__init__.py

@@ -0,0 +1,3 @@
+"""twitter-cli: A CLI for Twitter/X."""
+
+__version__ = "0.1.0"