📝 Expandir e melhorar docstrings dos módulos

Author: GusFurtado

DadosAbertosBrasil/__init__.py

@@ -1,38 +1,51 @@
-"""Dados Abertos Brasil é uma iniciativa para facilitar o acesso a dados
-abertos e APIs do governo brasileiro.
+"""
+Dados Abertos Brasil
+====================
+
+Dados Abertos Brasil é uma iniciativa para facilitar o acesso a dados abertos e APIs do governo brasileiro.
 
-É um pacote open-source para Python e Pandas e a forma mais simples de acessar
-dados de instituições como IGBE, IPEA, Banco Central, etc.
+É um pacote open-source para Python e Pandas e a forma mais simples de acessar dados de instituições como IBGE, IPEA, Banco Central, etc.
 
 Módulos
 -------
-- DadosAbertosBrasil.ibge
-- DadosAbertosBrasil.ipea
-- DadosAbertosBrasil.camara
-- DadosAbertosBrasil.senado
-- DadosAbertosBrasil.bacen
-- DadosAbertosBrasil.favoritos
-- DadosAbertosBrasil.UF
+
+- ``DadosAbertosBrasil.ibge``
+- ``DadosAbertosBrasil.ipea``
+- ``DadosAbertosBrasil.camara``
+- ``DadosAbertosBrasil.senado``
+- ``DadosAbertosBrasil.bacen``
+- ``DadosAbertosBrasil.favoritos``
+- ``DadosAbertosBrasil.uf``
 
 Sobre
 -----
-- Página Oficial: https://www.gustavofurtado.com/dab.html
-- Documentação: https://www.gustavofurtado.com/DadosAbertosBrasil
+
+- **Página Oficial:** `<https://www.gustavofurtado.com/dab.html>`_
+- **Documentação:** `<https://www.gustavofurtado.com/DadosAbertosBrasil>`_
 
 Instalação
 ----------
-- `pip install DadosAbertosBrasil`
+
+Para instalar, utilize o seguinte comando:
+
+.. code-block:: bash
+
+   pip install DadosAbertosBrasil
 
 Dependências
 ------------
-- Python 3.6 ou superior
-- pandas
-- requests
+
+- `Python 3.10 ou superior <https://www.python.org/>`_
+- `Pandas <https://pandas.pydata.org/>`_
+- `Pydantic <https://docs.pydantic.dev/latest/>`_
+- `Requests <https://requests.readthedocs.io/en/master/>`_
 
 Licença
 -------
+
 - MIT
 
+
 """
 
 from . import bacen

DadosAbertosBrasil/bacen/__init__.py

@@ -1,15 +1,17 @@
-"""Módulo de captura de dados das APIs do Banco Central do Brasil.
+"""Módulo para captura de dados das APIs do Banco Central do Brasil.
 
-Notes
------
-SGS - Sistema Gerenciador de Séries Temporais
-    https://www3.bcb.gov.br/sgspub/
+Este módulo permite o acesso a diversas informações econômicas disponibilizadas pelo Banco Central, incluindo:
 
-Cotação do Câmbio
-    https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3
-    
-Expectativas de Mercado
-    https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/swagger-ui3#/
+- Histórico de câmbio das principais moedas do mundo;
+- Expectativas do mercado para indicadores macroeconômicos do Brasil;
+- Consulta a séries temporais do Sistema Gerenciador de Séries Temporais (SGS).
+
+APIs Oficiais
+-------------
+
+- **SGS - Sistema Gerenciador de Séries Temporais:** `<https://www3.bcb.gov.br/sgspub/>`_
+- **Cotação de Câmbio (PTAX):** `<https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3>`_
+- **Expectativas de Mercado:** `<https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/swagger-ui3#/>`_
 
 """
 

DadosAbertosBrasil/camara/__init__.py

@@ -1,25 +1,46 @@
-"""Módulo para captura dos dados abertos da Câmara dos Deputados do Brasil.
+"""Módulo para captura de dados abertos da Câmara dos Deputados do Brasil.
+
+Este módulo permite acessar informações detalhadas sobre deputados, partidos, 
+frentes parlamentares, proposições, votações e outros dados legislativos 
+disponibilizados pela API da Câmara dos Deputados.
 
 Mini-Tutorial
 -------------
