enappsys 0.1.0__tar.gz

enappsys-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

enappsys-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: enappsys
+Version: 0.1.0
+Summary: The EnAppSys Python client provides a light-weight client that allows for simple access to EnAppSys' API services.
+Author-email: Silvan Murre <silvan.murre@montel.energy>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Provides-Extra: async
+Requires-Dist: aiohttp; extra == "async"
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: enappsys[async]; extra == "dev"
+Requires-Dist: enappsys[pandas]; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# EnAppSys Python Client
+
+The Python library for the [EnAppSys](https://app.enappsys.com) platform provides a light-weight Python client to interact with EnAppSys' API services. Additionally, there is an asynchronous client for non-blocking operations.
+
+## Installation
+
+Supports Python 3.7+.
+
+```bash
+pip install enappsys[async,pandas]
+```
+
+The extras are optional:
+
+- `async` required for using the `EnAppSysAsync` asynchronous client.
+- `pandas` required for converting API responses to DataFrames, e.g. via `client_response.to_df()`
+
+If you only need the synchronous client and raw responses, install without extras:
+
+```bash
+pip install enappsys
+```
+
+### Configuring credentials
+
+Your EnAppSys username and secret are required to make API requests. You can obtain these as follows:
+
+1. Go to any download page on EnAppSys and click **Copy API URL**.
+2. In the copied URL:
+
+    - The value after `user=` is your **username**.
+    - The value after `pass=` is your **secret** (a long numeric string).
+
+
+The client looks for credentials in the following order:
+
+1. **Direct arguments** when creating the client:
+
+    ```python
+    from enappsys import EnAppSys
+
+    client = EnAppSys(
+        user="example_user",
+        secret="123456789123456789123456789123456789"
+    )
+    ```
+    
+2. **Environment variables**:
+
+    ```bash
+    export ENAPPSYS_USER=example_user
+    export ENAPPSYS_SECRET=123456789123456789123456789123456789
+    ```
+
+3. **Credentials file** at your home directory, the default location is: `~/.credentials/enappsys.json`:
+
+    ```json
+    {
+        "user": "example_user",
+        "secret": "123456789123456789123456789123456789"
+    }
+    ```
+
+    You can also save and specify a custom path:
+
+    ```python
+    client = EnAppSys(credentials_file="path/to/credentials.json")
+    ```
+
+
+### Development
+
+Install in editable mode:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+Install the commit hooks:
+
+```bash
+pre-commit install
+```

enappsys-0.1.0/README.md

@@ -0,0 +1,83 @@
+# EnAppSys Python Client
+
+The Python library for the [EnAppSys](https://app.enappsys.com) platform provides a light-weight Python client to interact with EnAppSys' API services. Additionally, there is an asynchronous client for non-blocking operations.
+
+## Installation
+
+Supports Python 3.7+.
+
+```bash
+pip install enappsys[async,pandas]
+```
+
+The extras are optional:
+
+- `async` required for using the `EnAppSysAsync` asynchronous client.
+- `pandas` required for converting API responses to DataFrames, e.g. via `client_response.to_df()`
+
+If you only need the synchronous client and raw responses, install without extras:
+
+```bash
+pip install enappsys
+```
+
+### Configuring credentials
+
+Your EnAppSys username and secret are required to make API requests. You can obtain these as follows:
+
+1. Go to any download page on EnAppSys and click **Copy API URL**.
+2. In the copied URL:
+
+    - The value after `user=` is your **username**.
+    - The value after `pass=` is your **secret** (a long numeric string).
+
+
+The client looks for credentials in the following order:
+
+1. **Direct arguments** when creating the client:
+
+    ```python
+    from enappsys import EnAppSys
+
+    client = EnAppSys(
+        user="example_user",
+        secret="123456789123456789123456789123456789"
+    )
+    ```
+    
+2. **Environment variables**:
+
+    ```bash
+    export ENAPPSYS_USER=example_user
+    export ENAPPSYS_SECRET=123456789123456789123456789123456789
+    ```
+
+3. **Credentials file** at your home directory, the default location is: `~/.credentials/enappsys.json`:
+
+    ```json
+    {
+        "user": "example_user",
+        "secret": "123456789123456789123456789123456789"
+    }
+    ```
+
+    You can also save and specify a custom path:
+
+    ```python
+    client = EnAppSys(credentials_file="path/to/credentials.json")
+    ```
+
+
+### Development
+
+Install in editable mode:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+Install the commit hooks:
+
+```bash
+pre-commit install
+```

enappsys-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "enappsys"
+authors = [
+    {name = "Silvan Murre", email = "silvan.murre@montel.energy"},
+]
+description = """The EnAppSys Python client provides a light-weight client that allows for simple access to EnAppSys' API services."""
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "requests",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+async = [
+    "aiohttp"
+]
+pandas = [
+    "pandas"
+]
+dev = [
+    "enappsys[async]",
+    "enappsys[pandas]",
+    "pre-commit",
+    "pytest-asyncio",
+    "pytest-benchmark",
+    "pytest",
+    "ruff",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.dynamic]
+version = {attr = "enappsys.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

enappsys-0.1.0/setup.cfg

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

enappsys-0.1.0/src/enappsys/__init__.py

@@ -0,0 +1,9 @@
+"""
+The EnAppSys Python client provides a light-weight client that allows for simple access
+to EnAppSys' API services.
+"""
+
+__version__ = "0.1.0"
+
+from .client import EnAppSys as EnAppSys
+from .client_async import EnAppSysAsync as EnAppSysAsync

enappsys-0.1.0/src/enappsys/client.py

@@ -0,0 +1,60 @@
+from .services.bulk import BulkAPI
+from .services.chart import ChartAPI
+from .services.price_volume_curve import PriceVolumeCurveAPI
+from .session import Session
+
+
+class EnAppSys:
+    def __init__(
+        self,
+        user: str | None = None,
+        secret: str | None = None,
+        credentials_file: str | None = None,
+        max_retries: int = 3
+    ):
+        """
+        Client interface for the EnAppSys API.
+
+        Provides convenient access to the various service endpoints through dedicated 
+        interfaces for bulk data retrieval, chart data, and price-volume curves.
+
+        This client handles authentication, request validation, chunked retrieval
+        for large datasets, automatic retries, and rate limiting.
+
+        Parameters
+        ----------
+        user : str | None, optional
+            EnAppSys username for authentication.
+        secret : str | None, optional
+            EnAppSys secret associated with the username.
+        credentials_file: str | None, optional
+            Path to a credentials file containing the user and secret.
+            Defaults to ``~/.credentials/enappsys.json``.
+        max_retries : int, default=3
+            Maximum number of retry attempts for failed HTTP requests.
+        """
+        self._session = Session(user, secret, credentials_file, max_retries)
+
+        # --- Public members ---
+        self.bulk = BulkAPI(self)
+        """An instance of :class:`BulkAPI`.
+        
+        Provides access to the Bulk API for retrieving time series data,
+        such as generation, demand, and price data.
+        """
+
+        self.chart = ChartAPI(self)
+        """
+        An instance of :class:`ChartAPI`.
+        
+        Provides access to the Chart API for retrieving time series data 
+        from charts.
+        """
+
+        self.price_volume_curve = PriceVolumeCurveAPI(self)
+        """
+        An instance of :class:`PriceVolumeCurveAPI`.
+        
+        Provides access to the Price Volume Curve API for retrieving 
+        price volume curves from charts.
+        """

enappsys-0.1.0/src/enappsys/client_async.py

@@ -0,0 +1,65 @@
+from typing import Literal, Union
+
+from .enum import AppEnvEnum
+from .services_async.bulk import AsyncBulkAPI
+from .services_async.chart import AsyncChartAPI
+from .services_async.price_volume_curve import AsyncPriceVolumeCurveAPI
+from .session_async import AsyncSession
+
+
+class EnAppSysAsync:
+    def __init__(
+        self,
+        user: str | None = None,
+        secret: str | None = None,
+        credentials_file: str | None = None,
+        max_retries: int = 3
+    ):
+        """Client for the EnAppSys API.
+
+        Parameters
+        ----------
+        user : str | None, optional
+            EnAppSys username.
+        secret : str | None, optional
+            EnAppSys secret.
+        credentials_file: str | None, optional
+            Specify path to the credentials file to have it at another place
+            than ~/.enappsys/api_credentials.json
+        profile_name : str | None, optional
+            Specify the profile name to load credentials from. If it is not found,
+            the ``default`` profile name will be used.
+        """
+        self._session = AsyncSession(
+            user, secret, credentials_file, max_retries
+        )
+
+        # --- Public members ---
+        self.bulk = AsyncBulkAPI(self)
+        """An instance of :class:`BulkAPI`.
+        
+        Provides the interface for retrieving time series data.
+        """
+
+        self.chart = AsyncChartAPI(self)
+        """
+        An instance of :class:`ChartAPI`.
+        
+        Provides the interface for retrieving data from a chart.
+        """
+
+        self.price_volume_curve = AsyncPriceVolumeCurveAPI(self)
+        """
+        An instance of :class:`PriceVolumeCurveAPI`.
+        
+        Provides the interface for retrieving price volume curve data.
+        """
+
+    async def aclose(self) -> None:
+        await self._session.close()
+
+    async def __aenter__(self) -> "EnAppSysAsync":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()

enappsys-0.1.0/src/enappsys/credentials.py

@@ -0,0 +1,101 @@
+import json
+import logging
+import os
+
+from pathlib import Path
+
+from .exceptions import (
+    NoCredentialsError,
+    PartialCredentialsError,
+    InvalidCredentialsFile,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Credentials:
+    """Holds the credentials needed to authenticate requests."""
+
+    def __init__(
+        self,
+        user: str | None = None,
+        secret: str | None = None,
+        credentials_file: str | None = None
+    ) -> None:
+        """Initialize a :class:`Credentials` instance.
+
+        The EnAppSys client will look for credentials in the following order:
+        explicitly passed arguments, environment variables or a credentials file.
+
+        Parameters
+        ----------
+        user : str | None, optional
+            EnAppSys username.
+        secret : str | None, optional
+            EnAppSys secret.
+        credentials_file: str | None, optional
+            Specify path to the credentials file to have it at another place
+            than ~/.enappsys/api_credentials.json
+        """
+        self.user = user
+        self.secret = secret
+        self.credentials_file = credentials_file
+        self.method = None
+
+        if (
+            not self._set_with_explicit_args()
+            and not self._set_with_environment_vars()
+            and not self._set_with_config_file()
+        ):
+            raise NoCredentialsError()
+
+        self.api_format = {"user": self.user, "pass": self.secret}
+
+    def _set_with_explicit_args(self) -> bool:
+        self.method = "explicit arguments"
+
+        return self._validate_credentials()
+
+    def _set_with_environment_vars(self) -> bool:
+        self.method = "environment variables"
+
+        self.user = self.user or os.getenv("ENAPPSYS_USER")
+        self.secret = self.secret or os.getenv("ENAPPSYS_SECRET")
+
+        return self._validate_credentials()
+
+    def _set_with_config_file(self) -> bool:
+        self.method = "credentials file"
+
+        self.credentials_file = (
+            self.credentials_file or Path.home() / ".credentials" / "enappsys.json"
+        )
+
+        try:
+            with open(self.credentials_file, mode="r", encoding="utf-8") as f:
+                credentials = json.load(f)
+        except IOError as e:
+            raise InvalidCredentialsFile(
+                f"Could not retrieve credentials from '{self.credentials_file}'. "
+                f"Reason: {e}"
+            ) from e
+
+        self.user = credentials.get("user")
+        self.secret = credentials.get("secret")
+
+        if not self.user or not self.secret:
+            raise InvalidCredentialsFile(
+                f"Invalid format in credentials file '{self.credentials_file}'. "
+                f"Expected keys: 'user' and 'secret'. Got: {list(credentials.keys())}"
+            )
+        
+        return self._validate_credentials()
+
+    def _validate_credentials(self) -> str | None:
+        if not self.user and not self.secret:
+            return False
+        elif self.user and not self.secret:
+            raise PartialCredentialsError(provider=self.method, cred_var="secret")
+        elif self.secret and not self.user:
+            raise PartialCredentialsError(provider=self.method, cred_var="user")
+        return True

enappsys-0.1.0/src/enappsys/enum.py

@@ -0,0 +1,139 @@
+from datetime import timedelta
+from enum import Enum
+from typing import Union
+
+from .exceptions import ValidationError
+
+
+class BaseEnum(Enum):
+    """Base Enum that resolves a member by matching any of its public attributes."""
+
+    @classmethod
+    def _from_value(cls, value: Union[str, int, float, bool, Enum, object]):
+        """Return the Enum member matching any of its public attribute values.
+
+        Accepts either:
+        - the Enum member itself
+        - any attribute value belonging to one of the Enum members
+        """
+        if isinstance(value, cls):
+            return value
+
+        # Iterate through all members and their public attributes
+        for member in cls:
+            for attr, attr_value in member.__dict__.items():
+                if attr.startswith("_"):
+                    continue
+                if attr_value == value:
+                    return member
+
+        # no match found → raise informative error
+        value_type = type(value).__name__
+        public_attrs = {
+            m.name: {k: v for k, v in m.__dict__.items() if not k.startswith("_")}
+            for m in cls
+        }
+        raise ValidationError(
+            reason=(
+                f"No match for {value!r} ({value_type}) in {cls.__name__}. "
+                f"Checked attributes:\n{public_attrs}"
+            )
+        )
+
+
+class AppEnvEnum(BaseEnum):
+    APP = ("app", "https://app.enappsys.com")
+    APPQA = ("appqa", "https://appqa.enappsys.com")
+    APPDEV = ("appdev", "https://appdev.enappsys.com")
+
+    def __init__(self, platform, app_env_url):
+        self.platform = platform
+        self.app_env_url = app_env_url
+
+
+class ResponseFormatEnum(BaseEnum):
+    JSON = ("json", "jsonapi", "json", "JSON")
+    JSON_MAP = ("json_map", "jsonmapapi", "json_map", None)
+    CSV = ("csv", "csvapi", "csv", "CSV")
+    XML = ("xml", "xmlapi", "xml", "XML")
+
+    def __init__(self, platform, bulk_url, chart_tag, epex_tag):
+        self.platform = platform
+        self.bulk_url = bulk_url
+        self.chart_tag = chart_tag
+        self.epex_tag = epex_tag
+
+
+class ResolutionEnum(BaseEnum):
+    """Supported temporal resolutions with platform, ISO 8601, pandas and timedelta."""
+
+    PT1S = ("1s", "PT1S", "s", timedelta(seconds=1))
+    PT15S = ("15s", "PT15S", "15s", timedelta(seconds=15))
+    PT1M = ("min", "PT1M", "min", timedelta(minutes=1))
+    PT5M = ("5min", "PT5M", "5min", timedelta(minutes=5))
+    PT15M = ("qh", "PT15M", "15min", timedelta(minutes=15))
+    PT30M = ("hh", "PT30M", "30min", timedelta(minutes=30))
+    PT1H = ("hourly", "PT1H", "h", timedelta(hours=1))
+    PT3H = ("3hourly", "PT3H", "3h", timedelta(hours=3))
+    PT6H = ("6hourly", "PT6H", "6h", timedelta(hours=6))
+    PT12H = ("12hourly", "PT12H", "12h", timedelta(hours=12))
+    P1D = ("daily", "P1D", "D", timedelta(days=1))
+    P1W = ("weekly", "P1W", "W", timedelta(weeks=1))
+    P1M = ("monthly", "P1M", "M", timedelta(days=30))
+    P1Y = ("yearly", "P1Y", "Y", timedelta(days=365))
+
+    def __init__(self, platform: str, iso: str, pandas: str, delta: timedelta):
+        self.platform = platform
+        self.iso = iso
+        self.pandas = pandas
+        self.delta = delta
+
+
+class TimeZoneEnum(BaseEnum):
+    UTC = "UTC"
+    WET = "WET"
+    CET = "CET"
+    EET = "EET"
+
+    def __init__(self, platform):
+        self.platform = platform
+
+
+class CurrencyEnum(BaseEnum):
+    BAM = "BAM"
+    BGN = "BGN"
+    CAD = "CAD"
+    CHF = "CHF"
+    CNY = "CNY"
+    CZK = "CZK"
+    DKK = "DKK"
+    EUR = "EUR"
+    EURCENTS = "EURcents"
+    GBP = "GBP"
+    GBPPENCE = "GBPpence"
+    HKD = "HKD"
+    HRK = "HRK"
+    HUF = "HUF"
+    JPY = "JPY"
+    NOK = "NOK"
+    PLN = "PLN"
+    RON = "RON"
+    RUB = "RUB"
+    SEK = "SEK"
+    SGD = "SGD"
+    TRY = "TRY"
+    USD = "USD"
+
+    def __init__(self, platform):
+        self.platform = platform
+
+
+class DelimiterEnum(BaseEnum):
+    COMMA = ("comma", ",")
+    TAB = ("tab", "")
+    SEMICOLON = ("semicolon", ";")
+    PIPE = ("pipe", "|")
+
+    def __init__(self, platform, character):
+        self.platform = platform
+        self.character = character