PyEcoTrend-ista¶

✨ Wishlist from Amazon ✨

Unofficial python library for the pyecotrend-ista API

pyecotrend_ista ¶

PyEcotrend Ista.

Modules:

const –

Constants for PyEcotrendIsta.
exception_classes –

Exception Class.
helper_object_de –

Dataclasses.
login_helper –

Login helper for Keycloak.
pyecotrend_ista –

Unofficial python library for the ista EcoTrend API.
types –

Types for PyEcotrendIsta.

Classes:

KeycloakAuthenticationError –

Keycloak authentication error exception.
KeycloakError –

Base class for custom Keycloak errors.
KeycloakGetError –

Keycloak request get error exception.
KeycloakInvalidTokenError –

Keycloak invalid token exception.
KeycloakOperationError –

Keycloak operation error exception.
KeycloakPostError –

Keycloak request post error exception.
LoginError –

Exception raised for login- and authentication related errors.
ParserError –

Exception raised for errors encountered during parsing.
ServerError –

Exception raised for server errors during requests.
PyEcotrendIsta –

A Python client for interacting with the ista EcoTrend API.
ConsumptionsResponse –

A TypedDict representing the response structure for consumption data.

KeycloakAuthenticationError ¶

KeycloakAuthenticationError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakAuthenticationError[KeycloakAuthenticationError]
              pyecotrend_ista.exception_classes.KeycloakError[KeycloakError]

                              pyecotrend_ista.exception_classes.KeycloakError --> pyecotrend_ista.KeycloakAuthenticationError
                


              click pyecotrend_ista.KeycloakAuthenticationError href "" "pyecotrend_ista.KeycloakAuthenticationError"
              click pyecotrend_ista.exception_classes.KeycloakError href "" "pyecotrend_ista.exception_classes.KeycloakError"

Keycloak authentication error exception.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

KeycloakError ¶

KeycloakError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakError[KeycloakError]

              

              click pyecotrend_ista.KeycloakError href "" "pyecotrend_ista.KeycloakError"

Base class for custom Keycloak errors.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

KeycloakGetError ¶

KeycloakGetError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakGetError[KeycloakGetError]
              pyecotrend_ista.exception_classes.KeycloakOperationError[KeycloakOperationError]
              pyecotrend_ista.exception_classes.KeycloakError[KeycloakError]

                              pyecotrend_ista.exception_classes.KeycloakOperationError --> pyecotrend_ista.KeycloakGetError
                                pyecotrend_ista.exception_classes.KeycloakError --> pyecotrend_ista.exception_classes.KeycloakOperationError
                



              click pyecotrend_ista.KeycloakGetError href "" "pyecotrend_ista.KeycloakGetError"
              click pyecotrend_ista.exception_classes.KeycloakOperationError href "" "pyecotrend_ista.exception_classes.KeycloakOperationError"
              click pyecotrend_ista.exception_classes.KeycloakError href "" "pyecotrend_ista.exception_classes.KeycloakError"

Keycloak request get error exception.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

KeycloakInvalidTokenError ¶

KeycloakInvalidTokenError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakInvalidTokenError[KeycloakInvalidTokenError]
              pyecotrend_ista.exception_classes.KeycloakOperationError[KeycloakOperationError]
              pyecotrend_ista.exception_classes.KeycloakError[KeycloakError]

                              pyecotrend_ista.exception_classes.KeycloakOperationError --> pyecotrend_ista.KeycloakInvalidTokenError
                                pyecotrend_ista.exception_classes.KeycloakError --> pyecotrend_ista.exception_classes.KeycloakOperationError
                



              click pyecotrend_ista.KeycloakInvalidTokenError href "" "pyecotrend_ista.KeycloakInvalidTokenError"
              click pyecotrend_ista.exception_classes.KeycloakOperationError href "" "pyecotrend_ista.exception_classes.KeycloakOperationError"
              click pyecotrend_ista.exception_classes.KeycloakError href "" "pyecotrend_ista.exception_classes.KeycloakError"

Keycloak invalid token exception.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

KeycloakOperationError ¶

KeycloakOperationError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakOperationError[KeycloakOperationError]
              pyecotrend_ista.exception_classes.KeycloakError[KeycloakError]

                              pyecotrend_ista.exception_classes.KeycloakError --> pyecotrend_ista.KeycloakOperationError
                


              click pyecotrend_ista.KeycloakOperationError href "" "pyecotrend_ista.KeycloakOperationError"
              click pyecotrend_ista.exception_classes.KeycloakError href "" "pyecotrend_ista.exception_classes.KeycloakError"

Keycloak operation error exception.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

KeycloakPostError ¶

KeycloakPostError(error_message='', response_code=None, response_body=None)


              flowchart TD
              pyecotrend_ista.KeycloakPostError[KeycloakPostError]
              pyecotrend_ista.exception_classes.KeycloakOperationError[KeycloakOperationError]
              pyecotrend_ista.exception_classes.KeycloakError[KeycloakError]

                              pyecotrend_ista.exception_classes.KeycloakOperationError --> pyecotrend_ista.KeycloakPostError
                                pyecotrend_ista.exception_classes.KeycloakError --> pyecotrend_ista.exception_classes.KeycloakOperationError
                



              click pyecotrend_ista.KeycloakPostError href "" "pyecotrend_ista.KeycloakPostError"
              click pyecotrend_ista.exception_classes.KeycloakOperationError href "" "pyecotrend_ista.exception_classes.KeycloakOperationError"
              click pyecotrend_ista.exception_classes.KeycloakError href "" "pyecotrend_ista.exception_classes.KeycloakError"

Keycloak request post error exception.

Parameters:

error_message ¶
(str, default: '' ) –

The error message (default is an empty string).
response_code ¶
(int, default: None ) –

The code of the response (default is None).
response_body ¶
(bytes, default: None ) –

Body of the response (default is None).

Methods:

__str__ –

Str method.

str ¶

__str__()

Str method.

Returns:

str –

String representation of the object.

LoginError ¶


              flowchart TD
              pyecotrend_ista.LoginError[LoginError]
              pyecotrend_ista.exception_classes.BaseError[BaseError]

                              pyecotrend_ista.exception_classes.BaseError --> pyecotrend_ista.LoginError
                


              click pyecotrend_ista.LoginError href "" "pyecotrend_ista.LoginError"
              click pyecotrend_ista.exception_classes.BaseError href "" "pyecotrend_ista.exception_classes.BaseError"

Exception raised for login- and authentication related errors.

This exception is raised when an authentication exception occurs during a request. It inherits from BaseError and is used specifically to handle issues related to authentication and login.

Methods:

__str__ –

Return a string representation of an authentication error.

str ¶

__str__() -> str

Return a string representation of an authentication error.

ParserError ¶


              flowchart TD
              pyecotrend_ista.ParserError[ParserError]
              pyecotrend_ista.exception_classes.ServerError[ServerError]
              pyecotrend_ista.exception_classes.BaseError[BaseError]

                              pyecotrend_ista.exception_classes.ServerError --> pyecotrend_ista.ParserError
                                pyecotrend_ista.exception_classes.BaseError --> pyecotrend_ista.exception_classes.ServerError
                



              click pyecotrend_ista.ParserError href "" "pyecotrend_ista.ParserError"
              click pyecotrend_ista.exception_classes.ServerError href "" "pyecotrend_ista.exception_classes.ServerError"
              click pyecotrend_ista.exception_classes.BaseError href "" "pyecotrend_ista.exception_classes.BaseError"

Exception raised for errors encountered during parsing.

This exception is raised when an error occurs during the parsing process of the request response. It inherits from BaseError and can be used to handle issues specifically related to parsing.

Methods:

__str__ –

Return a string representation of parser error.

str ¶

__str__() -> str

Return a string representation of parser error.

ServerError ¶


              flowchart TD
              pyecotrend_ista.ServerError[ServerError]
              pyecotrend_ista.exception_classes.BaseError[BaseError]

                              pyecotrend_ista.exception_classes.BaseError --> pyecotrend_ista.ServerError
                


              click pyecotrend_ista.ServerError href "" "pyecotrend_ista.ServerError"
              click pyecotrend_ista.exception_classes.BaseError href "" "pyecotrend_ista.exception_classes.BaseError"

Exception raised for server errors during requests.

This exception is raised when a exception occurs during a request. It inherits from BaseError and can be used to handle server-related issues specifically.

Methods:

__str__ –

Return a string representation of the error..

str ¶

__str__() -> str

Return a string representation of the error..

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.

ConsumptionsResponse ¶


              flowchart TD
              pyecotrend_ista.ConsumptionsResponse[ConsumptionsResponse]

              

              click pyecotrend_ista.ConsumptionsResponse href "" "pyecotrend_ista.ConsumptionsResponse"

A TypedDict representing the response structure for consumption data.

Attributes:

co2Emissions (list[IstaPeriods]) –

A list of CO2 emission data over different periods.
co2EmissionsBillingPeriods (list[IstaBillingPeriods]) –

A list of CO2 emission data over different billing periods.
consumptionUnitId (str) –

The unique identifier for the consumption unit.
consumptions (list[IstaPeriods]) –

A list of consumption data over different periods.
consumptionsBillingPeriods (IstaBillingPeriods) –

The consumption data over different billing periods.
costs (list[IstaPeriods]) –

A list of cost data over different periods.
costsBillingPeriods (IstaBillingPeriods) –

The cost data over different billing periods.
isSCEedBasicForCurrentMonth (bool) –

Indicates if the SCEed basic plan is active for the current month.
nonEEDBasicStartDate (Any) –

The start date for non-EED basic plan (data type unknown).
resident (dict[str, Any]) –

A dictionary containing resident information.

PyEcoTrend-ista¶

pyecotrend_ista ¶

KeycloakAuthenticationError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

KeycloakError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

KeycloakGetError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

KeycloakInvalidTokenError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

KeycloakOperationError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

KeycloakPostError ¶

error_message ¶

response_code ¶

response_body ¶

__str__ ¶

LoginError ¶

__str__ ¶

ParserError ¶

__str__ ¶

ServerError ¶

__str__ ¶

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 ¶

ConsumptionsResponse ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

`error_message` ¶

`response_code` ¶

`response_body` ¶

str ¶

str ¶

str ¶

str ¶

`email` ¶

`password` ¶

`totp` ¶

`session` ¶

access_token `property` `writable` ¶

`token` ¶

`select_year` ¶

`select_month` ¶

`filter_none` ¶

`obj_uuid` ¶

`obj_uuid` ¶