Breaking changes coming to Client.write
method
#1034
Labels
announcement
Announces some change or future change to be aware of
breaking-change
deprecation
Deprecates something, to be removed or changed in a later release
Summary
The
Client.write
method is a generic function for "writing" (POST
ing) data to Vault. It does not correspond to any specific backend and takes a raw path. This method is useful for being able to perform writes against backends that the library doesn't (yet) have direct support for.The method signature uses
kwargs
for specifying the data to write. This is problematic because it prevents the use of any of the method's other argument names as keys in the data. See also:What's changing
The end goal is to change the method so that it accepts a
data
argument which contains the data to write, and to deprecate and remove the ability to set keys viakwargs
. This change is not only breaking, there is no way to support both on the same method without sacrificing some backwards compatibility, because adding any arguments to the method also makes them unusable inkwargs
.The plan
We will first introduce a new (temporary!) method,
Client.write_data
which can be used as an alternative toClient.write
and accepts only thedata
argument for setting data.Over the course of several major versions, we will begin to make targeted breaking changes to the
write
method to bring it closer thewrite_data
implementation, with special care taken to warn on usages that could exhibit breakage and to try to avoid breakage on uses of the old method that can be used successfully without changing calls to the temporary method.Eventually,
write
will look exactly aswrite_data
does today, andwrite_data
will be removed.The schedule
This is the current proposed schedule for what changes will happen and when. The schedule is subject to change based on circumstances at the time but this is the plan as it stands today.
v1.2.0
-- TheClient.write_data
method is addedClient.write_data
method #1028v2.0.0
-- updatewrite
as follows:path
andwrap_ttl
, add*args
path
andwrap_ttl
based on*args
(for positional) and**kwargs
path
orwrap_ttl
values were gotten from**kwargs
, they won't be set as data (this preserves previous behavior), and we'll issue a warning suggesting the use ofwrite_data
or setting these positionallydata
exists inkwargs
we'll also warn about its impending use (see next items) and suggestwrite_data
v3.0.0
-- "activate" adata
parameter inwrite
:kwargs
containsdata
and no other non-argument keys, then this call will operate the same aswrite_data
(forward compatible)kwargs
contains bothdata
and other data keys, raise an exceptionwrite
does now (backward compatible), with a deprecation warning thatkwargs
is to be removed inv4.0.0
, suggesting using thedata
dictionary going forwardv4.0.0
-- updatewrite
to its Final Form™:*args
and**kwargs
, and return to defined arguments forpath
,wrap_ttl
, anddata
write
basically becomeswrite_data
v4.0.0
-- markwrite_data
as an alias forwrite
in documentationwrite
, to be removed inv5.0.0
or later (exact plan TBD).What do I need to change?
Whether you need to change anything, and what that change needs to be, depends on how you use the
write
method, so let's lay out some possibilities and what you need to do.Definitions:
I use the
write
method with static keys, andThe key names DO NOT contain the names
path
,wrap_ttl
, ordata
write
will continue to work for you untilv4.0.0
v2.0.0
, you will see warnings if you are settingpath
orwrap_ttl
viakwargs
. If you want to stop the warnings, there are two possibilities:write
method but switch thepath
andwrap_ttl
arguments to positionalwrite_data
and set data via thedata
argument; eventually will change this method call back towrite
v3.0.0
, you should update your usage of thewrite
method to set data via thedata
argumentclient.write(path='/a/b/c', wrap_ttl='5m', key1='A', key2='B')
should becomeclient.write(path='/a/b/c', wrap_ttl='5m', data={'key1': 'A', 'key2': 'B'})
write_data
inv2.0.0
, you may switch back towrite
at this point with no other changes to the callv4.0.0
, no changes are necessary if you were usingwrite
with thedata
argument inv3
. If you switched towrite_data
at any point, you should switch back now to avoid future breakage.The key names DO contain
path
,wrap_ttl
This usage is broken pre-1.2.0.
v1.2.0
-- switch towrite_data
v3.0.0
-- you may switch back towrite
at this point with the same method call aswrite_data
v4.0.0
--write_data
will be deprecated at this point, so switch back towrite
if you haven't inv3.0.0
The key names DO contain
data
v1.2.0
-- recommend switching towrite_data
v2.0.0
-- use of adata
key withwrite
will still work in this version but will issue a warning since it will break inv3.0.0
; switch towrite_data
nowv3.0.0
-- you may continue to usewrite_data
, or may switch back towrite
using thedata
argument to set the data dictionary (same method call aswrite_data
)v4.0.0
--write_data
will be deprecated; switch back towrite
using the same method call you've been using withwrite_data
I use the
write
method with dynamic keysYou may have been using this for a long time with no issues. You would only see a problem if your keys contained
path
orwrap_ttl
, however since your keys are dynamic, you cannot predict that in advance. Additionally, a key with the name ofdata
, which does work today inwrite
, will stop working inv3.0.0
without changing the call.v1.2.0
-- switch towrite_data
v3.0.0
-- you may continue to usewrite_data
, or may switch back towrite
using thedata
argument to set the data dictionary (same method call aswrite_data
)v4.0.0
--write_data
will be deprecated; switch back towrite
using the same method call you've been using withwrite_data
If there are any questions about what to do in your specific situation, please let us know!
The text was updated successfully, but these errors were encountered: