Documentation for `pyvesync.vesync` module↲

This module instantiates the vesync instance that holds the devices and maintains authentication information.

pyvesync.vesync.VeSync ↲

VeSync(
    username: str,
    password: str,
    country_code: str = DEFAULT_REGION,
    session: ClientSession | None = None,
    time_zone: str = DEFAULT_TZ,
    redact: bool = True,
)

VeSync Manager Class.

Initialize VeSync Manager.

This class is used as the manager for all VeSync objects, all methods and API calls are performed from this class. Time zone, debug and redact are optional. Time zone must be a string of an IANA time zone format. Once class is instantiated, call await manager.login() to log in to VeSync servers, which returns True if successful. Once logged in, call await manager.get_devices() to retrieve devices. Then awaitmanager.update()to update all devices orawait manager.devices[0].update()` to update a single device.

Parameters:

Name	Type	Description	Default
`username`	`str`	VeSync account username (usually email address)	required
`password`	`str`	VeSync account password	required
`country_code`	`str`	VeSync account country in ISO 3166 Alpha-2 format. By default, the account region is detected automatically at the login step If your account country is different from the default `US`, a second login attempt may be necessary - in this case you should specify the country directly to speed up the login process.	`DEFAULT_REGION`
`session`	`ClientSession`	aiohttp client session for API calls, by default None	`None`
`time_zone`	`str`	Time zone for device from IANA database, by default DEFAULT_TZ. This is automatically set to the time zone of the VeSync account during login.	`DEFAULT_TZ`
`redact`	`bool`	Enable redaction of sensitive information, by default True.	`True`

Attributes:

Name	Type	Description
`session`	`ClientSession`	Client session for API calls
`devices`	`DeviceContainer`	Container for all VeSync devices, has functionality of a mutable set. See `DeviceContainer` for more information
`auth`	`VeSyncAuth`	Authentication manager
`time_zone`	`str`	Time zone for VeSync account pulled from API
`enabled`	`bool`	True if logged in to VeSync, False if not

Note

This class is a context manager, use async with VeSync() as manager: to manage the session context. The session will be closed when exiting if no session is passed in.

The manager.devices attribute is a DeviceContainer object that contains all VeSync devices. The manager.devices object has the functionality of a set, and can be iterated over to access devices. See :obj:DeviceContainer for more information.

If using a context manager is not convenient, manager.__aenter__() and manager.__aexit__() can be called directly.

Either username/password or token/account_id must be provided for authentication.

Attributes↲

account_id `property` ↲

account_id: str

Return account ID.

Returns:

Name	Type	Description
`str`	`str`	Account ID.

Raises:

Type	Description
`AttributeError`	If account ID is not set.

auth `property` ↲

auth: VeSyncAuth

Return VeSync authentication manager.

country_code `property` ↲

country_code: str

Return country code.

current_region `property` ↲

current_region: str

Return current region.

debug `property` ↲

debug: bool

Return debug flag.

devices `property` ↲

devices: DeviceContainer

Return VeSync device container.

redact `property` `writable` ↲

redact: bool

Return debug flag.

token `property` ↲

token: str

Return authentication token.

Returns:

Name	Type	Description
`str`	`str`	Authentication token.

Raises:

Type	Description
`AttributeError`	If token is not set.

Functions↲

aenter `async` ↲

__aenter__() -> Self

Asynchronous context manager enter.

aexit `async` ↲

__aexit__(*exec_info: object) -> None

Asynchronous context manager exit.

_api_base_url_for_current_region ↲

_api_base_url_for_current_region() -> str

Retrieve the API base url for the current region.

At this point, only two different URLs exist: One for EU region (for all EU countries), and one for all others (currently US, CA, MX, JP - also used as a fallback).

If API_BASE_URL is set, it will take precedence over the determined URL.

_api_response_wrapper `async` ↲

_api_response_wrapper(
    response: ClientResponse,
    endpoint: str,
    request_body: dict | None,
    device: VeSyncBaseDevice | None = None,
) -> tuple[dict | None, int]

Internal wrapper used by async_call_api.

_reauthenticate `async` ↲

_reauthenticate() -> bool

Re-authenticate using stored username and password.

Returns:

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

_update_fw_version ↲

_update_fw_version(
    info_list: list[FirmwareDeviceItemModel],
) -> bool

Update device firmware versions from API response.

async_call_api `async` ↲

async_call_api(
    api: str,
    method: str,
    json_object: dict | None | DataClassORJSONMixin = None,
    headers: dict | None = None,
    device: VeSyncBaseDevice | None = None,
) -> tuple[dict | None, int]

Make API calls by passing endpoint, header and body.

api argument is appended to API_BASE_URL. Raises VeSyncRateLimitError if API returns a rate limit error.

Parameters:

Name	Type	Description	Default
`api`	`str`	Endpoint to call with `API_BASE_URL`.	required
`method`	`str`	HTTP method to use.	required
`json_object`	`dict \| RequestBaseModel`	JSON object to send in body.	`None`
`headers`	`dict`	Headers to send with request.	`None`
`device`	`VeSyncBaseDevice \| None`	Device making the request, if any.	`None`

Returns:

Type	Description
`tuple[dict \| None, int]`	tuple[dict \| None, int]: Response and status code. Attempts to parse response as JSON, if not possible returns None.

Raises:

Type	Description
`VeSyncAPIStatusCodeError`	If API returns an error status code.
`VeSyncRateLimitError`	If API returns a rate limit error.
`VeSyncServerError`	If API returns a server error.
`VeSyncTokenError`	If API returns an authentication error.
`ClientResponseError`	If API returns a client response error.

Note

Future releases will require the json_object argument to be a dataclass, instead of dictionary.

check_debug ↲

check_debug() -> bool

Check if debug logging is enabled - should be called minimally.

check_firmware `async` ↲

check_firmware() -> bool

Check for firmware updates for all devices.

This method will check for firmware updates for all devices in the device container. It will call the get_firmware_update() method on each device and log the results.

get_devices `async` ↲

get_devices() -> bool

Return tuple listing outlets, switches, and fans of devices.

This is also called by VeSync.update()

Raises:

Type	Description
`VeSyncAPIResponseError`	If API response is invalid.
`VeSyncServerError`	If server returns an error.

load_credentials_from_file `async` ↲

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

Load authentication credentials from a file.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path \| None`	The name of the file to load credentials from. If None, no action is taken.	`None`

