ANBIMA Scraper

Web scraper moderno e robusto para captura de dados financeiros da ANBIMA (Associação Brasileira das Entidades dos Mercados Financeiro e de Capitais)

📋 Índice

Visão Geral
Funcionalidades
Instalação
Uso Rápido
Documentação Detalhada
Estrutura do Projeto
Contribuição
Licença

🎯 Visão Geral

O ANBIMA Scraper é uma ferramenta Python moderna e robusta para capturar dados financeiros do site da ANBIMA. O projeto foi completamente refatorado aplicando as melhores práticas de desenvolvimento, incluindo:

✅ Arquitetura orientada a objetos com classes bem estruturadas
✅ Sistema de logging robusto com diferentes níveis e outputs
✅ Tratamento de erros avançado com retry automático
✅ Interface de linha de comando (CLI) intuitiva
✅ Configuração centralizada e flexível
✅ Type hints para melhor desenvolvimento
✅ Testes automatizados (estrutura preparada)
✅ Documentação completa com docstrings

🚀 Principais Melhorias

Estrutura modular: Código organizado em módulos específicos
Reutilização: Classe base BaseScraper com funcionalidades comuns
Robustez: Cliente HTTP com retry e rotação de user agents
Flexibilidade: Configuração via arquivos e variáveis de ambiente
Monitoramento: Logs detalhados para troubleshooting
Performance: Download apenas de dados novos

📊 Funcionalidades

🎯 Scrapers Implementados

Scraper	Status	Descrição	Dados Capturados
Indicators	✅ Completo	Indicadores financeiros	SELIC, CDI, IPCA, IGP-M, Dólar, Euro, TR, TBF, FDS
IDKA	✅ Completo	Índice de Duração Constante ANBIMA	Retornos, volatilidade, taxas de juros
IMA Carteiras	🔄 Estrutura	Carteiras teóricas IMA	Composição de carteiras
IMA Quadro Resumo	🔄 Estrutura	Quadro resumo IMA	Resultados diários
Curvas de Juros	🔄 Estrutura	Curvas de juros fechamento	Curvas zero-cupom
Debêntures	🔄 Estrutura	Mercado secundário de debêntures	Taxas médias

🔧 Funcionalidades Avançadas

Verificação automática: Detecta dados existentes e baixa apenas o necessário
Processamento seguro: Limpeza automática de dados inválidos
Deduplicação: Remove registros duplicados automaticamente
Ordenação: Organiza dados por data de referência
Validação: Verifica integridade dos dados baixados
Logs estruturados: Rastreamento completo das operações

🛠️ Instalação

Pré-requisitos

Python 3.8 ou superior
pip (gerenciador de pacotes Python)

Instalação Básica

# Clone o repositório
git clone https://github.com/royopa/anbima_scraper.git
cd anbima_scraper

# Instale as dependências
pip install -r requirements.txt

Instalação em Modo Desenvolvimento

# Clone o repositório
git clone https://github.com/royopa/anbima_scraper.git
cd anbima_scraper

# Instale em modo desenvolvimento
pip install -e .

# Instale dependências de desenvolvimento
pip install -r requirements.txt

Configuração Inicial

Crie os diretórios necessários (criados automaticamente):
```
mkdir -p data/raw data/processed logs
```
Configure arquivos opcionais:
- user-agents.txt: Lista de user agents para rotação
- ANBIMA.txt: Arquivo de feriados da ANBIMA

🚀 Uso Rápido

Interface de Linha de Comando (CLI)

# Executar todos os scrapers
python -m anbima_scraper run-all

# Executar apenas indicadores
python -m anbima_scraper run indicators

# Executar múltiplos scrapers
python -m anbima_scraper run indicators idka

# Forçar atualização (mesmo se dados existirem)
python -m anbima_scraper run-all --force

# Verificar status dos scrapers
python -m anbima_scraper status

