python-esios 0.1.0__tar.gz

python-esios-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.1
+Name: python-esios
+Version: 0.1.0
+Summary: A Python wrapper for the ESIOS API
+Home-page: https://github.com/datons/python-esios
+Author: Jesús López
+Author-email: jesus.lopez@datons.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pandas
+
+# ESIOS
+
+ESIOS is a Python library that wraps the ESIOS API and returns preprocessed data as Pandas DataFrames.
+
+## Overview
+
+This library provides a simple interface to interact with the ESIOS API, allowing you to fetch and process indicator data.
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install python-esios
+```
+
+## Usage
+
+Visit the [instructions here](https://github.com/datons/python-esios/blob/main/esios/endpoints/indicators/README.ipynb) and learn how to use the library.

python-esios-0.1.0/README.md

@@ -0,0 +1,19 @@
+# ESIOS
+
+ESIOS is a Python library that wraps the ESIOS API and returns preprocessed data as Pandas DataFrames.
+
+## Overview
+
+This library provides a simple interface to interact with the ESIOS API, allowing you to fetch and process indicator data.
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install python-esios
+```
+
+## Usage
+
+Visit the [instructions here](https://github.com/datons/python-esios/blob/main/esios/endpoints/indicators/README.ipynb) and learn how to use the library.

python-esios-0.1.0/esios/api_client.py

@@ -0,0 +1,19 @@
+import requests
+
+class APIClient:
+    base_url = 'https://api.esios.ree.es'
+    headers = {
+        'Accept': "application/json; application/vnd.esios-api-v1+json",
+        'Content-Type': "application/json",
+        'Host': 'api.esios.ree.es',
+    }
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.headers['x-api-key'] = self.api_key
+
+    def _api_call(self, method, endpoint, params=None, data=None):
+        url = self.base_url + endpoint
+        response = requests.request(method, url, headers=self.headers, params=params, json=data)
+        response.raise_for_status()
+        return response

python-esios-0.1.0/esios/endpoints/__init__.py

@@ -0,0 +1,3 @@
+from .indicators import Indicators
+
+__all__ = ['Indicators']

python-esios-0.1.0/esios/endpoints/archives/archives.py

@@ -0,0 +1,32 @@
+import os
+import pandas as pd
+from esios.api_client import APIClient
+from esios.utils import preprocessing
+
+class Archives(APIClient):
+    def __init__(self, api_key):
+        super().__init__(api_key)
+
+    def list(self, params=None):
+        endpoint = "/archives"
+        response = self._api_call('GET', endpoint)
+        return response.json()
+
+    def get(self, archive_id, params=None, write_home=None):
+        endpoint = f"/archives/{archive_id}/download"
+        response = self._api_call('GET', endpoint, params=params)
+
+        if write_home:
+            path = os.path.join(write_home, f'{archive_id}.zip')
+            with open(path, 'wb') as f:
+                f.write(response.content)
+            preprocessing.unzip_files_and_remove(path)
+
+        return ArchiveData(response.content)
+
+class ArchiveData:
+    def __init__(self, data):
+        self.data = data
+
+    def to_pandas(self):
+        return pd.DataFrame(self.data)

python-esios-0.1.0/esios/endpoints/indicators/__init__.py

@@ -0,0 +1,143 @@
+import pandas as pd
+from esios.api_client import APIClient
+import html
+from bs4 import BeautifulSoup
+
+class Indicators(APIClient):
+    def __init__(self, api_key):
+        super().__init__(api_key)
+    
+    def list(self, df=False):
+        """
+        Fetches a list of indicators.
+
+        Parameters
+        ----------
+        params : dict, optional
+            URL parameters to be sent with the request.
+
+        Returns
+        -------
+        list
+            A list of indicators.
+        """
+        endpoint = "/indicators"
+        response = self._api_call('GET', endpoint)
+        
+        data = response.json()
+        
+        if df:
+            df = pd.DataFrame(data['indicators'])
+            df['description'] = df['description'].apply(html.unescape)
+            df
+            return df.set_index('id')
+        else:
+            return data
+
+    def get(self, indicator_id, start_date=None, end_date=None, geo_ids=None, locale=None, time_agg=None, geo_agg=None, time_trunc=None, geo_trunc=None):
+        """
+        Fetches disaggregated indicator data optionally filtered by a date range and geo_ids,
+        grouped by geo_id and month, using specified aggregation settings. All parameters except
+        the indicator_id are optional.
+
+        Parameters
+        ----------
+        indicator_id : int
+            The ID of the indicator to fetch data for.
+        start_date : str, optional
+            The start date of the data range in ISO 8601 format (YYYY-MM-DD).
+        end_date : str, optional
+            The end date of the data range in ISO 8601 format (YYYY-MM-DD).
+        geo_ids : list of int, optional
+            A list of geographic IDs to filter the data by.
+        locale : str, optional, default 'es'
+            Language for translations. Defaults to Spanish ('es'). Can be 'es' for Spanish or 'en' for English.
+        time_agg : str, optional, default 'average'
+            Specifies how to aggregate the data over time. Typical values are 'average', 'sum', etc.
+        geo_agg : str, optional, default 'average'
+            Specifies how to aggregate the data geographically. Typical values are 'average', 'sum', etc.
+        time_trunc : str, optional
+            Specifies how to truncate the data time series. Typical values are 'day', 'month', 'year', etc.
+        geo_trunc : str, optional
+            Specifies how to group data at the geolocalization level. Typical values are 'province', 'region', etc.
+
+        Returns
+        -------
+        IndicatorData
+            An instance of IndicatorData containing the fetched data.
+        """
+        
+        params = {}
+        if start_date:
+            params['start_date'] = start_date
+        if end_date:
+            params['end_date'] = end_date + 'T23:59:59'
+        if geo_ids:
+            params['geo_ids'] = ','.join(map(str, geo_ids))
+        if locale:
+            params['locale'] = locale
+        if time_agg:
+            params['time_agg'] = time_agg
+        if geo_agg:
+            params['geo_agg'] = geo_agg
+        if time_trunc:
+            params['time_trunc'] = time_trunc
+        if geo_trunc:
+            params['geo_trunc'] = geo_trunc
+
+        endpoint = f"/indicators/{indicator_id}"
+        response = self._api_call('GET', endpoint, params=params)
+        return IndicatorData(response.json())
+
+class IndicatorData:
+    def __init__(self, data):
+        self.data = data
+
+    def to_dataframe(self, column_name='value'):
+        """
+        Converts the indicator values data to a Pandas DataFrame.
+
+        Parameters
+        -------
+        column_name : {'value', 'id', 'short_name'}, default 'value'
+            
+        Returns
+        -------
+        pandas.DataFrame
+            A DataFrame containing the indicator values.
+        """
+        data = self.data.get('indicator', {})
+        values = data.get('values', [])
+        
+        if values:
+            df = pd.DataFrame(values)
+            df = df.set_index('datetime')
+            df.index = pd.to_datetime(df.index, utc=True)
+            
+            columns = df.columns
+            mask = columns.str.contains('time')
+            
+            df.drop(columns=columns[mask], inplace=True)
+            
+            if column_name != 'value':
+                df = df.rename(columns={'value': data[column_name]})
+            
+            return df.tz_convert('Europe/Madrid')
+        else:
+            return pd.DataFrame()
+
+    def get_metadata(self):
+        """
+        Extracts metadata from the indicator data.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the metadata of the indicator.
+        """
+        
+        # extract all inside indicator key, except values
+        metadata = self.data.get('indicator', {})
+        metadata.pop('values', None)
+        
+        return metadata

python-esios-0.1.0/esios/tests/test_api_client.py

@@ -0,0 +1,15 @@
+import unittest
+from esios.api_client import APIClient
+
+class TestAPIClient(unittest.TestCase):
+
+    def setUp(self):
+        self.api_client = APIClient(api_key="test_key")
+
+    def test_api_call(self):
+        # This test is just a placeholder
+        # You would mock requests and test _api_call
+        pass
+
+if __name__ == '__main__':
+    unittest.main()

python-esios-0.1.0/esios/tests/test_indicators.py

@@ -0,0 +1,20 @@
+import unittest
+from esios.endpoints.indicators import Indicators
+
+class TestIndicators(unittest.TestCase):
+
+    def setUp(self):
+        self.indicators_client = Indicators(api_key="test_key")
+
+    def test_list(self):
+        # This test is just a placeholder
+        # You would mock requests and test the list method
+        pass
+
+    def test_get(self):
+        # This test is just a placeholder
+        # You would mock requests and test the get method
+        pass
+
+if __name__ == '__main__':
+    unittest.main()

python-esios-0.1.0/python_esios.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.1
+Name: python-esios
+Version: 0.1.0
+Summary: A Python wrapper for the ESIOS API
+Home-page: https://github.com/datons/python-esios
+Author: Jesús López
+Author-email: jesus.lopez@datons.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pandas
+
+# ESIOS
+
+ESIOS is a Python library that wraps the ESIOS API and returns preprocessed data as Pandas DataFrames.
+
+## Overview
+
+This library provides a simple interface to interact with the ESIOS API, allowing you to fetch and process indicator data.
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install python-esios
+```
+
+## Usage
+
+Visit the [instructions here](https://github.com/datons/python-esios/blob/main/esios/endpoints/indicators/README.ipynb) and learn how to use the library.

python-esios-0.1.0/python_esios.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+setup.py
+esios/__init__.py
+esios/api_client.py
+esios/endpoints/__init__.py
+esios/endpoints/archives/__init__.py
+esios/endpoints/archives/archives.py
+esios/endpoints/indicators/__init__.py
+esios/tests/__init__.py
+esios/tests/test_api_client.py
+esios/tests/test_indicators.py
+python_esios.egg-info/PKG-INFO
+python_esios.egg-info/SOURCES.txt
+python_esios.egg-info/dependency_links.txt
+python_esios.egg-info/requires.txt
+python_esios.egg-info/top_level.txt

python-esios-0.1.0/python_esios.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

python-esios-0.1.0/python_esios.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests
+pandas

python-esios-0.1.0/python_esios.egg-info/top_level.txt

@@ -0,0 +1 @@
+esios

python-esios-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python-esios-0.1.0/setup.py

@@ -0,0 +1,28 @@
+from setuptools import setup, find_packages
+
+
+from pathlib import Path
+this_directory = Path(__file__).parent
+long_description = (this_directory / "README.md").read_text(encoding='utf-8')
+
+setup(
+    name='python-esios',
+    version='0.1.0',
+    packages=find_packages(),
+    install_requires=[
+        'requests',
+        'pandas',
+    ],
+    author="Jesús López",
+    author_email="jesus.lopez@datons.ai",
+    description="A Python wrapper for the ESIOS API",
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    url="https://github.com/datons/python-esios",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.6',
+)