Metadata-Version: 2.4
Name: eleicoes-pt
Version: 0.1.0
Summary: Resultados eleitorais portugueses desde 1975, em acesso aberto
Project-URL: Homepage, https://github.com/openlousada/eleicoes-pt
Project-URL: Repository, https://github.com/openlousada/eleicoes-pt
Project-URL: Issues, https://github.com/openlousada/eleicoes-pt/issues
License: MIT
Keywords: MAI,civic-tech,eleições,open-data,portugal,resultados eleitorais
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Provides-Extra: audit
Requires-Dist: openpyxl>=3.1; extra == 'audit'
Requires-Dist: xlrd>=2.0; extra == 'audit'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Description-Content-Type: text/markdown

# eleicoes-pt

![banner](https://raw.githubusercontent.com/openlousada/eleicoes-pt/main/banner.png)

Resultados eleitorais portugueses desde 1975, em acesso aberto.

Dados pré-processados a partir das fontes oficiais do MAI (Ministério da Administração Interna), disponíveis para download directo sem necessidade de parsear XLSX ou tratar formatos históricos.

---

## Instalação

```bash
pip install eleicoes-pt
```

---

## Utilização

```python
from eleicoes_pt import fetch, list_available

# Ver o que está disponível
print(list_available())
# {
#   'AR': [1975, 1976, 1979, 1980, 1983, 1985, 1987, 1991, 1995, ...],
#   'CM': [1982, 1985, 1989, ...],
#   ...
# }

# Obter resultados
resultados = fetch("AR", 2024)
resultados = fetch("CM", 2021)
resultados = fetch("PR", 2011)
```

Os dados são devolvidos como lista de dicts. Ficheiros descarregados ficam disponíveis offline se passar `cache_dir`:

```python
from pathlib import Path
resultados = fetch("AR", 2024, cache_dir=Path("~/.cache/eleicoes-pt").expanduser())
```

---

## Tipos de eleição

| Código  | Eleição                                              |
|---------|------------------------------------------------------|
| `AR`    | Assembleia da República                              |
| `CM`    | Câmaras Municipais                                   |
| `AM`    | Assembleias Municipais                               |
| `AF`    | Assembleias de Freguesia                             |
| `PR`    | Presidente da República                              |
| `PE`    | Parlamento Europeu                                   |
| `ALRAM` | Assembleia Legislativa da Região Autónoma da Madeira |
| `ALRAA` | Assembleia Legislativa da Região Autónoma dos Açores |

---

## Modo de auditoria

Para verificar a integridade dos dados publicados face ao ficheiro original do MAI:

```bash
pip install eleicoes-pt[audit]
```

```python
from eleicoes_pt import audit
audit("AR", 2024)
```

---

## Fonte dos dados

Todos os dados provêm do MAI — Ministério da Administração Interna, disponíveis em [sg.mai.gov.pt](https://www.sg.mai.gov.pt). Os ficheiros originais (XLSX) são processados uma vez e publicados neste repositório como release de dados para facilitar o acesso.

---

## Licença

MIT © [Open Lousada](https://github.com/openlousada)
