tableau-cli 0.1.0__py3-none-any.whl

tableau_cli/errors/vds_error_handler.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from .cli_error import CliError
+
+# condition and details texts are aligned word-for-word with MCP's queryDatasourceErrorHandler.ts.
+# hint is CLI-specific added value (agent-friendly actionable guidance).
+VDS_ERROR_MAP: dict[str, dict[str, str | None]] = {
+    "400000": {
+        "condition": "Bad request",
+        "details": "The content of the request body is invalid. Check for missing or incomplete JSON.",
+        "hint": "Verify the --query JSON is valid and complete.",
+    },
+    "400800": {
+        "condition": "Invalid formula for calculation",
+        "details": "Invalid custom calculation syntax. For help, see https://help.tableau.com/current/pro/desktop/en-us/functions_operators.htm",
+        "hint": None,
+    },
+    "400802": {
+        "condition": "Invalid API request",
+        "details": "The incoming request isn't valid per the OpenAPI specification.",
+        "hint": None,
+    },
+    "400803": {
+        "condition": "Validation failed",
+        "details": "The incoming request isn't valid per the validation rules.",
+        "hint": (
+            "Check that all field names and filter values match the datasource metadata. "
+            "Use `tableau-cli datasources metadata <luid>` to verify available fields."
+        ),
+    },
+    "400804": {
+        "condition": "Response too large",
+        "details": "The response value exceeds the limit. You must apply a filter in your request.",
+        "hint": "Use --limit to restrict row count, or add filters to your query.",
+    },
+    "401001": {
+        "condition": "Login error",
+        "details": "The login failed for the given user.",
+        "hint": "Check your PAT credentials with `tableau-cli config show`.",
+    },
+    "401002": {
+        "condition": "Invalid authorization credentials",
+        "details": "The provided auth token is formatted incorrectly.",
+        "hint": (
+            "Re-authenticate by updating your PAT with `tableau-cli config set --pat-name <name> --pat-value <value>`."
+        ),
+    },
+    "403157": {
+        "condition": "Feature disabled",
+        "details": "The feature is disabled.",
+        "hint": (
+            "Ask your Tableau Server admin to enable VizQL Data Service via TSM. "
+            "See https://help.tableau.com/current/server-linux/en-us/cli_configuration-set_tsm.htm"
+        ),
+    },
+    "403800": {
+        "condition": "API access permission denied",
+        "details": (
+            "The user doesn't have API Access granted on the given data source. "
+            "Set the API Access capability for the given data source to Allowed. "
+            "For help, see https://help.tableau.com/current/online/en-us/permissions_capabilities.htm"
+        ),
+        "hint": None,
+    },
+    "404934": {
+        "condition": "Unknown field",
+        "details": "The requested field doesn't exist.",
+        "hint": ("Use `tableau-cli datasources metadata <luid>` to see available fields and their exact names."),
+    },
+    "404950": {
+        "condition": "API endpoint not found",
+        "details": "The request endpoint doesn't exist.",
+        "hint": "This feature may not be available on your Tableau Server version.",
+    },
+    "408000": {
+        "condition": "Request timeout",
+        "details": "The request timed out.",
+        "hint": "Try adding filters to reduce the data volume, or simplify your query.",
+    },
+    "429000": {
+        "condition": "Too many requests",
+        "details": (
+            "Too many requests in the allotted amount of time. "
+            "For help, see https://help.tableau.com/current/api/vizql-data-service/en-us/docs/vds_limitations.html#licensing-and-data-transfer"
+        ),
+        "hint": "Wait before retrying.",
+    },
+    "409000": {
+        "condition": "User already on site",
+        "details": "HTTP status conflict.",
+        "hint": None,
+    },
+    "500000": {
+        "condition": "Internal server error",
+        "details": "The request could not be completed.",
+        "hint": None,
+    },
+    "500810": {
+        "condition": "VDS empty table response",
+        "details": "The underlying data engine returned empty data value response.",
+        "hint": "The datasource may have no data, or your filters may be too restrictive.",
+    },
+    "500811": {
+        "condition": "VDS missing table",
+        "details": "The underlying data engine returned empty metadata associated with response.",
+        "hint": None,
+    },
+    "500812": {
+        "condition": "Error while processing an error",
+        "details": "Internal processing error.",
+        "hint": None,
+    },
+    "501000": {
+        "condition": "Not implemented",
+        "details": "Can't find response from upstream server.",
+        "hint": None,
+    },
+    "503800": {
+        "condition": "VDS unavailable",
+        "details": "The underlying data engine is unavailable.",
+        "hint": "The server may be under maintenance. Try again later.",
+    },
+    "503801": {
+        "condition": "VDS discovery error",
+        "details": "The upstream service can't be found.",
+        "hint": "The server may be under maintenance. Try again later.",
+    },
+    "504000": {
+        "condition": "Gateway timeout",
+        "details": "The upstream service response timed out.",
+        "hint": "Try a simpler query with fewer fields or more restrictive filters.",
+    },
+}
+
+
+def handle_vds_error(
+    error_message: str,
+    http_status: int,
+    tableau_error_code: str | None,
+) -> CliError:
+    entry = VDS_ERROR_MAP.get(tableau_error_code or "")
+
+    if entry:
+        condition = entry["condition"]
+        return CliError(
+            error_type=condition or "tableau-error",
+            message=f"{condition}: {error_message}" if condition else error_message,
+            details=entry.get("details"),
+            hint=entry.get("hint"),
+        )
+
+    return CliError(
+        error_type="tableau-error",
+        message=error_message,
+    )

tableau_cli/output/format.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .json_output import output_json
+from .table_output import output_table
+
+
+def output(data: Any, fmt: str) -> None:
+    if fmt == "table" and isinstance(data, list):
+        output_table(data)
+    else:
+        output_json(data)

tableau_cli/output/json_output.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def output_json(data: Any) -> None:
+    sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")

tableau_cli/output/table_output.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float, bool)):
+        return str(value)
+    if isinstance(value, list):
+        if len(value) == 0:
+            return ""
+        # Handle tags: [{"label": "x"}, ...]
+        if isinstance(value[0], dict) and "label" in value[0]:
+            return ", ".join(v.get("label", "") for v in value)
+        return ", ".join(_format_value(v) for v in value)
+    if isinstance(value, dict):
+        # Handle tags object: {"tag": [{"label": "x"}, ...]}
+        if "tag" in value:
+            tag = value["tag"]
+            if isinstance(tag, list):
+                return ", ".join(t.get("label", "") for t in tag)
+            return ""
+        # Handle empty-like objects
+        non_null = {k: v for k, v in value.items() if v is not None}
+        if not non_null:
+            return ""
+        # Handle common nested objects
+        if "name" in value and value["name"]:
+            return str(value["name"])
+        if "id" in value and value["id"]:
+            return str(value["id"])
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+def output_table(rows: list[dict[str, Any]]) -> None:
+    if not rows:
+        sys.stdout.write("(no results)\n")
+        return
+
+    columns = list(rows[0].keys())
+    formatted = [{col: _format_value(row.get(col)) for col in columns} for row in rows]
+
+    widths = [max(len(col), *(len(row[col]) for row in formatted)) for col in columns]
+
+    header = "  ".join(col.upper().ljust(w) for col, w in zip(columns, widths, strict=True))
+    separator = "  ".join("-" * w for w in widths)
+
+    sys.stdout.write(header + "\n")
+    sys.stdout.write(separator + "\n")
+
+    for row in formatted:
+        line = "  ".join(row[col].ljust(w) for col, w in zip(columns, widths, strict=True))
+        sys.stdout.write(line + "\n")

