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,
    debug: bool = False,
    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
debug	bool	Enable debug logging, by default False.	False
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
token	str	VeSync API token
account_id	str	VeSync account ID
country_code	str	Country code for VeSync account pulled from API
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.

See Also

:obj:DeviceContainer Container object to store VeSync devices :obj:DeviceState Object to store device state information

Attributes↲

account_id property ↲

account_id: str

Return VeSync account ID.

debug property writable ↲

debug: bool

Return debug flag.

devices property ↲

devices: DeviceContainer

Return VeSync device container.

See Also

The pyvesync.device_container.DeviceContainer object for methods and properties.

redact property writable ↲

redact: bool

Return debug flag.

token property ↲

token: str

Return VeSync API token.

verbose property writable ↲

verbose: bool

Enable verbose logging.

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.

_login_token async ↲

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

Exchanges the authorization code for a token.

This completes the login process. If the initial call fails with "login trigger cross region error.", the region is adjusted and another attempt is made.

Parameters:

Name	Type	Description	Default
auth_code	str	Auth code to use for logging in.	None
region_change_token	str	"bizToken" to use when calling this endpoint for a second time with a different region.	None

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.

_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,
) -> tuple[dict | None, int | None]

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

Returns:

Type	Description
tuple[dict | None, int | None]	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_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.

log_to_file ↲

log_to_file(
    filename: str | Path, std_out: 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
std_out	bool	If False, logs will not print to std out.	True

login async ↲

login() -> None

Log into VeSync server.

Username and password are provided when class is instantiated.

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.

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.