[EPIC] Realizar atualização das dependências

[robertatakenaka]

Descrição da tarefa

Realizar atualização das dependências.

[Épico] Atualização de dependências do opac_5

Contexto

O requirements.txt do opac_5 está com defasagem significativa em pacotes-chave (Flask 2.2, SQLAlchemy 1.4, Werkzeug 2.2, redis 4.x — alguns com 4+ anos de atraso). Este épico organiza a atualização em ondas, separando o que é seguro em lote do que exige migração dedicada.

Levantamento completo de versões (atual vs. mais recente no PyPI) e notas de breaking changes: ver comentário fixado / anexo guia_atualizacao_dependencias_opac5.md.

Não fazer tudo num PR só. Cada onda abaixo deve virar um PR próprio, com deploy em homologação e validação antes de avançar para a próxima.

---

Checklist geral

🔧 Preparação

• Rodar e corrigir todos os testes
• Confirmar versão de Python alvo em produção/homologação (vários pacotes novos exigem >=3.9 ou >=3.11)
• pip freeze > requirements.lock.old.txt como snapshot de rollback
• Criar branch test/fix-and-expand-test-suite
• Mapear no código usos de: flask._app_ctx_stack, werkzeug.urls.* (url_quote/url_encode/safe_join), Image.ANTIALIAS, Query legado do SQLAlchemy, chamadas diretas de baixo nível ao urllib3

🟢 Onda 1 — Baixo risco (lote único)

Patch/minor sem mudança de API relevante — subir todos juntos e rodar suíte de testes.

• Atualizar em lote: arrow, Babel, beautifulsoup4, blinker, cachelib, charset-normalizer, citeproc-py, citeproc-py-styles, click, dnspython, elastic-apm, feedparser, feedwerk, filelock, Flask-Caching, Flask-Login, Flask-Mail, Flask-WTF, idna, itsdangerous, Mako, natsort, oauthlib, pluggy, pyproject_api, python-dateutil, requests, six, soupsieve, tox, tweepy, Unidecode, WTForms, XlsxWriter, PyJWT
• colorama, cssmin, htmlmin, Flask-Principal, legendarium, passlib, picles.plumber, PySocks, text-unidecode — já estão na última versão, só confirmar
• Rodar suíte de testes automatizados
• Deploy em homologação + smoke test

🟡 Onda 2 — Médio risco (major bump, baixo acoplamento)

Major version bump mas isolado — subir em lote e validar com smoke test manual.

• Atualizar em lote: async-timeout, cachetools, certifi, chardet, croniter, email-validator, Flask-HTMLmin, Flask-Migrate, lxml, MarkupSafe, packaging, pbr, platformdirs, python-slugify, pytz, requests-oauthlib, virtualenv, wrapt, zope.event, zope.interface, tenacity
• Rodar suíte de testes automatizados
• Deploy em homologação + smoke test manual (atenção especial a Flask-Migrate e email-validator, que tocam fluxo de dados)

🔴 Onda 3 — Alto risco (uma issue por bloco, não por pacote)

• #issue: Flask + Werkzeug + Jinja2 (2.2→3.1 / 2.2→3.1 / 3.0→3.1) — subir os três juntos
• #issue: Flask-Admin (1.6.0→2.2.0) — depende do bloco anterior já estar em Flask 3.x
• #issue: Flask-BabelEx → Flask-Babel — migração (BabelEx está abandonado e incompatível com Flask 3.x)
• #issue: SQLAlchemy 2.0 (SQLAlchemy, Flask-SQLAlchemy, SQLAlchemy-Utils, alembic) — ativar SQLALCHEMY_WARN_20=1 na versão atual antes de migrar
• #issue: flask-mongoengine-3 — testar queries principais após bump (versão mais nova do flask-mongoengine)
• #issue: redis → rq → rq-dashboard/rq-scheduler(-dashboard) — checar antes se rq-scheduler-dashboard (parado em 0.0.2) suporta RQ 2.x
• #issue: Pillow (9.4→12.3) — checar uso de Image.ANTIALIAS (removido, usar LANCZOS)
• #issue: gevent + greenlet + gunicorn — validar worker class gevent em produção após bump
• #issue: urllib3 (1.26→2.7) — checar uso direto de API de baixo nível (via requests é transparente)

⚫ Remover / substituir (não atualizar, trocar)

• Flask-Script → usar flask.cli nativo (@app.cli.command())
• raven → migrar para sentry-sdk
• speaklater → remove sozinho ao migrar Flask-BabelEx → Flask-Babel
• python-editor → verificar se ainda é puxado como dependência transitiva de alembic; remover se não
• unicodecsv → avaliar remoção (csv nativo do Python 3 já lida com unicode)

✅ Fechamento

• Atualizar requirements.txt final
• Documentar no README/CHANGELOG as decisões de versão (o que ficou para trás e por quê)
• Remover requirements.lock.old.txt de backup após validação em produção

---

Sub-issues sugeridas (uma por bloco de alto risco)

Ao quebrar este épico, sugiro criar uma issue filha para cada item da seção 🔴 Onda 3 e para o bloco ⚫ Remover/substituir, referenciando esta issue como épico (Parte de #<número-deste-épico>).

Labels sugeridas

dependencies, tech-debt, epic

Referências

• Levantamento completo de versões e notas de breaking changes por pacote:
  https://docs.google.com/document/d/1HQ3wRbFlOzEaWRnmrdEHWyQEil6adegC2nsdBh9be94/edit?tab=t.0#heading=h.dsw8tncrfl8k