API documentation¶

pyecotrend_ista.PyEcotrendIsta ¶

PyEcotrendIsta(email: str, password: str, totp: str | None = None, session: Session | None = None)

A Python client for interacting with the ista EcoTrend API.

This class provides methods to authenticate and interact with the ista EcoTrend API.

Attributes:

_account (AccountResponse) –

The account information.
_uuid (str) –

The UUID of the consumption unit.
_access_token (str | None) –

The access token for API authentication.
_refresh_token (str | None) –

The refresh token for obtaining new access tokens.
_access_token_expires_in (int) –

The expiration time of the access token.
_header (dict[str, str]) –

The headers used in HTTP requests.
_support_code (str | None) –

The support code for the account.
_start_timer (float) –

The start time for tracking elapsed time.

Examples:

Initialize the client and log in:

>>> client = PyEcotrendIsta(email="user@example.com", password="password")
>>> client.login()

Parameters:

email ¶
(str) –

The email address used to log in to the ista EcoTrend API.
password ¶
(str) –

The password used to log in to the ista EcoTrend API.
totp ¶
(str, default: None ) –

An optional TOTP (Time-based One-Time Password) for two-factor authentication. Default is None.
session ¶
(Session, default: None ) –

An optional requests session for making HTTP requests. Default is None.

Methods:

get_version –

Get the version of the PyEcotrendIsta client.
login –

Perform the login process if not already connected or forced.
userinfo –

Retrieve user information using the provided access token.
logout –

Perform logout operation by invalidating the current session.
get_uuids –

Retrieve UUIDs of consumption units registered in the account.
consum_raw –

Process and filter consumption and cost data for a given consumption unit.
get_consumption_data –

Fetch consumption data from the API for a specific consumption unit.
get_consumption_unit_details –

Retrieve details of the consumption unit from the API.
get_support_code –

Return the support code associated with the instance.
get_user_agent –

Return the User-Agent string used for HTTP requests.
demo_user_login –

Retrieve authentication tokens for the demo user.
get_account –

Retrieve the account information.

access_token `property` `writable` ¶

access_token

Retrieve the access token, refreshing it if necessary.

This property checks if the access token is still valid. If the token has expired and the client is connected, it refreshes the token. The token is considered expired if the current time minus the start time exceeds the token's expiration period.

Returns:

str –

The current access token.

Notes

This method will automatically refresh the access token if it has expired.

__login ¶

__login() -> str | None

Perform the login process to obtain an access token.

If the email is a demo account, it logs in using a demo user login function. For other accounts, it retrieves a token using a login helper.

Returns:

str or None –

The access token if login is successful, None otherwise.

__refresh ¶

__refresh() -> None

Refresh the access token using the refresh token.

This method retrieves a new access token, updates internal variables, and resets the token expiration timer.

Raises:

ParserError –

If there is an error parsing the request response.
LoginError –

If there is an authorization failure.
ServerError –

If there is a server error, connection timeout, or request exception.

Notes

This method assumes self._refresh_token is already set.

__set_account ¶

__set_account() -> None

Fetch and set account information from the API.

This method performs an API request to retrieve account information, handles various potential errors that might occur during the request, and sets instance variables accordingly using the response data.

Raises:

ParserError –

If there is an error parsing the JSON response.
LoginError –

If the request fails due to an authorization error.
ServerError –

If the request fails due to a server error, timeout, or other request exceptions.

get_version ¶

get_version() -> str

Get the version of the PyEcotrendIsta client.

Returns:

str –

The version number of the PyEcotrendIsta client.

login ¶

login(**kwargs) -> str | None

Perform the login process if not already connected or forced.

Returns:

str or None –

The access token if login is successful, None otherwise.

Raises:

LoginError –

If the login process fails due to an error.
ServerError –

If a server error occurs during login attempts.
InternalServerError –

If an internal server error occurs during login attempts.
Exception –

For any other unexpected errors during the login process.

userinfo ¶

userinfo(token)

Retrieve user information using the provided access token.

This method constructs an authorization header using the provided access token and sends a GET request to the userinfo endpoint of the provider API. It expects a JSON response with user information.

Parameters:

token ¶
(str) –

The access token used for authentication.

Returns:

Any –

JSON response containing user information.

Raises:

RequestException –

If an error occurs while making the HTTP request.

Notes

This method constructs an authorization header using the provided access token and sends a GET request to the userinfo endpoint of the provider API. It expects a JSON response with user information.

Examples:

>>> client = PyEcotrendIsta(email="user@example.com", password="password")
>>> token = client.login()
>>> user_info = client.userinfo(token)

logout ¶

logout() -> None

Perform logout operation by invalidating the current session.

This method invokes the logout functionality in the loginhelper module, passing the current refresh token for session invalidation.

Raises:

KeycloakPostError –
If an error occurs during the logout process. This error is raised based on the response from the logout request. –

Notes

This method assumes self._refresh_token is already set.

Examples:

>>> client = PyEcotrendIsta(email="user@example.com", password="password")
>>> client.login()
>>> client.logout()

get_uuids ¶

get_uuids() -> list[str]

Retrieve UUIDs of consumption units registered in the account.

Returns:

list[str] –

A list containing UUIDs of consumption units. Each UUID represents a consumption unit, which could be a flat or a house for which consumption readings are provided.

Notes

A consumption unit represents a residence or building where consumption readings are recorded. The UUIDs are extracted from the _residentAndConsumptionUuidsMap attribute.

