pdf-toolkit/README.md

pdf-toolkit

Transforme, otimize e gerencie arquivos PDF com facilidade.

• Interface Web: Streamlit com upload drag-and-drop e configuração visual
• API REST: FastAPI com documentação OpenAPI automática em /docs
• Operações: compressão, PDF/A ↔ PDF comum, merge, split, rotação, extração de texto e imagens

---

🚀 Começando

Pré-requisitos

• Python 3.12+
• pip

Instalação

git clone <url-do-repositorio> pdf-toolkit
cd pdf-toolkit
pip install -r requirements.txt

Execução

Streamlit (interface web):

streamlit run app.py --server.port 8550

API REST:

uvicorn api:app --host 0.0.0.0 --port 8555 --reload

Acesse:

• Streamlit → http://localhost:8550
• API docs → http://localhost:8555/docs (Swagger)
• API docs → http://localhost:8555/redoc (Redoc)

---

📋 Operações disponíveis

Operação	CLI	API	Streamlit
Comprimir PDF	✅	POST /compress	✅
PDF/A → PDF comum	✅	POST /pdfa-to-regular	✅
Comprimir mantendo PDF/A	✅	POST /compress-pdfa	✅
Merge (juntar PDFs)	✅	POST /merge	✅
Split (extrair páginas)	✅	POST /split	✅
Extrair páginas específicas	✅	POST /extract-pages	✅
Rotacionar páginas	✅	POST /rotate	✅
Extrair texto	✅	POST /extract-text	✅
Extrair imagens	✅	POST /extract-images	✅
Inspecionar metadados	✅	POST /inspect	✅

Níveis de compressão

Preset	Qualidade	Dimensão máx	Descrição
screen	30	1200px	Agressivo — mínimo tamanho
ebook	60	2000px	Equilibrado — padrão
printer	85	3500px	Leve — alta qualidade
prepress	95	5000px	Mínima perda

---

🧠 Arquitetura

pdf-toolkit/
├── app.py               # Interface Streamlit (GUI)
├── api.py               # API REST (FastAPI)
├── config.py            # Constantes e limites
├── requirements.txt     # Dependências
├── core/
│   ├── engine.py        # Orquestrador central
│   ├── compress.py      # Compressão e re-amostragem
│   ├── operations.py    # Merge, split, rotate, extract
│   ├── validators.py    # Validação de PDFs
│   └── pdfa.py          # Detecção e conversão PDF/A
├── scripts/
│   ├── run-web.sh       # Inicia Streamlit
│   └── run-api.sh       # Inicia API
├── tests/               # Testes unitários
├── docs/
│   ├── ARCHITECTURE.md  # Detalhamento técnico
│   └── API.md           # Documentação da API
└── tmp/                 # Arquivos temporários (gitignored)

Decisões técnicas

• pypdf: manipulação PDF 100% Python, sem dependências binárias
• Pillow: re-amostragem de imagens com redimensionamento proporcional
• FastAPI: tipagem automática, validação de entrada, OpenAPI nativo
• Streamlit: prototipação rápida de GUI sem HTML/JS
• Sem Ghostscript: mantido leve — pypdf + Pillow cobre ~90% dos casos

Limitações conhecidas

• A compressão re-amostra imagens embutidas; PDFs sem imagens reduzem pouco
• A detecção de PDF/A é heurística (via metadados XMP + OutputIntents)
• Preview visual de páginas requer poppler-utils + pdf2image (não incluso)
• PDFs criptografados com senha não são suportados

---

🧪 Testes

python -m pytest tests/ -v

---

📦 Licença

MIT