Tableau API Lib

Warnings

• breaking The `tableau-api-lib` library mirrors Tableau's REST API. Breaking changes in the underlying Tableau Server/Cloud REST API (e.g., method renames, removed endpoints, or changes in response structure) for a specific API version can implicitly break your `tableau-api-lib` code if the library version you're using does not support the targeted Tableau Server/Cloud version or if you upgrade Tableau Server/Cloud without updating your code for the new API version. Tableau Cloud has quarterly releases, and Tableau Server has releases every eight months, each potentially introducing new REST API versions.
  Fix: Always test your code against the specific Tableau Server or Tableau Cloud version you intend to connect to. Monitor Tableau's official REST API documentation (developer.tableau.com/api-docs/rest-api/rest_api_ref) for breaking changes in new API versions and update your `api_version` in the config accordingly. Upgrade `tableau-api-lib` regularly to ensure compatibility and access to the latest REST API features.
• gotcha The `querying` utility functions, such as `get_sites_dataframe()` or `get_workbooks_dataframe()`, are located in a submodule and must be imported explicitly from `tableau_api_lib.utils.querying`. A common mistake is trying to import them directly from the top-level `tableau_api_lib` package.
  Fix: Ensure you use `from tableau_api_lib.utils import querying` (or `from tableau_api_lib.utils.querying import get_sites_dataframe`) to access these helper functions. Not importing them correctly will result in an `ImportError` or `AttributeError`.
• gotcha API method responses return the raw HTTP response object. To access the data returned by the Tableau REST API, you typically need to call `.json()` on the response object. The structure of the JSON body (e.g., nested keys like `['sites']['site']`) directly corresponds to Tableau's REST API documentation, not necessarily a flattened structure.
  Fix: Always inspect the `.json()` output of a response object. Refer to Tableau's official REST API reference for the specific endpoint you are calling to understand the expected JSON structure and how to navigate it to extract the desired data. For example, `response.json()['sites']['site']` is common for lists of sites.
• gotcha When using Personal Access Tokens (PATs) for authentication, ensure that the `token_name` and `token_value` are correctly provided in your configuration dictionary. If both PAT details and `username`/`password` are present, the library will prioritize PAT authentication. Incorrect or expired PATs will lead to authentication failures.
  Fix: Verify your PAT details (name and secret) in Tableau Server/Cloud. Use `conn.sign_in_with_personal_access_token()` if you intend to use PATs explicitly. If you're mixing auth methods in your config, be aware of the precedence. Ensure PATs have sufficient permissions for the API calls being made.
• gotcha Not all Tableau Server REST API methods support pagination. When using `querying` functions that involve pagination (e.g., `get_all_workbooks`), if the underlying REST API endpoint does not support pagination, you might encounter unexpected errors or truncated results. This can also happen if the connection's authentication token is invalid or expired.
  Fix: Refer to Tableau's REST API documentation to confirm if a specific endpoint supports pagination. Ensure your `TableauServerConnection` is properly authenticated and has a valid token before attempting paginated queries. Check GitHub issues for `tableau-api-lib` for specific pagination-related known issues.

Install

• pip install --upgrade tableau-api-lib Install latest version

Imports

• TableauServerConnection

  from tableau_api_lib import TableauServerConnection

• querying

  from tableau_api_lib.utils import querying

  The 'querying' utility functions (e.g., get_sites_dataframe) are in a submodule and require an explicit import path from 'tableau_api_lib.utils'.
• sample_config

  from tableau_api_lib import sample_config

  Provides a template for the configuration dictionary.

Quickstart

This quickstart demonstrates how to establish a connection to Tableau Server or Tableau Cloud using either username/password or a Personal Access Token (PAT), query available sites, and properly sign out. It uses environment variables for sensitive credentials for better security practices.

import os
from tableau_api_lib import TableauServerConnection
from tableau_api_lib import sample_config

# Define your configuration using environment variables or a direct dictionary
tableau_config = {
    'tableau_prod': {
        'server': os.environ.get('TABLEAU_SERVER', 'https://your.tableau.server.com'),
        'api_version': os.environ.get('TABLEAU_API_VERSION', '3.22'), # Use appropriate API version
        'username': os.environ.get('TABLEAU_USERNAME', 'your_user'),
        'password': os.environ.get('TABLEAU_PASSWORD', 'your_password'),
        'site_name': os.environ.get('TABLEAU_SITE_NAME', 'YourSiteName'),
        'site_url': os.environ.get('TABLEAU_SITE_URL', 'YourSiteUrl'), # Often matches site_name or is an empty string for default site
        'token_name': os.environ.get('TABLEAU_TOKEN_NAME', ''), # For Personal Access Tokens
        'token_value': os.environ.get('TABLEAU_TOKEN_VALUE', ''), # For Personal Access Tokens
    }
}

# If using Personal Access Token, ensure username/password are not set in config
# The library prioritizes PATs if token_name and token_value are present

conn = TableauServerConnection(tableaud_config, env='tableau_prod')

# Sign in using username/password or Personal Access Token
try:
    if tableau_config['tableau_prod'].get('token_name') and tableau_config['tableau_prod'].get('token_value'):
        conn.sign_in_with_personal_access_token()
    else:
        conn.sign_in()
    
    print(f"Successfully signed in to Tableau Server/Cloud (site: {conn.site_id})")

    # Example: Query sites
    response = conn.query_sites()
    if response.status_code == 200:
        sites_json = response.json()
        print("Available Sites:")
        for site in sites_json['sites']['site']:
            print(f"- {site['name']} (ID: {site['id']})")
    else:
        print(f"Failed to query sites: {response.status_code} - {response.text}")

finally:
    # Always sign out to release the connection
    if conn.is_signed_in():
        conn.sign_out()
        print("Signed out from Tableau Server/Cloud.")