This post outlines a bittersweet event: the release of tableau_tools 6, which will also be the final release of the library by me, the original author of the library. My time at Tableau has come to an end, but ownership of this blog and all of the various code will remain with Tableau. As the project has always been open-source under a permissive license, this just means that there won’t be any updates from me, but the project can continue as long as it proves useful to someone.
As always, you can install or upgrade tableau_tools from PyPi.org via pip:
pip install tableau_tools --upgrade
Note: Version 6.0.0 does break some backward compatibility (see below) and you may need to do some slight updates to code that used a 5.0.0 release, or a lot if you are still using 4.0.0.
What is different in version 6?
- Removal of the old style TableauRestApiConnection class. Only TableauServerRest remains. No functionality is lost but you may need to update old code
- Added an “API Version Override” so you can set what API version is being used in the URLs. Also removed a lot of “option checks” so the library remains useful even as newer versions of Tableau are released
- Older versions of tableau_tools had fairly strict checking on options to always match what was available in a given version of the Tableau Server REST API. Unfortunately this also meant the library could get far behind if it wasn’t updated, without the ability to override and force newer versions / options. So those limitations have been removed
- CREATE and UPDATE Site method refactoring: At some point, the number of possible options for these endpoints made it difficult to cover all the possibilities within the arguments of the method. As part of the “allow future changes” design of version 6, only the site_name and site_content_url arguments will be defined in the method, and then it will accept a Dict for all other options. You will have to check the Tableau Server REST API documentation for valid options.
- Methods that had all of their possible Filters listed out as arguments, have been reduced down to just take a list of UrlFilter objects, and all of the checking removed. More future proofing – maybe more options will be available you’ll want to take advantage of.
- Documentation on the basic structure and methods in the README. If anyone wants to take over maintenance, or just needs to implement something newer from a more recent API release, the documentation of the simplest pieces of the library is now available for you to build with.
Thoughts on tableau_tools vs. Tableau Server Client and tableau-api-lib
It’s 2021 (thankfully!), and you are reading this, and probably thinking – why are there multiple libraries for working with the Tableau REST API. It’s a long story, but in essence much of tableau_tools and the content on this blog covering it was written before the Tableau Server Client (TSC) library either existed or was mature enough to cover certain use cases. There is also the tableau-api-lib which is a newer implementation along the original lines of what tableau_tools started out as, and it seems fine for getting work done, but doesn’t seem to have some of the abstraction layers of tableau_tools.
All of the libraries are fit for a wide number of purposes. tableau_tools is distinguished by having two main packages:
- tableau_rest_api: Equivalent to TSC, used to send Tableau REST API commands
- tableau_documents: Equivalent to the Tableau Document API , used for modifying the Tableau XML documents themselves
There was a time where tableau_rest_api referenced some of the tableau_documents capabilities, but there are no longer any supported versions of Tableau Server where those techniques were necessary, so either component can be used by itself.
Where is tableau_tools still a strong choice?
- Dealing with Permissions on Tableau Server: There is a whole abstraction layer dealing with Published Content and Permissions, designed for replicating setups across many sites programmatically.
- Login Impersonation: Necessary for exposing a restricted form of the Rest API as a web service to the browser. There is even a class designed to be used in Flask or Django just for this purpose
- XML Document Modification: tableau_documents has more capabilities than the Document API, including updating TDSX / TWBX files with newly generated Hyper files from the Hyper API
- Very complex searching using XPath queries on the XML results: Tableau Server REST API has a lot more filtering possible through the API than it started with, but there are still plenty of requests that need filtering on the result set, and tableau_tools has those requests built in
- A learning tool / reference for the XML requests if you are building REST API calls in another language: The logging modes in tableau_tools can spit out the exact URL and XML of both requests and responses in a way that can be reasonably followed. Particularly for complex chains of actions, you can use tableau_tools as a prototype to double-check that your own code is doing the right thing.
If you have any of these needs in your project, then it is worth considering tableau_tools for at least some of the implementation. Otherwise, you should go with the TSC as it is more widely used, available, and supported within Tableau and the partner network.
(more…)