-1. Importe o módulo `camara`.
->>> from DadosAbertosBrasil import camara
 
-2. Busque o código do objeto de estudo utilizando as funções `lista`.
->>> camara.lista_deputados( ... )
+1. Importe o módulo `camara`:
+
+.. code-block:: python
+
+	from DadosAbertosBrasil import camara
+
+2. Busque o código do objeto de estudo utilizando as funções `lista`:
+
+.. code-block:: python
+
+	camara.lista_deputados(...)
+
+3. Instancie o objeto de estudo utilizando o código encontrado:
+
+.. code-block:: python
+
+	dep = camara.Deputado(cod)
+
+4. Utilize os atributos da classe para obter informações básicas do objeto:
+
+.. code-block:: python
+	
+    dep.dados
+
+5. Utilize os métodos da classe para obter informações detalhadas do objeto:
 
-3. Instancie o objeto de estudo utilizando o código encontrado.
->>> dep = camara.Deputado(cod)
+.. code-block:: python
 
-4. Utilize os atributos da classe para obter informações básicas do objeto.
->>> dep.dados
+	dep.despesas(...)
 
-5. Utilize os métodos da classe para obter informações detalhadas do objeto.
->>> dep.despesas( ... )
+API Oficial
+-----------
 
-Notes
------
-https://dadosabertos.camara.leg.br/swagger/api.html
+- **Dados Abertos da Câmara dos Deputados:** `<https://dadosabertos.camara.leg.br/swagger/api.html>`_
 
 """
 

DadosAbertosBrasil/favoritos/__init__.py

@@ -1,11 +1,12 @@
-"""Módulo para consulta a informações variadas.
+"""Módulo de consulta a informações de interesse público.
 
-Essas funções são importadas pelo `__init__` do super-módulo
-`DadosAbertosBrasil`.
+Este módulo reúne funções pré-parametrizadas de outros submódulos do 
+`DadosAbertosBrasil`, facilitando o acesso a informações diversas e 
+amplamente utilizadas.
 
-Elas consistem em informações diversas ou em funções pré-parametrizadas de
-outros módulo. Seu objetivo é facilitar o acesso às informações de maior
-interesse público.
+As funções deste módulo são importadas automaticamente pelo `__init__` 
+do supermódulo, proporcionando uma interface simplificada para consultas 
+rápidas.
 
 """
 

DadosAbertosBrasil/ibge/__init__.py

@@ -1,52 +1,67 @@
-"""Módulo para captura dos dados abertos das APIs do IBGE.
+"""Módulo para captura de dados abertos das APIs do IBGE.
+
+Este módulo fornece acesso a diversas informações do Instituto Brasileiro de Geografia e Estatística (IBGE), 
+incluindo dados geográficos, demográficos e estatísticos.
 
 Serviços Disponíveis
 --------------------
-- IBGE Cidades
-- Nomes 2.0
-- Agregados 3.0 (SIDRA)
-- Malhas Geográficas 2.0
-- Projeções 1.0
-- Localidades 1.0
+
+- **IBGE Cidades**: Informações sobre municípios brasileiros.
+- **Nomes 2.0**: Estatísticas sobre nomes mais comuns no Brasil.
+- **Agregados 3.0 (SIDRA)**: Dados de séries temporais e tabelas estatísticas.
+- **Malhas Geográficas 2.0**: Arquivos geoespaciais do Brasil.
+- **Projeções 1.0**: Projeções populacionais e estatísticas futuras.
+- **Localidades 1.0**: Informações detalhadas sobre unidades territoriais.
 
 Mini-Tutorial de SIDRA
 ----------------------
