qlurk-python

Plurk API 的現代化 Python SDK。

• Python 3.11+
• OAuth 1.0a 認證
• 乾淨的 namespace 介面（client.timeline、client.users、…）
• 單一執行期相依套件：httpx

安裝

pip install qlurk

事前準備

你需要自己註冊一個 Plurk OAuth 應用程式。到 https://www.plurk.com/PlurkApp/ 註冊後可取得 consumer_key 與 consumer_secret，每次建立 PlurkClient 時都必須傳入 —— qlurk 本身不提供任何預設憑證。

快速開始

已有 access token 的情況

from qlurk import PlurkClient

with PlurkClient(
    consumer_key="YOUR_CONSUMER_KEY",
    consumer_secret="YOUR_CONSUMER_SECRET",
    token="USER_ACCESS_TOKEN",
    token_secret="USER_TOKEN_SECRET",
) as client:
    me = client.users.me()
    plurks = client.timeline.get_plurks()
    for p in plurks:
        print(p.url, p.content_raw)

使用帳密登入

from qlurk import PlurkClient

client = PlurkClient(
    consumer_key="YOUR_CONSUMER_KEY",
    consumer_secret="YOUR_CONSUMER_SECRET",
)
user = client.login("nickname", "password", totp_code=123456)
# token 會自動存在 client 內部，後續呼叫皆為已認證狀態。

自訂 header

所有非必要 header（例如 User-Agent）都透過單一的 headers 參數傳入，每一個 請求都會帶上。qlurk 本身除了 OAuth 的 Authorization 之外不會送出任何預設 header。若 key 衝突，OAuth header 會蓋過使用者傳入的值。

client = PlurkClient(
    consumer_key="...",
    consumer_secret="...",
    headers={
        "User-Agent": "MyBot/1.0",
        "Plurk-App-Version": "my-client/1.0",
    },
)

API namespace

PlurkClient 以 lazy 方式暴露下列 namespace：

錯誤處理

from qlurk import PlurkError, AuthError, NotFoundError, RateLimitError

try:
    client.users.me()
except AuthError:
    ...
except RateLimitError:
    ...
except NotFoundError:
    ...
except PlurkError as e:
    print(e.raw)  # 原始 API 回傳的 dict

非噗浪官方

本專案與噗浪公司無任何關係，僅為民間愛好者作品。製作過程大量使用 claude code。

其中使用到噗浪官方 API 文件中未記載的 API Endpoint（如 Forum、Reaction、Video...等）。 這部分的功能噗浪未承諾其長期相容性。

授權條款

本專案以 Apache License 2.0 授權。詳見 LICENSE。