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,
    session: ClientSession | None = None,
    time_zone: str = DEFAULT_TZ,
)

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
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

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.

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 https://smartapi.vesync.com url. Raises VeSyncRateLimitError if API returns a rate limit error.

Parameters:

Name	Type	Description	Default
api	str	Endpoint to call with https://smartapi.vesync.com.	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.

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) -> None

Log to file and enable debug logging.

login async ↲

login() -> bool

Log into VeSync server.

Username and password are provided when class is instantiated.

Returns:

Type	Description
bool	True if login successful, False if not.

Raises:

Type	Description
VeSyncLoginError	If login fails 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.