diff --git a/.github/ISSUE_TEMPLATE/revisao_retroativa.yaml b/.github/ISSUE_TEMPLATE/revisao_retroativa.yaml index 220227651..c8469def7 100644 --- a/.github/ISSUE_TEMPLATE/revisao_retroativa.yaml +++ b/.github/ISSUE_TEMPLATE/revisao_retroativa.yaml @@ -1,6 +1,6 @@ name: Revisão retroativa description: Dar manutenção em código legado de raspadores no repositório -title: "[Revisão retroativa]: Raspador de " +title: "[Revisão retroativa]: " labels: ["refactor"] body: - type: dropdown @@ -10,7 +10,7 @@ body: description: Selecione a opção abaixo multiple: false options: - - Neste repositório, há muitos códigos de raspadores que foram desenvolvidos no começo do projeto e não estão sendo usados. Para passar a usar o raspador deste município, é necessário testar para verificar se segue funcionando e revisá-lo caso não esteja. + - Neste repositório, há muitos códigos de raspadores que foram desenvolvidos no começo do projeto e não estão sendo usados. Para passar a usar o raspador deste município, é necessário testar para verificar se segue funcionando e revisá-lo caso não esteja. Consulte a documentação para te ajudar. validations: required: true - type: input @@ -39,10 +39,3 @@ body: placeholder: ex. mês/ano até atualmente; de 2016 à 2020 validations: required: true - - type: textarea - id: test-list - attributes: - label: Lista de testes - description: "Utilize a lista a seguir de referência para teste. O raspador precisa atender todos os itens para estar pronto para ser usado. \n 1. [ ] Você executou uma extração completa do spider localmente e os dados retornados estavam corretos.\n 2. [ ] Você executou uma extração por período (start_date e end_date definidos) ao menos uma vez e os dados retornados estavam corretos. \n 3. [ ] Você verificou que não existe nenhum erro nos logs (log/ERROR igual a zero).\n 4. [ ] Você definiu o atributo de classe start_date no seu spider com a data do Diário Oficial mais antigo disponível na página da cidade.\n 5. [ ] Você garantiu que todos os campos que poderiam ser extraídos foram extraídos de acordo com a documentação. \n \n Por favor, inclua qualquer informação relevante para o desenvolvimento." - validations: - required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f4b8350e3..f810e0b59 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,12 +1,27 @@ -**AO ABRIR** um Pull Request de um novo raspador (spider), marque com um `X` cada um dos items do checklist -abaixo. **NÃO ABRA** um novo Pull Request antes de completar todos os items abaixo. - -#### Checklist - Novo spider -- [ ] Você executou uma extração completa do spider localmente e os dados retornados estavam corretos. -- [ ] Você executou uma extração por período (`start_date` e `end_date` definidos) ao menos uma vez e os dados retornados estavam corretos. -- [ ] Você verificou que não existe nenhum erro nos logs (`log_count/ERROR` igual a zero). -- [ ] Você definiu o atributo de classe `start_date` no seu spider com a data do Diário Oficial mais antigo disponível na página da cidade. -- [ ] Você garantiu que todos os campos que poderiam ser extraídos foram extraídos [de acordo com a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/escrevendo-um-novo-spider.html#definicao-de-campos). +**AO ABRIR** uma *Pull Request* de um novo raspador (*spider*), marque com um `X` cada um dos items da checklist abaixo. Caso algum item não seja marcado, JUSTIFIQUE o motivo. + +#### Layout do site publicador de diários oficiais +Marque apenas um dos itens a seguir: +- [ ] O *layout* não se parece com nenhum caso [da lista de *layouts* padrão](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/lista-sistemas-replicaveis.html) +- [ ] É um *layout* padrão e esta PR adiciona a spider base do padrão ao projeto junto com alguns municípios que fazem parte do padrão. +- [ ] É um *layout* padrão e todos os municípios adicionados usam a [classe de spider base](https://github.com/okfn-brasil/querido-diario/tree/main/data_collection/gazette/spiders/base) adequada para o padrão. + +#### Código da(s) spider(s) +- [ ] O(s) raspador(es) adicionado(s) tem os [atributos de classe exigidos](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider). +- [ ] O(s) raspador(es) adicionado(s) cria(m) objetos do tipo Gazette coletando todos [os metadados necessários](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#Gazette). +- [ ] O atributo de classe [start_date](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider.start_date) foi preenchido com a data da edição de diário oficial mais antiga disponível no site. +- [ ] Explicitar o atributo de classe [end_date](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider.end_date) não se fez necessário. +- [ ] Não utilizo `custom_settings` em meu raspador. + +#### Testes +- [ ] Uma coleta-teste **da última edição** foi feita. O arquivo de `.log` deste teste está anexado na PR. +- [ ] Uma coleta-teste **por intervalo arbitrário** foi feita. Os arquivos de `.log`e `.csv` deste teste estão anexados na PR. +- [ ] Uma coleta-teste **completa** foi feita. Os arquivos de `.log` e `.csv` deste teste estão anexados na PR. + +#### Verificações +- [ ] Eu experimentei abrir alguns arquivos de diários oficiais coletados pelo meu raspador e verifiquei eles [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#diarios-oficiais-coletados) não encontrando problemas. +- [ ] Eu verifiquei os arquivos `.csv` gerados pela minha coleta [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#arquivos-auxiliares) não encontrando problemas. +- [ ] Eu verifiquei os arquivos de `.log` gerados pela minha coleta [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#arquivos-auxiliares) não encontrando problemas. #### Descrição diff --git a/data_collection/gazette/settings.py b/data_collection/gazette/settings.py index 7f951e418..ef7cf28aa 100644 --- a/data_collection/gazette/settings.py +++ b/data_collection/gazette/settings.py @@ -16,6 +16,8 @@ "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:108.0) Gecko/20100101 Firefox/108.0" ) +TEMPLATES_DIR = "templates" + DOWNLOAD_TIMEOUT = 360 FILES_STORE = config("FILES_STORE", default="data") diff --git a/data_collection/templates/spiders/qdtemplate.tmpl b/data_collection/templates/spiders/qdtemplate.tmpl new file mode 100644 index 000000000..c32b4a132 --- /dev/null +++ b/data_collection/templates/spiders/qdtemplate.tmpl @@ -0,0 +1,29 @@ +from datetime import date + +from gazette.items import Gazette +from gazette.spiders.base import BaseGazetteSpider + +class UFMunicipioSpider(BaseGazetteSpider): + name = "$name" + TERRITORY_ID = "" + allowed_domains = ["$domain"] + start_urls = ["$url"] + start_date = date() + + def parse(self, response): + # Lógica de extração de metadados + + # partindo de response ... + # + # ... o que deve ser feito para coletar DATA DO DIÁRIO? + # ... o que deve ser feito para coletar NÚMERO DA EDIÇÃO? + # ... o que deve ser feito para coletar se a EDIÇÃO É EXTRA? + # ... o que deve ser feito para coletar a URL DE DOWNLOAD do arquivo? + + yield Gazette( + date = date(), + edition_number = "", + is_extra_edition = False, + file_urls = [""], + power = "executive", + ) \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4a068ade7..958cafc03 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,10 +4,12 @@ O Querido Diário possui um [Guia para Contribuição](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#contribuindo) principal que é relevante para todos os seus repositórios. Este guia traz informações gerais sobre como interagir com o projeto, o código de conduta que você adere ao contribuir, a lista de repositórios do ecossistema e as primeiras ações que você pode tomar. Recomendamos sua leitura antes de continuar. Já leu? Então vamos às informações específicas deste repositório: -- [Contribuindo](#contribuindo) - - [Desafios](#desafios) - - [Metas do Repositório](#metas-do-repositório) - - [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento) +- [Desafios](#desafios) +- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento) +- [Desafios](#desafios) + - [Labels](#labels) + - [Metas do Repositório](#metas-do-repositório) +- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento) - [Em Linux](#em-linux) - [Em Windows](#em-windows) - [Formatação automática de código](#formação-automática-de-código) @@ -17,12 +19,17 @@ Já leu? Então vamos às informações específicas deste repositório: ## Desafios O principal desafio deste repositório é ter cada vez mais raspadores de sites publicadores de diários oficiais, visando atingir os 5570 municípios brasileiros. Utilizamos o [Quadro de Expansão de Cidades](https://github.com/orgs/okfn-brasil/projects/12/views/13) para organizar o progresso do desafio. Consulte-o para localizar tarefas relevantes com as quais você pode contribuir. -Para te ajudar a desenvolver, utilize as orientações da página sobre [como escrever um novo raspador](https://docs.queridodiario.ok.org.br/pt-br/latest/escrevendo-um-novo-spider.html) disponível na [documentação técnica do Querido Diário](https://docs.queridodiario.ok.org.br/pt-br/latest/). +Para te ajudar a desenvolver, utilize as orientações da página ["contrbuindo com raspadores"](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#contribuindo-com-raspadores) disponível na [documentação técnica do Querido Diário](https://docs.queridodiario.ok.org.br/). -## Metas do Repositório +### Labels +As issues são marcadas com etiquetas, um recurso que serve para classificar issues de mesmo tipo, sinalizar se há algum empecilho ou direcionar a comunidade para tarefas mais do perfil delas. No geral, adotamos *labels* comuns a outros projetos de código aberto como "docs", "bug", "dependencies", mas também temos algumas específicas. Veja quais são na seção de [labels](https://github.com/okfn-brasil/querido-diario/labels) + + +### Metas do Repositório Para garantir que nossos esforços estejam alinhados e focados em objetivos claros, definimos metas para o desenvolvimento e expansão do projeto. Estas metas são revisadas e atualizadas regularmente, refletindo as prioridades e os desafios que enfrentamos. Convidamos as pessoas contribuidoras a se familiarizarem com estas metas, disponíveis em nosso [Quadro de Metas](https://github.com/okfn-brasil/querido-diario/milestones). Sua contribuição pode ser ainda mais valiosa quando alinhada com estas direções. + ## Como configurar o ambiente de desenvolvimento Os raspadores são desenvolvidos usando [Python](https://docs.python.org/3/) e o framework [Scrapy](https://scrapy.org). Você pode conferir [como instalar Python](https://www.python.org/downloads/) em seu sistema operacional e conhecer mais sobre o Scrapy [neste tutorial](https://docs.scrapy.org/en/latest/intro/tutorial.html). Com Python em seu computador, siga o passo-a-passo da configuração do ambiente de desenvolvimento: diff --git a/docs/README.md b/docs/README.md index 8cddd0eeb..cffd41a02 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,6 +13,7 @@ Conheça mais sobre as [tecnologias](https://queridodiario.ok.org.br/tecnologia) # Sumário - [Como contribuir](#como-contribuir) - [Ambiente de desenvolvimento](#ambiente-de-desenvolvimento) +- [Template para raspadores](#template-para-raspadores) - [Como executar](#como-executar) - [Dicas de execução](#dicas-de-execução) - [Solução de problemas](#solução-de-problemas) @@ -48,6 +49,21 @@ pre-commit install > A configuração em outros sistemas operacionais está disponível em ["como configurar o ambiente de desenvolvimento"](/docs/CONTRIBUTING.md#como-configurar-o-ambiente-de-desenvolvimento), incluindo mais detalhes para quem deseja contribuir com o desenvolvimento do repositório. +# Template para raspadores + +Ao invés de começar um arquivo de raspador do zero, você pode inicializar um arquivo de código de raspador já no padrão do Querido Diário, a partir de um template. Para isso, faça: + +1. Vá para o diretório `data_collection`: +```console +cd data_collection +``` +2. Acione o template: +```console +scrapy genspider -t qdtemplate +``` + +Um arquivo `uf_nome_do_municipio.py` será criado no diretório `spiders`, com alguns campos já preenchidos. O diretório é organizado por UF, lembre-se de mover o arquivo para o diretório adequado. + # Como executar Para experimentar a execução de um raspador já integrado ao projeto ou testar o que esteja desenvolvendo, siga os comandos: