[WIP] Add AdapterResponse
types, and HvacAdapter
#898
+453
−1
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #797
Closes #293
Closes #385
Closes #660
This started after discussion about how we might handle 204 responses better in the
JSONAdapter
(see also #847), but led to us thinking about it in a new way that's a bit more comprehensive.The basic idea is to return a specialized response class instead of raw data in some form or another.
The first members of this class are
raw
,status
, andvalue
, wherestatus
is meant to represent the HTTP status code returned from the request,raw
is meant to be the raw response object (whatever it may be) or possiblyNone
(this is Adapter-dependent), andvalue
is meant to be the "usable" data/result of the request (also Adapter-dependent).This is implemented here first as an abstract base class for adapter responses, an abstract subclass that is tuned for
requests.Response
-based response classes, and finally theHvacAdapterResponse
which is first concrete response class.HvacAdapterResponse
is nominally very simple: it inherits from theRequestsAdapterResponse
and only needs to overridevalue
; it takes similar steps to theJSONAdapter
of trying to interpret the HTTP response as JSON, with an extra step for handling empty 204 responses. On a 204, an empty dict{}
is returned.If the response in not parseable as JSON, and the response code is not 204, then it returns
None
. If the caller knows how to handle the particular response, they can use the.raw
member to get access to the response object and handle it however they wish.HvacAdapterResponse
includes an additional set of deprecated behaviors: it overrides__getattr__
,__getitem__
,__setitem__
, and__delitem__
, and proxies them to thevalue
member instead. The purpose of this is so that code likeresp = client.secrets.kv2.read_secret_version(...)
which assumes thatresp
is a dict, can still work ifresp
is aHvacAdapterResponse
; essentially letting consumers still treat it like a dict for a while.Each time this happens, a deprecation warning will be shown. Consuming code should change their calls like
resp.get('key', None)
orresp['key']
toresp.value.get('key', None)
orresp.value['key']
, etc.The next step is introducing a new Adapter, called the
HvacAdapter
. It operates rather transparently, based onRawAdapter
, and simply returns anHvacAdatperResponse
based on therequests.Response
from theRawAdapter
.Basic (tentative) plan for introduction and use
v1.x
HvacAdapter
in v2.0.0JSONAdatper
functionality can now explicitly specify it, and the warning will go away.JSONAdapter
is not deprecated and their code will work indefinitely.v2.0.0
HvacAdapter
. Responses are now of typeHvacAdapterResponse
.value
member, or may choose to explicitly set theJSONAdapter
(or another one of their choosing).v3.0.0
This gives a lot of advance warning of the changes coming, and provides a lot of overlapping functionality so that downstream projects have time to support both ways so that their consumers can still use a wide range of
hvac
versions.Opting into
HvacAdatper
is available from the beginning; opting out to stick withJSONAdapter
is also available from the beginning.This is a draft, still WIP, and is subject to change.