Iniciando a construção da camada bronze
Olá, pessoal.
Boas-vindas de volta.
Vamos para a próxima etapa da nossa pipeline. Agora, vamos finalmente construir a nossa camada bronze. Já apresentamos um panorama sobre o repositório e sobre a infraestrutura. Agora, vamos analisar o código para compreender o que vai acontecer nesta primeira etapa.
Explorando a documentação da api do banco central
Antes de vermos o código em si, vamos mostrar a documentação. Se procurarmos no site do Banco Central, veremos a API que vamos usar. Ela trata sobre o dólar comercial, com cotação de compra e de venda. Vamos usar um endpoint que retorna a relação da cotação do dólar em uma determinada data. Existem vários outros endpoints relacionados a essa API, mas este é o que vamos usar.
Na documentação, estão listados todos os parâmetros aceitos e os parâmetros retornados. São três principais (apenas esses três, de fato): cotação compra, cotação venda e data-hora cotação. Os tipos são decimal, decimal e, no caso da data-hora, texto. Há também uma descrição breve do que acontece. Esta consulta serve para termos uma ideia do que vamos consumir nessa API.
Revisando o arquivo de configuração
Vamos voltar ao nosso repositório. Agora, vamos para onde está o código de verdade. O código deste repositório está dentro da pasta "source", "syntax pipeline". Aqui está todo o código da pipeline, fim a fim. Há também esse “quad”, sobre o qual vamos falar depois. A primeira parte do bronze está no arquivo injection pipe. Porém, antes de olharmos esse arquivo, vamos passar pelo config.py, que é um arquivo que permeia todos os outros. Ele traz algumas variáveis e constantes, que vamos examinar brevemente.
É um arquivo simples, basicamente com a definição de algumas constantes. Ele importa annotations (vamos falar mais disso quando abrirmos o arquivo principal desta aula) e importa Path para resolver o caminho de algumas constantes. Agora, veja como isso aparece no código do config:
from __future__ import annotations
from pathlib import Path
Encontramos a URL da API que estamos usando, isto é, a URL onde estarão os dados, além dos campos esperados (os mesmos que vimos na documentação: cotação compra, cotação venda e data-hora cotação). Há também o tempo de espera da requisição (REQUEST_TIMEOUT), uma configuração que define por quanto tempo vamos aguardar a resposta da API; vamos usar essa constante ao fazer a requisição. No código:
BCB_PTAX_BASE_URL = "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata"
EXPECTED_FIELDS: list[str] = [
"cotacaoCompra",
"cotacaoVenda",
"dataHoraCotacao",
]
E o tempo limite da requisição:
O arquivo define onde está a raiz do projeto, informando que está dois níveis acima no diretório. Define também onde estarão os diretórios com os dados que vamos baixar: o diretório de dados "data" e, dentro dele, as camadas "bronze", "silver" e "gold". No código, isso fica:
PROJECT_ROOT = Path(__file__).resolve().parents[2]
DATA_DIR = PROJECT_ROOT / "data"
BRONZE_DIR = DATA_DIR / "bronze"
SILVER_DIR = DATA_DIR / "silver"
GOLD_DIR = DATA_DIR / "gold"
Além disso, há configurações de atualidade dos dados (freshness) e de quantas linhas esperamos por cada resposta. Vamos usar essas configurações mais adiante, quando estivermos testando as saídas da nossa pipeline. Em resumo, é um arquivo simples, apenas com essas constantes:
FRESHNESS_SLA_DAYS = 7
MIN_EXPECTED_ROWS = 1
Implementando a ingestão na camada bronze
Agora, vamos ao conteúdo principal desta aula. Vamos passar pelo código da ingestão, que é a camada bronze. A ingestão é conhecida como camada bronze, isto é, a camada que contém os dados mais brutos. A ideia é armazenarmos os dados que vamos utilizar nas camadas seguintes da forma mais próxima possível da fonte. Caso seja necessário fazer um backfill ou um reprocessamento, não precisamos consumir a API repetidamente. Isso ajuda muito com o volume de dados e também com a estratégia de testes, permitindo chegarmos mais confiantes nas camadas acima. É isso que vamos ver aqui, e vamos percorrer o código.
Começamos com from __future__ import annotations. Isso é uma anotação para ajustar a resolução de tipagem no Python. Pode parecer complexo dependendo do quanto se utiliza tipagem em Python, mas serve para reduzir a quantidade de erros de tipagem durante a execução. Não altera a execução do código em si; trata muito mais da resolução de tipos. Esse import aparece em quase todos os arquivos, então não é motivo de preocupação: ele cuida apenas da resolução de tipagem para o Python, não é algo específico da pipeline ou do código de dados. No arquivo principal da ingestão, iniciamos assim:
from __future__ import annotations
Em seguida, entramos no que vamos de fato usar no arquivo. Vamos trabalhar com CSVs. Importamos de collections.abc alguns tipos mais complexos com os quais vamos trabalhar, como Iterable e Mapping, para explorarmos os dados que estamos recebendo. Vamos trabalhar com datetime, pois vimos que a API retorna a data. Usamos Path para trabalhar com arquivos, criação de arquivos e caminhos no repositório. Também importamos tipos como Protocol, TypedDict e cast para estruturar nossas definições de tipos, especialmente para a requisição HTTP e para compreendermos nossos dados. Esses imports ficam assim:
import csv
from collections.abc import Iterable, Mapping
from datetime import date, datetime
from pathlib import Path
from typing import Protocol, TypedDict, cast
Para consumo da API, importamos três itens relacionados à requisição HTTP: requests, HTTPAdapter e Retry, para possibilitar retentativas de requisição. Importamos também o arquivo config com algumas constantes: a BCB_PTAX_BASE_URL, o diretório de bronze, os campos esperados e o tempo de REQUEST_TIMEOUT. Essas são as constantes que vamos utilizar aqui:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
E em seguida, as constantes do config:
from config import BCB_PTAX_BASE_URL, BRONZE_DIR, EXPECTED_FIELDS, REQUEST_TIMEOUT
Criamos a classe RawRecord, que representa o retorno da API: cotação compra, cotação venda e data-hora cotação. Seguimos a documentação, atribuindo float ao que a documentação define como decimal e str ao que a documentação define como texto (no caso da data-hora):
class RawRecord(TypedDict):
cotacaoCompra: float
cotacaoVenda: float
dataHoraCotacao: str
Em seguida, criamos classes para a nossa requisição. Definimos a resposta como um Protocol que deve implementar um método json, que retorna um object, e um método raise_for_status, que não retorna nada. Essa tipagem é útil porque, ao olharmos para os tipos, conseguimos entender melhor o que acontece nos métodos e funções, sem precisar ir imediatamente à implementação. Assim, a classe de resposta deverá implementar esses dois métodos:
class Response(Protocol):
def json(self) -> object: ...
def raise_for_status(self) -> None: ...
Aqui, o HttpClient, de forma semelhante, precisará implementar o método get, que recebe uma string url, pode receber parâmetros, possui um timeout (tempo limite) que pode ser um número de ponto flutuante ou None, e retorna uma Response, que é a classe que acabamos de criar:
class HttpClient(Protocol):
def get(self, url: str, *, timeout: float | None = None) -> Response: ...
Construindo url do período da api
Partindo para a implementação concreta, a primeira função é build_period_url. Ela recebe start e end, que são duas datas, e retorna uma string. Trata-se da URL (endereço) que estamos construindo: passamos as datas e obtemos uma string com essa URL incluindo as datas:
def build_period_url(start: date, end: date) -> str:
Como o foco do curso é teste, é importante conferirmos nosso código. Queremos garantir que, para as datas que estamos passando, a data final seja maior que a data de início. Caso contrário, estaríamos começando no futuro e parando no presente ou no passado, o que não faz sentido. Se isso ocorrer, devemos lançar um ValueError informando o erro:
if end < start:
raise ValueError("end date must be after start date")
Se estiver correto, convertemos start e end para strings no formato esperado, que é o formato americano. É diferente do formato brasileiro, portanto, precisamos ter atenção:
start_str = start.strftime("%m-%d-%Y")
end_str = end.strftime("%m-%d-%Y")
O recurso da API que vamos utilizar é a cotação do dólar por período. Nele, passamos a data inicial com @dataInicial e a data final com @dataFinalCotacao. Esse “cotacao” torna o nome dos campos um pouco assimétrico (poderia ser apenas dataInicial e dataFinal), então precisamos ter cuidado para não esquecer essa parte ao escrever o código:
resource = f"CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)"
Em seguida, passamos as datas que estamos usando, definimos a data inicial e a data final com as strings que acabamos de criar e solicitamos a resposta no formato JSON (formato de dados). Por fim, retornamos a URL base somada aos parâmetros que acabamos de construir:
query = f"@dataInicial='{start_str}'&@dataFinalCotacao='{end_str}'&$format=json"
return f&
Extraindo registros do payload
Na função seguinte, recebemos um objeto payload e retornamos uma lista da classe RawRecord, que criamos anteriormente. A lógica segue a mesma ideia explicada na função anterior. Primeiro, verificamos se payload é do tipo mapping (mapeamento). Se não for, lançamos um TypeError. Depois, checamos se existe o campo value em payload. Caso exista, extraímos value de payload, pois dentro dele virão diferentes campos (como o código), mas queremos apenas value, onde estarão os dados:
def extract_records(payload: object) -> list[RawRecord]:
if not isinstance(payload, Mapping):
raise TypeError("payload must be a mapping")
if &
raise ValueError(&
Após extrair value, verificamos se ele é uma lista, pois esperamos uma lista de dados. Se não for, sinalizamos que precisa ser uma lista e geramos a exceção correspondente. Se tudo estiver de acordo, tentamos converter esse value em uma lista de objetos:
value = payload["value"]
if not isinstance(value, list):
raise TypeError(&
value &
Em seguida, começamos a iterar para extrair as informações do payload. Criamos records, que será uma lista de RawRecord. Iteramos sobre value com um laço for para extrair os campos:
records: list[RawRecord] = []
for index, record in enumerate(value):
if not isinstance(record, Mapping):
raise TypeError(f&
Dentro de cada item que percorremos, verificamos se é do tipo mapping (mapeamento); caso contrário, indicamos que está incorreto. Também checamos se todas as colunas esperadas estão presentes. A variável missing verifica se todos os campos esperados estão presentes no registro que estamos analisando. Se estiver faltando algum, informamos a ausência; caso contrário, adicionamos (append) o novo registro à lista records que estamos montando a partir da resposta do payload da API. Ao final, depois de percorrer todos os itens dentro de value extraído de payload, retornamos records já com o cast para RawRecord, no formato da classe esperada:
missing = [field for field in EXPECTED_FIELDS if field not in record]
if missing:
raise ValueError(f"record is missing fields: {missing}")
records.append(cast(RawRecord, record))
return records
Temos também um método com um sublinhado no início do nome. Isso segue uma boa prática do Python: quando for um método interno ou privado, utilizamos o sublinhado inicial (underscore (sublinhado)) para indicar que a intenção é que ele seja utilizado apenas por esse arquivo. Não precisaríamos criar _build_default_session em outros arquivos; o sublinhado serve para reforçar essa indicação.
Essa função retorna uma sessão de requisições (request session (sessão de requisições)). Faz sentido: _build_default_session retorna uma sessão. Definimos valores padrão, criamos uma sessão a partir da biblioteca requests, configuramos um retry (nova tentativa) para essa sessão, que tentará três vezes, e definimos um backoff (retardo incremental) de 0.1, isto é, aumentamos gradualmente o tempo de espera entre falhas. Definimos a lista de códigos de resposta da API que aceitaremos e indicamos que o único método com o qual queremos trabalhar é o verbo GET (verbo HTTP). Em seguida, criamos a sessão, aplicamos um HTTP adapter (adaptador HTTP) para passar a configuração de retry que acabamos de definir e, com isso, temos a sessão pronta:
def _build_default_session() -> requests.Session:
session = requests.Session()
retry = Retry(
total=3,
backoff_factor=0.1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"],
)
session.mount("https://", HTTPAdapter(max_retries=retry))
return session
Utilizando a sessão para buscar registros do período
Passamos então a utilizar essa sessão. A função fetch_period usa essa sessão. Ela recebe uma data de início, uma data final, pode receber outros parâmetros, recebe uma sessão e retorna a lista de RawRecord. Diversos elementos aqui já foram vistos anteriormente, pois estamos juntando as peças que criamos.
Primeiro, chamamos build_period_url, passando start e end. Em seguida, criamos um cliente que verifica se uma sessão existe; se não existir, chamamos _build_default_session que acabamos de ver. Esse cliente nos garante que temos uma sessão válida. Com a sessão disponível, fazemos uma requisição get à URL que criamos anteriormente, definindo o timeout (tempo limite), que é aquele definido como constante no arquivo config. Após obter a resposta, chamamos raise_for_status() para lançar uma exceção caso o código de status (código de resposta) indique erro.
Se tudo estiver correto, vamos retornar o response.json aplicado ao método que vimos anteriormente, o extract_records, que recebe o payload e realiza a extração para a lista de records existente na nossa classe RawRecord, que implementa essa mesma estrutura.
def fetch_period(start: date, end: date, *, session: HttpClient | None = None) -> list[RawRecord]:
url = build_period_url(start, end)
client: HttpClient = session if session is not None else _build_default_session()
response = client.get(url, timeout=REQUEST_TIMEOUT)
response.raise_for_status()
return extract_records(response.json())
Isso nos fornecerá a saída esperada.
Essa é a ideia do que devemos fazer na camada bronze: acessar a API (interface de programação de aplicações) e consumi-la.
Faltará apenas uma etapa adicional: salvar. Agora que estamos consumindo, precisamos fazer algo com essa informação, que é salvá-la.
Salvando dados em csv na camada bronze
Para isso, teremos o método save_bronze, que receberá os records extraídos e obterá um destination para realizarmos o salvamento.
Nesse ponto, o método verifica se esse destino existe. Se não existir, ele será criado.
Em seguida, o arquivo será aberto como CSV (valores separados por vírgula). O nome já indica que estamos utilizando o formato CSV.
Vamos criar o escritor, o objeto responsável pela escrita: DictWriter, utilizando o csvfile.
Definiremos os campos esperados conforme a documentação da API. Em seguida, escreveremos o cabeçalho e, para cada registro no nosso iterável (lista de registros), escreveremos a linha no arquivo.
Depois disso, retornaremos o destination, que é o caminho onde estamos salvando. Isso serve para retornar algo útil, pois, às vezes, executamos um código que tem apenas efeitos colaterais (efeitos paralelos) e nada aparece no terminal, o que pode gerar dúvida sobre o funcionamento. Nessas situações, retornar algo, como um print do path, pode ajudar a verificar que tudo está executando corretamente. Isso indica que o fluxo foi concluído e, ao final, o caminho foi impresso.
def save_bronze(records: Iterable[Mapping[str, object]], destination: Path) -> Path:
destination.parent.mkdir(parents=True, exist_ok=True)
with open(destination, &
writer &
writer.writeheader()
for record in records:
writer.writerow({field: record.get(field) for field in EXPECTED_FIELDS})
return destination
Orquestrando a ingestão por período
Por fim, temos o ingest_period, que simplesmente aglomera todos os métodos que acabamos de ver. Ele executará o fetch_period (já discutido acima), definirá um filename composto pela data de começo, a data de fim e a extensão .csv, construirá o destination com o caminho do diretório de saída e o filename, e chamará o save_bronze com os registros retornados por fetch_period e o destination recém-criado.
O ingest_period, portanto, apenas concatena os métodos que precisam ser executados.
def ingest_period(start: date, end: date, *, session: HttpClient | None = None) -> None:
records = fetch_period(start, end, session=session)
destination &
save_bronze(records, destination)
Isso nos fornece a camada bronze: percorremos desde o consumo da API até o salvamento dos dados localmente (ou em um servidor). Dessa forma, temos os dados salvos em uma parte do nosso fluxo de dados (pipeline), compondo essa etapa da arquitetura.
Vamos encerrar este vídeo por aqui. No próximo, vamos abordar os testes desse fluxo de dados (pipeline), referentes à primeira etapa.