🧱 notion-starter

📋 Índice

• 📖 Sobre o Projeto
• 📁 Estrutura do Projeto
• 🚀 Funcionalidades
• 🎯 Como Usar
• ⚙️ Configuração
• ✅ Qualidade
• 📄 Licença
• 👤 Autor
• 🤝 Contribuições

📖 Sobre o Projeto

O notion-starter é o núcleo do ecossistema Automações do Notion. Ele oferece uma API Python tipada para trabalhar com páginas, databases, tarefas e conteúdo do Notion com retries, rate limit e erros previsíveis.

Além do cliente base, este repositório concentra a camada compartilhada entre o notion-tasks-cli e o notion-workspace-app: adaptadores GitHub/OpenRouter e notion_starter.services para tarefas, conteúdo, clonagem, ingestão, inventário GitHub, exportação DOCX e IA. As bordas e a configuração de ambiente permanecem nos consumidores.

📁 Estrutura do Projeto

notion-starter/
│
├── 📁 src/notion_starter/       # Biblioteca pública e módulos de domínio
│   ├── 📁 services/             # Casos de uso compartilhados
│   ├── client.py                # Cliente HTTP resiliente do Notion
│   ├── content.py               # Conversão Markdown ↔ blocos
│   ├── properties.py            # Builders de propriedades e schemas
│   └── tasks.py                 # Tarefa e TaskList
│
├── 📁 examples/                 # Scripts de uso da biblioteca
├── 📁 tests/                    # Suíte automatizada sem rede
├── .github/workflows/ci.yml     # Gate em Python 3.10–3.13
├── pyproject.toml               # Pacote, dependências e ferramentas
├── QUALIDADE.md                 # Contrato de qualidade do módulo
├── README.md                    # Este arquivo
└── LICENSE                      # Licença MIT

🚀 Funcionalidades

• NotionClient — cliente HTTP resiliente com retries, rate limit e erros tipados; inclui obter_pagina e atualizar_pagina para propriedades.
• Schema — leitura e comparação de schemas de databases com comparar_schema.
• Tarefas — modelos Tarefa e TaskList para criar, editar, mover e concluir tarefas; na criação, a coluna de título é descoberta pelo schema para também aceitar databases genéricos.
• Conteúdo — leitura e escrita de blocos, incluindo conversão Markdown ↔ blocos.
• Propriedades — builders properties.* para title, rich_text, select, status, number, date, relation e outros tipos; textos acima de 2.000 unidades UTF-16 são fatiados automaticamente.
• Inventário — varredura de páginas, databases e árvore do workspace.
• Classificação em lote — notion_starter.services.classificacao calcula a distribuição de uma regra sobre linhas já buscadas, lista as linhas sem classificação e só escreve quando o chamador pede explicitamente.
• Relatórios DOCX — notion_starter.services.relatorios_docx exporta um arquivo por data, combinando propriedades e corpo sem arquivos intermediários.
• Utilidades — saneamento de texto/JSON, fatiar_utf16, logging e readers.

Exemplo de fluxo: Markdown → blocos tipados da API do Notion → página atualizada.

🎯 Como Usar

Classificação em lote com dry-run

As linhas são buscadas pelo chamador para que o relatório possa ser conferido antes da escrita. O padrão é um dry-run; a aplicação pode ocorrer depois, e o valor é tratado como select por padrão:

from notion_starter.services.classificacao import (
    aplicar_classificacoes,
    classificar_em_lote,
)

relatorio = classificar_em_lote(linhas, regra_de_classificacao)
print(relatorio.distribuicao)
print(relatorio.ids_sem_classificacao)

aplicar_classificacoes(relatorio, cliente=cliente, coluna="Tipo")

Para outro tipo de coluna, passe um montar_propriedade, como properties.status. Linhas sem classificação nunca são alteradas.

Instalação

# Instalação pública da biblioteca
python -m pip install "notion-starter>=0.3.1,<0.4.0"

O release 0.3.1 será publicado no PyPI como wheel e sdist. Ele não depende de checkout Git e não instala Django, React ou a CLI. Para operar o produto completo, use notion-automacoes[app].

Para desenvolvimento, clone o repositório e use python -m pip install -e ".[dev]".

Para desenvolvimento:

# Clone e instale com as dependências de desenvolvimento
git clone https://github.com/Felipe-Alcantara/notion-starter.git
cd notion-starter
python -m pip install -e ".[dev]"

Uso rápido

from notion_starter import NotionClient

client = NotionClient()  # lê NOTION_TOKEN do ambiente

A pasta examples/ contém scripts completos para listar páginas, exportar linhas, sincronizar CSV, gerar a árvore HTML do workspace, gerenciar tarefas e publicar relatórios diários a partir do histórico de um repositório git (relatorios_do_git.py, com --simular para conferir antes de escrever).

⚙️ Configuração

Use variáveis de ambiente ou um arquivo .env local baseado em .env.example. Nunca versione tokens ou IDs reais.

✅ Qualidade

O gate local combina lint e testes:

python -m ruff check .
python -m pytest

A CI repete o gate em Python 3.10, 3.11, 3.12 e 3.13. Consulte QUALIDADE.md para o critério de pronto e a política de dependências deste pacote.

📄 Licença

Este projeto está sob a licença MIT — veja LICENSE.

👤 Autor

Felipe Alcantara

• GitHub: @Felipe-Alcantara
• Repositório: notion-starter

🤝 Contribuições

Contribuições são bem-vindas. Algumas ideias para quem quiser colaborar:

• ampliar a cobertura de tipos de propriedade do Notion;
• adicionar tipos de bloco ao conversor Markdown;
• expandir a escrita de linhas em data sources;
• melhorar exemplos, testes e documentação.

Leia CONTRIBUTING.md antes de enviar uma mudança.

⭐ Se esta biblioteca foi útil, considere dar uma estrela no GitHub.