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.

What distinguishes tableau_tools.tableau_rest_api?

The tableau_tools.tableau_rest_api package follows (relatively) the following principles in its design:

• All Methods in the Tableau REST API Reference are implemented with the exact naming convention (converted to standard Python style), with all options available as arguments of the method:
  • Example: CREATE GROUP is implemented as create_group(group_name: str) [Note: the latest versions have additional new parameters)
  • TSC instead has a design of modifying a Python Object representing the Tableau Object, then using methods on an Endpoint representation to cause the actual REST API commands to happen
• All Responses from GET or QUERY methods are returned as standard Python ElementTree objects
  • TSC transforms responses into defined Python Objects that represent the various Tableau Server Objects described by the XML
• Most CREATE and UPDATE methods have a direct_xml_request argument for situations where you need want to bypass the internal methods (perhaps the library has not been updated for new properties in a new version of Tableau)
• “PublishedContent” types, representing objects on Tableau Server (Project, Workbook, Datasource, Prep Flow, etc.), are complex Python objects that contain all of the necessary mechanisms for efficiently setting Permissions and Default Permissions on Tableau Server

Using tableau_tools.documents for XML file modification

Tableau’s files are mostly composed of XML (Tableau Prep files are JSON), and since there are no Tableau Server APIs for doing a number of necessary things, tableau_tools includes a package for directly modifying the XML files. As mentioned above, this is directly equivalent to the Tableau Document API Python library (which is just a Python library) and works in basically the same way. Since they work the same fundamental manner but tableau_tools does more, there is no reason to not use tableau_tools.tableau_documents for these activities.

We use XML modification primarily when moving or copying content from Dev to Test to Prod or for publishing variations of a template file to different Tableau Sites.

Major Use Cases:

• Updating a TWBX or TDSX with a new Hyper file generated from the Hyper API
• Changes to connection string details
• Changing a Custom SQL query
• Switching Stored Procedure parameters