Add complete type annotations for mypy strict compliance (Phase 3)

- bcb/utils.py: annotate Date comparison methods with proper parameter types
- bcb/sgs/__init__.py: fix _get_url_and_payload return type to tuple[str, dict],
  add Optional[str] for freq param, use Mapping for SGSCodeInput covariance,
  fix SGSCode.__repr__ (self.code -> self.value)
- bcb/currency.py: annotate CACHE, fix _currency_url param type, add Optional
  import, raise CurrencyNotFoundError in _get_currency_id instead of returning NaN
- bcb/odata/framework.py: annotate all classes and methods, add Self for chainable
  ODataQuery methods, add fullname attr to ODataEntitySet, use typing_extensions.Self
- bcb/odata/api.py: annotate all methods, declare BASE_URL on BaseODataAPI,
  rename K -> SERVICE_KEY on subclasses, collect() -> pd.DataFrame
- pyproject.toml: add types-requests to dev dependencies

poetry run mypy bcb/ exits with 0 errors across 9 source files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: wilsonfreitas

bcb/currency.py

@@ -2,7 +2,7 @@
 import warnings
 from datetime import date, timedelta
 from io import BytesIO, StringIO
-from typing import List, Union
+from typing import List, Optional, Union
 
 import numpy as np
 import pandas as pd
@@ -17,7 +17,7 @@
 """
 
 
-def _currency_url(currency_id: str, start_date: DateInput, end_date: DateInput) -> str:
+def _currency_url(currency_id: int, start_date: DateInput, end_date: DateInput) -> str:
     start_date = Date(start_date)
     end_date = Date(end_date)
     return (
@@ -27,7 +27,7 @@ def _currency_url(currency_id: str, start_date: DateInput, end_date: DateInput)
     )
 
 
-CACHE = dict()
+CACHE: dict[str, pd.DataFrame] = dict()
 
 
 def _currency_id_list() -> pd.DataFrame:
@@ -100,11 +100,17 @@ def _get_currency_id(symbol: str) -> int:
     id_list = _currency_id_list()
     all_currencies = get_currency_list()
     x = pd.merge(id_list, all_currencies, on=["name"])
-    return np.max(x.loc[x["symbol"] == symbol, "id"])
+    matches = x.loc[x["symbol"] == symbol, "id"]
+    if matches.empty:
+        raise CurrencyNotFoundError(f"Unknown currency symbol: {symbol}")
+    return int(matches.max())
 
 
-def _get_symbol(symbol: str, start_date: DateInput, end_date: DateInput) -> pd.DataFrame:
-    cid = _get_currency_id(symbol)
+def _get_symbol(symbol: str, start_date: DateInput, end_date: DateInput) -> Optional[pd.DataFrame]:
+    try:
+        cid = _get_currency_id(symbol)
+    except CurrencyNotFoundError:
+        return None
     url = _currency_url(cid, start_date, end_date)
     res = requests.get(url)
 

bcb/odata/api.py

@@ -1,3 +1,4 @@
+from typing import Any, Optional
 from .framework import (
     ODataEntitySet,
     ODataFunctionImport,
@@ -13,10 +14,10 @@
 
 
 class EndpointMeta(type):
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
-    def __call__(self, *args):
+    def __call__(self, *args: Any) -> Any:
         obj = super().__call__(*args)
         entity = args[0]
         if isinstance(entity, ODataEntitySet):
@@ -29,18 +30,18 @@ def __call__(self, *args):
 
 
 class EndpointQuery(ODataQuery):
-    _DATE_COLUMN_NAMES_BY_ENDPOINT = {
+    _DATE_COLUMN_NAMES_BY_ENDPOINT: dict[str, dict[str, str]] = {
         "IfDataCadastro": {"Data": "%Y%m"}
     }
-    _DATE_COLUMN_NAMES = {
+    _DATE_COLUMN_NAMES: set[str] = {
         "Data",
         "dataHoraCotacao",
         "InicioPeriodo",
         "FimPeriodo",
         "DataVigencia",
     }
 
-    def collect(self):
+    def collect(self) -> pd.DataFrame:
         raw_data = super().collect()
         data = pd.DataFrame(raw_data["value"])
         if not self._raw:
@@ -65,7 +66,7 @@ class Endpoint(metaclass=EndpointMeta):
     :py:meth:`bcb.odata.api.BaseODataAPI.get_endpoint` das classes que herdam
     :py:class:`bcb.odata.api.BaseODataAPI`.
     """
-    def __init__(self, entity, url):
+    def __init__(self, entity: Any, url: str) -> None:
         """
         Construtor da classe Endpoint.
 
@@ -80,7 +81,7 @@ def __init__(self, entity, url):
         self._entity = entity
         self._url = url
 
-    def get(self, *args, **kwargs):
+    def get(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
         """
         Executa a consulta na API OData e retorna o resultado.
 
@@ -120,7 +121,7 @@ def get(self, *args, **kwargs):
         _query.reset()
         return data
 
-    def query(self):
+    def query(self) -> EndpointQuery:
         """
         Retorna uma instância de EndpointQuery através da qual se construirá a consulta na API OData.
 
@@ -138,13 +139,15 @@ class BaseODataAPI:
     Essa classe não deve ser acessada diretamente.
     """
 
-    def __init__(self):
+    BASE_URL: str
+
+    def __init__(self) -> None:
         """
         BaseODataAPI construtor
         """
         self.service = ODataService(self.BASE_URL)
 
-    def describe(self, endpoint=None):
+    def describe(self, endpoint: Optional[str] = None) -> None:
         """
         Mostra a descrição de uma API ou de um *endpoint*
         específico.
@@ -166,7 +169,7 @@ def describe(self, endpoint=None):
         else:
             self.service.describe()
 
-    def get_endpoint(self, endpoint):
+    def get_endpoint(self, endpoint: str) -> Endpoint:
         """
         Obtem o *endpoint*
 
@@ -200,7 +203,7 @@ class ODataAPI(BaseODataAPI):
     não possuem implementação específica.
     """
 
-    def __init__(self, url):
+    def __init__(self, url: str) -> None:
         """
         Parameters
         ----------
@@ -411,8 +414,8 @@ class TarifasBancariasPorInstituicaoFinanceira(BaseODataAPI):
     cobradas por instituições financeiras, por Segmento e por Instituição.
     """
 
-    K = "Informes_ListaTarifasPorInstituicaoFinanceira"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "Informes_ListaTarifasPorInstituicaoFinanceira"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 class TarifasBancariasPorServico(BaseODataAPI):
@@ -424,8 +427,8 @@ class TarifasBancariasPorServico(BaseODataAPI):
     por serviço.
     """
 
-    K = "Informes_ListaValoresDeServicoBancario"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "Informes_ListaValoresDeServicoBancario"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 class PostosAtendimentoEletronicoPorInstituicaoFinanceira(BaseODataAPI):
@@ -437,8 +440,8 @@ class PostosAtendimentoEletronicoPorInstituicaoFinanceira(BaseODataAPI):
     pelo Banco Central.
     """
 
-    K = "Informes_PostosDeAtendimentoEletronico"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "Informes_PostosDeAtendimentoEletronico"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 class PostosAtendimentoCorrespondentesPorInstituicaoFinanceira(BaseODataAPI):
@@ -451,8 +454,8 @@ class PostosAtendimentoCorrespondentesPorInstituicaoFinanceira(BaseODataAPI):
     descrito na Resolução 3.954.
     """
 
-    K = "Informes_Correspondentes"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "Informes_Correspondentes"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 class EstatisticasSTR(BaseODataAPI):
@@ -464,8 +467,8 @@ class EstatisticasSTR(BaseODataAPI):
     mantidas pelos participantes no Banco Central.
     """
 
-    K = "STR"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "STR"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 class DinheiroCirculacao(BaseODataAPI):
@@ -478,8 +481,8 @@ class DinheiroCirculacao(BaseODataAPI):
     Real (símbolos : R$, BRL).
     """
 
-    K = "mecir_dinheiro_em_circulacao"
-    BASE_URL = f"{OLINDA_BASE_URL}/{K}/versao/v1/odata/"
+    SERVICE_KEY = "mecir_dinheiro_em_circulacao"
+    BASE_URL = f"{OLINDA_BASE_URL}/{SERVICE_KEY}/versao/v1/odata/"
 
 
 # /Informes_Ouvidorias/versao/v1/odata/