Metadata-Version: 2.5
Name: notion-starter
Version: 0.3.1
Summary: Biblioteca Python para operar a API oficial do Notion: cliente resiliente, schema, tarefas, conteúdo e inventário.
Project-URL: Homepage, https://github.com/Felipe-Alcantara/notion-starter
Project-URL: Repository, https://github.com/Felipe-Alcantara/notion-starter
Author: Felipe Alcantara
License: MIT License
        
        Copyright (c) 2026 Felipe Alcantara
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,notion,notion-api,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: python-docx>=1.1
Requires-Dist: requests>=2.25
Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: openpyxl>=3.1; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: planilha
Requires-Dist: openpyxl>=3.1; extra == 'planilha'
Description-Content-Type: text/markdown

# 🧱 notion-starter

<div align="center">

![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
![Requests](https://img.shields.io/badge/Requests-2.25%2B-20232A?style=for-the-badge&logo=python&logoColor=white)
[![PyPI](https://img.shields.io/pypi/v/notion-starter?style=for-the-badge&label=PyPI)](https://pypi.org/project/notion-starter/)
![Licença MIT](https://img.shields.io/badge/Licen%C3%A7a-MIT-green?style=for-the-badge)

**Biblioteca Python resiliente para operar a API oficial do Notion e compartilhar regras de negócio entre interfaces.**

[📖 Sobre](#-sobre-o-projeto) • [🚀 Funcionalidades](#-funcionalidades) • [🎯 Como usar](#-como-usar) • [✅ Qualidade](#-qualidade)

</div>

---

## 📋 Índice

- [📖 Sobre o Projeto](#-sobre-o-projeto)
- [📁 Estrutura do Projeto](#-estrutura-do-projeto)
- [🚀 Funcionalidades](#-funcionalidades)
- [🎯 Como Usar](#-como-usar)
- [⚙️ Configuração](#-configuração)
- [✅ Qualidade](#-qualidade)
- [📄 Licença](#-licença)
- [👤 Autor](#-autor)
- [🤝 Contribuições](#-contribuições)

---

## 📖 Sobre o Projeto

O `notion-starter` é o núcleo do ecossistema
[Automações do Notion](https://github.com/Felipe-Alcantara/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](https://github.com/Felipe-Alcantara/notion-tasks-cli) e o
[notion-workspace-app](https://github.com/Felipe-Alcantara/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

```text
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:

```python
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

```bash
# 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](https://pypi.org/project/notion-starter/)
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]`](https://pypi.org/project/notion-automacoes/).

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

Para desenvolvimento:

```bash
# 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

```python
from notion_starter import NotionClient

client = NotionClient()  # lê NOTION_TOKEN do ambiente
```

A pasta [`examples/`](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`](examples/relatorios_do_git.py), com `--simular`
para conferir antes de escrever).

---

## ⚙️ Configuração

| Variável | Descrição |
| --- | --- |
| `NOTION_TOKEN` | Token de integração interna do Notion (obrigatório) |
| `NOTION_DATABASE_ID` | Database padrão de tarefas (opcional) |

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:

```bash
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`](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`](LICENSE).

---

## 👤 Autor

**Felipe Alcantara**

- GitHub: [@Felipe-Alcantara](https://github.com/Felipe-Alcantara)
- Repositório: [notion-starter](https://github.com/Felipe-Alcantara/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`](CONTRIBUTING.md) antes de enviar uma mudança.

---

⭐ Se esta biblioteca foi útil, considere dar uma estrela no
[GitHub](https://github.com/Felipe-Alcantara/notion-starter).
