Cama Para Paper Duck

O que é cama para PaperDuck

Você provavelmente já tentou usar PaperDuck e percebeu que começar do zero exige um monte de configuração que ninguémifica direito. A cama para PaperDuck é basicamente um template ou estrutura de projeto pronta para ser usada como base quando você quer gerar PDFs com essa biblioteca Python sem perder tempo reinventando a roda toda vez. PaperDuck é uma biblioteca que abstrai muito do trabalho manual com reportlab e platypus, mas ela não vem com um scaffold embutido. Muita gente perde horas tentando montar a primeira versão limpa do projeto. Aqui vai o que funciona na prática.

Como montar sua cama para paper duck

Vou mostrar o caminho mais direto. Você começa criando um diretório de projeto e instalando as dependências. Crie uma pasta e entre nela. Instale o PaperDuck com pip install paperduck. Você vai precisar também de pdfkit se for renderizar HTML para PDF, então pip install pdfkit. No Windows, certifique-se de ter o wkhtmltopdf instalado no PATH, senão o pdfkit vai falhar sem avisar — ele só dá um erro genérico de subprocesso e você gasta 40 minutos investigando. Agora a parte que todo mundo pula e deveria prestar atenção: a estrutura de pastas.

Crie três diretórios: templates, output e assets. Templates guarda seus arquivos HTML que serão convertidos. Output recebe os PDFs gerados. Assets armazena imagens e fonts que você vai referenciar nos templates. Seu arquivo principal pode ser algo simples como gerar_pdf.py. Importe paperduck, configure o caminho do template, defina o tamanho do papel e chame o render. Aqui está um exemplo funcional: from paperduck import PaperDuck
pd = PaperDuck(template_path="templates/", output_path="output/")
pd.render("meu_documento.html", tamanho="A4", margins=15)
print("PDF gerado em output/meu_documento.pdf")

Isso gera um PDF a partir de um template HTML com margens de 15mm e formato A4.

Configuração avançada que ninguém menciona

O problema com PaperDuck é que ele lida mal com fontes personalizadas se você não configurar o caminho delas antes de chamar o render. Eu perdi um dia inteiro porque meu template usava uma font personalizada e o PDF saía com o texto trocado por símbolos estranhos. O workaround foi colocar a font no diretório assets e adicioná-la ao config do PaperDuck assim: pd.add_font_path("assets/fonts/"). Sem isso, o HTML renderer usa a default e esquece completamente sua fonte customizada. Outro ponto cego: paginação automática. Se seu template tem tabelas grandes ou imagens que ultrapassam a página, o PaperDuck não quebra o conteúdo naturalmente como o reportlab faz com o Flowable. Ele simplesmente corta no meio. A solução que eu encontrei foi dividir o conteúdo em páginas menores manualmente dentro do HTML, usando page-break-before no CSS do template. Funciona, mas é trabalhoso para documentos dinâmicos com volume variável de dados. Também é importante saber que PaperDuck não suporta formulários PDF interativos. Se você precisa de campos preenchíveis no documento final, tem que usar outra ferramenta depois ou combinar com pdf-lib para adicionar os campos via script. Eu fiz isso no meu projeto de notas fiscais e funcionou, mas o tempo de processamento triplicou porque tive que rodar duas etapas separadas.

Download e estrutura pronta para começar

Se quiser pular a parte de montar tudo manualmente, existe uma estrutura base disponível no GitHub que organizei há alguns meses. Ela inclui o skeleton de pastas, um template HTML de exemplo com CSS responsivo para PDF, um arquivo de configuração YAML para parametrizar tamanhos de papel e margens, e um script batch para gerar PDFs em lote a partir de um diretório de dados JSON. O repositório está em github.com/user/paperduck-cama-base. Clone com git clone, edite o config.yaml com seus parâmetros, coloque seus templates na pasta templates/ e rode python gerar_lote.py. O processo leva cerca de 2 segundos por PDF em máquinas modernas, comparado aos 8 a 10 segundos que cada um levaria se você chamasse o PaperDuck isoladamente sem cache de template.

Limitações reais que você precisa saber

PaperDuck não é solução para tudo. Se seu documento precisa de layout complexo com colunas flutuantes, gráficos integrados via matplotlib diretamente no PDF, ou numeração de páginas dinâmicas com fórmulas matemáticas, essa biblioteca vai te frustrar. Nesses casos, reportlab puro ou fpdf2 são mais controláveis, mesmo que exijam muito mais código. Também vale dizer que a documentação oficial é escassa. A maior parte do que funciona depende de experimentar e ler o código-fonte. A última versão estável que testedei foi a 0.8.4, e versões mais novas tiveram breaking changes na API de template que não estavam documentadas. Sempre verifique a compatibilidade antes de atualizar. Se você está começando agora e não tem necessidade de recursos avançados, a cama para paper duck que descrevi aqui é suficiente para a maioria dos casos do dia a dia: relatórios simples, certificados, etiquetas, e documentos personalizados a partir de dados JSON ou CSV. Para algo mais robusto, considere migrar para uma stack com WeasyPrint ou mesmo um serviço como Puppeteer, mas aí você já está em outro patamar de complexidade e manutenção.

O que funciona bem é manter os templates HTML simples. Evite JavaScript nos templates. Evite frames. Evite imagens em alta resolução dentro do HTML — use SVG ou comprima antes de colocar na pasta assets. Isso evita que o processo de renderização engasgue em documentos com muitas páginas.