Tableau Server Client (Python)

The Tableau Server Client (TSC) library is a Python wrapper for the Tableau Server REST API. It is designed to increase productivity by providing a Pythonic interface for interacting with Tableau Server.

Key capabilities include:

• Publishing workbooks and data sources.
• Managing users and groups.
• Querying projects, sites, and other server resources.

Note: As of September 2024, support for Python 3.7 and 3.8 is being dropped. Support for older versions follows the official Python version support guidelines.

The Namespace class is used to manage and detect the correct XML namespace for Tableau API responses. It supports two known namespaces:

• http://tableausoftware.com/api (Legacy)
• http://tableau.com/api (Current)

Use the detect(xml) method to inspect the provided XML bytes. If the XML starts with a standard XML declaration (<?xml) and contains a recognized namespace in the root tag, the Namespace instance will update its internal mapping. If an unrecognized namespace is found, it raises UnknownNamespaceError.

Once a Server instance is initialized and you have signed in, you can access various Tableau resources through dedicated attributes. These attributes act as namespaces for specific API endpoints.

Common resource attributes include:

• server.auth: Authentication management
• server.sites: Site management
• server.users: User management
• server.workbooks: Workbook management
• server.datasources: Datasource management
• server.projects: Project management
• server.views: View management
• server.groups: Group management
• server.jobs: Job management
• server.metadata: Metadata access
• ...and many others (e.g., webhooks, flows, metrics, tags).

The tableauserverclient library uses the Config class to manage operational parameters. You can override the default behavior of the library by setting specific environment variables.

Supported environment variables:

• TSC_FILESIZE_LIMIT_MB: Sets the maximum size of a file that can be published in a single request. The value is capped at a maximum of 64MB. Defaults to 64.
• TSC_CHUNK_SIZE_MB: Sets the size of chunks used when breaking down large datasources (over 64MB) for publishing. Defaults to 50.
• TSC_PAGE_SIZE: Sets the default page size for paginated requests. Defaults to 100.

# Example: Overriding defaults via shell
export TSC_PAGE_SIZE=50
export TSC_CHUNK_SIZE_MB=25
python your_script.py

You can pass additional configuration to the underlying requests library using add_http_options(options_dict). This is useful for configuring SSL verification or other request-level settings.

• add_http_options(options_dict): Updates the current HTTP options with the provided dictionary.
• clear_http_options(): Resets the HTTP options to an empty dictionary.

Note: If you set "verify": False in your options, the library will automatically disable urllib3 insecure request warnings.

import tableauserverclient as TSC

server = TSC.Server('https://MY-SERVER')

# Example: Disabling SSL verification
server.add_http_options({'verify': False})

When using Python 3.12 or later with older Tableau Server versions, you might encounter SSL errors due to modern Python enforcing stronger security requirements for Diffie-Hellman (DH) keys.

You can use configure_ssl(allow_weak_dh=True) as a temporary workaround.

WARNING: This reduces security by allowing DH keys as small as 512 bits. Use this only as a temporary measure until the server is upgraded.

import tableauserverclient as TSC

server = TSC.Server('https://MY-SERVER')

# Workaround for SSL errors in Python 3.12+ with older servers
server.configure_ssl(allow_weak_dh=True)

The REST API version determines which features are accessible. You can manage this in two ways:

1. Automatic Detection: Call use_server_version() to query the server and set the library to use the highest supported REST API version.
2. Manual Setting: Set the version attribute directly to a specific string (e.g., '2.8').

By default, the library uses version '2.4' (the first version that dropped the legacy auth endpoint), though it may default to '2.3' (Tableau Server 10.0) in some contexts.

import tableauserverclient as TSC

server = TSC.Server('https://MY-SERVER')

# Option 1: Automatically detect and use the highest version
server.use_server_version()

# Option 2: Manually specify a version
server.version = '2.8'

The tableauserverclient package exposes the primary entry points for interacting with Tableau Server. The core of the library is the Server class, which is used to manage connections and perform operations. Authentication is handled via various auth classes such as TableauAuth and PersonalAccessTokenAuth. Data models for Tableau resources (like WorkbookItem, DatasourceItem, UserItem, etc.) and request options for downloads (like PDFRequestOptions, CSVRequestOptions) are also available at the top level.

import tableauserverclient as TSC

# Example of the primary components available
# TSC.Server: The main client class
# TSC.TableauAuth: For username/password authentication
# TSC.WorkbookItem: Model for workbooks
# TSC.PDFRequestOptions: Options for downloading PDFs

The PublishMode class enumerates the options available when publishing a workbook or data source to Tableau Server.

# Available options:
# PublishMode.Append
# PublishMode.Overwrite
# PublishMode.CreateNew
# PublishMode.Replace

Use these classes to configure specific requests (like file downloads) or to handle server responses and pagination:

CSVRequestOptions
ExcelRequestOptions
ImageRequestOptions
PDFRequestOptions
PPTXRequestOptions
RequestOptions
Filter
Pager
Sort