- :class:`KlapTransport <kasa.klaptransport.KlapTransport>`

- :class:`KlapTransportV2 <kasa.klaptransport.KlapTransportV2>`

Errors and Exceptions

The base exception for all library errors is :class:`KasaException <kasa.exceptions.KasaException>`.

- If the device returns an error the library raises a :class:`DeviceError <kasa.exceptions.DeviceError>` which will usually contain an ``error_code`` with the detail.

- If the device fails to authenticate the library raises an :class:`AuthenticationError <kasa.exceptions.AuthenticationError>` which is derived

from :class:`DeviceError <kasa.exceptions.DeviceError>` and could contain an ``error_code`` depending on the type of failure.

- If the library encounters and unsupported deviceit raises an :class:`UnsupportedDeviceError <kasa.exceptions.UnsupportedDeviceError>`.

- If the device fails to respond within a timeout the library raises a :class:`TimeoutError <kasa.exceptions.TimeoutError>`.

- All other failures will raise the base :class:`KasaException <kasa.exceptions.KasaException>` class.

API documentation for modules

:members:

:inherited-members:

:undoc-members:

API documentation for errors and exceptions

.. autoclass:: kasa.exceptions.KasaException

:members:

:undoc-members:

.. autoclass:: kasa.exceptions.DeviceError

:members:

:undoc-members:

.. autoclass:: kasa.exceptions.AuthenticationError

:members:

:undoc-members:

.. autoclass:: kasa.exceptions.UnsupportedDeviceError

:members:

:undoc-members:

.. autoclass:: kasa.exceptions.TimeoutError

:members:

:undoc-members:

You can assume that the operation has succeeded if no exception is raised.

These methods will return the device response, which can be useful for some use cases.

Errors are raised as :class:`KasaException` instances for the library user to handle.

Simple example script showing some functionality for legacy devices:

.. autoclass:: Credentials

:members:

:undoc-members:

from importlib.metadata import version

from kasa.discover import Discover

from kasa.emeterstatus import EmeterStatus

from kasa.exceptions import (

AuthenticationError,

DeviceError,

KasaException,

TimeoutError,

UnsupportedDeviceError,

)

from kasa.feature import Feature, FeatureType

from kasa.iot.iotbulb import BulbPreset, TurnOnBehavior, TurnOnBehaviors

"Device",

"Bulb",

"Plug",

"KasaException",

"AuthenticationError",

"DeviceError",

"UnsupportedDeviceError",

"TimeoutError",

"Credentials",

"DeviceConfig",

"ConnectionType",

"SmartDimmer": iot.IotDimmer,

"SmartBulbPreset": BulbPreset,

}

deprecated_exceptions = {

"SmartDeviceException": KasaException,

"UnsupportedDeviceException": UnsupportedDeviceError,

"AuthenticationException": AuthenticationError,

"TimeoutException": TimeoutError,

}

def __getattr__(name):

stacklevel=1,

)

return new_class

if name in deprecated_exceptions:

new_class = deprecated_exceptions[name]

msg = f"{name} is deprecated, use {new_class.__name__} instead"

warn(msg, DeprecationWarning, stacklevel=1)

return new_class

raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

SmartStrip = iot.IotStrip

SmartDimmer = iot.IotDimmer

SmartBulbPreset = BulbPreset

SmartDeviceException = KasaException

UnsupportedDeviceException = UnsupportedDeviceError

AuthenticationException = AuthenticationError

TimeoutException = TimeoutError

# Instanstiate all classes so the type checkers catch abstract issues

from . import smart

from .exceptions import (

SMART_AUTHENTICATION_ERRORS,

SMART_RETRYABLE_ERRORS,

AuthenticationError,

DeviceError,

KasaException,

SmartErrorCode,

_RetryableError,

)

from .httpclient import HttpClient

from .json import dumps as json_dumps

if error_code == SmartErrorCode.SUCCESS:

return

msg = f"{msg}: {self._host}: {error_code.name}({error_code.value})"

if error_code in SMART_RETRYABLE_ERRORS:

raise _RetryableError(msg, error_code=error_code)

if error_code in SMART_AUTHENTICATION_ERRORS:

self._state = TransportState.HANDSHAKE_REQUIRED

raise AuthenticationError(msg, error_code=error_code)

raise DeviceError(msg, error_code=error_code)

async def send_secure_passthrough(self, request: str) -> Dict[str, Any]:

"""Send encrypted message as passthrough."""

# _LOGGER.debug(f"secure_passthrough response is {status_code}: {resp_dict}")

if status_code != 200:

raise KasaException(

f"{self._host} responded with an unexpected "

+ f"status code {status_code} to passthrough"

)

self._host,

)

except Exception:

raise KasaException(

f"Unable to decrypt response from {self._host}, "

+ f"error: {ex}, response: {raw_response}",

ex,

"""Login to the device."""

try:

await self.try_login(self._login_params)

except AuthenticationError as aex:

try:

if aex.error_code is not SmartErrorCode.LOGIN_ERROR:

raise aex

"%s: logged in with default credentials",

self._host,

)

except AuthenticationError:

raise

except Exception as ex:

raise KasaException(

"Unable to login and trying default "

+ f"login raised another exception: {ex}",

ex,

_LOGGER.debug("Device responded with: %s", resp_dict)

if status_code != 200:

raise KasaException(

f"{self._host} responded with an unexpected "

+ f"status code {status_code} to handshake"

)

await self.perform_login()

# After a login failure handshake needs to

# be redone or a 9999 error is received.

except AuthenticationError as ex:

self._state = TransportState.HANDSHAKE_REQUIRED

raise ex

import asyncclick as click

from kasa import (

AuthenticationError,

Bulb,

ConnectionType,

Credentials,

DeviceFamilyType,

Discover,

EncryptType,

KasaException,

UnsupportedDeviceError,

)

from kasa.discover import DiscoveryResult

from kasa.iot import IotBulb, IotDevice, IotDimmer, IotLightStrip, IotPlug, IotStrip

unsupported = []

auth_failed = []

async def print_unsupported(unsupported_exception: UnsupportedDeviceError):

unsupported.append(unsupported_exception)

async with sem:

if unsupported_exception.discovery_result:

async with sem:

try:

await dev.update()

except AuthenticationError:

auth_failed.append(dev._discovery_info)

echo("== Authentication failed for device ==")

_echo_discovery_info(dev._discovery_info)

elif isinstance(dev, SmartDevice):

res = await dev._query_helper(command, parameters)

else:

raise KasaException("Unexpected device type %s.", dev)

echo(json.dumps(res))

return res

from .device_type import DeviceType

from .deviceconfig import DeviceConfig

from .emeterstatus import EmeterStatus

from .exceptions import KasaException

from .feature import Feature

from .iotprotocol import IotProtocol

from .protocol import BaseProtocol

if p.alias == name:

return p

raise KasaException(f"Device has no child with {name}")

def get_plug_by_index(self, index: int) -> "Device":

"""Return child device for the given index."""

if index + 1 > len(self.children) or index < 0:

raise KasaException(

f"Invalid index {index}, device has {len(self.children)} plugs"

)

return self.children[index]

"""Add a new feature to the device."""

desc_name = feature.name.lower().replace(" ", "_")

if desc_name in self._features:

raise KasaException("Duplicate feature name %s" % desc_name)

self._features[desc_name] = feature

@property