Examples:

>>> client = PyEcotrendIsta(email="user@example.com", password="password")
>>> client.login()
>>> uuids = client.get_uuids()
>>> print(uuids)
['uuid1', 'uuid2', 'uuid3']

consum_raw ¶

consum_raw(select_year: list[int] | None = None, select_month: list[int] | None = None, filter_none: bool = True, obj_uuid: str | None = None) -> dict[str, Any] | ConsumptionsResponse

Process and filter consumption and cost data for a given consumption unit.

This method processes consumption and cost data obtained from the get_consumption_data method. It filters and aggregates data based on the parameters provided.

Parameters:

select_year ¶
(list[int] | None, default: None ) –

List of years to filter data by year, default is None.
select_month ¶
(list[int] | None, default: None ) –

List of months to filter data by month, default is None.
filter_none ¶
(bool, default: True ) –

Whether to filter out None values in readings, default is True.
obj_uuid ¶
(str | None, default: None ) –

UUID of the consumption unit to fetch data for, default is None.

Returns:

dict[str, Any] | ConsumptionsResponse –

Processed data including consumption types, total additional values, last values, last costs, sum by year, and last year compared consumption.

Raises:

Exception –

If there is an unexpected error during data processing.

Notes

This method processes consumption and cost data obtained from the get_consumption_data method. It filters and aggregates data based on the parameters provided.

Examples:

>>> api = PyEcotrendIsta()
>>> result = api.consum_raw(select_year=[2023], select_month=[7], filter_none=True, obj_uuid="uuid")
>>> print(result)

get_consumption_data ¶

get_consumption_data(obj_uuid: str | None = None) -> ConsumptionsResponse

Fetch consumption data from the API for a specific consumption unit.

This method sends a GET request to the ista EcoTrend API to retrieve consumption data for a specific consumption unit identified by the provided UUID. If no UUID is provided, the method uses the UUID associated with the instance.

Parameters:

obj_uuid ¶
(str, default: None ) –

The UUID of the consumption unit. If not provided, defaults to the UUID associated with the instance (self._uuid).

Returns:

ConsumptionsResponse –

A dictionary containing the consumption data fetched from the API.

Raises:

LoginError –

If the API responds with an error indicating authorization failure.
ParserError –

If there is an error parsing the request response.
ValueError –

If the provided UUID is invalid.
ServerError –

If there is a server error, connection timeout, or request exception.

Examples:

>>> api = PyEcotrendIsta()
>>> data = api.get_consumption_data(obj_uuid="uuid")
>>> print(data)

get_consumption_unit_details ¶

get_consumption_unit_details() -> ConsumptionUnitDetailsResponse

Retrieve details of the consumption unit from the API.

Returns:

ConsumptionUnitDetailsResponse –

A dictionary containing the details of the consumption unit.

Raises:

LoginError –

If the API responds with an authorization failure.
ParserError –

If there is an issue with decoding the JSON response
ServerError –

If there is a server error, connection timeout, or request exception.

get_support_code ¶

get_support_code() -> str | None

Return the support code associated with the instance.

Returns:

str or None –

The support code associated with the instance, or None if not set.

get_user_agent ¶

get_user_agent() -> str

Return the User-Agent string used for HTTP requests.

Returns:

str –

The User-Agent string.

Notes

This method provides a static User-Agent string commonly used for web browsers.

demo_user_login ¶

demo_user_login() -> GetTokenResponse

Retrieve authentication tokens for the demo user.

Returns:

GetTokenResponse –

A TypedDict containing authentication tokens including 'accessToken', 'accessTokenExpiresIn', and 'refreshToken'.

Raises:

ParserError –

If there is an error parsing the request response.
ServerError –

If there is a server error, connection timeout, or request exception.

get_account ¶

get_account() -> AccountResponse | None

Retrieve the account information.

Returns the _account attribute if it exists, otherwise returns None.

Returns:

AccountResponse | None –

Account information if available, otherwise None.

API documentation¶

pyecotrend_ista.PyEcotrendIsta ¶

`email` ¶

`password` ¶

`totp` ¶

`session` ¶

access_token `property` `writable` ¶

__login ¶

__refresh ¶

__set_account ¶

get_version ¶

userinfo ¶

`token` ¶

logout ¶

get_uuids ¶

consum_raw ¶

`select_year` ¶

`select_month` ¶

`filter_none` ¶

`obj_uuid` ¶

get_consumption_data ¶

`obj_uuid` ¶

get_consumption_unit_details ¶

get_support_code ¶

get_user_agent ¶

demo_user_login ¶

get_account ¶

API documentation¶

pyecotrend_ista.PyEcotrendIsta ¶

email ¶

password ¶

totp ¶

session ¶

access_token property writable ¶

__login ¶

__refresh ¶

__set_account ¶

get_version ¶

login ¶

userinfo ¶

token ¶

logout ¶

get_uuids ¶

consum_raw ¶

select_year ¶

select_month ¶

filter_none ¶

obj_uuid ¶

get_consumption_data ¶

obj_uuid ¶

get_consumption_unit_details ¶

get_support_code ¶

get_user_agent ¶

demo_user_login ¶

get_account ¶

`email` ¶

`password` ¶

`totp` ¶

`session` ¶

access_token `property` `writable` ¶

`token` ¶

`select_year` ¶

`select_month` ¶

`filter_none` ¶

`obj_uuid` ¶

`obj_uuid` ¶