| title | Documentação |
|---|---|
| author | Eric Brasil |
| date | 2022-03-05 |
Acesse o site de documentação da pyHDB aqui
Ferramenta de auxílio metodológico para pesquisa na Hemeroteca Digital Brasileira da Biblioteca Nacional.
Desenvolvida por Eric Brasil como parte de pesquisa acadêmica da área de História Digital.
Essa ferramenta não possui fins lucrativos nem pretende acessar dados sigilosos ou alterar informações nos servidores da instituição.
Tem como objetivo auxiliar pesquisadores e pesquisadoras no processo de documentação e registro preciso das etapas de pesquisa e garantir o rigor metodológico. Portanto, é uma ferramenta heurística digital.
Seu desenvolvimento está no âmbito das pesquisas realizadas no curso de História do IHLM/Unilab e do LABHDUFBA.
Os resultados da pesquisa serão publicados em artigo científico avaliado por pares na Revista História da Historiografia em 2022 e seu código e documentação serão disponibilizados publicamente, com licença MIT.
Buscamos não sobrecarregar os servidores da Biblioteca Nacional e respeitar os termos de uso.
Essa ferramenta foi escrita em Python 3.9. Esta é uma linguagem de programação que te permite trabalhar rapidamente e integrar diferentes sistemas com maior eficiência.
Para executar o arquivo .py é preciso instalar o Python3 em seu computador, assim como as bibliotecas utilizadas na ferramentas.
Clique aqui para um tutorial de instalação do Python no Windows, clique aqui para Linux e clique aqui para Mac.
Após a instalação, vc pode executar arquivos .py direto do prompt de comando do Windows ou pelo terminal do Linux, ou utilizar as diversas IDE disponíveis.
Para saber mais sobre a instalação e configuração do Python em vários sistemas operacionais, veja a lição Introdução e instalação do Python de William J. Turkel e Adam Crymble 1.
Além do Python, seu computador precisa ter o pip instalado, um programa para instalar pacotes de software. Nas versões mais recentes do Python, o pip já vem instalado. Para saber mais, veja a lição Instalação de Módulos Python com pip, de Fred Gibbs 2.
- urllib.requests: módulo do Python que lida com urls. Saiba mais.
- Selenium: o Selenium é um conjunto de ferramentas para automatização de utilização de navegadores.
- webdriver.manager: biblioteca que auxilia na instalação e configuração dos drivers de navegadores. Saiba mais
- pandas: Pandas é uma biblioteca escrita em Python para manipulação e análise de dados.
OBS 1: A ferramenta foi desenvolvida e testada no sistema operacional Linux, em distribuição baseada no Ubuntu 20.10. Entretanto, ela foi projetada para funcionar em qualquer sistema operacional que suporte o Python 3.9.
OBS 2: É necessário possuir o navegador Chrome instalado, pois este será utilizado pelo Selenium para acessar o site da HDB.
Para baixar a ferramenta para seu computador, existem duas formas. Para ambos os casos, é necessário acessar o repositório do GitHub ericbrasiln/pyHDB e clicar no botão Code.
Para baixar o arquivo pyHDB.zip, após clicar em Code, clique em Download ZIP e salve em seu computador.
Em seguida, descompacte o arquivo no local de sua preferência.
Para quem utiliza o sistema de controle de versões Git, basta clonar o repositório para seu computador, executando os comandos a partir da pasta em que deseja salvar o repositório.
git clone https://github.com/ericbrasiln/pyHDB.gitQuem utiliza o GitHub, pode também criar um fork do repositório.
Após baixar ou clonar o repositório para seu computador, acesse a pasta através do terminal ou powershell para visualizar os códigos que compõe a ferramenta:
cd <caminho para pasta>/pyHDB/srcÉ necessário instalar os requisitos (módulos e bibliotecas). Para isso, execute o comando abaixo:
$ pip3 install -r requirements.txtApós a conclusão do processo, a ferramenta estará pronta para ser utilizada.
Para iniciar a ferramenta, é preciso executar o arquivo pyHDB.py usando Python3, a partir da pasta pyHDB/src.
$ python3 pyHDB.pyAo executar o programa, o usuário verá as informações introdutórias da ferramentas, como na imagem abaixo:
Em seguida, o usuário deverá inserir os parâmetros de busca. Lembrando que nessa versão do programa, a busca inicial é estabelecida pela opção local.
1- Local
Orientações para busca:
- O termo deve ser idêntico às opções listadas na página da HDB;
- Esse parâmetro é case sensitive;
Digite o local de busca:
É possível incluir uma opção de recorte temporal em seguida.
2 - Período
Orientações para busca:
- O recorte deve ser escrito de forma idêntica às opções listadas na página da HDB;
- É possível buscar todos os periódicos digitando `Todos`
Digite o período de busca:
OBS 3: Lembrando que os parâmetros
LocalePeríododevem ser escritos de forma idêntica às opções listadas na página da HDB. Por Exemplo, se o usuários deseja buscar os periódicos existentes no Rio de Janeiro, deve colocarRJ. Se o usuário deseja buscar os periódicos existentes no Rio de Janeiro na década de 1910, deve colocar1910 - 1919, pois as opções de período existentes na HDB estão organizadas por décadas.
A busca será efetuada em todos os acervos existentes para essa configuração (3 - Periódico: Todos), após a inclusão do termo da busca.
4 - Termo da busca
Orientações para busca:
- Coloque o termo entre aspas duplas para expressões exatas;
- Não use acentos;
- Não mais que três palavras
Digite o termo de busca:
Portanto, a busca foi elaborada a partir das demandas de pesquisa e interesses pessoais e serão explicadas detalhadamente em artigo.
A partir dos parâmetros de busca definidos pelo usuário, o programa retorna todos os acervos dos jornais com alguma ocorrência, até o limite de 100 jornais (ou seja, a segunda página de resultados).
A ferramenta pyHDB permite a busca por acervos específicos, ou lista de acervos específicos. Para tanto é preciso executar o arquivo pyHDB_acervos.py.
O usuário deverá informar o número do acervo ou a lista de acervos que deseja pesquisar.
Essa opção foi desenvolvida para sanar erros no processo de raspagem que podem acontecer principalmente em buscas com milhares de ocorrências.
Se algum acervo não for raspado corretamente pela ferramenta principal pyHDB, o usuário poderá executar o arquivo pyHDB_acervos.py para raspagem de acervos específicos.
Ao final do processo, a ferramenta criará arquivos csv e relatórios em txt no mesmo padrão da ferramenta principal pyHDB. Além disso, retornará automaticamente um csv final mesclando os dados recém coletados com os dados já existentes (desde que a busca seja executada na mesma data).
O programa retorna os seguintes resultados:
-
Cria diretórios de armazenamento:
HDB/{termo da busca}/{data da busca}/ -
CSV: Cria um diretórioHDB/{termo da busca}/{data da busca}/CSVe, dentro dele, salva arquivo csv contendo os seguintes dados para cada ocorrência:Termo da busca, Data da Busca, Acervo, Ano, Edição, Página, Nome do arquivo, Link. -
RELATÓRIOS: Cria um diretórioHDB/{termo da busca}/{data da busca}/RELATÓRIOSe salva nele relatórios de busca para cada pesquisa.- GERAL: Com os dados gerais da pesquisa
O título do arquivo tem o seguinte padrão:
- Data e hora da busca - Local da busca - Período da busca - Periódico da busca: - Termo da busca - Lista de acervos com ocorrências (máx. de 100) e quantidade de ocorrências - Total de acervos com ocorrências (máx. de 100) - Informações adicionais: Total de páginas pesquisadas; Total de acervos pesquisados; Total de ocorrências e Frequência de ocorrências por página.GERAL_{termo da pesquisa}_{data e hora da busca}.txt - Acervo: Com os dados de cada acervo
O título do arquivo tem o seguinte padrão:
- Data e hora da busca - Termo da busca - Acervo - Total de ocorrências - Link da lista de resultadosrelatório_{nome do acervo}_{número do acervo}_{data e hora da busca}.txt - ERRO: registra acervos que não puderam ser raspados
O título do arquivo tem o seguinte padrão:
- Data e hora da busca - Termo da busca - Acervo com ocorrência que não pode ser acessadoERRO_{número do acervo}_{data e hora da busca}.txt - INFORMAÇÕES GERAIS: registra dados gerais relativo ao quantitativo de acervos e páginas pesquisadas na busca e a quantidade de ocorrências, assim como a frequência de ocorrências por página.
- Acervo
- Total de Páginas
- Total de Ocorrências
- Frequência de ocorrências X páginas.
O título do arquivo tem o seguinte padrão:
{infos_acervos}_{período}_{page01 ou 02}.csv
- GERAL: Com os dados gerais da pesquisa
-
ARQUIVOS_IMG: Cria um diretórioHDB/{termo da busca}/{data da busca}/ARQUIVOS_IMGe salva as imagens das páginas com ocorrências. O nome do arquivo é a combinação no número do acervo com o número geral da página. Ex:168319_02_12603.jpg
HDB
├── {termo da busca}
│ ├── {data}
│ │ ├── CSV
│ │ ├── RELATÓRIOS
│ │ ├── ARQUIVOS_IMG
Sendo a ferramenta pyHDB um scraper, um raspador de dados da internet, ela está profundamente ligada e dependente da estrutura e funcionamento do site da Hemeroteca Digital Brasileira da Biblioteca Nacional. Instabilidades no funcionamento do site da HDB afetam e prejudicam a raspagem de dados. Assim como, alterações na estrutura do site da HDB podem inviabilizar o funcionamento da ferramenta.
Portanto, erros de execução, de resultados, entre outros podem acontecer a qualquer momento. Para que a ferramenta possa continuar funcionando corretamente, o usuário deverá relatar os erros e sugestões para a equipe de desenvolvimento da ferramenta.
Sugerimos que o usuário crie issues no GitHub da ferramenta pyHDB explicando da forma mais detalhada possível os problemas e qual sistema operacional está utilizando.
É possível clicar em Cite this repository na aba à direita da página inicial do repositório no GitHub para acessar a citação nos formatos APA e BibTex, ou ainda acessar o arquivo da citação em formato .cff.
Abaixo a citação no formato BibTex:
@software{Eric_pyhdb2021,
author = {Eric Brasil},
doi = {10.5281/zenodo.5696671}
title = {pyHDB - Ferramenta heurística para a Hemeroteca Digital Brasileira},
url = {https://github.com/ericbrasiln/pyHDB}
version = {1.4}
year = {2021},
note = {Online; accessed 08 April 2022}
}
Agradeço ao LABHDUFBA pela parceria e possibilidades de aprendizado e desenvolvimento de ferramentas e reflexões para a pesquisa em história e humanidades digitais.
A pyHDB não seria possível sem a participação ativa de Leonardo F. Nascimento (a quem devo o agradecimento pela sugestão do nome da ferramenta) e Gabriel Andrade.
Copyright (c) 2021 Eric Brasil
Footnotes
-
William J. Turkel e Adam Crymble, "Introdução e instalação do Python", traduzido por Josir C. Gomes, Programming Historian em português 1 (2021), https://doi.org/10.46430/phpt0004. ↩
-
Fred Gibbs, "Instalação de Módulos Python com pip", traduzido por Felipe Lamarca, Programming Historian em português 1 (2021), https://doi.org/10.46430/phpt0018. ↩