Timmy
38b4bc5377
- Add MDAuth class for authentication and session management - Add MDClient class for note operations (CRUD + export/search) - Add CLI tool mdclient_cli.py for quick operations - Support for CodiMD, HedgeDoc, and HackMD services - Multi-endpoint API compatibility Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
198 lines
3.3 KiB
Markdown
198 lines
3.3 KiB
Markdown
# MDclient
|
||
|
||
Markdown 筆記服務的 Python 客戶端函式庫。
|
||
|
||
支援 CodiMD、HedgeDoc、HackMD 等服務。
|
||
|
||
## 特色
|
||
|
||
- ✅ 簡單好用的 Python API
|
||
- ✅ 支援多種 Markdown 筆記服務
|
||
- ✅ 自動會話管理（Cookie）
|
||
- ✅ 支援 .env 設定檔
|
||
- ✅ 完整的筆記操作（建立、讀取、更新、刪除、匯出）
|
||
|
||
## 安裝
|
||
|
||
```bash
|
||
pip install mdclient
|
||
```
|
||
|
||
如果需要 .env 支援：
|
||
|
||
```bash
|
||
pip install "mdclient[env]"
|
||
```
|
||
|
||
## 快速開始
|
||
|
||
```python
|
||
from mdclient import MDClient, MDAuth
|
||
|
||
# 登入
|
||
auth = MDAuth()
|
||
auth.login("your@email.com", "password")
|
||
|
||
# 使用客戶端
|
||
client = MDClient()
|
||
notes = client.list_notes()
|
||
|
||
for note in notes:
|
||
print(f"{note['text']} - {note['id']}")
|
||
```
|
||
|
||
## 主要功能
|
||
|
||
### 列出筆記
|
||
|
||
```python
|
||
client = MDClient()
|
||
notes = client.list_notes()
|
||
```
|
||
|
||
### 建立筆記
|
||
|
||
```python
|
||
result = client.create_note("標題", "# 內容")
|
||
```
|
||
|
||
### 取得筆記
|
||
|
||
```python
|
||
note = client.get_note(note_id)
|
||
print(note['content'])
|
||
```
|
||
|
||
### 匯出筆記
|
||
|
||
```python
|
||
content = client.export_note(note_id, format="md")
|
||
```
|
||
|
||
### 搜尋筆記
|
||
|
||
```python
|
||
results = client.search_notes("關鍵字")
|
||
```
|
||
|
||
### 刪除筆記
|
||
|
||
```python
|
||
client.delete_note(note_id)
|
||
```
|
||
|
||
## 使用 .env 檔案
|
||
|
||
建立 `.env` 檔案：
|
||
|
||
```env
|
||
MDCLIENT_URL=https://codimd.lotimmy.com
|
||
MDCLIENT_EMAIL=your@email.com
|
||
MDCLIENT_PASSWORD=your_password
|
||
```
|
||
|
||
在程式碼中使用：
|
||
|
||
```python
|
||
import os
|
||
from dotenv import load_dotenv
|
||
from mdclient import MDAuth, MDClient
|
||
|
||
load_dotenv()
|
||
|
||
auth = MDAuth(base_url=os.getenv('MDCLIENT_URL'))
|
||
auth.login(
|
||
os.getenv('MDCLIENT_EMAIL'),
|
||
os.getenv('MDCLIENT_PASSWORD')
|
||
)
|
||
|
||
client = MDClient(base_url=os.getenv('MDCLIENT_URL'))
|
||
notes = client.list_notes()
|
||
```
|
||
|
||
## 自訂伺服器
|
||
|
||
```python
|
||
from mdclient import MDAuth, MDClient
|
||
|
||
auth = MDAuth(base_url="https://your-server.com")
|
||
auth.login("user@example.com", "password")
|
||
|
||
client = MDClient(base_url="https://your-server.com")
|
||
notes = client.list_notes()
|
||
```
|
||
|
||
## CLI 工具（可選）
|
||
|
||
專案包含一個可選的 CLI 工具：
|
||
|
||
```bash
|
||
# 登入
|
||
python3 mdclient_cli.py login
|
||
|
||
# 列出筆記
|
||
python3 mdclient_cli.py list
|
||
|
||
# 建立筆記
|
||
python3 mdclient_cli.py create "標題"
|
||
|
||
# 取得筆記
|
||
python3 mdclient_cli.py get <note_id>
|
||
|
||
# 匯出筆記
|
||
python3 mdclient_cli.py export <note_id> -o note.md
|
||
```
|
||
|
||
## API 參考
|
||
|
||
詳細的 API 文件請查看 [API.md](API.md)。
|
||
|
||
## 範例
|
||
|
||
- [example.py](example.py) - 基本使用範例
|
||
- [auth_example.py](auth_example.py) - 認證功能範例
|
||
|
||
## 專案結構
|
||
|
||
```
|
||
mdclient/
|
||
├── mdclient/ # 核心 Python 函式庫
|
||
│ ├── __init__.py # 匯出 MDClient, MDAuth
|
||
│ ├── auth.py # 認證功能
|
||
│ └── client.py # API 客戶端
|
||
├── mdclient_cli.py # 可選的 CLI 工具
|
||
├── example.py # Python 使用範例
|
||
├── auth_example.py # 認證範例
|
||
├── .env.example # 環境變數範例
|
||
├── API.md # API 文件
|
||
├── QUICKSTART.md # 快速開始
|
||
└── README.md # 本檔案
|
||
```
|
||
|
||
## 環境變數
|
||
|
||
- `MDCLIENT_URL` - 伺服器位址
|
||
- `MDCLIENT_EMAIL` - 登入信箱
|
||
- `MDCLIENT_PASSWORD` - 登入密碼
|
||
- `MDCLIENT_COOKIE_FILE` - Cookie 檔案路徑
|
||
|
||
## 開發
|
||
|
||
```bash
|
||
# 安裝開發依賴
|
||
pip install -e ".[dev]"
|
||
|
||
# 執行測試
|
||
pytest
|
||
|
||
# 程式碼格式化
|
||
black mdclient/
|
||
|
||
# 型別檢查
|
||
mypy mdclient/
|
||
```
|
||
|
||
## 授權
|
||
|
||
MIT
|