Add support for raw data retrieval in currency, OData, and SGS modules

Author: wilsonfreitas

docs/currency.rst

@@ -77,3 +77,32 @@ O módulo :py:mod:`bcb.currency` obtem dados de moedas do conversor de moedas do
 
     currency.get_currency_list().head()
 
+Obtendo o CSV bruto
+^^^^^^^^^^^^^^^^^^^
+
+Para pipelines de dados onde o dado bruto deve ser persistido antes de qualquer transformação,
+o parâmetro ``output='text'`` pode ser passado à função :py:func:`bcb.currency.get`.
+
+Para um único símbolo é retornada uma ``str`` com o CSV bruto; para múltiplos símbolos é
+retornado um ``dict`` mapeando símbolo ISO → CSV string.
+
+.. code:: python
+
+    from bcb import currency
+
+    # único símbolo → str (CSV)
+    raw = currency.get('USD', start='2024-01-01', end='2024-01-31', output='text')
+
+    # múltiplos símbolos → dict[str, str]
+    raws = currency.get(['USD', 'EUR'], start='2024-01-01', end='2024-01-31', output='text')
+    # raws['USD'] → CSV string
+    # raws['EUR'] → CSV string
+
+    # salvar em disco
+    with open('usd_raw.csv', 'w') as f:
+        f.write(raw)
+
+O CSV retornado usa ponto-e-vírgula como separador, datas no formato ``DDMMYYYY`` e vírgula
+como separador decimal — exatamente como devolvido pela API PTAX do BCB.
+O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro não é informado.
+

docs/odata.rst

@@ -387,6 +387,34 @@ Para isso incluímos o método ``format`` na cadeia da consulta e passamos como
        .limit(5)
        .text())
 
+O parâmetro ``output='text'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Para pipelines de dados onde é necessário persistir o dado bruto antes de qualquer transformação
+(camada SOR/SOT), o parâmetro ``output='text'`` pode ser passado diretamente ao método ``collect``
+ou ao método ``get`` do endpoint.
+Isso evita serializar um DataFrame de volta para texto, o que pode ser uma operação com perda de informação.
+
+.. code:: python
+
+    ep = em.get_endpoint('ExpectativasMercadoTop5Anuais')
+
+    # via query chain
+    raw = (ep.query()
+              .filter(ep.Indicador == 'IPCA')
+              .limit(100)
+              .collect(output='text'))
+
+    # via atalho get()
+    raw = ep.get(ep.Indicador == 'IPCA', limit=100, output='text')
+
+    # salvar em disco
+    with open('expectativas_raw.json', 'w') as f:
+        f.write(raw)
+
+O texto retornado é o JSON bruto da resposta OData, incluindo o campo ``@odata.context`` e o array ``value``.
+O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro não é informado.
+
 
 Classe ODataAPI
 ---------------

docs/sgs.rst

@@ -36,6 +36,37 @@ Exemplos
     plt.legend().set_visible(False)
 
 
+Obtendo o JSON bruto
+--------------------
+
+A função :py:func:`bcb.sgs.get_json` retorna o JSON bruto da API para um único código.
+Para pipelines de dados onde o dado bruto deve ser persistido antes de qualquer transformação,
+o parâmetro ``output='text'`` pode ser passado à função :py:func:`bcb.sgs.get`.
+
+Para um único código é retornada uma ``str``; para múltiplos códigos é retornado um ``dict``
+mapeando código inteiro → JSON string.
+
+.. code:: python
+
+    from bcb import sgs
+
+    # único código → str
+    raw = sgs.get(433, start='2024-01-01', output='text')
+
+    # múltiplos códigos → dict[int, str]
+    raws = sgs.get([433, 189], start='2024-01-01', output='text')
+    # raws[433] → JSON string do IPCA
+    # raws[189] → JSON string do IGP-M
+
+    # salvar em disco
+    with open('ipca_raw.json', 'w') as f:
+        f.write(raw)
+
+O JSON retornado é um array de objetos com os campos ``data`` e ``valor``, exatamente como
+devolvido pela API BCData/SGS.
+O comportamento padrão (retorno de DataFrame) é mantido quando o parâmetro não é informado.
+
+
 Dados de Inadimplência de Operações de Crédito
 ==============================================