gridstatusio 0.1.0__tar.gz

gridstatusio-0.1.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2022 James Max Kanter
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

gridstatusio-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.1
+Name: gridstatusio
+Version: 0.1.0
+Summary: Python Client for GridStatus.io API
+Author-email: Max Kanter <kmax12@gmail.com>
+Maintainer-email: Max Kanter <kmax12@gmail.com>
+License: Copyright 2022 James Max Kanter
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Source Code, https://github.com/kmax12/gridstatusio/
+Project-URL: Issue Tracker, https://github.com/kmax12/gridstatusio/issues
+Keywords: energy,independent system operator
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: <4,>=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Provides-Extra: dev
+License-File: LICENSE
+
+# GridStatus.io Hosted API
+
+Python client for accessing the [GridStatusIO API](https://www.gridstatus.io/api).
+
+## Installation
+
+Install the library using pip:
+
+```bash
+pip install gridstatusio
+```
+
+
+## Usage
+
+### Set API Key
+To use the library, first set your API key:
+
+```python
+import gridstatusio as gs
+
+gs.api_key  = '<YOUR-API-KEY>'
+```
+
+if you don't have an API, request one [here](https://www.gridstatus.io/api). 
+
+### List available datasets
+
+```python
+gs.list_datasets()
+```
+
+### Get specific date
+
+Request a dataset at a specific date
+
+```python
+gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    date="2023-01-01",
+)
+```
+
+### Get data range
+
+```python
+df = gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    start="2023-01-01",
+    end="2023-01-05",
+    verbose=True,
+)
+```
+
+## Get Help
+
+We'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io

gridstatusio-0.1.0/README.md

@@ -0,0 +1,57 @@
+# GridStatus.io Hosted API
+
+Python client for accessing the [GridStatusIO API](https://www.gridstatus.io/api).
+
+## Installation
+
+Install the library using pip:
+
+```bash
+pip install gridstatusio
+```
+
+
+## Usage
+
+### Set API Key
+To use the library, first set your API key:
+
+```python
+import gridstatusio as gs
+
+gs.api_key  = '<YOUR-API-KEY>'
+```
+
+if you don't have an API, request one [here](https://www.gridstatus.io/api). 
+
+### List available datasets
+
+```python
+gs.list_datasets()
+```
+
+### Get specific date
+
+Request a dataset at a specific date
+
+```python
+gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    date="2023-01-01",
+)
+```
+
+### Get data range
+
+```python
+df = gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    start="2023-01-01",
+    end="2023-01-05",
+    verbose=True,
+)
+```
+
+## Get Help
+
+We'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io

gridstatusio-0.1.0/gridstatusio/__init__.py

@@ -0,0 +1,3 @@
+from gridstatusio.version import __version__
+
+from gridstatusio.api import *

gridstatusio-0.1.0/gridstatusio/api.py

@@ -0,0 +1,116 @@
+from io import StringIO
+
+import pandas as pd
+import requests
+import tqdm
+
+API_BASE = "https://data.gridstatus.io"
+
+# decorator that requieres kwargs
+
+
+def require_only_kwargs(func):
+    def wrapper(*args, **kwargs):
+        if len(args) > 0:
+            raise TypeError("Please use only keyword arguments.")
+        return func(**kwargs)
+
+    return wrapper
+
+
+def get_api_key():
+    import gridstatusio as gs
+
+    try:
+        return gs.api_key
+    except AttributeError:
+        raise AttributeError(
+            "API key not set. Please set the api_key attribute.",
+        )
+
+
+def _make_request(url, verbose=False):
+    """Make a request to the GridStatus.io API."""
+    if verbose:
+        print("Requesting: {}".format(url))
+
+    headers = {"x-api-key": get_api_key()}
+    response = requests.get(url, headers=headers)
+
+    return response
+
+
+@require_only_kwargs
+def _get_single_csv_dataset(dataset: str, date, verbose=False):
+    """Get a single dataset from the GridStatus.io API."""
+    if date:
+        date_str = date.strftime("%Y-%m-%d")
+        url = "{}/{}/archive/{}.csv".format(API_BASE, dataset, date_str)
+    else:
+        url = "{}/{}/latest.csv".format(API_BASE, dataset)
+
+    response = _make_request(url, verbose=verbose)
+    df = pd.read_csv(StringIO(response.text))
+
+    if "Time" in df.columns:
+        df["Time"] = pd.to_datetime(df["Time"])
+        df = df.set_index("Time")
+
+    return df
+
+
+@require_only_kwargs
+def get_dataset(dataset: str, date=None, start=None, end=None, verbose=False):
+    """Get a dataset from the GridStatus.io API.
+
+    Args:
+        dataset (str): The dataset to get. For example, "isone/fuel_mix_clean".
+        date (str): The date to get. For example, "2020-01-01".
+        start (str): The start date to get. For example, "2020-01-01".
+        end (str): The end date to get. For example, "2020-01-05".
+        verbose (bool): Whether to print verbose output.
+
+    Returns:
+        pandas.DataFrame: The dataset.
+    """
+
+    # require either date or start and end
+    if date is None and (start is None or end is None):
+        raise TypeError("Please provide either date or start and end.")
+
+    if date is not None:
+        date = pd.to_datetime(date)
+        return _get_single_csv_dataset(
+            dataset=dataset,
+            date=date,
+            verbose=verbose,
+        )
+
+    dfs = []
+    dates = pd.date_range(start, end).tolist()
+    for date in tqdm.tqdm(dates):
+        df = _get_single_csv_dataset(
+            dataset=dataset,
+            date=date,
+            verbose=verbose,
+        )
+        dfs.append(df)
+
+    return pd.concat(dfs)
+
+
+def list_datasets(verbose=False):
+    """List all datasets available on the GridStatus.io API."""
+    dataset_availability = "datasets/historical_data_availability"
+
+    df = _get_single_csv_dataset(
+        dataset=dataset_availability,
+        date=None,
+        verbose=verbose,
+    )
+
+    df["dataset"] = df["iso"] + "/" + df["dataset"]
+    df = df[~df["hidden"]]
+    df.drop(["iso", "hidden"], axis=1, inplace=True)
+
+    return df

gridstatusio-0.1.0/gridstatusio/tests/test_api.py

@@ -0,0 +1,63 @@
+import pandas as pd
+import pytest
+
+import gridstatusio as gs
+
+
+def _check_dataframe(df):
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) > 0
+
+
+def test_api_key_must_be_set():
+    with pytest.raises(AttributeError):
+        gs.get_api_key()
+
+
+def test_set_api_works():
+    gs.api_key = "test"
+    assert gs.get_api_key() == "test"
+
+
+# todo test require_only_kwargs
+
+
+def test_get_dataset_date():
+    gs.api_key = "TQfPZ3zOQ65Z7AbI1jMsMaLJvjcwAuyG85WjKNJI"
+
+    df = gs.get_dataset(
+        dataset="isone/fuel_mix_clean",
+        date="2023-01-01",
+    )
+
+    _check_dataframe(df)
+
+
+def test_get_dataset_date_range():
+    gs.api_key = "TQfPZ3zOQ65Z7AbI1jMsMaLJvjcwAuyG85WjKNJI"
+
+    df = gs.get_dataset(
+        dataset="isone/fuel_mix_clean",
+        start="2023-01-01",
+        end="2023-01-05",
+        verbose=True,
+    )
+
+    _check_dataframe(df)
+
+
+def test_list_datasets():
+    gs.api_key = "TQfPZ3zOQ65Z7AbI1jMsMaLJvjcwAuyG85WjKNJI"
+
+    df = gs.list_datasets()
+
+    cols = [
+        "dataset",
+        "earliest",
+        "latest",
+        "num_missing",
+        "earliest_no_missing",
+        "missing",
+    ]
+
+    assert df.columns.tolist() == cols

gridstatusio-0.1.0/gridstatusio/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gridstatusio-0.1.0/gridstatusio.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.1
+Name: gridstatusio
+Version: 0.1.0
+Summary: Python Client for GridStatus.io API
+Author-email: Max Kanter <kmax12@gmail.com>
+Maintainer-email: Max Kanter <kmax12@gmail.com>
+License: Copyright 2022 James Max Kanter
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Source Code, https://github.com/kmax12/gridstatusio/
+Project-URL: Issue Tracker, https://github.com/kmax12/gridstatusio/issues
+Keywords: energy,independent system operator
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: <4,>=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Provides-Extra: dev
+License-File: LICENSE
+
+# GridStatus.io Hosted API
+
+Python client for accessing the [GridStatusIO API](https://www.gridstatus.io/api).
+
+## Installation
+
+Install the library using pip:
+
+```bash
+pip install gridstatusio
+```
+
+
+## Usage
+
+### Set API Key
+To use the library, first set your API key:
+
+```python
+import gridstatusio as gs
+
+gs.api_key  = '<YOUR-API-KEY>'
+```
+
+if you don't have an API, request one [here](https://www.gridstatus.io/api). 
+
+### List available datasets
+
+```python
+gs.list_datasets()
+```
+
+### Get specific date
+
+Request a dataset at a specific date
+
+```python
+gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    date="2023-01-01",
+)
+```
+
+### Get data range
+
+```python
+df = gs.get_dataset(
+    dataset="isone/fuel_mix_clean",
+    start="2023-01-01",
+    end="2023-01-05",
+    verbose=True,
+)
+```
+
+## Get Help
+
+We'd love to answer any usage or data access questions! Please let us know by emailing us at contact@gridstatus.io

gridstatusio-0.1.0/gridstatusio.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+gridstatusio/__init__.py
+gridstatusio/api.py
+gridstatusio/version.py
+gridstatusio.egg-info/PKG-INFO
+gridstatusio.egg-info/SOURCES.txt
+gridstatusio.egg-info/dependency_links.txt
+gridstatusio.egg-info/requires.txt
+gridstatusio.egg-info/top_level.txt
+gridstatusio/tests/__init__.py
+gridstatusio/tests/test_api.py

gridstatusio-0.1.0/gridstatusio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gridstatusio-0.1.0/gridstatusio.egg-info/requires.txt

@@ -0,0 +1,13 @@
+requests>=2.28.1
+pandas>=1.3.0
+tqdm>=4.64.1
+
+[dev]
+ruff==0.0.202
+black[jupyter]==22.12.0
+pre-commit==2.21.0
+
+[test]
+pytest==7.1.2
+pytest-xdist==3.0.2
+pytest-rerunfailures==10.3

gridstatusio-0.1.0/gridstatusio.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+gridstatusio

gridstatusio-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "gridstatusio"
+readme = { file = "README.md", content-type = "text/markdown" }
+description = "Python Client for GridStatus.io API"
+dynamic = ["version"]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+authors = [
+    {name="Max Kanter", email="kmax12@gmail.com"}
+]
+maintainers = [
+    {name="Max Kanter", email="kmax12@gmail.com"}
+]
+keywords = ["energy", "independent system operator"]
+license = {file = "LICENSE"}
+requires-python = ">=3.7,<4"
+dependencies = [
+    "requests >= 2.28.1",
+    "pandas >= 1.3.0",
+    "tqdm >= 4.64.1",
+]
+
+[project.urls]
+"Source Code"= "https://github.com/kmax12/gridstatusio/"
+"Issue Tracker" = "https://github.com/kmax12/gridstatusio/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest == 7.1.2",
+    "pytest-xdist == 3.0.2",
+    "pytest-rerunfailures == 10.3",
+]
+dev = [
+    "ruff == 0.0.202",
+    "black[jupyter] == 22.12.0",
+    "pre-commit == 2.21.0",
+]
+
+
+[tool.setuptools]
+include-package-data = true
+license-files = ["LICENSE"]
+
+[tool.setuptools.dynamic]
+version = {attr = "gridstatusio.version.__version__"}
+
+[tool.setuptools.packages.find]
+namespaces = true
+
+[tool.setuptools.package-data]
+"*" = [
+    "LICENSE",
+    "README.md",
+]
+[tool.setuptools.exclude-package-data]
+"*" = [
+    "* __pycache__",
+    "*.py[co]",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "gridstatusio/tests/*"
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+
+[build-system]
+requires = [
+    "setuptools >= 61",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 88
+ignore = []
+select = [
+    # Pyflakes
+    "F",
+    # Pycodestyle
+    "E",
+    "W",
+    # flake8-quotes
+    "Q",
+    # isort
+    "I001"
+]
+src = ["gridstatusio"]
+
+[tool.ruff.isort]
+known-first-party = ["gridstatusio"]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401", "E402", "F403", "F405", "E501", "I001"]

gridstatusio-0.1.0/setup.cfg

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