Fix TOTP retry logic, improve cassette handling; document

[eloquence]

As part of working on #134 I noticed that setUp in test_api.py was not working as expected: when regenerating the cassette, authentication would either succeed, or it would fail and keep failing. The TOTP code was not successfully re-retrieved.

The logic does not work as currently written because 1) it would keep using the same TOTP code if it actually looped, which it doesn't because, 2) it will quietly exit the loop after sleeping.

Because we're already using a cassette to record the API response(s), there's really no reason for an additional utility method to stash and load it -- we just need to make sure we don't run sleeps when we're in playback mode.

Also fixes a path error for the RPC policy changes documented in the README.

Status

Ready for review. CI will fail until #133 and #136 land.

Test plan

Reproduce the error

On the main branch, run the following command in your virtualenv:

rm data/test-setup.yml && python -m pytest -v -k test_api_auth

What this command does: remove the setup cassette and attempt to obtain a fresh, valid API token

• Observe: Expected behavior: test success. Actual behavior (usually, initially): test success

Run it again once or twice, in quick succession.

• Observe: Expected behavior: test success. Actual behavior: long sleep, test failure.

Reproduce the fix

Perform the same steps on this branch.

• Observe that the error no longer occurs, and that the API test successfully completes.

No sleep during playback

Check that the file data/test-setup.yml still contains a 403 response from the previous run. If not, re-run until you observe a sleep, then preserve data/test-setup.yml with a 403 in it.

Run all tests from the cassettes (reminded that dev env needs to be restarted between full test runs, due to the deletion related tests):

make test TESTS=tests/test_api.py

• Observe that all tests pass
• Observe that in spite of the 403 in the previous recorded auth response, there is no 31 second sleep during test execution.

[eloquence]

AuthError is the more specific, occasionally expected error, so it seemed the more appropriate one to catch here so we don't accidentally swallow other useful exceptions.

[eloquence]

Tweaked this further to remove utility methods we don't really need. Ready for review but would be good to land CI fixes first so we can rebase and get a clean CI run in.

[kushaldas]

After following the standard test steps from the PR description, I did the following steps:

• rm data/*.yml
• make test TESTS=tests/test_api.py

This is good for me, approved.