pyzotero

Pyzotero

Pyzotero は、Zotero API v3 用の Python ラッパーです。Zotero ライブラリをプログラムから管理できます。アイテムやコレクションの読み取り、文献情報の作成と更新、添付ファイルのアップロード、タグの管理、引用文献のエクスポートに利用できます。

認証の設定

必要な認証情報 — https://www.zotero.org/settings/keys から取得してください。

• ユーザー ID：「Your userID for use in API calls」として表示されます
• API キー：https://www.zotero.org/settings/keys/new で作成してください
• ライブラリ ID：グループライブラリの場合、グループ URL の /groups/ の後にある整数です

認証情報は環境変数または .env ファイルに保存してください。

ZOTERO_LIBRARY_ID=your_user_id
ZOTERO_API_KEY=your_api_key
ZOTERO_LIBRARY_TYPE=user  # or "group"

設定の詳細は、references/authentication.md を参照してください。

インストール

uv add pyzotero
# or with CLI support:
uv add "pyzotero[cli]"

クイックスタート

from pyzotero import Zotero

zot = Zotero(library_id='123456', library_type='user', api_key='ABC1234XYZ')

# Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10)
for item in items:
    print(item['data']['title'], item['data']['itemType'])

# Search by keyword
results = zot.items(q='machine learning', limit=20)

# Retrieve all items (use everything() for complete results)
all_items = zot.everything(zot.items())

主な概念

• Zotero インスタンスは単一のライブラリ（ユーザーまたはグループ）に紐付けられます。すべてのメソッドはそのライブラリを対象に動作します。
• アイテムのデータは item['data'] に格納されています。item['data']['title'] や item['data']['creators'] のようにフィールドにアクセスできます。
• Pyzotero はデフォルトで 100 件のアイテムを返します（API のデフォルトは 25 件です）。すべてのアイテムを取得するには zot.everything(zot.items()) を使用してください。
• 書き込みメソッドは成功時に True を返し、失敗時には ZoteroError を発生させます。

リファレンスファイル

ファイル	内容
references/authentication.md	認証情報、ライブラリの種類、ローカルモード
references/read-api.md	アイテム、コレクション、タグ、グループの取得
references/search-params.md	絞り込み、並べ替え、検索パラメーター
references/write-api.md	アイテムの作成、更新、削除
references/collections.md	コレクションの CRUD 操作
references/tags.md	タグの取得と管理
references/files-attachments.md	ファイルの取得と添付ファイルのアップロード
references/exports.md	BibTeX、CSL-JSON、参考文献のエクスポート
references/pagination.md	follow()、everything()、ジェネレーター
references/full-text.md	全文コンテンツのインデックス作成と取得
references/saved-searches.md	保存済み検索の管理
references/cli.md	コマンドラインインターフェースの使用方法
references/error-handling.md	エラーと例外処理

よくあるパターン

アイテムの取得と変更

item = zot.item('ITEMKEY')
item['data']['title'] = 'New Title'
zot.update_item(item)

テンプレートからアイテムを作成

template = zot.item_template('journalArticle')
template['title'] = 'My Paper'
template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
zot.create_items([template])

BibTeX としてエクスポート

zot.add_parameters(format='bibtex')
bibtex = zot.top(limit=50)
# bibtex is a bibtexparser BibDatabase object
print(bibtex.entries)

ローカルモード（読み取り専用、API キー不要）

zot = Zotero(library_id='123456', library_type='user', local=True)
items = zot.items()