Metadata-Version: 2.4
Name: mads-bombas-gasolina
Version: 0.1.0
Summary: Biblioteca Python para registo, consulta e análise de compras em bombas de gasolina.
Author: Afonso Jerónimo, Cristiano Teixeira, Pedro Silva
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: branca>=0.7.0
Requires-Dist: folium>=0.16.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# 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

```bash
pip install .
```

## Importação

```python
from MadsBombasGasolina import *
```

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

```python
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

```python
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.
