`curb_energy.client`¶

Client module for interacting with the Curb REST and Real-Time APIs

class curb_energy.client.AuthToken(access_token=None, refresh_token=None, expires_in=0, user_id=0, token_type='bearer')[source]¶

Curb API OAuth2 Token. For more information, refer to: <https://oauth.net/articles/authentication/>

__init__(access_token=None, refresh_token=None, expires_in=0, user_id=0, token_type='bearer')[source]¶

Create an AuthToken instance.

Parameters:	access_token (`Optional`[`str`]) – The access token refresh_token (`Optional`[`str`]) – The refresh token expires_in (`int`) – The time, in seconds, this token is valid for. user_id (`int`) – The unique ID of the user associated with this token token_type (`str`) – Bearer type

expiry¶

The expiration date of the token (in UTC)

Return type:	`datetime`
Returns:	Expiry date (in UTC)
Return type:	datetime.datetime

static from_json()[source]¶

Creates an AuthToken object from the given JSON payload.

Parameters:	data (`str`) – Token data
Return type:	`AuthToken`
Returns:	Creates an AuthToken instance from the given payload
Raises:	`ValueError`

json()[source]¶

Serializes the AuthToken into JSON

Return type:	`str`
Returns:	JSON version of the AuthToken

class curb_energy.client.RestApiClient(loop=None, username=None, password=None, auth_token=None, api_url='https://app.energycurb.com', client_token='CHANGE_ME', client_secret='CHANGE_ME', ssl_context=None)[source]¶

A client for the Curb REST API

__init__(loop=None, username=None, password=None, auth_token=None, api_url='https://app.energycurb.com', client_token='CHANGE_ME', client_secret='CHANGE_ME', ssl_context=None)[source]¶

Initialize the REST API client.

The Curb API uses Oauth2 authentication. An access token can be fetched by supplying a valid username and password as credentials. Subsequent authentication with the API will be done using the Oauth2 token in the form of AuthToken.

You can also pass an existing token instead of a username/password.

Parameters:

username (Optional[str]) – Username
password (Optional[str]) – Password
auth_token (Optional[AuthToken]) – Oauth2 client token
api_url (str) – The URL to the Curb REST API
client_token (str) – The application client token (app identifier)
client_secret (str) – The application client secret (app password)
ssl_context (Optional[SSLContext]) – Optional SSL

Warning

As a client to the Curb REST API, you MUST provide your own client_token and client_secret which identifies the APPLICATION you are developing. This is separate from the username/password or access token that identifies the USER accessing their data.

See <http://docs.energycurb.com/authentication.html> for more info. You’ll need to contact the Curb Support Team at <http://energycurb.com/support/> for assistance.

Example:

async with RestApiClient(username=user,
                         password=pass, 
                         client_token='CHANGE_ME', 
                         client_secret='CHANGE_ME') as client:
    profiles = await client.profiles()
    devices = await client.devices()

    for profile in profiles:
        print(profile)

    for device in devices:
        print(device)

Or more traditionally:

client = RestApiClient(username=user,
                       password=pass, 
                       client_token='CHANGE_ME',
                       client_secret='CHANGE_ME')
try:
    # Fetch and set the access token
    await client.authenticate()
    
    # code goes here
    
finally:
    await client.session.close()            

auth_token¶

The AuthToken associated with the REST API session

Return type:	`AuthToken`
Returns:	The AuthToken associated with the session

authenticate()[source]¶

Authenticates with the REST API by fetching an access token, raising an exception on failure. The access token is stored as a property. This method is automatically called when the client is used as a context manager.

Return type:	`AuthToken`
Returns:	The authentication token
Raises:	`CurbBaseException`

devices()[source]¶

Return a list of devices associated with the authenticated user

Return type:	`List`[`Device`]
Returns:	A list of devices

entry_point()[source]¶

Return the resources the authenticated user has access to, namely Profiles and Devices. This is automatically called when the client is used as a context manager.

Return type:	`Dict`[~KT, ~VT]
Returns:	a dict of links to the Profiles and Devices

fetch_access_token(client_token=None, client_secret=None, username=None, password=None)[source]¶

Fetches an access token using the given credentials. The supplied parameters override the original credentials passed to instance of the REST API client.

Parameters:	client_token (`Optional`[`str`]) – The OAuth Client Token (app identifier) client_secret (`Optional`[`str`]) – The OAuth Client Secret (app password) username (`Optional`[`str`]) – The username to authenticate with password (`Optional`[`str`]) – The password to authenticate with
Return type:	`Optional`[`AuthToken`]
Returns:	Returns the access token after authentication

historical_data(profile_id=0, granularity='1H', unit='$/hr', since=0, until=None)[source]¶

Return all recorded measurements for the given profile.

Parameters:	profile_id (`int`) – The profile configuration granularity (`str`) – Per Minute, Per Hour (default), or Per Day unit (`str`) – Dollars Per Hour, or Watts (default) since (`int`) – Start time of measurements (in epoch format). Use 0 to indicate the beginning, which is the default. until (`Optional`[`int`]) – End time of measurements (in epoch format)
Return type:	`Measurement`

profiles()[source]¶

Return a list of profiles associated with the authenticated user.

Return type:	`List`[`Profile`]
Returns:	A list of profiles

refresh_access_token()[source]¶

Get a new access token using an existing refresh token and associated user ID. All other access tokens are immediately invalidated. When calling this method, auth_token is automatically set to the new token.

Return type:	`AuthToken`
Returns:	a new access token
Raises:	`CurbBaseException` when `auth_token` is not set

class curb_energy.client.RealTimeClient(config, driver=<class 'hbmqtt.client.MQTTClient'>)[source]¶

A client to the Curb Energy Real-Time Streaming API

Todo

Refactor to support different access mechanisms. For now, we’re limited to using MQTT over WebSockets

__init__(config, driver=<class 'hbmqtt.client.MQTTClient'>)[source]¶

Create an instance of RealTimeClient.

Parameters:	config (`RealTimeConfig`) – Real Time Config driver (`Callable`) – Real Time client driver

Example:

client = RealTimeClient(config)
await client.connect()
while condition:
    data = await client.stream()
await client.disconnect()

Used as a context manager:

async with RealTimeClient(config) as client:
    while condition:
        data = await client.stream()        

config¶

Returns the configuration parameters for the client.

Return type:	`RealTimeConfig`

connect()[source]¶: Connect to the Real-time API

disconnect()[source]¶: Disconnect from the Real-time API

is_connected¶

Returns True if the real-time client has successfully established a connection with the Real-Time API, False otherwise.

Return type:	`bool`

read()[source]¶

Returns a single stream from the real-time API, or None when an error occurs. This may raise a ValueError when the returned data is invalid JSON.

Return type:	`RealTimeMessage`
Returns:	Returns measurements
Raises:	`ValueError`

class curb_energy.client.RealTimeMessage(timestamp, measurements)¶

measurements¶: Alias for field number 1

timestamp¶: Alias for field number 0

curb_energy.client¶

`curb_energy.client`¶