Add new exception types for HTTP status 405 and 412

[mweigel]

HTTP exception type changes

Any HTTP exception in hvac which does not have a pre-existing mapped status code to exception will return an UnexpectedError exeption.

We would like to add exception types for status codes 412 (PreconditionFailed) and 405 (UnsupportedOperation).

Breaking change

Existing code that wants to catch those exceptions may be written similarly to this:

try:
    client.do_thing()
except UnexpectedError as e:
    # check status code in e and handle appropriately

If we then map those status codes to new exception types, the above code will fail to catch them.

As a result, we will do this change in two stages:

• This PR introduces the new classes, but does not map the existing status codes to them, so those exceptions will never be raised. This change will be added to hvac 2.2.0.
• Update exception status map for HTTP 405 and 412 #1149 will be introduced in hvac 3.0.0 and will map the status codes.

Action needed

If you currently use UnexpectedError to catch status codes 405 or 412, update your code before v3.0.0 to something like the following (using UnsupportedOperation as the example):

try:
   client.do_thing()
except (UnexpectedError, UnsupportedOperation) as e:
    # handle

or if you want to handle them differently:

try:
   client.do_thing()
except UnsupportedOperation as e:
    # handle
except UnexpectedError as e:
    # handle

This ensures that your code is ready to handle the new exception type. This is especially important if your project intends to support multiple major versions of hvac.

Future exception types

If you are using UnexpectedError as a catch-all for any exception without a dedicated type, and you want to future proof against more HTTP exception types being added in the future, you may consider catching the base class VaultError instead or in addition to `:

try:
    client.do_thing()
except Unauthorized:
    # handle unauthorized
except Forbidden:
    # handle forbidden
except VaultError as e:
    # conditionally handle any exception not named in a previous except block

---

• Prepare for Add an exception type for HTTP status code 412 #1093 by adding PreconditionFailed exception for status code 412
• Add UnsupportedOperation exception for status code 405

Adding the UnsupportedOperation exception is a reasonably significant change as there might be quite a bit of code expecting UnexpectedError on a 405. Can take it out if it's too much.

[briantist]

Thanks for putting this up @mweigel ! I'll need some time to fully review it as I have a busy couple of weeks ahead.

One thing I should have mentioned in the original issue, is that while we can introduce the new exceptions in a minor release, we can't update the status map until a major release.

The reason is that if people have code that is expecting to catch UnknownException to deal with 412 and 405 now, their code will break once we raise a new exception type.

So I think we should split the PR; the new exception classes are introduced in the next (minor) release, and that lets folks update their except blocks to catch both UnknownException and the new one(s), then in the next major version we'll update the status map.

Does that make sense to you?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.68%. Comparing base (48027db) to head (5dc203f).
Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1148      +/-   ##
==========================================
+ Coverage   87.66%   87.68%   +0.01%     
==========================================
  Files          66       66              
  Lines        3227     3231       +4     
==========================================
+ Hits         2829     2833       +4     
  Misses        398      398              

Files	Coverage Δ
hvac/exceptions.py	100.00% <100.00%> (ø)

[mweigel]

Yes, that makes sense. I was originally thinking the change wouldn't be merged until 3.0.0. I've reverted the changes to the status map and tests.

[briantist]

I want to edit the PR description as a signpost for people reading the changelog, to give instructions on what to do before merging, but this will bein the next release, thank you!

[briantist]

@mweigel if you wouldn't mind also submitting the PR containing the status map changes and tests, that would be great, that way we have it prepared and reviewed and ready for 3.0.0.

[mweigel]

Cool, pushed #1149