bb_api 0.5.2__tar.gz → 0.5.4__tar.gz

{bb_api-0.5.2 → bb_api-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.2
+Version: 0.5.4
 Summary: Wrapper da API do Banco do Brasil.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{bb_api-0.5.2 → bb_api-0.5.4}/bb_api/__init__.py

@@ -4,7 +4,7 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("bb_api")
 except PackageNotFoundError:
-    __version__ = "0.5.2"
+    __version__ = "0.5.4"
 
 
 from .common import Ambiente
@@ -14,6 +14,7 @@ from .accountability import (
     AccountabilityV3ControleAPI,
     ExtratoError,
     IntervaloLongoDemaisError,
+    RespostaError,
     SemLancamentosError,
 )
 from .sia import (
@@ -36,6 +37,7 @@ __all__ = [
     "CredenciaisNecessariasError",
     "ExtratoError",
     "IntervaloLongoDemaisError",
+    "RespostaError",
     "SemLancamentosError",
     "FalhaDownload",
     "ResultadoDownloads",

{bb_api-0.5.2 → bb_api-0.5.4}/bb_api/accountability.py

@@ -23,23 +23,34 @@ _STATUS_SEM_MOVIMENTO = 404
 _SEM_MOVIMENTO_PADRAO = "não há movimento no período consultado"
 
 
-class ExtratoError(Exception):
-    """Erro devolvido pela API ao consultar o extrato do órgão repassador.
+class RespostaError(Exception):
+    """Resposta de erro devolvida pela API do Banco do Brasil.
 
-    Carrega o status HTTP e a mensagem originais do Banco do Brasil, porque a
-    API usa ``400`` tanto para falha de verdade quanto para situações normais.
+    Carrega o status HTTP e a mensagem originais junto da ação que falhou. Sem
+    eles, um ``404`` de "não há o que devolver", um ``403`` de escopo que falta
+    e um ``400`` de parâmetro inválido chegam ao chamador iguais.
     """
 
     status_code: int
     mensagem: str
 
-    def __init__(self, status_code: int, mensagem: str) -> None:
-        detalhe = f"(HTTP {status_code}): {mensagem}"
-        super().__init__(f"Não foi possível reaver o extrato do órgão repassador {detalhe}")
+    def __init__(self, acao: str, status_code: int, mensagem: str) -> None:
+        super().__init__(f"Não foi possível {acao} (HTTP {status_code}): {mensagem}")
         self.status_code = status_code
         self.mensagem = mensagem
 
 
+class ExtratoError(RespostaError):
+    """Erro devolvido pela API ao consultar o extrato do órgão repassador.
+
+    Carrega o status HTTP e a mensagem originais do Banco do Brasil, porque a
+    API usa ``400`` tanto para falha de verdade quanto para situações normais.
+    """
+
+    def __init__(self, status_code: int, mensagem: str) -> None:
+        super().__init__("reaver o extrato do órgão repassador", status_code, mensagem)
+
+
 class SemLancamentosError(ExtratoError):
     """A conta não tem lançamento nenhum no período consultado.
 
@@ -99,6 +110,11 @@ def _mensagem_da_lista_de_erros(campos: dict[str, object]) -> str:
     return ""
 
 
+def _erro(acao: str, res: requests.Response) -> RespostaError:
+    """Erro de uma resposta não-200, com a ação que falhou e o que o BB disse."""
+    return RespostaError(acao, res.status_code, _mensagem_de_erro(res))
+
+
 def _erro_extrato(res: requests.Response) -> ExtratoError:
     mensagem = _mensagem_de_erro(res)
     normalizada = mensagem.casefold()
@@ -235,7 +251,7 @@ class _AccountabilityV3BaseAPI:
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível adquirir as novas credenciais de acesso.")
+            raise _erro("adquirir as novas credenciais de acesso", res)
 
         data = common.parse_json_object(res)
         self._access_token = cast("str", data["access_token"])
@@ -266,9 +282,7 @@ class _AccountabilityV3BaseAPI:
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as agências próximas", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -411,7 +425,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro("reaver o documento de despesa do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -542,7 +556,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro("reaver o documento de despesa da prestação de contas", res)
 
         res = common.parse_json_object(res)
 
@@ -674,7 +688,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro("reaver o extrato de subtransações do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -761,6 +775,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         df = common.handle_results(
             extrato,
             main_list="listaLancamentosExtrato",
+            keep_header_when_empty=True,
             insertables=[
                 "numeroAgenciaRecebedora",
                 "digitoVerificadoraContaRecebedora",
@@ -913,6 +928,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         return common.handle_results(
             res,
             main_list="listaLancamentos",
+            keep_header_when_empty=True,
             insertables=[
                 "codigoProgramaGoverno",
                 "nomeProgramaGoverno",
@@ -972,9 +988,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar os lançamentos atualizados do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1015,9 +1029,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar os sublançamentos atualizados do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1051,9 +1063,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as categorias do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1084,9 +1094,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o saldo das aplicações financeiras", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1123,9 +1131,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o saldo da conta corrente", res)
 
         res = common.parse_json_object(res)
 
@@ -1171,9 +1177,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("categorizar a despesa do lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1220,9 +1224,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("identificar o lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1253,9 +1255,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code not in [200, 201]:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("excluir a identificação do lançamento a crédito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1284,9 +1284,7 @@ class AccountabilityV3RepasseAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as identificações dos lançamentos a débito", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1429,7 +1427,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro("reaver o documento de despesa do programa de governo", res)
 
         res = common.parse_json_object(res)
 
@@ -1560,7 +1558,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception("Não foi possível reaver o extrato do órgão repassador.")
+            raise _erro("reaver o documento de despesa da prestação de contas", res)
 
         res = common.parse_json_object(res)
 
@@ -1686,9 +1684,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("reaver o extrato de subtransações do programa de governo", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(
@@ -1773,6 +1769,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         df = common.handle_results(
             extrato,
             main_list="listaLancamentosExtrato",
+            keep_header_when_empty=True,
             insertables=[
                 "numeroAgenciaRecebedora",
                 "digitoVerificadoraContaRecebedora",
@@ -1922,6 +1919,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         return common.handle_results(
             res,
             main_list="listaLancamentos",
+            keep_header_when_empty=True,
             insertables=[
                 "codigoProgramaGoverno",
                 "nomeProgramaGoverno",
@@ -1974,9 +1972,7 @@ class AccountabilityV3ControleAPI(_AccountabilityV3BaseAPI):
         )
 
         if res.status_code != 200:
-            raise Exception(
-                "Não foi possível listar as categorias do programa de governo."
-            )
+            raise _erro("listar as contas correntes do órgão de controle", res)
 
         res = common.parse_json_object(res)
         return common.handle_results(

{bb_api-0.5.2 → bb_api-0.5.4}/bb_api/common.py

@@ -60,9 +60,27 @@ def handle_numeric_string_with_symbols(v: str) -> str:
     return re.sub(r"\D", "", v)
 
 
+def _data_de_texto(texto: str) -> datetime:
+    """Interpreta uma data em ISO ou em dd/mm/aaaa.
+
+    A API devolve os dois formatos, e o valor de uma resposta costuma virar
+    parâmetro da consulta seguinte: o ``bookingDate`` do extrato chega em
+    dd/mm/aaaa e é o que identifica o documento de despesa daquela transação.
+    """
+    formatos = ("%Y-%m-%d", "%d/%m/%Y")
+    for formato in formatos:
+        try:
+            return datetime.strptime(texto, formato)
+        except ValueError:
+            continue
+
+    aceitos = " ou ".join(formatos)
+    raise ValueError(f"A data '{texto}' não está em {aceitos}.")
+
+
 def handle_dates(v: DateLike) -> str:
     if isinstance(v, str):
-        dt = datetime.strptime(v, "%Y-%m-%d")
+        dt = _data_de_texto(v)
     elif isinstance(v, datetime):
         dt = v
     else:
@@ -81,11 +99,25 @@ def handle_results(
     insertables: Sequence[str] | None = None,
     explodeables: Sequence[str] | None = None,
     rename_dict: Mapping[str, str] | None = None,
+    *,
+    keep_header_when_empty: bool = False,
 ) -> pd.DataFrame:
+    """Monta o DataFrame da resposta: uma linha por item de ``main_list``.
+
+    Os campos de ``insertables`` ficam no nível de cima da resposta, fora da
+    lista, e são repetidos em todas as linhas.
+
+    Com ``keep_header_when_empty``, uma lista vazia devolve uma linha só com
+    esses campos, em vez de um DataFrame sem linha nenhuma. É o que preserva o
+    cabeçalho das respostas em que ele carrega o dado principal, como o
+    rendimento do mês nos extratos de aplicação.
+    """
     record = cast("Mapping[str, object]", data)
 
     if main_list is not None:
-        df = pd.DataFrame(cast("list[dict[Hashable, object]]", record[main_list]))
+        itens = cast("list[dict[Hashable, object]]", record.get(main_list) or [])
+        so_cabecalho = not itens and keep_header_when_empty
+        df = pd.DataFrame(index=[0]) if so_cabecalho else pd.DataFrame(itens)
     else:
         df = pd.DataFrame([dict(record)])
 

{bb_api-0.5.2 → bb_api-0.5.4}/bb_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bb_api
-Version: 0.5.2
+Version: 0.5.4
 Summary: Wrapper da API do Banco do Brasil.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

{bb_api-0.5.2 → bb_api-0.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bb_api"
-version = "0.5.2"
+version = "0.5.4"
 description = "Wrapper da API do Banco do Brasil."
 readme = "README.md"
 requires-python = ">=3.13"