tableau_cli/utils/datasource_metadata_utils.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def get_graphql_query(datasource_luid: str) -> str:
+    return f"""
+  query datasourceFieldInfo {{
+    publishedDatasources(filter: {{ luid: "{datasource_luid}" }}) {{
+      name
+      description
+      owner {{
+        name
+      }}
+      fields {{
+        name
+        isHidden
+        description
+        descriptionInherited {{
+          attribute
+          value
+        }}
+        fullyQualifiedName
+        __typename
+        upstreamTables {{
+          name
+        }}
+        ... on AnalyticsField {{
+          __typename
+        }}
+        ... on ColumnField {{
+          dataCategory
+          role
+          dataType
+          defaultFormat
+          semanticRole
+          aggregation
+          aggregationParam
+        }}
+        ... on CalculatedField {{
+          dataCategory
+          role
+          dataType
+          defaultFormat
+          semanticRole
+          aggregation
+          aggregationParam
+          formula
+          isAutoGenerated
+          hasUserReference
+        }}
+        ... on BinField {{
+          dataCategory
+          role
+          dataType
+          formula
+          binSize
+        }}
+        ... on GroupField {{
+          dataCategory
+          role
+          dataType
+          hasOther
+        }}
+        ... on CombinedSetField {{
+          delimiter
+          combinationType
+        }}
+      }}
+    }}
+  }}"""
+
+
+def _normalize_logical_table_id(logical_table_id: str | None) -> str | None:
+    if logical_table_id is None:
+        return None
+    normalized = logical_table_id.strip()
+    return normalized if normalized else None
+
+
+def _group_fields_by_logical_table_id(
+    fields: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    grouped: dict[str | None, list[dict[str, Any]]] = {}
+    for field in fields:
+        key = field.get("logicalTableId")
+        grouped.setdefault(key, []).append(field)
+    return [{"logicalTableId": k, "fields": v} for k, v in grouped.items()]
+
+
+def _populate_field_with_additional_properties(source_field: dict[str, Any], target_field: dict[str, Any]) -> None:
+    if source_field.get("description"):
+        target_field["description"] = source_field["description"]
+    desc_inherited = source_field.get("descriptionInherited")
+    if isinstance(desc_inherited, list) and desc_inherited:
+        target_field["descriptionInherited"] = desc_inherited
+    if source_field.get("dataCategory"):
+        target_field["dataCategory"] = source_field["dataCategory"]
+    if source_field.get("role"):
+        target_field["role"] = source_field["role"]
+    if source_field.get("defaultFormat"):
+        target_field["defaultFormat"] = source_field["defaultFormat"]
+    if source_field.get("formula"):
+        target_field["formula"] = source_field["formula"]
+        if source_field.get("isAutoGenerated") is not None:
+            target_field["isAutoGenerated"] = source_field["isAutoGenerated"]
+        if source_field.get("hasUserReference") is not None:
+            target_field["hasUserReference"] = source_field["hasUserReference"]
+    if source_field.get("binSize") is not None:
+        target_field["binSize"] = source_field["binSize"]
+
+
+def _build_parameters(extra_data: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not extra_data or not extra_data.get("parameters"):
+        return []
+    parameters: list[dict[str, Any]] = []
+    for param in extra_data["parameters"]:
+        entry: dict[str, Any] = {
+            "name": param.get("parameterCaption"),
+            "parameterType": param.get("parameterType"),
+            "dataType": param.get("dataType"),
+            "value": param.get("value"),
+        }
+        param_type = param.get("parameterType")
+        if param_type == "LIST" and param.get("members"):
+            entry["members"] = param["members"]
+        elif param_type == "QUANTITATIVE_DATE":
+            entry["minDate"] = param.get("minDate")
+            entry["maxDate"] = param.get("maxDate")
+            entry["periodValue"] = param.get("periodValue")
+            entry["periodType"] = param.get("periodType")
+        elif param_type == "QUANTITATIVE_RANGE":
+            entry["min"] = param.get("min")
+            entry["max"] = param.get("max")
+            entry["step"] = param.get("step")
+        parameters.append(entry)
+    return parameters
+
+
+def simplify_read_metadata_result(
+    read_metadata_result: dict[str, Any],
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "datasourceDescription": "",
+        "fieldGroups": [],
+        "parameters": [],
+    }
+
+    data = read_metadata_result.get("data")
+    if not data:
+        return result
+
+    fields: list[dict[str, Any]] = []
+    for field in data:
+        entry: dict[str, Any] = {
+            "name": field.get("fieldCaption"),
+            "dataType": field.get("dataType"),
+            "columnClass": field.get("columnClass"),
+            "logicalTableId": _normalize_logical_table_id(field.get("logicalTableId")),
+        }
+        if field.get("defaultAggregation"):
+            entry["defaultAggregation"] = field["defaultAggregation"]
+        if field.get("formula"):
+            entry["formula"] = field["formula"]
+        fields.append(entry)
+
+    result["parameters"] = _build_parameters(read_metadata_result.get("extraData"))
+    result["fieldGroups"] = _group_fields_by_logical_table_id(fields)
+    return result
+
+
+def combine_fields(
+    read_metadata_result: dict[str, Any],
+    list_fields_result: dict[str, Any],
+) -> dict[str, Any]:
+    ds_list = list_fields_result.get("data", {}).get("publishedDatasources", [])
+    ds = ds_list[0] if ds_list else None
+
+    combined: dict[str, Any] = {
+        "datasourceDescription": (ds.get("description") or "") if ds else "",
+        "fieldGroups": [],
+        "parameters": [],
+    }
+
+    data = read_metadata_result.get("data")
+    fields: list[dict[str, Any]] = []
+
+    if not data:
+        # Fallback to GraphQL results
+        if ds and ds.get("fields"):
+            for field in ds["fields"]:
+                entry: dict[str, Any] = {
+                    "name": field.get("name"),
+                    "logicalTableId": None,
+                }
+                if field.get("dataType"):
+                    entry["dataType"] = field["dataType"]
+                if field.get("aggregation"):
+                    entry["defaultAggregation"] = field["aggregation"]
+                _populate_field_with_additional_properties(field, entry)
+                fields.append(entry)
+        combined["fieldGroups"] = _group_fields_by_logical_table_id(fields)
+        return combined
+
+    # Build fields from VizQL Data Service
+    for field in data:
+        entry = {
+            "name": field.get("fieldCaption"),
+            "dataType": field.get("dataType"),
+            "columnClass": field.get("columnClass"),
+            "logicalTableId": _normalize_logical_table_id(field.get("logicalTableId")),
+        }
+        if field.get("defaultAggregation"):
+            entry["defaultAggregation"] = field["defaultAggregation"]
+        if field.get("formula"):
+            entry["formula"] = field["formula"]
+        fields.append(entry)
+
+    combined["parameters"] = _build_parameters(read_metadata_result.get("extraData"))
+
+    # Enrich fields with GraphQL data
+    if ds and ds.get("fields"):
+        for field in fields:
+            match = next((f for f in ds["fields"] if f.get("name") == field.get("name")), None)
+            if match:
+                _populate_field_with_additional_properties(match, field)
+
+    combined["fieldGroups"] = _group_fields_by_logical_table_id(fields)
+    return combined

tableau_cli/utils/paginate.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+def paginate(
+    *,
+    page_size: int | None = None,
+    limit: int | None = None,
+    get_data_fn: Callable[[int | None, int | None], dict[str, Any]],
+) -> list[Any]:
+    """Paginate through Tableau REST API results.
+
+    get_data_fn(page_size, page_number) should return {"pagination": {...}, "data": [...]}.
+    """
+    response = get_data_fn(page_size, None)
+    pagination = response["pagination"]
+    result = list(response["data"])
+
+    total_available: int = pagination["totalAvailable"]
+    page_number: int = pagination["pageNumber"]
+
+    while total_available > len(result) and (not limit or limit > len(result)):
+        response = get_data_fn(page_size, page_number + 1)
+        next_data = response["data"]
+
+        if len(next_data) == 0:
+            raise RuntimeError(
+                f"No more data available. Last fetched page number: {page_number}, "
+                f"Total available: {total_available}, Total fetched: {len(result)}"
+            )
+
+        pagination = response["pagination"]
+        total_available = pagination["totalAvailable"]
+        page_number = pagination["pageNumber"]
+        result.extend(next_data)
+
+    if limit and limit < len(result):
+        result = result[:limit]
+
+    return result

tableau_cli/utils/search_content_utils.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _get_reduced_search_item_content(content: dict[str, Any]) -> dict[str, Any]:
+    r: dict[str, Any] = {}
+    if content.get("modifiedTime"):
+        r["modifiedTime"] = content["modifiedTime"]
+    if content.get("sheetType"):
+        r["sheetType"] = content["sheetType"]
+    if content.get("caption"):
+        r["caption"] = content["caption"]
+    if content.get("workbookDescription"):
+        r["workbookDescription"] = content["workbookDescription"]
+    if content.get("type"):
+        r["type"] = content["type"]
+    if content.get("ownerId"):
+        r["ownerId"] = content["ownerId"]
+    if content.get("title"):
+        r["title"] = content["title"]
+    if content.get("ownerName"):
+        r["ownerName"] = content["ownerName"]
+    if content.get("containerName"):
+        if content.get("type") == "view":
+            r["parentWorkbookName"] = content["containerName"]
+        else:
+            r["containerName"] = content["containerName"]
+    if content.get("luid"):
+        r["luid"] = content["luid"]
+    if content.get("locationName"):
+        r["locationName"] = content["locationName"]
+    if isinstance(content.get("comments"), list) and content["comments"]:
+        r["comments"] = content["comments"]
+    if content.get("hitsTotal") is not None:
+        r["totalViewCount"] = content["hitsTotal"]
+    if content.get("favoritesTotal") is not None:
+        r["favoritesTotal"] = content["favoritesTotal"]
+    if isinstance(content.get("tags"), list) and content["tags"]:
+        r["tags"] = content["tags"]
+    if content.get("projectId"):
+        r["projectId"] = content["projectId"]
+    if content.get("projectName"):
+        r["projectName"] = content["projectName"]
+    if content.get("hitsSmallSpanTotal") is not None:
+        r["viewCountLastMonth"] = content["hitsSmallSpanTotal"]
+    if content.get("downstreamWorkbookCount") is not None:
+        r["downstreamWorkbookCount"] = content["downstreamWorkbookCount"]
+    if content.get("isConnectable") is not None:
+        r["isConnectable"] = content["isConnectable"]
+    if content.get("datasourceIsPublished") is not None:
+        r["datasourceIsPublished"] = content["datasourceIsPublished"]
+    if content.get("connectionType"):
+        r["connectionType"] = content["connectionType"]
+    if content.get("isCertified") is not None:
+        r["isCertified"] = content["isCertified"]
+    if content.get("hasExtracts") is not None:
+        r["hasExtracts"] = content["hasExtracts"]
+    if content.get("extractRefreshedAt"):
+        r["extractRefreshedAt"] = content["extractRefreshedAt"]
+    if content.get("extractUpdatedAt"):
+        r["extractUpdatedAt"] = content["extractUpdatedAt"]
+    if content.get("connectedWorkbooksCount") is not None:
+        r["connectedWorkbooksCount"] = content["connectedWorkbooksCount"]
+    if content.get("extractCreationPending") is not None:
+        r["extractCreationPending"] = content["extractCreationPending"]
+    if content.get("hasSevereDataQualityWarning") is not None:
+        r["hasSevereDataQualityWarning"] = content["hasSevereDataQualityWarning"]
+    if content.get("datasourceLuid"):
+        r["datasourceLuid"] = content["datasourceLuid"]
+    if content.get("hasActiveDataQualityWarning") is not None:
+        r["hasActiveDataQualityWarning"] = content["hasActiveDataQualityWarning"]
+    return r
+
+
+def reduce_search_content_response(response: dict[str, Any]) -> list[dict[str, Any]]:
+    search_results: list[dict[str, Any]] = []
+    items = response.get("items") or []
+    for item in items:
+        search_results.append(_get_reduced_search_item_content(item.get("content", {})))
+
+    # Remove duplicate datasources with luid matching a unifieddatasource's datasourceLuid
+    unified_datasource_luids: set[str] = set()
+    for item in search_results:
+        if item.get("type") == "unifieddatasource" and isinstance(item.get("datasourceLuid"), str):
+            unified_datasource_luids.add(item["datasourceLuid"])
+
+    search_results = [
+        item
+        for item in search_results
+        if not (
+            item.get("type") == "datasource"
+            and isinstance(item.get("luid"), str)
+            and item["luid"] in unified_datasource_luids
+        )
+    ]
+
+    # Normalize unifieddatasource entries to datasource entries
+    for item in search_results:
+        if item.get("type") == "unifieddatasource":
+            item["type"] = "datasource"
+            item["luid"] = item.pop("datasourceLuid", None)
+
+    return search_results