Updated documentation

Author: wilsonfreitas

CHANGELOG.md

@@ -1,6 +1,10 @@
 
 # Changelog
 
+## [0.1.9] - 
+- Created class bcb.ODataAPI to directly wrap OData APIs
+- Updated documentation
+
 ## [0.1.8] - 2022-09-10
 - Updated documentation
 - Migrated to poetry

bcb/sgs.py

@@ -1,4 +1,3 @@
-
 from io import StringIO
 
 import requests
@@ -42,52 +41,48 @@ def _codes(codes):
 
 
 def _get_url_and_payload(code, start_date, end_date, last):
-    payload = {'formato': 'json'}
+    payload = {"formato": "json"}
     if last == 0:
         if start_date is not None or end_date is not None:
-            payload['dataInicial'] = Date(start_date).date.strftime('%d/%m/%Y')
-            end_date = end_date if end_date else 'today'
-            payload['dataFinal'] = Date(end_date).date.strftime('%d/%m/%Y')
-        url = 'http://api.bcb.gov.br/dados/serie/bcdata.sgs.{}/dados'\
-            .format(code)
+            payload["dataInicial"] = Date(start_date).date.strftime("%d/%m/%Y")
+            end_date = end_date if end_date else "today"
+            payload["dataFinal"] = Date(end_date).date.strftime("%d/%m/%Y")
+        url = "http://api.bcb.gov.br/dados/serie/bcdata.sgs.{}/dados".format(code)
     else:
-        url = ('http://api.bcb.gov.br/dados/serie/bcdata.sgs.{}/dados'
-               '/ultimos/{}').format(code, last)
+        url = (
+            "http://api.bcb.gov.br/dados/serie/bcdata.sgs.{}/dados" "/ultimos/{}"
+        ).format(code, last)
 
-    return {
-        'payload': payload,
-        'url': url
-    }
+    return {"payload": payload, "url": url}
 
 
 def _format_df(df, code, freq):
-    cns = {'data': 'Date', 'valor': code.name, 'datafim': 'enddate'}
+    cns = {"data": "Date", "valor": code.name, "datafim": "enddate"}
     df = df.rename(columns=cns)
-    if 'Date' in df:
-        df['Date'] = pd.to_datetime(df['Date'], format='%d/%m/%Y')
-    if 'enddate' in df:
-        df['enddate'] = pd.to_datetime(df['enddate'], format='%d/%m/%Y')
-    df = df.set_index('Date')
+    if "Date" in df:
+        df["Date"] = pd.to_datetime(df["Date"], format="%d/%m/%Y")
+    if "enddate" in df:
+        df["enddate"] = pd.to_datetime(df["enddate"], format="%d/%m/%Y")
+    df = df.set_index("Date")
     if freq:
         df.index = df.index.to_period(freq)
     return df
 
 
 def get(codes, start=None, end=None, last=0, multi=True, freq=None):
