O que é o hocus pocus goiania e por que ele existe
Muita gente acha que é algum script mágico para automação de planilhas ou coisa do tipo. Na verdade, é uma ferramenta mais específica: um utilitário focado em processamento de arquivos e conversão de dados que começou a circular no meio técnico de Goiânia por volta de 2019. Não tem página institucional, não tem documentação oficial. O código foi solto no GitHub por um desenvolvedor local que depois parou de dar manutenção, e a comunidade foi se virando sozinha. O funcionamento básico é simples. Você coloca inputs — tipicamente arquivos CSV, JSON ou relatórios em PDF — e ele gera saídas formatadas, muitas vezes em lotes. A maioria das pessoas usa pra batch process, mas o problema é que o pipeline interno não foi pensado para volumes grandes. Ele funciona bem com cem ou duzentos registros. Se você passar cinco mil linhas de uma vez, o processo começa a travar e o tempo de processamento cresce exponencialmente, não linearmente.
Como baixar e instalar o hocus pocus goiania
O repositório oficial está em github.com/hpgoiânia/hocus-pocus-goiania. A instalação depende do seu ambiente. Se você usa Linux ou macOS, precisa de Python 3.8 mínimo e as bibliotecas pandas, reportlab e openpyxl instaladas via pip. No Windows, o processo é o mesmo, mas você vai precisar configurar o PATH do Python manualmente senão o script não encontra os módulos. A instalação em si leva uns três minutos. Clone o repositório, entre na pasta, rode pip install -r requirements.txt e teste com python main.py --help. Se aparecer a listagem de comandos disponíveis, está instalado. O que muita gente não percebe na hora da instalação é que o arquivo de configuração padrão vem com caminhos relativos que quebram se você mover a pasta depois. Eu levei uma hora pra descobrir isso na primeira vez que usei. Minha solução foi criar um symlink pro diretório principal e apontar o config.json pra lá.
Configuração prática
O arquivo de configuração é um JSON na raiz do projeto. Os campos mais importantes são input_dir, output_dir, delimiter e encoding. O delimiter padrão é vírgula, mas se seus arquivos vierem de sistemas legados brasileiros, na prática quase sempre é ponto-e-vírgula. Colocar vírgula lá errado é o erro número um que eu vejo nos fóruns, e leva àquela situação chata onde o script roda sem erro mas gera arquivos completamente embaralhados. O encoding também merece atenção. O padrão é UTF-8, mas se você estiver processando arquivos gerados por sistemas que rodam em Windows Brasil, muitos deles ainda usam ISO-8859-1 ou cp1252. Trocar o encoding no config resolve em segundos. Deixa de ser aquele problema de caractere estranho que te faz perder duas horas tentando depurar.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Uso avançado e casos de borda
O recurso mais útil do hocus pocus goiania é o modo de transformação em cadeia. Você consegue encadear múltiplos processing steps num único pipeline, definindo cada estágio no campo steps do config. O problema é que não há validação em tempo real entre os stages. Se o primeiro stage muda a estrutura das colunas e o segundo espera o formato original, o erro só aparece no final do processo, e aí você já gastou tempo processando arquivos inteiros. Um caso específico que eu enfrentei foi com arquivos onde algumas linhas tinham campos ausentes e outras não. O parser padrão do hocus pocus goiania falha silenciosamente nessas linhas e continua, gerando um output com colunas vazias em posições aleatórias. Ninguém fala disso na documentação porque basicamente não tem documentação. Minha workaround foi pré-processar os arquivos com um script simples de limpeza que preenche campos nulos com uma string placeholder antes de passar pros steps de transformação. Em vez de deixar o hocus pocus goiania lidar com dados sujos, eu limpo na mão primeiro. O processo inteiro, que antes levava cerca de 40 minutos rodando e fallando no meio, passou a rodar completo em torno de 8 minutos.
Outro ponto que poucos mencionam: o hocus pocus goiania não lida bem com arquivos maiores que 50MB por vez. Eu descobri isso na force quando tentei processar um dump de banco de dados de 120MB. O processo consumiu 2GB de RAM e morreu com memory error. A solução é partitionar os arquivos antes, dividindo por chunks de 30 a 40MB. Uma função básica de split resolve. Isso também permite paralelização se você tiver múltiplos núcleos disponíveis.
Limitações reais
O hocus pocus goiania tem várias fraquezas que você precisa aceitar desde o início. Ele não tem interface gráfica, então tudo é via linha de comando ou chamadas programáticas. Não tem logging estruturado — os erros vão pro stderr e você fica a mercê de ler mensagens genéricas como "processing failed at stage 3". Não há suporte a arquivos Excel com múltiplas abas, então se seu input vem de planilhas com várias sheets, você precisa separar antes. Para quem precisa de algo mais robusto e com manutenção ativa, ferramentas como o pandas com pipelines customizados ou o Apache Airflow dão muito mais controle, embora demande mais tempo de setup inicial. Se o seu uso é esporádico e os arquivos são pequenos e bem comportados, o hocus pocus goiania ainda pode valer o esforço. Se você vai rodar isso diariamente com dados sujos e volumes crescentes, é melhor migrar antes de perder tempo brigando com um tool que não recebe updates há dois anos.
O repositório continua acessível e o código-fonte está disponível pra quem quiser fazer fork e corrigir as questões que citei. Não é perfeito, mas em cenários específicos ele ainda resolve problemas que levariam muito mais tempo sendo feitos manualmente.
