Breaking changes coming to `Client.write` method

[briantist]

Summary

The Client.write method is a generic function for "writing" (POSTing) 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:

• Cannot write to keys named "path" #133

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 via kwargs. 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 in kwargs.

The plan

We will first introduce a new (temporary!) method, Client.write_data which can be used as an alternative to Client.write and accepts only the data 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 the write_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 as write_data does today, and write_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 -- The Client.write_data method is added
  • add Client.write_data method #1028
• v2.0.0 -- update write as follows:
  • remove the (explicit) arguments path and wrap_ttl, add *args
  • set value of path and wrap_ttl based on *args (for positional) and **kwargs
  • if path or wrap_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 of write_data or setting these positionally
  • if data exists in kwargs we'll also warn about its impending use (see next items) and suggest write_data
• v3.0.0 -- "activate" a data parameter in write:
  • if kwargs contains data and no other non-argument keys, then this call will operate the same as write_data (forward compatible)
  • if kwargs contains both data and other data keys, raise an exception
  • otherwise, it will operate the same as write does now (backward compatible), with a deprecation warning that kwargs is to be removed in v4.0.0, suggesting using the data dictionary going forward
• v4.0.0 -- update write to its Final Form™:
  • remove *args and **kwargs, and return to defined arguments for path, wrap_ttl, and data
  • no more warnings
  • at this point, write basically becomes write_data
• v4.0.0 -- mark write_data as an alias for write in documentation
  • deprecate its name in favor of write, to be removed in v5.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:

• static keys -- this means the key names that you use are fully known at design time, or that the keys you use at runtime are limited to a known set
• dynamic keys -- this means that the key names are unknown during design time, that is you read or generate them and cannot know ahead of time what names will or will not be included

I use the write method with static keys, and

The key names DO NOT contain the names path, wrap_ttl, or data

• write will continue to work for you until v4.0.0
• In v2.0.0, you will see warnings if you are setting path or wrap_ttl via kwargs. If you want to stop the warnings, there are two possibilities:
  • keep using the write method but switch the path and wrap_ttl arguments to positional
  • switch to write_data and set data via the data argument; eventually will change this method call back to write
• In v3.0.0, you should update your usage of the write method to set data via the data argument
  • client.write(path='/a/b/c', wrap_ttl='5m', key1='A', key2='B') should become client.write(path='/a/b/c', wrap_ttl='5m', data={'key1': 'A', 'key2': 'B'})
  • if you switched to write_data in v2.0.0, you may switch back to write at this point with no other changes to the call
• In v4.0.0, no changes are necessary if you were using write with the data argument in v3. If you switched to write_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 to write_data
• v3.0.0 -- you may switch back to write at this point with the same method call as write_data
• v4.0.0 -- write_data will be deprecated at this point, so switch back to write if you haven't in v3.0.0

The key names DO contain data

• v1.2.0 -- recommend switching to write_data
• v2.0.0 -- use of a data key with write will still work in this version but will issue a warning since it will break in v3.0.0; switch to write_data now
• v3.0.0 -- you may continue to use write_data, or may switch back to write using the data argument to set the data dictionary (same method call as write_data)
• v4.0.0 -- write_data will be deprecated; switch back to write using the same method call you've been using with write_data

I use the write method with dynamic keys

You may have been using this for a long time with no issues. You would only see a problem if your keys contained path or wrap_ttl, however since your keys are dynamic, you cannot predict that in advance. Additionally, a key with the name of data, which does work today in write, will stop working in v3.0.0 without changing the call.

• v1.2.0 -- switch to write_data
• v3.0.0 -- you may continue to use write_data, or may switch back to write using the data argument to set the data dictionary (same method call as write_data)
• v4.0.0 -- write_data will be deprecated; switch back to write using the same method call you've been using with write_data

---

If there are any questions about what to do in your specific situation, please let us know!