Document hashing of credentials #1416
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #1416 +/- ##
=======================================
Coverage 92.52% 92.52%
=======================================
Files 132 132
Lines 8251 8251
Branches 848 848
=======================================
Hits 7634 7634
Misses 453 453
Partials 164 164 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
|
||
| 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. | ||
| ::: | ||
|
|
There was a problem hiding this comment.
| 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. | |
| ::: | |
| 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. | |
| **All of your code needs to run inside the same event loop so only call `asyncio.run` once.** | |
I think this looked better as a self contained note which separated it from the rest of the details on each page. Making the asyncio.run seems to end the note and breaks up the whole thing.
Before:
After:
Perhaps the note should self-contain all the details about the async, and then a subsequent important section contains everything about the credentials.
| 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. |
There was a problem hiding this comment.
| 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. | |
| Credentials are required by newer Kasa devices and all Tapo devices. | |
| They are the TPLink cloud *username* (e-mail) and *password* used to provision the device in the native app, and they are usually both case-sensitive. | |
| Some firmware versions of Tapo Cameras will not authenticate unless you enable Tapo Lab > Third-Party Compatibility in the native Tapo app. |
Users probably don't need to know about hashing or transports, just that credentials are usually case sensitive. Probably makes sense to have all the relevant credentials information in the one snippet.
| .. include:: ../creds_hashing.md | ||
| :parser: myst_parser.sphinx_ | ||
There was a problem hiding this comment.
| .. include:: ../creds_hashing.md | |
| :parser: myst_parser.sphinx_ |
This is repeated at the top of the page. We should either remove it from codeinfo.md or remove it here. Maybe it's better to remove it from codeinfo.md so we can place it where it's most relevant.
|
There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. |
This improves the documentation to inform library users that the credentials hashed and are thus case-sensitive.
Added the note also to
codeinfo.mdfor now, but perhaps it's too much considering the same note appears also in places where the credentials are discussed?Related comments:
Thanks to @TheHairforce and @ZeliardM for helping spot the issue, I will create a separate PR to update the exception messages to help users encountering the challenge hash mismatch.