{"id":4271,"library":"tableau-api-lib","title":"Tableau API Lib","description":"Tableau API Lib is a Python library that allows developers to interact with Tableau Server's REST API. It mirrors the methods available in Tableau's official REST API documentation, providing an easy way to automate administrative tasks, manage content, and retrieve data from Tableau Server and Tableau Cloud. The library is currently at version 0.1.50 and typically updates to reflect changes and additions in the Tableau REST API.","status":"active","version":"0.1.50","language":"en","source_language":"en","source_url":"https://github.com/divinorum-webb/tableau-api-lib","tags":["tableau","rest-api","automation","data-visualization","server-management","cloud-management","business-intelligence"],"install":[{"cmd":"pip install --upgrade tableau-api-lib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"For making HTTP requests to the Tableau Server REST API.","package":"requests","optional":false},{"reason":"HTTP client library, typically a dependency of 'requests'.","package":"urllib3","optional":false},{"reason":"Used by `querying` utilities to package API responses into DataFrames.","package":"pandas","optional":true},{"reason":"Provides utilities for requests, such as multipart encoding.","package":"requests-toolbelt","optional":false},{"reason":"HTML sanitization library, likely used for handling API responses.","package":"bleach","optional":false},{"reason":"For runtime type checking.","package":"typeguard","optional":false},{"reason":"Core utilities for Python package management.","package":"packaging","optional":false}],"imports":[{"symbol":"TableauServerConnection","correct":"from tableau_api_lib import TableauServerConnection"},{"note":"The 'querying' utility functions (e.g., get_sites_dataframe) are in a submodule and require an explicit import path from 'tableau_api_lib.utils'.","wrong":"from tableau_api_lib import querying","symbol":"querying","correct":"from tableau_api_lib.utils import querying"},{"note":"Provides a template for the configuration dictionary.","symbol":"sample_config","correct":"from tableau_api_lib import sample_config"}],"quickstart":{"code":"import os\nfrom tableau_api_lib import TableauServerConnection\nfrom tableau_api_lib import sample_config\n\n# Define your configuration using environment variables or a direct dictionary\ntableau_config = {\n    'tableau_prod': {\n        'server': os.environ.get('TABLEAU_SERVER', 'https://your.tableau.server.com'),\n        'api_version': os.environ.get('TABLEAU_API_VERSION', '3.22'), # Use appropriate API version\n        'username': os.environ.get('TABLEAU_USERNAME', 'your_user'),\n        'password': os.environ.get('TABLEAU_PASSWORD', 'your_password'),\n        'site_name': os.environ.get('TABLEAU_SITE_NAME', 'YourSiteName'),\n        'site_url': os.environ.get('TABLEAU_SITE_URL', 'YourSiteUrl'), # Often matches site_name or is an empty string for default site\n        'token_name': os.environ.get('TABLEAU_TOKEN_NAME', ''), # For Personal Access Tokens\n        'token_value': os.environ.get('TABLEAU_TOKEN_VALUE', ''), # For Personal Access Tokens\n    }\n}\n\n# If using Personal Access Token, ensure username/password are not set in config\n# The library prioritizes PATs if token_name and token_value are present\n\nconn = TableauServerConnection(tableaud_config, env='tableau_prod')\n\n# Sign in using username/password or Personal Access Token\ntry:\n    if tableau_config['tableau_prod'].get('token_name') and tableau_config['tableau_prod'].get('token_value'):\n        conn.sign_in_with_personal_access_token()\n    else:\n        conn.sign_in()\n    \n    print(f\"Successfully signed in to Tableau Server/Cloud (site: {conn.site_id})\")\n\n    # Example: Query sites\n    response = conn.query_sites()\n    if response.status_code == 200:\n        sites_json = response.json()\n        print(\"Available Sites:\")\n        for site in sites_json['sites']['site']:\n            print(f\"- {site['name']} (ID: {site['id']})\")\n    else:\n        print(f\"Failed to query sites: {response.status_code} - {response.text}\")\n\nfinally:\n    # Always sign out to release the connection\n    if conn.is_signed_in():\n        conn.sign_out()\n        print(\"Signed out from Tableau Server/Cloud.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}