Document hashing of credentials

docs/source/codeinfo.md

@@ -1,6 +1,15 @@
 
 :::{note}
 The library is fully async and methods that perform IO need to be run inside an async coroutine.
+
+The main entry point for the API is {meth}`~kasa.Discover.discover` and
+{meth}`~kasa.Discover.discover_single` which return Device objects.
+Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.
+
+:::{important}
+All of your code needs to run inside the same event loop so only call `asyncio.run` once.
+:::
+
 Code examples assume you are following them inside `asyncio REPL`:
 ```
     $ python -m asyncio
@@ -18,9 +27,7 @@ async def main():
 if __name__ == "__main__":
     asyncio.run(main())
 ```
-**All of your code needs to run inside the same event loop so only call `asyncio.run` once.**
 
-*The main entry point for the API is {meth}`~kasa.Discover.discover` and
+::::{include} ../creds_hashing.md
-{meth}`~kasa.Discover.discover_single` which return Device objects.
+
-Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.*
 :::

docs/source/creds_hashing.md

@@ -0,0 +1,4 @@
+:::{important}
+Most transports hash the credentials, so both *username* (e-mail) and *password* are case-sensitive.
+If you are unable to authenticate with the device, verify they match to your account.
+:::

kasa/deviceconfig.py

@@ -14,6 +14,9 @@ Discovery returns a list of discovered devices:
 >>> print(device.alias)  # Alias is None because update() has not been called
 None
 
+.. include:: ../creds_hashing.md
+   :parser: myst_parser.sphinx_
+
 >>> config_dict = device.config.to_dict()
 >>> # DeviceConfig.to_dict() can be used to store for later
 >>> print(config_dict)

kasa/discover.py

@@ -24,7 +24,7 @@ Discovery returns a dict of {ip: discovered devices}:
 >>> [dev.model for dev in found_devices.values()]
 ['KP303', 'HS110', 'L530E', 'KL430', 'HS220']
 
-You can pass username and password for devices requiring authentication
+You can pass username and password for devices requiring authentication:
 
 >>> devices = await Discover.discover(
 >>>     username="user@example.com",
@@ -33,13 +33,16 @@ You can pass username and password for devices requiring authentication
 >>> print(len(devices))
 5
 
-You can also pass a :class:`kasa.Credentials`
+You can also pass a :class:`kasa.Credentials`:
 
 >>> creds = Credentials("user@example.com", "great_password")
 >>> devices = await Discover.discover(credentials=creds)
 >>> print(len(devices))
 5
 
+.. include:: ../creds_hashing.md
+   :parser: myst_parser.sphinx_
+
 Discovery can also be targeted to a specific broadcast address instead of
 the default 255.255.255.255: