CINEMA EM POA

CINEMA EM POA é um portal agregador de filmes das casas de cinema de Porto Alegre.

Está rodando em https://cinemaempoa.com.br.

O conteúdo é agregado realizando web scrapping em quatro diferentes sites:

• CineBancários
• Cinemateca Paulo Amorim
• Cinemateca Capitólio
• Sala Redenção

O projeto encoraja contribuições (veja Contribuições).

Desenvolvimento

O projeto é composto de dois módulos: scrapers/, que contém a lógica para coleção de dados e flask_backend/, onde fica o código do portal.

Este projeto requer Python 3.10.x ou 3.11.x. Versões superiores não são suportadas no momento. Recomendamos utilizar a série 3.10 (por exemplo, 3.10.19).

O banco de dados utilizado é o sqlite3.

Instalando o projeto localmente

A instalação recomendada é usando um ambiente virtual (venv).

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

Instalando o projeto usando Docker

Você pode usar o arquivo docker-compose.dev.yml para iniciar um container com todas as dependências necessárias.

docker compose -f docker-compose.dev.yml up -d

Ao utilizar o docker, os comandos mencionados na seção seguinte devem ser rodados de dentro do container.

# utilize o `docker exec` para abrir um terminal dentro do container
docker exec -it cinemaempoa_flask_dev bash

Antes de abrir um Pull Request, rode os comandos abaixo no seu terminal para validar e formatar o código:

ruff check --fix # roda o linter para código python
ruff format # roda o formatter para código python
djlint flask_backend/templates --lint --profile=jinja # roda o linter para os arquivos .html
djlint --reformat flask_backend/templates --format-css --format-js # roda o formatter para os arquivos .html

Opcionalmente, o pre-commit pode automatizar a formatação do código quando você rodar um git commit.

Para utilizá-lo, instale com:

pre-commit install

Rodando o projeto

Para rodar o portal, você vai precisar de três comandos (todos rodados a partir da raíz do projeto):

flask --app flask_backend init-db # inicializa as tabelas no banco de dados
flask --app flask_backend seed-db # optional: popula o banco com dados iniciais
flask --app flask_backend run --debug # inicia o projeto em modo desenvolvimento

Lembre-se de utilizar a flag --host=0.0.0.0 caso esteja rodando o projeto através do docker de desenvolvimento (docker-compose.dev.yml).

O projeto vai rodar em http://localhost:5000.

Nota para usuários macOS: Se você estiver usando macOS e encontrar um erro 403 ao reiniciar a aplicação, a porta 5000 pode estar sendo usada pelo AirPlay Receiver. Nesse caso, use uma porta alternativa:

flask --app flask_backend run --debug --port=5001

Se você rodou o comando para popular o banco de dados, vai ter um usuário admin criado com login: cinemaempoa e senha: 123123.

Você pode fazer login via http://localhost:5000/auth/login.

Migrações do Banco de Dados

O projeto utiliza Alembic para gerenciar migrações do banco de dados. Isso permite que alterações no schema sejam versionadas e aplicadas de forma controlada.

Comandos disponíveis:

• flask --app flask_backend init-db - Aplica todas as migrações pendentes (inicializa ou atualiza o banco)
• flask --app flask_backend db-upgrade [revision] - Aplica migrações até uma revisão específica (padrão: head)
• flask --app flask_backend db-downgrade [revision] - Reverte migrações até uma revisão específica
• flask --app flask_backend db-revision --autogenerate -m "mensagem" - Cria uma nova migração automaticamente baseada nas mudanças nos modelos
• flask --app flask_backend db-current - Mostra a revisão atual do banco de dados
• flask --app flask_backend db-history - Mostra o histórico de migrações

Criando uma nova migração:

Quando você modificar os modelos em flask_backend/models.py, crie uma nova migração:

flask --app flask_backend db-revision --autogenerate -m "Descrição da mudança"

Utilizando os scrappers

Os scrappers podem ser disparados através da interface web na URL http://127.0.0.1:5000/screening/import, clicando no botão "Fazer Scrapping dos cinemas selecionados".

Alternativamente, os scrappers também podem ser rodados via linha de comandos, com o script

./cinemaempoa.py -h

usage: cinemaempoa [-h] -r ROOMS [ROOMS ...]

Extrai os horários das salas de cinema de Porto Alegre em formato JSON utilizando webscrapping.

options:
-h, --help            show this help message and exit
-r ROOMS [ROOMS ...], --rooms ROOMS [ROOMS ...]
                        Define as salas de cinemas para extração dos horários de exibição. Opções: capitolio, sala-redencao, cinebancarios, paulo-amorim

Para disparar os scrappers e conseguir os filmes em cartaz em formato json (que pode ser importado no portal), rode o comando com a flag r, listando as salas de cinema desejadas, e direcione a saída para um arquivo.

./cinemaempoa.py -r capitolio sala-redencao cinebancarios paulo-amorim > import.json

Você pode inspecionar o arquivo import.json resultante para entender melhor a estrutura de saída dos scrappers.

Importando dados no portal

Caso você tenha rodado os scrappers via linha de comando, você vai precisar importar o arquivo .json resultante no portal.

Após logar, vá para a página http://localhost:5000/screening/import.

Lá, selecione o arquivo gerado na etapa anterior e clique em Enviar.

As sessões importadas vão estar disponíveis na home.

Importando dados pela linha de comandos

Uma alternativa a importação via portal é utilizando a linha de comando.

Dentro do seu ambiente, rode o seguinte comando:

flask --app flask_backend import-json /caminho/ate/o/arquivo.json

Testes automatizados

O projeto possui alguns (poucos) testes automatizados. Certifique-se de que eles estão atualizados e passando sempre que você fizer alguma modificação no código.

Testes do portal

Veja o README dos testes do portal.

Testes dos scrappers

Veja os testes em ./tests.

Contribuições

Veja nossos issues pra entender o que está sendo feito no projeto.

Implementações mais simples estão marcadas com good first issue.

Deploy (produção)

Atualmente o projeto (em https://cinemaempoa.com.br) está hospedado em uma máquina virtual.

Os arquivos usados para o deployment são:

• .env (deve ser criado a partir do example.env).
• docker-compose.production.yml
• Dockerfile.prod

A cada novo merge no branch principal, o workflow em .github/workflows/deploy-server.yml faz o processo de atualização do servidor.

Backups do banco de dados

Diariamente uma cópia do banco de dados é enviada para o google drive em https://drive.google.com/drive/u/0/folders/1f9qFHb2Fxdg_EGg3Vq4W-leDaGed9kXk.

O processo é automatizado pelo script backup-db.sh em um cronjob na máquina virtual.

$ crontab -l
55 23 * * * cd /home/ubuntu/cinemaempoa && ./backup-db.sh