Metadata-Version: 2.1
Name: bchydro
Version: 0.8.0
Summary: BCHydro API
Home-page: https://github.com/emcniece/bchydro
Author: Eric McNiece
Author-email: emcniece@gmail.com
License: MIT
Download-URL: https://github.com/emcniece/bchydro/releases/latest/download/package.tar.gz
Keywords: bchydro
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
Requires-Dist: aiohttp (<=3.7.3)
Requires-Dist: beautifulsoup4 (<=4.9.3)
Requires-Dist: tenacity (<=6.3.1)
Requires-Dist: ratelimit (<=2.2.1)

# BCHydro API

[![PyPi version](https://img.shields.io/pypi/v/bchydro?logo=pypi&logoColor=lightgrey)](https://pypi.org/project/bchydro/) ![Tested Python versions](https://img.shields.io/pypi/pyversions/bchydro?logo=python&logoColor=lightgrey) [![PyPi publish](https://github.com/emcniece/bchydro/workflows/Publish%20PyPi/badge.svg)](https://github.com/emcniece/bchydro/actions?query=workflow%3A%22Publish+PyPi%22?event=release) ![PyPi downloads](https://img.shields.io/pypi/dm/bchydro) ![Dependency updates](https://img.shields.io/librariesio/github/emcniece/bchydro)

BCHydro Python API for extracting electricity usage statistics from your personal account.

## Installation

Via [PyPi](https://pypi.org/project/bchydro/):

```sh
pip install bchydro
```

Via Github:

```sh
# Fetch the code
git clone https://github.com/emcniece/bchydro.git
cd bchydro

# Set up environment

pip install -r requirements.txt

```

## Usage

Running the example script:

```sh
pip install bchydro

export BCH_USER=your.email@domain.com
export BCH_PASS=your-bch-password

python test.py
```

Using in a project:

```py
import asyncio
from bchydro import BCHydroApi

async def main():
    a = BCHydroApi("username", "password")

    usage = await a.get_usage(hourly=False)
    print(usage.electricity)
    print(a.get_latest_point())
    print(a.get_latest_usage())
    print(a.get_latest_cost())

asyncio.run(main())
```

#### ⚠ Read-Only Account Sharing

This project accesses your BCHydro account as would a human in a browser. It is recommended that a read-only account is set up for use with this project for more secure operation. Using this secondary account also enables backup access in the event of account lockout.

- Instructions for adding read-only accounts can be [found here](https://www.bchydro.com/news/conservation/2014/myhydro-sharing-access.html).
- Read-only accounts can be [configured here](https://app.bchydro.com/BCHCustomerPortal/web/accountAccessView.html) after logging in.



## Version Publishing

This repo is automatically published to [PyPi](https://pypi.org/project/bchydro/) by means of a [Github Workflow](https://github.com/emcniece/bchydro/actions?query=workflow%3A%22Publish+PyPi%22) when a new [release](https://github.com/emcniece/bchydro/releases) is created on Github.


### Maintenance

Dependencies can be updated with [pip-tools](https://github.com/jazzband/pip-tools):

```sh
# Install pip-compile and pip-sync
pip install pip-tools

# Upgrade requirements
pip-compile --upgrade
```


## Todo

- [x] Publish on release, not tag
- [x] Handle account locking (looks for HTML alert dialogs)
- [ ] Unit tests
- [x] Automatic initial and re-authentication
- [x] Rate limiting, auth retries
- [ ] Exception documentation


## Disclaimer

This package has been developed without the express permission of BC Hydro. It accesses data by submitting forms that end-users would typically use in a browser. I'd love to work with BC Hydro to find a better way to access this data, perhaps through an official API... if you know anyone that works there, pass this along!