# Listar scrapers disponíveis
python -m anbima_scraper list

Uso via Python

from anbima_scraper import ANBIMAScraper

# Criar instância do scraper
scraper = ANBIMAScraper()

# Executar todos os scrapers
results = scraper.run_all()

# Executar scraper específico
success = scraper.run_scraper("indicators")

# Verificar status
status = scraper.get_scraper_status()

# Executar múltiplos scrapers
results = scraper.run_multiple(["indicators", "idka"])

Exemplo Completo

#!/usr/bin/env python3
"""
Exemplo completo de uso do ANBIMA Scraper.
"""

from anbima_scraper import ANBIMAScraper

def main():
    # Criar instância
    scraper = ANBIMAScraper()
    
    # Verificar status atual
    print("Status atual:")
    status = scraper.get_scraper_status()
    for name, last_date in status.items():
        date_str = last_date.strftime("%Y-%m-%d") if last_date else "Sem dados"
        print(f"  {name}: {date_str}")
    
    # Executar scrapers
    print("\nExecutando scrapers...")
    results = scraper.run_all()
    
    # Mostrar resultados
    print("\nResultados:")
    for name, success in results.items():
        status = "✓" if success else "✗"
        print(f"{status} {name}")

if __name__ == "__main__":
    main()

📚 Documentação Detalhada

Configuração

O projeto usa configuração centralizada em src/anbima_scraper/config/settings.py:

# URLs da ANBIMA
ANBIMA_URLS = {
    "indicators": "https://www.anbima.com.br/informacoes/indicadores/",
    "idka": "http://www.anbima.com.br/informacoes/idka/IDkA-down.asp",
    # ... outras URLs
}

# Configurações de requisição
REQUEST_SETTINGS = {
    "timeout": 30,
    "max_retries": 3,
    "retry_delay": 1,
    # ... outras configurações
}

Estrutura de Dados

Indicadores ANBIMA

data_referencia,data_captura,indice,descricao,valor
2023-12-15,2023-12-15,selic,Taxa SELIC do BC2,13.75
2023-12-15,2023-12-15,cdi,DI-CETIP3,13.65

IDKA

dt_referencia,no_indexador,no_indice,nu_indice,ret_dia_perc,ret_mes_perc,ret_ano_perc,ret_12_meses_perc,vol_aa_perc,taxa_juros_aa_perc_compra_d1,taxa_juros_aa_perc_venda_d0
2023-12-15,Prefixado,IDkA-P,1234.56,0.12,2.34,15.67,18.90,8.45,13.50,13.60

Logs

O sistema gera logs estruturados em logs/anbima_scraper.log:

2023-12-15 10:30:15 [INFO] anbima_scraper.core.anbima_scraper: Starting ANBIMA scraper for all data sources
2023-12-15 10:30:16 [INFO] anbima_scraper.scrapers.indicators: Scraping ANBIMA indicators
2023-12-15 10:30:18 [INFO] anbima_scraper.scrapers.indicators: Indicators data updated successfully

🏗️ Estrutura do Projeto

anbima_scraper/
├── src/anbima_scraper/          # Código fonte principal
│   ├── __init__.py              # Exports principais
│   ├── cli.py                   # Interface de linha de comando
│   ├── core/                    # Funcionalidades centrais
│   │   ├── __init__.py
│   │   ├── anbima_scraper.py    # Classe principal
│   │   └── scraper.py           # Classe base
│   ├── scrapers/                # Scrapers específicos
│   │   ├── __init__.py
│   │   ├── indicators.py        # Indicadores ANBIMA
│   │   ├── idka.py             # IDKA
│   │   ├── ima.py              # IMA
│   │   ├── curves.py           # Curvas de juros
│   │   └── debentures.py       # Debêntures
│   ├── utils/                   # Utilitários
│   │   ├── __init__.py
│   │   ├── http_client.py      # Cliente HTTP
│   │   ├── calendar.py         # Utilitários de calendário
│   │   └── data_processor.py   # Processamento de dados
│   └── config/                  # Configurações
│       ├── __init__.py
│       └── settings.py         # Configurações centralizadas
├── data/                        # Dados processados
│   ├── raw/                     # Dados brutos
│   └── processed/               # Dados processados
├── tests/                       # Testes
│   ├── __init__.py
│   └── test_indicators.py      # Testes dos indicadores
├── examples/                    # Exemplos de uso
│   └── basic_usage.py          # Exemplo básico
├── logs/                        # Logs do sistema
├── pyproject.toml              # Configuração do projeto
├── requirements.txt            # Dependências
├── .pre-commit-config.yaml    # Hooks de pre-commit
├── .gitignore                 # Arquivos ignorados
└── README.md                  # Este arquivo

