An asyncio-based Python3 library for interacting with WattTime
Project description
🌎 aiowatttime: an asyncio-based, Python3 library for WattTime emissions data
aiowatttime
is a Python 3, asyncio-friendly library for interacting with
WattTime emissions data.
Python Versions
aiowatttime
is currently supported on:
- Python 3.8
- Python 3.9
Installation
pip install aiowatttime
Usage
Getting an API Key
Simply clone this repo and run the included interactive script:
$ script/register
Note that WattTime offers three plans: Visitors, Analyst, and Pro. The type you use will determine which elements of this library are available to use. You can read more details here: https://www.watttime.org/get-the-data/data-plans/
Creating and Using a Client
The Client
is the primary method of interacting with the API:
import asyncio
from aiowatttime import Client
async def main() -> None:
client = await Client.login("<USERNAME>", "<PASSWORD>")
# ...
asyncio.run(main())
By default, the library creates a new connection to the API with each coroutine. If
you are calling a large number of coroutines (or merely want to squeeze out every second of runtime savings possible), an
aiohttp
ClientSession
can be used for connection
pooling:
import asyncio
from aiohttp import ClientSession
from aiowatttime import Client
async def main() -> None:
async with ClientSession() as session:
client = await Client.login("<USERNAME>", "<PASSWORD>", session=session)
# ...
asyncio.run(main())
Programmatically Requesting a Password Reset
await client.async_request_password_reset()
Getting Emissions Data
Grid Region
It may be useful to first get the "grid region" (i.e., geographical info) for the area you care about:
await client.emissions.async_get_grid_region("<LATITUDE>", "<LONGITUDE>")
# >>> { "id": 263, "abbrev": "PJM_NJ", "name": "PJM New Jersey" }
Getting emissions data will require either your latitude/longitude or the "balancing
authority abbreviation" (PJM_NJ
in the example above).
Realtime Data
await client.emissions.async_get_realtime_emissions("<LATITUDE>", "<LONGITUDE>")
# >>> { "freq": "300", "ba": "CAISO_NORTH", "percent": "53", "moer": "850.743982", ... }
Forecasted Data
await client.emissions.async_get_forecasted_emissions("<BA_ABBREVATION>")
# >>> [ { "generated_at": "2021-08-05T09:05:00+00:00", "forecast": [...] } ]
You can also get the forecasted data using a specific start and end datetime.datetime
:
from datetime import datetime
await client.emissions.async_get_forecasted_emissions(
"<BA_ABBREVATION>",
start_datetime=datetime(2021, 1, 1),
end_datetime=datetime(2021, 2, 1),
)
# >>> [ { "generated_at": "2021-08-05T09:05:00+00:00", "forecast": [...] } ]
Historical Data
await client.emissions.async_get_historical_emissions("<LATITUDE>", "<LONGITUDE>")
# >>> [ { "point_time": "2019-02-21T00:15:00.000Z", "value": 844, ... } ]
You can also get the historical data using a specific start and end datetime.datetime
:
from datetime import datetime
await client.emissions.async_get_historical_emissions(
"<LATITUDE>",
"<LONGITUDE>"
start_datetime=datetime(2021, 1, 1),
end_datetime=datetime(2021, 2, 1),
)
# >>> [ { "point_time": "2019-02-21T00:15:00.000Z", "value": 844, ... } ]
Contributing
- Check for open features/bugs or initiate a discussion on one.
- Fork the repository.
- (optional, but highly recommended) Create a virtual environment:
python3 -m venv .venv
- (optional, but highly recommended) Enter the virtual environment:
source ./venv/bin/activate
- Install the dev environment:
script/setup
- Code your new feature or bug fix.
- Write tests that cover your new functionality.
- Run tests and ensure 100% code coverage:
script/test
- Update
README.md
with any new documentation. - Add yourself to
AUTHORS.md
. - Submit a pull request!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aiowatttime-0.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1df05f26036a268f1bc87b24b95c6d1493da9e254f6b166eaadc0cbf31413f02 |
|
MD5 | 5b2ff8b0b57c5bb6db2bad9bb6700e07 |
|
BLAKE2b-256 | eb02e99f88e4a881b2d34b06da9eaaaf8d7f0f22daae3ac03257c608b3383ec2 |