-    '''
+    """
     Retorna um DataFrame pandas com séries temporais obtidas do SGS.
 
     Parameters
     ----------
 
-    symbols : {int, List[int], List[str], Dict[str:int]}
+    codes : {int, List[int], List[str], Dict[str:int]}
         Este argumento pode ser uma das opções:
 
-        ``int`` : código da série temporal
-
-        ``list`` ou ``tuple`` : lista ou tupla com pares ``('nome', código)``
-
-        ``dict`` : dicionário com pares ``{'nome': código}``
+        * ``int`` : código da série temporal
+        * ``list`` ou ``tuple`` : lista ou tupla com códigos
+        * ``list`` ou ``tuple`` : lista ou tupla com pares ``('nome', código)``
+        * ``dict`` : dicionário com pares ``{'nome': código}``
 
         Com códigos numéricos é interessante utilizar os nomes com os códigos
         para definir os nomes nas colunas das séries temporais.
@@ -112,18 +107,18 @@ def get(codes, start=None, end=None, last=0, multi=True, freq=None):
 
     ``DataFrame`` :
         série temporal univariada ou multivariada,
-        quando solicitado mais de uma série.
+        quando solicitado mais de uma série (parâmetro ``multi=True``).
 
     ``list`` :
         lista com séries temporais univariadas,
-        quando solicitado mais de uma série.
-    '''
+        quando solicitado mais de uma série (parâmetro ``multi=False``).
+    """
     dfs = []
     for code in _codes(codes):
         urd = _get_url_and_payload(code.value, start, end, last)
-        res = requests.get(urd['url'], params=urd['payload'])
+        res = requests.get(urd["url"], params=urd["payload"])
         if res.status_code != 200:
-            raise Exception('Download error: code = {}'.format(code.value))
+            raise Exception("Download error: code = {}".format(code.value))
         df = pd.read_json(StringIO(res.text))
         df = _format_df(df, code, freq)
         dfs.append(df)

docs/_static/images/savefig/taxajuros1.png

@@ -2,17 +2,17 @@
 API
 ===
 
-Módulo :ref:`bcb.sgs`
----------------------
+Módulo :py:mod:`bcb.sgs`
+------------------------
 
 .. currentmodule:: bcb.sgs
 
 .. autosummary::
 
    get
 
-Módulo :ref:`bcb.currency`
---------------------------
+Módulo :py:mod:`bcb.currency`
+-----------------------------
 
 .. currentmodule:: bcb.currency
 
@@ -22,24 +22,19 @@ Módulo :ref:`bcb.currency`
    get_currency_list
 
 
-APIs OData
-----------
+:ref:`APIs OData`
+-----------------
 
 .. currentmodule:: bcb
 
 .. autosummary::
 
    Endpoint
    BaseODataAPI
+   ODataAPI
    Expectativas
    PTAX
    IFDATA
    TaxaJuros
    SPI
    MercadoImobiliario
-   TarifasBancariasPorInstituicaoFinanceira
-   TarifasBancariasPorServico
-   PostosAtendimentoEletronicoPorInstituicaoFinanceira
-   PostosAtendimentoCorrespondentesPorInstituicaoFinanceira
-   EstatisticasSTR
-   DinheiroCirculacao

docs/api.rst

@@ -60,11 +60,20 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "pydata_sphinx_theme"
+html_theme = "furo"
 html_theme_options = {
-    "external_links": [],
-    "github_url": "https://github.com/wilsonfreitas/python-bcb",
+    "source_repository": "https://github.com/wilsonfreitas/python-bcb/",
+    "source_branch": "main",
+    "source_directory": "docs/",
 }
+# html_theme = "alabaster"
+# html_theme_options = {
+#     "description": "Interface em Python para o portal de dados abertos do BCB",
+#     "github_user": "wilsonfreitas",
+#     "github_repo": "python-bcb",
+#     "fixed_sidebar": True,
+# }
+
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/conf.py

@@ -1,5 +1,5 @@
 Moedas
-######
+======
 
 O pacote tem 2 APIs que dão acesso a informações de moedas.
 
@@ -11,22 +11,24 @@ O pacote tem 2 APIs que dão acesso a informações de moedas.
 Conversor de Moedas
 -------------------
 
-O módulo ``currency`` obtem dados de moedas do conversor de moedas do Banco Central através de webscraping.
+.. automodule:: bcb.currency
 
-.. currentmodule:: bcb.currency
+O módulo :py:mod:`bcb.currency` obtem dados de moedas do conversor de moedas do Banco Central através de webscraping.
 
+.. currentmodule:: bcb.currency
 
 .. autofunction:: get
 
 
 .. ipython:: python
 
     from bcb import currency
-    df = currency.get(['USD', 'EUR'], start='2000-01-01', end='2021-01-01', side='ask')
+    df = currency.get(['USD', 'EUR'],
+                      start='2000-01-01',
+                      end='2021-01-01',
+                      side='ask')
     df.head()
 
-.. ipython:: python
-
     @savefig currency1.png
     df.plot(figsize=(12, 6));
 
@@ -46,7 +48,7 @@ API OData
 
 __ documentacao_
 
-Diferente da interface _`currency`, os dados são obtidos a partir da `API de Moedas`__.
+Diferente do módulo :py:mod:`bcb.currency`, aqui os dados são obtidos a partir da `API de Moedas`__.
 
 .. currentmodule:: bcb
 
@@ -65,10 +67,28 @@ Diferente da interface _`currency`, os dados são obtidos a partir da `API de Mo
 
     ptax.describe('Moedas')
 
+    ep = ptax.get_endpoint('Moedas')
+    ep.query().limit(10).collect()
+
 .. ipython:: python
 
-    ptax.describe('CotacaoMoedaPeriodoFechamento')
+    ptax.describe('CotacaoMoedaDia')
+
+    ep = ptax.get_endpoint('CotacaoMoedaDia')
+    (ep.query()
+       .parameters(moeda='AUD', dataCotacao='1/31/2022')
+       .collect())
+
+É importante notar que as datas estão no formato dia/mês/ano e os números não
+são preenchidos com 0 para ter 2 dígitos.
 
 .. ipython:: python
 
     ptax.describe('CotacaoMoedaPeriodo')
+    
+    ep = ptax.get_endpoint('CotacaoMoedaPeriodo')
+    (ep.query()
+       .parameters(moeda='AUD',
+                   dataInicial='1/1/2022',
+                   dataFinalCotacao='1/5/2022')
+       .collect())

docs/currency.rst

@@ -6,17 +6,6 @@
 python-bcb 
 ==========
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Conteúdo:
-
-   sgs
-   currency
-   expectativas
-   taxajuros
-   odata
-   api
-
 **python-bcb** é uma interface em Python estruturada para obter informações
 da API de dados abertos do `Banco Central do Brasil <https://www.bcb.gov.br>`_.
 
@@ -87,6 +76,16 @@ Uso
    sgs.get(('IPCA', 433), last=12)
 
 
+.. toctree::
+   :maxdepth: 1
+
+   sgs
+   currency
+   expectativas
+   taxajuros
+   odata
+   api
+
 Índices e tabelas
 ==================
 

docs/index.rst

@@ -1,19 +1,22 @@
 SGS
-###
+===
 
 O módulo ``sgs`` obtem os dados do webservice do Banco Central,
 interface json do serviço BCData/SGS - 
 `Sistema Gerenciador de Séries Temporais (SGS) <https://www3.bcb.gov.br/sgspub/localizarseries/localizarSeries.do?method=prepararTelaLocalizarSeries>`_.
 
 .. automodule:: bcb.sgs
 
-Função :ref:`bcb.sgs.get`
--------------------------
+Função bcb.sgs.get
+--------------------
 
 .. currentmodule:: bcb.sgs
 
 .. autofunction:: get
 
+Exemplo
+-------
+
 .. ipython:: python
 
     from bcb import sgs

docs/sgs.rst

@@ -21,6 +21,7 @@ Sphinx = "^5.1.1"
 pydata-sphinx-theme = "^0.10.1"
 matplotlib = "^3.5.3"
 ipython = "^8.5.0"
+furo = "^2022.6.21"
 
 
 [tool.poetry.group.dev.dependencies]