Arquitetura

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Module    │    │  Python API     │    │  Configuration  │
│                 │    │                 │    │                 │
│  run-all        │    │  ANBIMAScraper  │    │  settings.py    │
│  run            │    │  run_all()      │    │  URLs           │
│  status         │    │  run_scraper()  │    │  Settings       │
│  list           │    │  get_status()   │    │  Logging        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Base Scraper   │
                    │                 │
                    │  BaseScraper    │
                    │  - HTTP Client  │
                    │  - Calendar     │
                    │  - Data Proc    │
                    └─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Indicators     │    │     IDKA        │    │     Others      │
│                 │    │                 │    │                 │
│  - SELIC        │    │  - Returns      │    │  - IMA          │
│  - CDI          │    │  - Volatility   │    │  - Curves       │
│  - IPCA         │    │  - Rates        │    │  - Debentures   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🧪 Testes

Executar Testes

# Executar todos os testes
pytest

# Executar com cobertura
pytest --cov=anbima_scraper

# Executar testes específicos
pytest tests/test_indicators.py

# Executar com verbose
pytest -v

Estrutura de Testes

# Exemplo de teste
def test_map_indicator_selic(scraper):
    """Test SELIC indicator mapping."""
    result = scraper._map_indicator("Taxa SELIC do BC2", "Descrição")
    assert result == "selic"

🔧 Desenvolvimento

Configuração do Ambiente

# Instalar pre-commit hooks
pre-commit install

# Formatar código
black src/ tests/

# Verificar imports
isort src/ tests/

# Verificar tipos
mypy src/

# Verificar linting
flake8 src/ tests/

Adicionando Novos Scrapers

Criar classe do scraper:

from ..core.scraper import BaseScraper

class NewScraper(BaseScraper):
    def __init__(self):
        super().__init__("new_scraper")
    
    def scrape(self, start_date=None, end_date=None):
        # Implementar lógica do scraper
        pass

Adicionar configurações:

# Em settings.py
ANBIMA_URLS["new_scraper"] = "https://anbima.com.br/new-endpoint"
FILE_PATHS["new_scraper"] = PROCESSED_DATA_DIR / "new_scraper.csv"

Registrar no scraper principal:

# Em anbima_scraper.py
self.scrapers["new_scraper"] = NewScraper()

📈 Monitoramento e Logs

Níveis de Log

DEBUG: Informações detalhadas para desenvolvimento
INFO: Informações gerais sobre operações
WARNING: Avisos sobre situações não críticas
ERROR: Erros que impedem operação normal

Exemplo de Logs

2023-12-15 10:30:15 [INFO] anbima_scraper.core.anbima_scraper: Starting ANBIMA scraper for all data sources
2023-12-15 10:30:16 [INFO] anbima_scraper.scrapers.indicators: Scraping ANBIMA indicators
2023-12-15 10:30:17 [DEBUG] anbima_scraper.utils.http_client: Making GET request to: https://www.anbima.com.br/informacoes/indicadores/
2023-12-15 10:30:18 [INFO] anbima_scraper.utils.http_client: Request successful: 200
2023-12-15 10:30:19 [INFO] anbima_scraper.scrapers.indicators: Fetched indicators data: 25 rows
2023-12-15 10:30:20 [INFO] anbima_scraper.scrapers.indicators: Processed indicators data: 25 rows
2023-12-15 10:30:21 [INFO] anbima_scraper.scrapers.indicators: Indicators data updated successfully

