Pular para conteúdo

Pesquisa por Pregão

A seção filings_b3.search_trading_session lê os arquivos por pregão da B3, baixados de www.b3.com.br/pesquisapregao/download?filelist=…. Cada dataset é um arquivo (em geral um ZIP, às vezes contendo XML ou vários membros tabulares); um reader transforma um pregão em um pandas.DataFrame tipado, validado por contrato e com proveniência.

Veja também: Visão geral da API · Uso · Exemplos

Padrões implementados

Cada padrão ganha a sua própria página, com Descrição e Exemplos. Ao migrar um novo dataset desta seção, acrescente uma página nesta pasta e registre-a no nav: do mkdocs.yml no mesmo commit.

Duas formas de reader nesta seção

A maioria dos datasets desta seção são downloads tabulares (CSV/ZIP) e compartilham a base Template-Method _base_pregao_reader (download → localizar membro → ler → carimbar). Uma fonte que não cabe nessa forma — a família instruments_file, que é XML aninhado — usa a base _base_instruments_file_reader, que implementa o port IngestionReader diretamente, reaproveitando os mesmos seams internos (download com retry, retenção do artefato bruto, proveniência), mas achatando o XML pelo seam xml_reader em vez de ler uma tabela.

Um download, dezoito readers

O IN{aammdd}.zip traz XML em que cada registro <Instrm> aninha os seus campos específicos sob exatamente um de 20 blocos <InstrmInf>. Daí duas formas de ler o mesmo arquivo:

Quero… Reader Resultado
todos os tipos, layout publicado pela B3 InstrumentsFileReader 52 colunas, uma linha por instrumento de qualquer tipo
um tipo, com todos os campos dele InstrumentsFile<Tipo>Reader só os registros daquele bloco, com a lista completa de campos do tipo

Os readers por tipo herdam ainda as colunas de nível de registro comuns a todo instrumento (data de referência, identificação e atributos comuns), que vivem fora do bloco — é o que mantém os frames por tipo comparáveis entre si.

Qual XML de dentro do arquivo

O download é um .zip cujo único membro é outro .zip, e é esse que traz os XML — um por snapshot intradiário que a B3 publicou para o pregão (nos arquivos conferidos, um de pré-abertura e um de pós-fechamento). Os snapshots são cumulativos: no IN260729 o mais recente trazia os 183.164 instrumentos do primeiro mais 10, sem remover nenhum.

Por isso todo reader da família lê o snapshot de maior CreDtAndTm — o cabeçalho BizFileHdr de cada XML declara quando ele foi gerado. Ler qualquer outro descartaria em silêncio os registros tardios do pregão. Um snapshot sem CreDtAndTm faz o reader falhar alto, em vez de adivinhar qual é o vigente.

Download incompleto não passa por pregão pequeno

O mesmo cabeçalho declara quantos registros o snapshot carrega (TtlNbOfMsg — em ISO-20022 cada <Instrm> é uma message). Todo reader da família confere esse número contra os registros efetivamente lidos e falha alto quando eles divergem.

A conferência existe porque um download interrompido é invisível por construção: o XML é bem-formado até onde chegou, cada linha que chegou é válida, o contrato e a tipagem passam — e o frame volta menor, indistinguível de uma sessão com menos instrumentos. A contagem é feita antes do filtro de sub-bloco, então vale igual para o reader consolidado e para os dezessete por tipo, cujas linhas são um recorte do arquivo.

Todo reader tem a mesma forma pública:

Reader(date_ref: datetime.date, path_raw: pathlib.Path | None = None) -> Reader
Reader.read() -> pandas.DataFrame
Parâmetro Tipo Significado
date_ref datetime.date Pregão a ler. Obrigatório — o endpoint é endereçado por data.
path_raw pathlib.Path, opcional Diretório onde manter o artefato bruto baixado (camada bronze do datalake). None (padrão) usa um diretório temporário removido ao final.

Memória

O XML é lido em stream: cada registro é projetado e liberado em seguida, então o pico de memória acompanha as linhas mantidas, não o tamanho do arquivo. Medido contra um IN260729 real (660 MB, 183.164 registros):

Leitura Pico
um bloco pequeno (ex.: FICInf, 2 linhas) ~1,13 GB
InstrumentsFileReader (todos os 183.164 registros) ~1,86 GB

Até a 0.3.0 a árvore inteira era materializada e qualquer leitura custava ~3,0–3,6 GB — uma projeção de duas linhas pagava o arquivo todo. Ainda assim, contar com ~2 GB disponíveis é o mínimo razoável para ler este arquivo.

Colunas de proveniência

Todo DataFrame devolvido carrega, ao lado das colunas de origem, seis colunas de proveniência — url, updated_at (UTC, tz-aware), source_key, package_version, ingestion_run_id, content_hash — anexadas depois da validação de contrato, para que a camada bronze seja autodescritiva e rastreável.

Artefato bruto — path_raw

  • None (padrão) — o artefato é baixado num diretório temporário, lido e descartado.
  • Um caminho — o artefato bruto e intacto (.zip) é gravado ali e mantido, antes de qualquer parsing — os bytes exatos que uma quebra de contrato produziria ficam reproduzíveis.

Validação por contrato

Cada reader declara um FileContract (privado, em _internal/config/contracts/search_trading_session/) que fixa as colunas obrigatórias. Uma fonte que viola o contrato levanta ContractError. Colunas monetárias e quantidades são decimal.Decimal exato, nunca float binário.