qlurk 0.1.0

A modern Python SDK for the Plurk API

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：

Namespace	用途
timeline	貼文、轉噗、收藏、已讀狀態
users	使用者資料、karma、頭像上傳
responses	回應噗文
profile	公開個人資料
friends	朋友、粉絲、追蹤
alerts	通知、好友邀請
blocks	封鎖的使用者
cliques	朋友分組
bookmarks	已收藏的噗與標籤
search	噗與使用者搜尋
emoticons	自訂表情符號
polls	噗內投票
reactions	Emoji 反應
video	影片上傳與預覽
premium	噗幣、禮物、廣告
forum	論壇管理

錯誤處理

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。