🚨 Troubleshooting

Problemas Comuns

1. Erro de Conexão

Error: Request failed: Connection timeout

Solução: Verificar conectividade com internet e configurações de proxy.

2. Dados Não Atualizados

No new data to download

Solução: Usar flag --force para forçar atualização.

3. Erro de Permissão

Permission denied: logs/anbima_scraper.log

Solução: Verificar permissões do diretório logs/.

4. Dependências Ausentes

ModuleNotFoundError: No module named 'pandas'

Solução: Instalar dependências com pip install -r requirements.txt.

Logs de Debug

Para obter mais informações sobre problemas:

import logging
logging.getLogger('anbima_scraper').setLevel(logging.DEBUG)

🤝 Contribuição

Como Contribuir

Fork o projeto
Clone seu fork
Crie uma branch para sua feature
Implemente suas mudanças
Adicione testes
Execute os testes
Commit suas mudanças
Push para sua branch
Abra um Pull Request

Padrões de Código

Use Black para formatação
Use isort para organização de imports
Use flake8 para linting
Use mypy para type checking
Adicione docstrings para todas as funções
Escreva testes para novas funcionalidades

Checklist de Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

ANBIMA por disponibilizar os dados financeiros
Comunidade Python pelas ferramentas e bibliotecas
Contribuidores que ajudaram a melhorar o projeto

📞 Suporte

Issues: GitHub Issues
Documentação: Este README e docstrings no código
Email: royopa@gmail.com

⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.vscode		.vscode
bases		bases
examples		examples
notebooks		notebooks
src/anbima_scraper		src/anbima_scraper
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.travis.yml		.travis.yml
ANBIMA.txt		ANBIMA.txt
README.md		README.md
curva_juros_fechamento.py		curva_juros_fechamento.py
debentures_mercado_secundario.py		debentures_mercado_secundario.py
idka.py		idka.py
ima_carteiras.py		ima_carteiras.py
ima_quadro_resumo.py		ima_quadro_resumo.py
indicadores_anbima.py		indicadores_anbima.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
titulos_publicos_mercado_secundario.py		titulos_publicos_mercado_secundario.py
user-agents.txt		user-agents.txt
utils.py		utils.py

Folders and files

Latest commit

History

Repository files navigation

ANBIMA Scraper

📋 Índice

🎯 Visão Geral

🚀 Principais Melhorias

📊 Funcionalidades

🎯 Scrapers Implementados

🔧 Funcionalidades Avançadas

🛠️ Instalação

Pré-requisitos

Instalação Básica

Instalação em Modo Desenvolvimento

Configuração Inicial

🚀 Uso Rápido

Interface de Linha de Comando (CLI)

Uso via Python

Exemplo Completo

📚 Documentação Detalhada

Configuração

Estrutura de Dados

Indicadores ANBIMA

IDKA

Logs

🏗️ Estrutura do Projeto

Arquitetura

🧪 Testes

Executar Testes

Estrutura de Testes

🔧 Desenvolvimento

Configuração do Ambiente

Adicionando Novos Scrapers

📈 Monitoramento e Logs

Níveis de Log

Exemplo de Logs

🚨 Troubleshooting

Problemas Comuns

1. Erro de Conexão

2. Dados Não Atualizados

3. Erro de Permissão

4. Dependências Ausentes

Logs de Debug

🤝 Contribuição

Como Contribuir

Padrões de Código

Checklist de Pull Request

📄 Licença

🙏 Agradecimentos

📞 Suporte

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages