Api Module

class Taipower.api.TaipowerElectricMeter(electric_meter_json)[source]

Bases: object

Taipower electric meter information.

Parameters:

electric_meter_json (dict) – Electric meter json of a specific meter.

classmethod from_electric_meter_list(electric_meter_json: dict, electric_numbers: List[str] | str | None = None) → Dict[str, object][source]

Use electric numbers to pick electric_meter_json accordingly.

Parameters:

  • electric_meter_json (dict) – electric_meter_json retrieved from connection.GetMember.

  • electric_numbers (Optional[Union[List[str], str]]) – Electric numbers. If None is given, all ami enabled meters will be included, by default None.

Returns:

A dict of TaipowerElectricMeter instances with electric number key.

Return type:

dict

property user_id: str

The user id of the electric number.

Returns:

The user id of the electric number.

Return type:

str

property name: str

The user name of the electric number.

Returns:

The user name of the electric number.

Return type:

str

property nickname: str | None

The nickname of the electric number, which can be changed in the Taipower app.

Returns:

The nickname, if not set in the app, None will be returned.

Return type:

Optional[str]

property number: str

Electric number.

Returns:

Electric number.

Return type:

str

property number_verified: bool

Whether or not the electric number is verified.

Returns:

Return True if the number is verified.

Return type:

bool

property type: str

Electric meter type.

Returns:

AMI or unknown.

Return type:

str

property main_addr: str

The main address of the electric number.

Returns:

The main address of the electric number.

Return type:

str

class Taipower.api.TaipowerAPI(account: str, password: str, electric_numbers: List[str] | str | None = None, ami_period: str = 'daily', max_retries: int = 5, print_response: bool = False)[source]

Bases: object

Taipower API.

Parameters:

  • account (str) – User phone number.

  • password (str) – User password.

  • electric_numbers (list of str or str or None, optional) – Electric numbers. If None is given, all available AMI enabled electric meters will be included, by default None.

  • ami_period (str, optional) – The retrieved AMI period. Available options: quater, hour, daily, monthly, by default daily.

  • max_retries (int, optional) – Maximum number of retries when setting status, by default 5.

  • print_response (bool, optional) – If set, all responses of httpx and MQTT will be printed, by default False.

property meters: Dict[str, TaipowerElectricMeter]

Picked Taipower electric meters.

Returns:

A dict of TaipowerElectricMeter instances.

Return type:

Dict[str, TaipowerElectricMeter]

login() → None[source]

Login API.

Raises:

RuntimeError – If a login error occurs, RuntimeError will be raised.

reauth(use_refresh_token: bool = False) → None[source]

Reauthenticate with Taipower API to retrieve new tokens.

Parameters:

use_refresh_token (bool, optional) – Whether or not to use refresh token, by default False

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

get_ami(electric_number: str, dt: datetime | None = None) → Dict[str, TaipowerAMI][source]

Get AMI.

Parameters:

  • electric_number (str) – Electric number.

  • dt (datetime.datetime, optional) – The retrieved AMI date and time, by default None

Returns:

AMI.

Return type:

Dict[str, model.TaipowerAMI]

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

async async_get_ami(electric_number: str, dt: datetime | None = None, client: AsyncClient | None = None) → Dict[str, TaipowerAMI][source]

Asynchronously get AMI.

Parameters:

  • electric_number (str) – Electric number.

  • dt (datetime.datetime, optional) – The retrieved AMI date and time. If None is given, current date and time will be used, by default None

  • client (httpx.AsyncClient, optional) – AsyncClient for requests, by default None

Returns:

AMI.

Return type:

Dict[str, model.TaipowerAMI]

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

get_ami_bill(electric_number: str) → TaipowerAMIBill[source]

Get AMI bill.

Parameters:

electric_number (str) – Electric number.

Returns:

AMI bill.

Return type:

model.TaipowerAMIBill

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

async async_get_ami_bill(electric_number: str, client: AsyncClient | None = None) → TaipowerAMIBill[source]

Asynchronously get AMI bill.

Parameters:

  • electric_number (str) – Electric number.

  • client (httpx.AsyncClient, optional) – AsyncClient for requests, by default None

Returns:

AMI bill.

Return type:

model.TaipowerAMIBill

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

get_ami_unbilled(electric_number: str) → TaipowerAMIUnbilled[source]

Get AMI unbilled.

Parameters:

electric_number (str) – Electric number.

Returns:

AMI unbilled.

Return type:

model.TaipowerAMIUnbilled

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

async async_get_ami_unbilled(electric_number: str, client: AsyncClient | None = None) → TaipowerAMIUnbilled[source]

Asynchronously get AMI unbilled.

Parameters:

  • electric_number (str) – Electric number.

  • client (httpx.AsyncClient, optional) – AsyncClient for requests, by default None

Returns:

AMI unbilled.

Return type:

model.TaipowerAMIUnbilled

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

get_bill_records(electric_number: int) → Dict[str, TaipowerBillRecord][source]

Get bill records.

Parameters:

electric_number (str) – Electric number.

Returns:

Bill records.

Return type:

Dict[str, model.TaipowerBillRecord]

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

async async_get_bill_records(electric_number: int, client: AsyncClient | None = None) → Dict[str, TaipowerBillRecord][source]

Asynchronously get bill records.

Parameters:

  • electric_number (str) – Electric number.

  • client (httpx.AsyncClient, optional) – AsyncClient for requests, by default None

Returns:

Bill records.

Return type:

Dict[str, model.TaipowerBillRecord]

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

refresh_status(electric_number: str | None = None, refresh_ami: bool = True, refresh_ami_bill: bool = True, refresh_ami_unbilled: bool = True, refresh_bill_records: bool = True)[source]

Refresh status from Taipower API.

Parameters:

  • electric_number (str, optional) – Electric number. If None is given, all meters will be refreshed, by default None.

  • refresh_ami (bool, optional) – Whether or not to refresh AMI, by default True

  • refresh_ami_bill (bool, optional) – Whether or not to refresh AMI bill, by default True

  • refresh_ami_unbilled (bool, optional) – Whether or not to refresh AMI unbilled, by default True

  • refresh_bill_records (bool, optional) – Whether or not to refresh bill records, by default True

Raises:

RuntimeError – If errors occur, a RuntimeError containing all errors will be raised.