Pyzotero

Pyzotero é um wrapper Python para a API v3 do Zotero. Use-o para gerenciar bibliotecas Zotero programaticamente: ler itens e coleções, criar e atualizar referências, fazer upload de anexos, gerenciar tags e exportar citações.

Alvo revisado: pyzotero 1.15.2 em 30/09/2026. Verificadas a documentação oficial do SDK, o código fonte de lançamento e os contratos da Web API. Exemplos que exigem uma biblioteca privada ou a execução do Zotero são ilustrativos; sondagens públicas somente leitura e verificações isoladas de contratos do SDK não estabelecem sucesso de escrita autenticada.

Configuração de Autenticação

Para leituras e escritas privadas remotas, obtenha as credenciais em https://www.zotero.org/settings/keys:

• User ID: exibido como "Seu userID para uso em chamadas de API"
• API Key: crie em https://www.zotero.org/settings/keys/new
• Library ID: para bibliotecas de grupo, o inteiro após /groups/ no URL do grupo

Armazene as credenciais em variáveis de ambiente ou em um arquivo .env:

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

Veja references/authentication.md para detalhes completos de configuração.

Instalação

uv add "pyzotero==1.15.2"    # Reviewed Web API client
uv add "pyzotero[cli]==1.15.2"  # + local CLI
uv add "pyzotero[mcp]==1.15.2"  # + MCP server

Início Rápido

import os
from pyzotero import Zotero

zot = Zotero(
    library_id=os.environ['ZOTERO_LIBRARY_ID'],
    library_type=os.environ.get('ZOTERO_LIBRARY_TYPE', 'user'),
    api_key=os.environ['ZOTERO_API_KEY'],
)

# Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10)
for item in items:
    print(item['data'].get('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())

Conceitos Principais

• Uma instância Zotero está vinculada a uma única biblioteca (usuário ou grupo). Todos os métodos operam nessa biblioteca.
• Os dados do item residem em item['data']. Acesse campos como item['data']['title'], item['data']['creators'].
• Pyzotero retorna 100 itens por padrão (o padrão da API é 25). Use zot.everything(zot.items()) para obter todos os itens.
• Os tipos de retorno são específicos do método: update_item() relata sucesso Booleano, enquanto create_items() retorna o status de criação por item. Inspecione seus mapeamentos failed, successful (objetos salvos completos), success (chaves legadas) e unchanged e retenha o mapeamento índice-de-entrada-para-chave. Um dicionário de resposta "truthy" não estabelece que cada item foi criado; relate falhas parciais e tente novamente apenas as entradas falhas após a reconciliação. Veja os contratos de métodos de escrita.

Arquivos de Referência

Padrões Comuns

Buscar e modificar um item

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

…