Documentation for pyvesync.auth module↲

This module handles the authentication logic for the VeSync API. It is stored as the auth instance attribute of the VeSync class.

pyvesync.auth.VeSyncAuth ↲

VeSyncAuth(
    manager: VeSync,
    username: str,
    password: str,
    country_code: str = DEFAULT_REGION,
)

VeSync Authentication Manager.

Handles login, token management, and persistent storage of authentication credentials for VeSync API access.

Initialize VeSync Authentication Manager.

Parameters:

Name	Type	Description	Default
manager	VeSync	VeSync manager instance for API calls	required
username	str	VeSync account username (email)	required
password	str	VeSync account password	required
country_code	str	Country code in ISO 3166 Alpha-2 format	DEFAULT_REGION

Note

Either username/password or token/account_id must be provided. If token_file_path is provided, credentials will be saved/loaded automatically.

Attributes↲

account_id property ↲

account_id: str

Return VeSync account ID.

country_code property writable ↲

country_code: str

Return country code.

current_region property ↲

current_region: str

Return current region.

is_authenticated property ↲

is_authenticated: bool

Check if user is authenticated.

token property ↲

token: str

Return VeSync API token.

Functions↲

__repr__ ↲

__repr__() -> str

Return string representation of VeSyncAuth.

_country_code_to_region ↲

_country_code_to_region() -> str

Convert country code to region string for API use.

_exchange_authorization_code async ↲

_exchange_authorization_code(
    auth_code: str, region_change_token: str | None = None
) -> None

Exchange authorization code for access token.

Parameters:

Name	Type	Description	Default
auth_code	str	Authorization code from first auth step	required
region_change_token	str | None	Token for region change (retry scenario)	None

Raises:

Type	Description
VeSyncLoginError	If login fails
VeSyncAPIResponseError	If API response is invalid

_get_authorization_code async ↲

_get_authorization_code() -> str

Get authorization code using username and password.

Returns:

Type	Description
str	Authorization code

Raises:

Type	Description
VeSyncAPIResponseError	If API response is invalid
VeSyncLoginError	If authentication fails

_login_with_credentials async ↲

_login_with_credentials() -> bool

Login using username and password.

Returns:

Type	Description
bool	True if login successful

Raises:

Type	Description
VeSyncLoginError	If login fails
VeSyncAPIResponseError	If API response is invalid

clear_credentials ↲

clear_credentials() -> None

Clear all stored credentials.

load_credentials_from_file async ↲

load_credentials_from_file(
    file_path: str | Path | None = None,
) -> bool

Load credentials from token file if path is set.

If no path is provided, it will try to load from the users home directory and then the current working directory.

login async ↲

login() -> bool

Log into VeSync server using username/password or existing token.

Returns:

Type	Description
bool	True if login successful, False otherwise

Raises:

Type	Description
VeSyncLoginError	If login fails due to invalid credentials
VeSyncAPIResponseError	If API response is invalid
VeSyncServerError	If server returns an error

output_credentials_dict ↲

output_credentials_dict() -> dict[str, str] | None

Output current credentials as a dictionary.

output_credentials_json ↲

output_credentials_json() -> str | None

Output current authentication credentials as a JSON string.

reauthenticate async ↲

reauthenticate() -> bool

Re-authenticate using stored username and password.

Returns:

Type	Description
bool	True if re-authentication successful, False otherwise

save_credentials_to_file async ↲

save_credentials_to_file(
    file_path: str | Path | None = None,
) -> None

Save authentication credentials to file.

set_credentials ↲

set_credentials(
    token: str,
    account_id: str,
    country_code: str,
    region: str,
) -> None

Set authentication credentials.

Parameters:

Name	Type	Description	Default
token	str	Authentication token	required
account_id	str	Account ID	required
country_code	str	Country code in ISO 3166 Alpha-2 format	required
region	str	Current region code	required