Metadata-Version: 2.4
Name: aguasgo-py
Version: 2026.7.2
Summary: Python client for unofficial Global Omnium water API
Author-email: carlos-48 <karloselmaster@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/carlos-48/aguasgo-py
Project-URL: Repository, https://github.com/carlos-48/aguasgo-py
Project-URL: Issues, https://github.com/carlos-48/aguasgo-py/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4,>=3.8.0
Provides-Extra: mqtt
Requires-Dist: paho-mqtt<2,>=1.6.1; extra == "mqtt"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: ruff>=0.1; extra == "test"
Requires-Dist: mypy>=1.0; extra == "test"
Requires-Dist: requests>=2.25.0; extra == "test"
Dynamic: license-file

# Aguasgo-py Python API

[![GitHub Release](https://img.shields.io/github/v/release/carlos-48/aguasgo-py)](https://github.com/carlos-48/aguasgo-py/releases)
[![CodeQL](https://github.com/carlos-48/aguasgo-py/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/carlos-48/aguasgo-py/actions/workflows/codeql-analysis.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

Programmatic access to water consumption data from [Global Omnium](https://www.globalomnium.com/), the Spanish water distributor management group.

## 🚀 Features

- **Multi-entity Support**: Compatible with various Global Omnium management companies (e.g., Emivasa, Aguas de Valencia, and others).
- **Automatic Municipality → Base URL Detection**: Enter your municipality during setup; the library resolves the correct API endpoint automatically.
- **Modern Python**: Fully updated for Python 3.11+ with strong type hinting and asynchronous support (`asyncio` / `aiohttp`).
- **Consumption Data**: Retrieve current readings and hourly/historical consumption.
- **Historical Backfill**: Fetch complete historical data in chunks (30-day windows) for Home Assistant Energy Dashboard integration.
- **Reliable**: Robust parsing and session management designed for stable Home Assistant integrations.

## 📦 Installation

### For Development (Editable Mode)
If you are contributing or developing a component based on this library, install it in editable mode:

```bash
git clone https://github.com/carlos-48/aguasgo-py.git
cd aguasgo-py
pip install -e .
```

### For Production
```bash
pip install aguasgo-py
```

## 🛠️ Quick Start

```python
import asyncio
import aiohttp
from aguasgo import Client

async def main():
    async with aiohttp.ClientSession() as session:
        # base_url is mandatory as it depends on the management company of your municipality
        client = Client(
            session=session,
            username="your_username",
            password="your_password",
            base_url="https://www.emivasa.es/VirtualOffice"
        )
        
        # Example: Get current measure
        measure = await client.get_measure()
        print(f"Current Reading: {measure.accumulate} m³")
        print(f"Instant Consumption: {measure.instant} l/h")

asyncio.run(main())
```

## 🧪 Testing

The library includes a comprehensive test suite using `pytest`.

### Unit Tests
Run fast, deterministic tests using local fixtures:
```bash
pytest tests/unit
```

### Integration Tests
Run tests against the live Global Omnium API (requires credentials):
```bash
pytest --run-integration tests/integration
```

## ⚖️ License & Attribution

This project is licensed under the **GNU General Public License v3.0 (GPLv3)**.

**Attribution Notice:**
This library is based on the original work by [ldotlopez](https://github.com/ldotlopez), adapted, refactored, and updated by **carlos-48** to migrate from electrical energy data (original project) to water supply data.

## 🔗 Useful Links

- [Home Assistant Component](https://github.com/carlos-48/ha-aguasgo)
- [Original ideenergy Python API](https://github.com/ldotlopez/ideenergy)