-1. Importe o módulo `ibge`.
->>> from DadosAbertosBrasil import ibge
-
-2. Utilize a função `lista_tabelas` com os filtros necessários para encontrar
-a tabela desejada.
->>> ibge.lista_tabelas( ... )
-
-3. Utilize as funções `lista_pesquisas` e `referencias` para facilitar a busca.
->>> pesquisas = ibge.lista_pesquisas( ... )
->>> referencias = ibge.referencias( ... )
-
-4. Após obter o código numérico da tabela, insira-o como argumento de um
-objeto `Metadados`.
->>> dados = ibge.Metadados(tabela)
-
-5. Pelos atributos do objeto `Metadados`, veja quais são os valores
-disponíveis para consulta desta tabela.
->>> print(dados.periodos)
->>> print(dados.variaveis)
->>> print(dados.localidades)
->>> print(dados.classificacoes)
-
-6. Utilize os valores encontrados nos metadados da tabela para alimentar a
-função `sidra`.
->>> ibge.sidra( ... )
-
-Notes
------
-IBGE Cidades
-    https://cidades.ibge.gov.br/
-
-Serviços
-    https://servicodados.ibge.gov.br/api/docs
-
-SIDRA
-    http://api.sidra.ibge.gov.br/
+
+1. Importe o módulo `ibge`:
+
+.. code-block:: python
+
+	from DadosAbertosBrasil import ibge
+
+2. Utilize `lista_tabelas` para encontrar a tabela desejada:
+
+.. code-block:: python
+
+	ibge.lista_tabelas(...)
+
+3. Use `lista_pesquisas` e `referencias` para facilitar a busca:
+
+.. code-block:: python
+
+	pesquisas = ibge.lista_pesquisas(...)
+	referencias = ibge.referencias(...)
+
+4. Após obter o código numérico da tabela, instancie um objeto `Metadados`:
+
+.. code-block:: python
+
+	dados = ibge.Metadados(tabela)
+
+5. Verifique os valores disponíveis para consulta na tabela:
+
+.. code-block:: python
+
+	print(dados.periodos)
+	print(dados.variaveis)
+	print(dados.localidades)
+	print(dados.classificacoes)
+
+6. Use os valores dos metadados para alimentar a função `sidra`:
+
+.. code-block:: python
+
+	ibge.sidra(...)
+
+APIs Originais
+--------------
+
+- **IBGE Cidades:** `<https://cidades.ibge.gov.br/>`_
+- **Serviços IBGE:** `<https://servicodados.ibge.gov.br/api/docs>`_
+- **SIDRA:** `<http://api.sidra.ibge.gov.br/>`_
 
 """
 

DadosAbertosBrasil/ibge/_cidades.py

@@ -1,16 +1,3 @@
-"""Submódulo IBGE contendo os wrappers das APIs do IBGE Cidades.
-
-Este submódulo é importado automaticamente com o módulo `ibge`.
-
->>> from DadosAbertosBrasil import ibge
-
-Notes
------
-API original do IBGE Cidades
-    https://cidades.ibge.gov.br/
-
-"""
-
 from typing import Iterator, Optional
 
 from ..utils import Get, parse

DadosAbertosBrasil/ibge/_misc.py

@@ -1,11 +1,3 @@
-"""Submódulo IBGE contendo funções diversas.
-
-Este submódulo é importado automaticamente com o módulo `ibge`.
-
->>> from DadosAbertosBrasil import ibge
-
-"""
-
 from typing import Literal, Optional
 
 import pandas as pd

DadosAbertosBrasil/ibge/_nomes.py

@@ -1,15 +1,3 @@
-"""Submódulo IBGE contendo os wrappers da API do Nomes 2.0.
-
-Este submódulo é importado automaticamente com o módulo `ibge`.
-
->>> from DadosAbertosBrasil import ibge
-
-Documentação Original
----------------------
-https://servicodados.ibge.gov.br/api/docs
-
-"""
-
 from typing import Literal, Optional
 
 import pandas as pd

DadosAbertosBrasil/ibge/_sidra.py

@@ -1,15 +1,3 @@
-"""Submódulo IBGE contendo os wrappers da API do SIDRA.
-
-Este submódulo é importado automaticamente com o módulo `ibge`.
-
->>> from DadosAbertosBrasil import ibge
-
-Documentação Original
----------------------
-http://api.sidra.ibge.gov.br/
-
-"""
-
 from typing import Optional, Literal
 
 import pandas as pd