mdclient/API.md

MDclient API 文件

MDAuth

認證類，用於登入和管理會話。

建構函式

MDAuth(base_url="https://codimd.lotimmy.com", cookie_file="key.conf")

參數：

• base_url (str): 伺服器位址
• cookie_file (str): Cookie 儲存檔案路徑

方法

login()

登入並儲存 Cookie。

success = auth.login(email, password)

參數：

• email (str): 登入信箱
• password (str): 登入密碼

回傳：

• bool: 是否登入成功

test_cookie()

測試儲存的 Cookie 是否有效。

is_valid = auth.test_cookie()

回傳：

• bool: Cookie 是否有效

load_cookie()

從檔案載入 Cookie。

cookies = auth.load_cookie()

回傳：

• dict | None: Cookie 字典，檔案不存在時返回 None

---

MDClient

客戶端類，提供所有筆記操作的 API。

建構函式

MDClient(base_url="https://codimd.lotimmy.com", cookie_file="key.conf", email=None, password=None)

參數：

• base_url (str): 伺服器位址
• cookie_file (str): Cookie 檔案路徑
• email (str): 登入信箱（可選）
• password (str): 登入密碼（可選）

方法

list_notes()

列出所有筆記。

notes = client.list_notes()

回傳：

• list | None: 筆記列表，失敗時返回 None

筆記物件結構：

{
    "id": "note_id",
    "text": "筆記標題",
    "time": 1234567890,
    "tags": ["tag1", "tag2"],
    "pinned": False
}

get_note()

取得筆記內容。

note = client.get_note(note_id)

參數：

• note_id (str): 筆記 ID

回傳：

• dict | None: 筆記內容，失敗時返回 None

筆記內容結構：

{
    "id": "note_id",
    "title": "筆記標題",
    "content": "Markdown 內容",
    "lastChangeAt": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
}

create_note()

建立新筆記。

result = client.create_note(title, content="")

參數：

• title (str): 筆記標題
• content (str): Markdown 內容

回傳：

• dict | None: 建立結果，失敗時返回 None

回傳結構：

{
    "id": "new_note_id",
    "url": "https://server.com/new_note_id"
}

delete_note()

刪除筆記。

success = client.delete_note(note_id)

參數：

• note_id (str): 筆記 ID

回傳：

• bool: 是否刪除成功

export_note()

匯出筆記。

content = client.export_note(note_id, format="md")

參數：

• note_id (str): 筆記 ID
• format (str): 匯出格式（md, pdf, html, slides）

回傳：

• str | None: 匯出的內容，失敗時返回 None

search_notes()

搜尋筆記。

results = client.search_notes(query)

參數：

• query (str): 搜尋關鍵字

回傳：

• list | None: 符合的筆記列表

---

使用範例

完整工作流程

from mdclient import MDAuth, MDClient

# 1. 登入
auth = MDAuth()
auth.login("user@example.com", "password")

# 2. 使用客戶端
client = MDClient()

# 3. 列出筆記
notes = client.list_notes()

# 4. 建立筆記
result = client.create_note("新筆記", "# 內容")

# 5. 取得筆記
note = client.get_note(result['id'])

# 6. 匯出筆記
content = client.export_note(result['id'])

# 7. 刪除筆記
client.delete_note(result['id'])

錯誤處理

from mdclient import MDClient

client = MDClient()

# 檢查回傳值
notes = client.list_notes()
if notes is None:
    print("取得筆記失敗")
else:
    for note in notes:
        print(note['text'])

# 檢查操作結果
result = client.create_note("標題", "內容")
if result:
    print(f"建立成功: {result['id']}")
else:
    print("建立失敗")

自訂伺服器

from mdclient import MDAuth, MDClient

# 連接到不同的伺服器
auth = MDAuth(base_url="https://demo.hedgedoc.org")
auth.login("user@example.com", "password")

client = MDClient(base_url="https://demo.hedgedoc.org")
notes = client.list_notes()