Returns:

Name	Type	Description
`bool`	`bool`	True if credentials were loaded successfully, False otherwise.

log_to_file ↲

log_to_file(
    filename: str | Path, stdout: bool = True
) -> None

Log to file and enable debug logging.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	The name of the file to log to.	required
`stdout`	`bool`	Whether to also log to stdout, by default True.	`True`

login() -> bool

Log into VeSync server.

Username and password are provided when class is instantiated.

Returns:

Type	Description
`bool`	True if login successful, False otherwise

Raises:

Type	Description
`VeSyncLoginError`	If login fails, for example due to invalid username or password.
`VeSyncAPIResponseError`	If API response is invalid.
`VeSyncServerError`	If server returns an error.

output_credentials_dict ↲

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

Output current authentication credentials as a dictionary.

output_credentials_json ↲

output_credentials_json() -> str | None

Output current authentication credentials as a JSON string.

save_credentials `async` ↲

save_credentials(filename: str | Path | None) -> None

Save authentication credentials to a file.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path \| None`	The name of the file to save credentials to. If None, no action is taken.	required

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

update `async` ↲

update() -> None

Fetch updated information about devices and new device list.

Pulls devices list from VeSync and instantiates any new devices. Devices are stored in the instance attributes outlets, switches, fans, and bulbs. The _device_list attribute is a dictionary of these attributes.

update_all_devices `async` ↲

update_all_devices() -> None

Run get_details() for each device and update state.

Documentation for pyvesync.vesync module↲

pyvesync.vesync.VeSync ↲

Attributes↲

account_id property ↲

auth property ↲

country_code property ↲

current_region property ↲

debug property ↲

devices property ↲

redact property writable ↲

token property ↲

Functions↲

__aenter__ async ↲

__aexit__ async ↲

_api_base_url_for_current_region ↲

_api_response_wrapper async ↲

_reauthenticate async ↲

_update_fw_version ↲

async_call_api async ↲

check_debug ↲

check_firmware async ↲

get_devices async ↲

load_credentials_from_file async ↲

log_to_file ↲

login async ↲

output_credentials_dict ↲

output_credentials_json ↲

save_credentials async ↲

set_credentials ↲

update async ↲

update_all_devices async ↲

Documentation for `pyvesync.vesync` module↲

account_id `property` ↲

auth `property` ↲

country_code `property` ↲

current_region `property` ↲

debug `property` ↲

devices `property` ↲

redact `property` `writable` ↲

token `property` ↲

aenter `async` ↲

aexit `async` ↲

_api_response_wrapper `async` ↲

_reauthenticate `async` ↲

async_call_api `async` ↲

check_firmware `async` ↲

get_devices `async` ↲

load_credentials_from_file `async` ↲

login `async` ↲

save_credentials `async` ↲

update `async` ↲

update_all_devices `async` ↲