mads-bombas-gasolina 0.1.0

Biblioteca Python para registo, consulta e análise de compras em bombas de gasolina.

MADS Bombas de Gasolina

Biblioteca Python para registo, consulta e análise de compras em bombas de gasolina.

O módulo foi organizado a partir do conteúdo do Colab original e disponibiliza funções para:

• registo de compras de combustível;
• listagem de bombas por marca;
• consulta do histórico de preços;
• obtenção do preço mais recente;
• registo de localizações para mapa;
• visualização geográfica com Folium;
• gráfico de variação de preços;
• filtragem por período;
• top 3 bombas mais baratas e mais caras;
• exportação de consultas para CSV e PDF;
• exportação total dos dados para CSV.

Instalação local

pip install .

Importação

from MadsBombasGasolina import *

Também é possível importar funções específicas:

from MadsBombasGasolina import registar_compra, listar_bombas_por_marca, mapa_bombas

Estrutura de dados

O módulo trabalha com dois ficheiros JSON locais:

• compras.json
• localizacoes_mapa.json

Isto significa que os dados ficam persistidos em ficheiros no diretório onde o programa é executado.

Fluxo recomendado

1. Registar compras com registar_compra.
2. Consultar preços com consultar_historico_precos ou get_preco_mais_recente.
3. Registar localizações com registar_localizacao_mapa.
4. Gerar o mapa com mapa_bombas.
5. Analisar dados por período ou rankings.
6. Exportar resultados com exportar_consulta_resumida ou exportar_todos_dados.

API Principal

HU01 — Registar compra de combustível

registar_compra(nif, marca, preco, data, tipo_combustivel)

Valida e regista uma compra no ficheiro compras.json.

Validações principais:

• NIF com 9 dígitos;
• marca válida: galp, bp, repsol, cepsa, prio;
• preço positivo;
• data no formato YYYY-MM-DD e não futura;
• tipo de combustível válido: gasolina, gasoleo, gpl;
• evita duplicados para a mesma marca, NIF e data.

HU02 — Listar bombas por marca

listar_bombas_por_marca(marca)

Lista todos os registos existentes para uma marca.

HU03 — Consultar histórico de preços

consultar_historico_precos(marca)

Mostra o histórico cronológico de preços de uma marca.

HU04 — Obter preço mais recente

get_preco_mais_recente(marca)

Devolve o preço mais recente registado para uma marca.

HU05 — Adicionar bombas ao mapa

registar_localizacao_mapa(marca, latitude, longitude)

Regista a localização geográfica de uma marca, associando também a cor usada no mapa.

HU06 — Mapa com identificação da bomba

mapa_bombas()

Gera um mapa Folium com:

• limite do concelho da Maia;
• várias camadas cartográficas;
• marcadores por marca;
• popup com marca e preço mais recente;
• legenda dinâmica.

HU07 — Gráfico de variação de preços

grafico_variacao_precos(marca)

Mostra um gráfico com a evolução dos preços da marca nos últimos 6 meses.

HU08 — Filtrar dados por data

filtrar_dados_por_periodo(data_inicio, data_fim)

Filtra compras entre duas datas no formato YYYY-MM-DD.

HU09 — Top 3 bombas mais baratas

top_3_bombas_mais_baratas(data_inicio, data_fim)

Devolve as 3 compras mais baratas no período indicado.

HU10 — Top 3 bombas mais caras

top_3_bombas_mais_caras(data_inicio, data_fim)

Devolve as 3 compras mais caras no período indicado.

HU11 — Exportar consulta resumida

exportar_consulta_resumida(dados, formato="csv", nome_ficheiro="exportacao_consulta")

Exporta uma lista de resultados para:

• CSV
• PDF

HU12 — Exportar todos os dados

exportar_todos_dados(nome_ficheiro="backup_total_bombas")

Exporta todos os registos existentes em compras.json para CSV.

Exemplo completo

from MadsBombasGasolina import *

registar_compra("123456789", "galp", 1.75, "2026-03-10", "gasolina")
registar_compra("987654321", "bp", 1.69, "2026-03-11", "gasoleo")

print(listar_bombas_por_marca("galp"))
print(consultar_historico_precos("bp"))

registar_localizacao_mapa("galp", 41.235, -8.620)
registar_localizacao_mapa("bp", 41.220, -8.600)

mapa = mapa_bombas()
mapa.save("mapa_bombas.html")

dados = filtrar_dados_por_periodo("2026-03-01", "2026-03-31")
exportar_consulta_resumida(dados, formato="csv", nome_ficheiro="consulta_marco")
exportar_todos_dados()

Conteúdo incluído no repositório

• pacote Python MadsBombasGasolina;
• notebook original Bombas_de_Gasolina.ipynb;
• ficheiros de empacotamento (pyproject.toml, setup.py, MANIFEST.in);
• licença MIT;
• .gitignore.

About

Projeto desenvolvido no âmbito da UC Metodologias Ágeis de Desenvolvimento de Software, reorganizado em formato de repositório GitHub.