Allow for reading deleted secret versions (kv2) without an exception

[briantist]

Fixes #906

Here's the final state of this PR

• VaultError (the base class for all the Vault exceptions) has been updated as follows:
  • constructor accepts optional text and json arguments and populates them as fields
  • [nicety] a new class method from_status is added to return an instance of a specific Vault exception, based on the given status code; this replaces the logic in raise_for_error to something a little cleaner
• utils.raise_for_error now accepts text and json fields to pass along to the exception classes, and is reduced to just calling VaultError.from_status
• RawAdapter (the only current place where raise_for_status is used) has been updated to populate the text and json fields as best it can from its requests.Response

All of the above now enables methods to remain Adapter-agnostic, but gain some additional information in the exceptions raised which can allow for handling of some conditions. With that:

• kv_v2's read_secret_version can catch the InvalidPath exception, inspect the json field to try to determine if the cause was due to a deleted secret version, and if so, can respond by returning the data instead of allowing the exception to be raised.
• that functionality is a (slightly) breaking change though, so it's controlled by a new parameter raise_on_deleted_version
  • Currently this parameter defaults to None
  • A value of None will default to True (preserving the old behavior) with a warning explaining that the default will change to False in v3.0.0
  • In v3.0.0 we'll change the actual default to False and remove the warning code and the test for it

Since clients also gain from the new exception fields, sophisticated clients can decide how to handle a deleted version result in their application (whether by setting the new parameter, or catching exceptions), including:

• using additional calls to determine the next newest non-deleted secret (if they have permission to make those calls)
• "brute-forcing" the finding of a non-deleted version, by using the version number V returned in the metadata, and requesting version V-1 until a non-deleted version is encountered or they get to 0
• reporting a more appropriate status relevant to their use case

At this time, I don't think we should look to implement these workarounds in hvac itself.

Tests have also been added or improved, and all of the changes here have 100% test coverage.

[codecov]

Codecov Report

Merging #907 (669ddfc) into develop (a98cbf8) will increase coverage by 1.91%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop     #907      +/-   ##
===========================================
+ Coverage    81.64%   83.56%   +1.91%     
===========================================
  Files           65       65              
  Lines         3002     3011       +9     
===========================================
+ Hits          2451     2516      +65     
+ Misses         551      495      -56     

Impacted Files	Coverage Δ
hvac/adapters.py	89.52% <100.00%> (+2.78%)	⬆️
hvac/api/secrets_engines/kv_v2.py	100.00% <100.00%> (+1.25%)	⬆️
hvac/exceptions.py	100.00% <100.00%> (ø)
hvac/utils.py	78.26% <100.00%> (+0.98%)	⬆️
hvac/api/system_backend/namespace.py	83.33% <0.00%> (+33.33%)	⬆️
hvac/api/secrets_engines/transform.py	64.06% <0.00%> (+34.37%)	⬆️

[adammike]

Really clean, looks good!

[blatnoy7447]

How can you avoid this error?
DeprecationWarning: The raise_on_deleted_version parameter will change its default value to False in hvac v3.0.0. The current default of True will presere previous behavior. To use the old behavior with no warning, e
xplicitly set this value to True. See #907

[briantist]

@blatnoy7447 set raise_on_deleted_version to any explicit value and the warning will go away. If you want to preserve the current default behavior, set it to True, if you want the future default behavior, set it to False. See the original post for details.
If you have further questions please open a new Q&A discussion.