e-data 1.2.22__tar.gz → 2.0.0b1__tar.gz

e_data-2.0.0b1/.python-version

@@ -0,0 +1 @@
+3.11

e_data-2.0.0b1/MANIFEST.in

@@ -0,0 +1,22 @@
+# Configuration files
+include pyproject.toml
+include Makefile
+include .python-version
+
+# Documentation
+include *.md
+
+# License
+include LICENSE
+
+# Include tests (setuptools auto-includes package files)
+recursive-include edata/tests *.py
+
+# Exclude compiled files and caches
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__
+global-exclude .DS_Store
+prune build
+prune dist
+prune *.egg-info

e_data-2.0.0b1/Makefile

@@ -0,0 +1,51 @@
+.PHONY: help install install-dev test lint format build clean publish publish-test
+
+help:  ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install the package in development mode
+	pip install -e .
+
+install-dev:  ## Install with development dependencies
+	pip install -e ".[dev,test]"
+
+test:  ## Run tests
+	pytest
+
+test-cov:  ## Run tests with coverage
+	pytest --cov=edata --cov-report=html --cov-report=term
+
+lint:  ## Run linting checks
+	flake8 edata/
+	mypy edata/
+
+format:  ## Format code with black
+	black edata/
+
+format-check:  ## Check if code is formatted
+	black --check edata/
+
+clean:  ## Clean build artifacts
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+build:  ## Build the package
+	python -m build
+
+publish-test:  ## Publish to TestPyPI
+	python -m twine upload --repository testpypi dist/*
+
+publish:  ## Publish to PyPI
+	python -m twine upload dist/*
+
+# Combined workflow commands
+dev-setup: install-dev  ## Setup development environment
+
+pre-commit: format lint test  ## Run all pre-commit checks
+
+release: clean build publish  ## Build and publish to PyPI
+
+release-test: clean build publish-test  ## Build and publish to TestPyPI

e_data-2.0.0b1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: e-data
+Version: 2.0.0b1
+Summary: Python library for managing spanish energy data from various web providers
+Author-email: VMG <vmayorg@outlook.es>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/uvejota/python-edata
+Project-URL: Repository, https://github.com/uvejota/python-edata
+Project-URL: Issues, https://github.com/uvejota/python-edata/issues
+Keywords: energy,data,spain,electricity,consumption
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dateparser>=1.1.2
+Requires-Dist: holidays>=0.14.2
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: requests>=2.28.1
+Requires-Dist: voluptuous>=0.13.1
+Requires-Dist: Jinja2>=3.1.2
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sqlmodel>=0.0.24
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.1.2; extra == "dev"
+Requires-Dist: freezegun>=1.2.1; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.1.2; extra == "test"
+Requires-Dist: freezegun>=1.2.1; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "test"
+Dynamic: license-file
+
+[![Downloads](https://pepy.tech/badge/e-data)](https://pepy.tech/project/e-data)
+[![Downloads](https://pepy.tech/badge/e-data/month)](https://pepy.tech/project/e-data)
+[![Downloads](https://pepy.tech/badge/e-data/week)](https://pepy.tech/project/e-data)
+
+# python-edata
+
+Este paquete proporciona herramientas para la descarga de tus datos de consumo eléctrico (desde Datadis.es) y su posterior procesado. La motivación principal es que conocer el consumo puede ayudarnos a reducirlo, e incluso a elegir una tarifa que mejor se adapte a nuestras necesidades. A día de hoy sus capacidades de facturación (€) son limitadas, soporta PVPC (según disponibilidad de datos de REData) y tarificación fija por tramos. Es el corazón de la integración [homeassistant-edata](https://github.com/uvejota/homeassistant-edata).
+
+_**Esta herramienta no mantiene ningún tipo de vinculación con los proveedores de datos anteriormente mencionados, simplemente consulta la información disponible y facilita su posterior análisis.**_
+
+## Instalación
+
+Puedes instalar la última versión estable mediante:
+
+``` bash
+pip install e-data
+```
+
+Si quieres probar la versión `dev` o contribuir a su desarrollo, clona este repositorio e instala manualmente las dependencias:
+
+``` bash
+make install-dev
+```
+
+## Estructura
+
+El paquete utiliza una **arquitectura basada en servicios** con los siguientes módulos:
+
+* **Conectores** (módulo `connectors`), para definir los métodos de consulta a los diferentes proveedores: Datadis y REData.
+* **Modelos** (módulo `models`), que definen las estructuras de datos usando Pydantic v2 para validación robusta. Incluye modelos para suministros, contratos, consumos, maxímetro, precios y base de datos.
+* **Servicios** (módulo `services`), que implementan la lógica de negocio para cada dominio: gestión de suministros, contratos, consumos, maxímetro, facturación y base de datos SQLite.
+* **Helper principal** (`helpers.py`), que orquesta todos los servicios y proporciona una interfaz simplificada. El `EdataHelper` permite descargar y procesar datos automáticamente, calculando más de 40 atributos de resumen.
+
+Estos módulos corresponden a la siguiente estructura del paquete:
+
+```
+edata/
+    · __init__.py
+    · const.py                  # Constantes y definiciones de atributos
+    · utils.py                  # Utilidades generales
+    · helpers.py                # Helper principal (EdataHelper)
+    · connectors/
+        · __init__.py
+        · datadis.py           # Conector API Datadis
+        · redata.py            # Conector API REData (PVPC)
+    · models/
+        · __init__.py
+        · base.py              # Modelos base con Pydantic
+        · supply.py            # Modelo de suministros
+        · contract.py          # Modelo de contratos
+        · consumption.py       # Modelo de consumos
+        · maximeter.py         # Modelo de maxímetro
+        · pricing.py           # Modelo de reglas de precios
+        · database.py          # Modelos para SQLite
+    · services/
+        · __init__.py
+        · database.py          # Servicio de base de datos SQLite
+        · supply.py            # Gestión de suministros
+        · contract.py          # Gestión de contratos
+        · consumption.py       # Gestión de consumos
+        · maximeter.py         # Gestión de maxímetro
+        · billing.py           # Gestión de facturación
+    · scripts/
+        · __init__.py
+        · dump.py              # Script interactivo de descarga
+```
+
+## Script interactivo
+
+El paquete incluye un script interactivo que facilita la descarga inicial de datos:
+
+```bash
+# Ejecutar el script interactivo
+python -m edata.scripts.dump
+
+# Con directorio personalizado
+python -m edata.scripts.dump --storage-dir /ruta/personalizada
+```
+
+Este script te guiará paso a paso para:
+1. Configurar credenciales de Datadis
+2. Seleccionar el suministro a procesar
+3. Definir el rango de fechas
+4. Descargar y almacenar todos los datos
+
+## Ejemplo de uso
+
+Partimos de que tenemos credenciales en Datadis.es. Algunas aclaraciones:
+* No es necesario solicitar API pública en el registro (se utilizará la API privada habilitada por defecto)
+* El username suele ser el NIF del titular
+* Copie el CUPS de la web de Datadis, algunas comercializadoras adhieren caracteres adicionales en el CUPS mostrado en su factura.
+* La herramienta acepta el uso de NIF autorizado para consultar el suministro de otro titular.
+
+``` python
+import asyncio
+from datetime import datetime
+import json
+
+# importamos el modelo de reglas de tarificación
+from edata.models.pricing import PricingRules
+# importamos el helper principal
+from edata.helpers import EdataHelper
+# importamos utilidades para serialización
+from edata import utils
+
+# Preparar reglas de tarificación (si se quiere)
+PRICING_RULES_PVPC = PricingRules(
+    p1_kw_year_eur=30.67266,
+    p2_kw_year_eur=1.4243591,
+    meter_month_eur=0.81,
+    market_kw_year_eur=3.113,
+    electricity_tax=1.0511300560,
+    iva_tax=1.05,
+    # podemos rellenar los siguientes campos si quisiéramos precio fijo (y no pvpc)
+    p1_kwh_eur=None,
+    p2_kwh_eur=None,
+    p3_kwh_eur=None,
+)
+
+async def main():
+    # Instanciar el helper
+    # 'datadis_authorized_nif' permite indicar el NIF de la persona que nos autoriza a consultar su CUPS.
+    # 'storage_dir_path' permite especificar dónde almacenar la base de datos local
+    edata = EdataHelper(
+                "datadis_user",
+                "datadis_password",
+                "cups",
+                datadis_authorized_nif=None,
+                pricing_rules=PRICING_RULES_PVPC, # si se le pasa None, no aplica tarificación
+                storage_dir_path=None, # por defecto usa ./edata.storage/
+            )
+
+    # Solicitar actualización de todo el histórico (los datos se almacenan en SQLite)
+    success = await edata.update(date_from=datetime(1970, 1, 1), date_to=datetime.today())
+    
+    if success:
+        # Imprimir atributos resumen calculados
+        print("Atributos calculados:")
+        for key, value in edata.attributes.items():
+            if value is not None:
+                print(f"  {key}: {value}")
+        
+        # Los datos se almacenan automáticamente en la base de datos SQLite
+        # ubicada en edata.storage/edata.db (por defecto)
+        print(f"\nDatos almacenados en la base de datos local")
+    else:
+        print("Error durante la actualización de datos")
+
+# Ejecutar el ejemplo
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Contribuir
+
+Este proyecto está en desarrollo activo. Las contribuciones son bienvenidas:
+
+1. Fork del repositorio
+2. Crear una rama para tu feature: `git checkout -b feature/nueva-funcionalidad`
+3. Commit de tus cambios: `git commit -am 'Añadir nueva funcionalidad'`
+4. Push a la rama: `git push origin feature/nueva-funcionalidad`
+5. Crear un Pull Request
+
+## Licencia
+
+Este proyecto está licenciado bajo GPLv3. Ver el archivo [LICENSE](LICENSE) para más detalles.

e_data-2.0.0b1/README.md

@@ -0,0 +1,166 @@
+[![Downloads](https://pepy.tech/badge/e-data)](https://pepy.tech/project/e-data)
+[![Downloads](https://pepy.tech/badge/e-data/month)](https://pepy.tech/project/e-data)
+[![Downloads](https://pepy.tech/badge/e-data/week)](https://pepy.tech/project/e-data)
+
+# python-edata
+
+Este paquete proporciona herramientas para la descarga de tus datos de consumo eléctrico (desde Datadis.es) y su posterior procesado. La motivación principal es que conocer el consumo puede ayudarnos a reducirlo, e incluso a elegir una tarifa que mejor se adapte a nuestras necesidades. A día de hoy sus capacidades de facturación (€) son limitadas, soporta PVPC (según disponibilidad de datos de REData) y tarificación fija por tramos. Es el corazón de la integración [homeassistant-edata](https://github.com/uvejota/homeassistant-edata).
+
+_**Esta herramienta no mantiene ningún tipo de vinculación con los proveedores de datos anteriormente mencionados, simplemente consulta la información disponible y facilita su posterior análisis.**_
+
+## Instalación
+
+Puedes instalar la última versión estable mediante:
+
+``` bash
+pip install e-data
+```
+
+Si quieres probar la versión `dev` o contribuir a su desarrollo, clona este repositorio e instala manualmente las dependencias:
+
+``` bash
+make install-dev
+```
+
+## Estructura
+
+El paquete utiliza una **arquitectura basada en servicios** con los siguientes módulos:
+
+* **Conectores** (módulo `connectors`), para definir los métodos de consulta a los diferentes proveedores: Datadis y REData.
+* **Modelos** (módulo `models`), que definen las estructuras de datos usando Pydantic v2 para validación robusta. Incluye modelos para suministros, contratos, consumos, maxímetro, precios y base de datos.
+* **Servicios** (módulo `services`), que implementan la lógica de negocio para cada dominio: gestión de suministros, contratos, consumos, maxímetro, facturación y base de datos SQLite.
+* **Helper principal** (`helpers.py`), que orquesta todos los servicios y proporciona una interfaz simplificada. El `EdataHelper` permite descargar y procesar datos automáticamente, calculando más de 40 atributos de resumen.
+
+Estos módulos corresponden a la siguiente estructura del paquete:
+
+```
+edata/
+    · __init__.py
+    · const.py                  # Constantes y definiciones de atributos
+    · utils.py                  # Utilidades generales
+    · helpers.py                # Helper principal (EdataHelper)
+    · connectors/
+        · __init__.py
+        · datadis.py           # Conector API Datadis
+        · redata.py            # Conector API REData (PVPC)
+    · models/
+        · __init__.py
+        · base.py              # Modelos base con Pydantic
+        · supply.py            # Modelo de suministros
+        · contract.py          # Modelo de contratos
+        · consumption.py       # Modelo de consumos
+        · maximeter.py         # Modelo de maxímetro
+        · pricing.py           # Modelo de reglas de precios
+        · database.py          # Modelos para SQLite
+    · services/
+        · __init__.py
+        · database.py          # Servicio de base de datos SQLite
+        · supply.py            # Gestión de suministros
+        · contract.py          # Gestión de contratos
+        · consumption.py       # Gestión de consumos
+        · maximeter.py         # Gestión de maxímetro
+        · billing.py           # Gestión de facturación
+    · scripts/
+        · __init__.py
+        · dump.py              # Script interactivo de descarga
+```
+
+## Script interactivo
+
+El paquete incluye un script interactivo que facilita la descarga inicial de datos:
+
+```bash
+# Ejecutar el script interactivo
+python -m edata.scripts.dump
+
+# Con directorio personalizado
+python -m edata.scripts.dump --storage-dir /ruta/personalizada
+```
+
+Este script te guiará paso a paso para:
+1. Configurar credenciales de Datadis
+2. Seleccionar el suministro a procesar
+3. Definir el rango de fechas
+4. Descargar y almacenar todos los datos
+
+## Ejemplo de uso
+
+Partimos de que tenemos credenciales en Datadis.es. Algunas aclaraciones:
+* No es necesario solicitar API pública en el registro (se utilizará la API privada habilitada por defecto)
+* El username suele ser el NIF del titular
+* Copie el CUPS de la web de Datadis, algunas comercializadoras adhieren caracteres adicionales en el CUPS mostrado en su factura.
+* La herramienta acepta el uso de NIF autorizado para consultar el suministro de otro titular.
+
+``` python
+import asyncio
+from datetime import datetime
+import json
+
+# importamos el modelo de reglas de tarificación
+from edata.models.pricing import PricingRules
+# importamos el helper principal
+from edata.helpers import EdataHelper
+# importamos utilidades para serialización
+from edata import utils
+
+# Preparar reglas de tarificación (si se quiere)
+PRICING_RULES_PVPC = PricingRules(
+    p1_kw_year_eur=30.67266,
+    p2_kw_year_eur=1.4243591,
+    meter_month_eur=0.81,
+    market_kw_year_eur=3.113,
+    electricity_tax=1.0511300560,
+    iva_tax=1.05,
+    # podemos rellenar los siguientes campos si quisiéramos precio fijo (y no pvpc)
+    p1_kwh_eur=None,
+    p2_kwh_eur=None,
+    p3_kwh_eur=None,
+)
+
+async def main():
+    # Instanciar el helper
+    # 'datadis_authorized_nif' permite indicar el NIF de la persona que nos autoriza a consultar su CUPS.
+    # 'storage_dir_path' permite especificar dónde almacenar la base de datos local
+    edata = EdataHelper(
+                "datadis_user",
+                "datadis_password",
+                "cups",
+                datadis_authorized_nif=None,
+                pricing_rules=PRICING_RULES_PVPC, # si se le pasa None, no aplica tarificación
+                storage_dir_path=None, # por defecto usa ./edata.storage/
+            )
+
+    # Solicitar actualización de todo el histórico (los datos se almacenan en SQLite)
+    success = await edata.update(date_from=datetime(1970, 1, 1), date_to=datetime.today())
+    
+    if success:
+        # Imprimir atributos resumen calculados
+        print("Atributos calculados:")
+        for key, value in edata.attributes.items():
+            if value is not None:
+                print(f"  {key}: {value}")
+        
+        # Los datos se almacenan automáticamente en la base de datos SQLite
+        # ubicada en edata.storage/edata.db (por defecto)
+        print(f"\nDatos almacenados en la base de datos local")
+    else:
+        print("Error durante la actualización de datos")
+
+# Ejecutar el ejemplo
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Contribuir
+
+Este proyecto está en desarrollo activo. Las contribuciones son bienvenidas:
+
+1. Fork del repositorio
+2. Crear una rama para tu feature: `git checkout -b feature/nueva-funcionalidad`
+3. Commit de tus cambios: `git commit -am 'Añadir nueva funcionalidad'`
+4. Push a la rama: `git push origin feature/nueva-funcionalidad`
+5. Crear un Pull Request
+
+## Licencia
+
+Este proyecto está licenciado bajo GPLv3. Ver el archivo [LICENSE](LICENSE) para más detalles.

e_data-2.0.0b1/e_data.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+.python-version
+LICENSE
+MANIFEST.in
+Makefile
+README.md
+pyproject.toml
+edata/__init__.py
+edata/const.py
+edata/helpers.py
+edata/utils.py
+edata/tests/__init__.py
+edata/tests/test_helpers.py
+edata/tests/connectors/__init__.py
+edata/tests/connectors/test_datadis_connector.py
+edata/tests/connectors/test_redata_connector.py
+edata/tests/services/__init__.py
+edata/tests/services/test_billing_service.py
+edata/tests/services/test_consumption_service.py
+edata/tests/services/test_contract_service.py
+edata/tests/services/test_database_service.py
+edata/tests/services/test_maximeter_service.py
+edata/tests/services/test_supply_service.py

e_data-2.0.0b1/edata/const.py

@@ -0,0 +1,56 @@
+"""Constants file."""
+
+PROG_NAME = "edata"
+DEFAULT_STORAGE_DIR = "edata.storage"
+
+# Attributes definition for backward compatibility
+ATTRIBUTES = {
+    "cups": None,
+    "contract_p1_kW": "kW",
+    "contract_p2_kW": "kW",
+    "yesterday_kWh": "kWh",
+    "yesterday_hours": "h",
+    "yesterday_p1_kWh": "kWh",
+    "yesterday_p2_kWh": "kWh",
+    "yesterday_p3_kWh": "kWh",
+    "yesterday_surplus_kWh": "kWh",
+    "yesterday_surplus_p1_kWh": "kWh",
+    "yesterday_surplus_p2_kWh": "kWh",
+    "yesterday_surplus_p3_kWh": "kWh",
+    "last_registered_date": None,
+    "last_registered_day_kWh": "kWh",
+    "last_registered_day_hours": "h",
+    "last_registered_day_p1_kWh": "kWh",
+    "last_registered_day_p2_kWh": "kWh",
+    "last_registered_day_p3_kWh": "kWh",
+    "last_registered_day_surplus_kWh": "kWh",
+    "last_registered_day_surplus_p1_kWh": "kWh",
+    "last_registered_day_surplus_p2_kWh": "kWh",
+    "last_registered_day_surplus_p3_kWh": "kWh",
+    "month_kWh": "kWh",
+    "month_daily_kWh": "kWh",
+    "month_days": "d",
+    "month_p1_kWh": "kWh",
+    "month_p2_kWh": "kWh",
+    "month_p3_kWh": "kWh",
+    "month_surplus_kWh": "kWh",
+    "month_surplus_p1_kWh": "kWh",
+    "month_surplus_p2_kWh": "kWh",
+    "month_surplus_p3_kWh": "kWh",
+    "month_€": "€",
+    "last_month_kWh": "kWh",
+    "last_month_daily_kWh": "kWh",
+    "last_month_days": "d",
+    "last_month_p1_kWh": "kWh",
+    "last_month_p2_kWh": "kWh",
+    "last_month_p3_kWh": "kWh",
+    "last_month_surplus_kWh": "kWh",
+    "last_month_surplus_p1_kWh": "kWh",
+    "last_month_surplus_p2_kWh": "kWh",
+    "last_month_surplus_p3_kWh": "kWh",
+    "last_month_€": "€",
+    "max_power_kW": "kW",
+    "max_power_date": None,
+    "max_power_mean_kW": "kW",
+    "max_power_90perc_kW": "kW",
+}