tableau-cli 0.1.0__py3-none-any.whl

tableau_cli/commands/convert_cmd.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import TYPE_CHECKING
+from zipfile import ZipFile
+
+import click
+
+from ..errors.cli_error import CliError
+from ..output.format import output
+
+if TYPE_CHECKING:
+    import polars as pl
+
+CONVERT_DEPS = ("pantab", "polars", "pyarrow")
+SUPPORTED_FORMATS = ("parquet", "csv")
+
+
+def _check_convert_deps() -> None:
+    """Check that optional convert dependencies are installed."""
+    missing = [pkg for pkg in CONVERT_DEPS if not _is_importable(pkg)]
+    if missing:
+        raise CliError(
+            error_type="missing-dependencies",
+            message=f"Convert requires packages not installed: {', '.join(missing)}",
+            hint="Run `pip install tableau-cli[convert]` to install conversion dependencies.",
+        )
+
+
+def _is_importable(name: str) -> bool:
+    try:
+        __import__(name)
+        return True
+    except ImportError:
+        return False
+
+
+def _extract_hyper_from_tdsx(tdsx_path: Path, target_dir: Path) -> Path:
+    """Extract the .hyper file from a TDSX archive."""
+    with ZipFile(tdsx_path) as zf:
+        members = [m for m in zf.namelist() if m.endswith(".hyper")]
+        if len(members) == 0:
+            raise CliError(
+                error_type="convert-error",
+                message=f"No .hyper file found in {tdsx_path.name}",
+                hint="This datasource may be a live connection with no embedded data.",
+            )
+        if len(members) != 1:
+            raise CliError(
+                error_type="convert-error",
+                message=f"Found {len(members)} .hyper files in {tdsx_path.name}, expected 1",
+            )
+        member = members[0]
+        zf.extract(member, path=target_dir)
+        extracted = target_dir / member
+        if extracted.parent != target_dir:
+            final_path = target_dir / extracted.name
+            extracted.replace(final_path)
+            return final_path
+        return extracted
+
+
+def _read_hyper(hyper_path: Path) -> pl.DataFrame:
+    """Read .hyper file and return as Polars DataFrame."""
+    import pantab
+    import polars as pl
+
+    frames = pantab.frames_from_hyper(str(hyper_path))
+    if not frames:
+        raise CliError(
+            error_type="convert-error",
+            message=f"No tables found in {hyper_path.name}",
+        )
+    if len(frames) != 1:
+        raise CliError(
+            error_type="convert-error",
+            message=f"Found {len(frames)} tables in {hyper_path.name}, expected 1",
+            hint="Multi-table hyper files are not supported yet.",
+        )
+    return pl.from_pandas(next(iter(frames.values())))
+
+
+def _write_df(df: pl.DataFrame, output_path: Path, to: str) -> None:
+    """Write DataFrame to the specified format."""
+    if to == "parquet":
+        df.write_parquet(output_path)
+    elif to == "csv":
+        df.write_csv(output_path)
+
+
+@click.command("convert")
+@click.argument("input_path", type=click.Path(exists=True))
+@click.option(
+    "--to", "to_fmt", default="parquet", type=click.Choice(SUPPORTED_FORMATS), help="Output format (default: parquet)"
+)
+@click.option("-o", "--output", "output_path", default=None, help="Output file or directory (default: same as input)")
+def convert_command(input_path, to_fmt, output_path):
+    """Convert TDSX/HYPER files to Parquet or CSV format."""
+    _check_convert_deps()
+
+    input_p = Path(input_path)
+    suffix = input_p.suffix.lower()
+
+    if suffix not in (".tdsx", ".hyper"):
+        raise CliError(
+            error_type="invalid-input",
+            message=f"Unsupported file type: {suffix}",
+            hint="Supported formats: .tdsx, .hyper",
+        )
+
+    # Resolve output path
+    ext = f".{to_fmt}"
+    if output_path is None:
+        out_p = input_p.with_suffix(ext)
+    elif os.path.isdir(output_path):
+        out_p = Path(output_path) / f"{input_p.stem}{ext}"
+    else:
+        out_p = Path(output_path)
+
+    # Read hyper data
+    if suffix == ".hyper":
+        df = _read_hyper(input_p)
+    else:
+        with TemporaryDirectory() as td:
+            hyper_path = _extract_hyper_from_tdsx(input_p, Path(td))
+            df = _read_hyper(hyper_path)
+
+    _write_df(df, out_p, to_fmt)
+
+    abs_path = os.path.abspath(out_p)
+    sys.stderr.write(f"Converted to {abs_path}\n")
+    output({"filePath": abs_path}, "json")

tableau_cli/commands/datasources_cmd.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import click
+
+from ..auth.with_auth import with_auth
+from ..config.store import resolve_config
+from ..output.format import output
+from ..utils.paginate import paginate
+
+
+@click.group("datasources")
+def datasources_group():
+    """Manage data sources."""
+
+
+# Alias: allow 'ds' as well
+ds_group = datasources_group
+
+
+@datasources_group.command("list")
+@click.option("--filter", "filter_", default=None, help="Filter string (e.g., name:eq:Superstore)")
+@click.option("--page-size", default=None, type=int, help="Page size for API requests")
+@click.option("--limit", default=None, type=int, help="Max total results")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def datasources_list(filter_, page_size, limit, fmt):
+    """List published data sources."""
+    config = resolve_config()
+
+    def fn(api):
+        def get_data_fn(ps, pn):
+            result = api.list_datasources(
+                site_id=api.site_id,
+                filter_=filter_ or "",
+                page_size=ps,
+                page_number=pn,
+            )
+            return {"pagination": result["pagination"], "data": result["datasources"]}
+
+        return paginate(page_size=page_size, limit=limit, get_data_fn=get_data_fn)
+
+    result = with_auth(config, fn)
+    output(result, fmt)
+
+
+@datasources_group.command("download")
+@click.argument("datasource_id")
+@click.option(
+    "-o", "--output", "output_path", default=".", help="Output file path or directory (default: current directory)"
+)
+def datasources_download(datasource_id, output_path):
+    """Download a datasource file (.tdsx)."""
+    config = resolve_config()
+
+    data, filename = with_auth(
+        config,
+        lambda api: api.download_datasource(datasource_id=datasource_id, site_id=api.site_id),
+    )
+
+    file_path = os.path.join(output_path, filename) if os.path.isdir(output_path) else output_path
+
+    with open(file_path, "wb") as f:
+        f.write(data)
+
+    abs_path = os.path.abspath(file_path)
+    sys.stderr.write(f"Downloaded to {abs_path}\n")
+    output({"filePath": abs_path}, "json")
+
+
+@datasources_group.command("metadata")
+@click.argument("luid")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def datasources_metadata(luid, fmt):
+    """Get data source field metadata."""
+    config = resolve_config()
+
+    def fn(api):
+        from ..utils.datasource_metadata_utils import (
+            combine_fields,
+            get_graphql_query,
+            simplify_read_metadata_result,
+        )
+
+        read_metadata_result = api.read_metadata(datasource_luid=luid)
+
+        # Try to enrich with Metadata API (GraphQL)
+        try:
+            graphql_result = api.graphql(get_graphql_query(luid))
+        except Exception:
+            # Metadata API may not be available
+            return simplify_read_metadata_result(read_metadata_result)
+
+        return combine_fields(read_metadata_result, graphql_result)
+
+    result = with_auth(config, fn)
+    output(result, fmt)
+
+
+@datasources_group.command("query")
+@click.argument("luid")
+@click.option("--query", "query_json", required=True, help="Query JSON (fields, filters, etc.)")
+@click.option("--limit", default=None, type=int, help="Row limit")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def datasources_query(luid, query_json, limit, fmt):
+    """Query a data source using VizQL Data Service."""
+    config = resolve_config()
+    query = json.loads(query_json)
+
+    def fn(api):
+        # Note: rowLimit is NOT sent to the API (consistent with MCP default behavior
+        # for Tableau versions < 2026.1.0 where server-side row limits are unsupported).
+        # Instead, truncation is done client-side after the response.
+        query_result = api.query_datasource(
+            datasource_luid=luid,
+            query=query,
+            options={
+                "returnFormat": "OBJECTS",
+                "debug": True,
+                "disaggregate": False,
+            },
+        )
+
+        if limit and query_result.get("data") and len(query_result["data"]) > limit:
+            query_result["data"] = query_result["data"][:limit]
+
+        return query_result
+
+    result = with_auth(config, fn)
+    output(result, fmt)

tableau_cli/commands/search_cmd.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import click
+
+from ..auth.with_auth import with_auth
+from ..config.store import resolve_config
+from ..output.format import output
+from ..utils.search_content_utils import reduce_search_content_response
+
+
+@click.command("search")
+@click.argument("terms", required=False, default=None)
+@click.option("--type", "type_", default=None, help="Comma-separated content types (e.g., workbook,view,datasource)")
+@click.option("--limit", default=100, type=int, help="Max results")
+@click.option("--order-by", default=None, help="Sort method (e.g., hitsTotal:desc)")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def search_command(terms, type_, limit, order_by, fmt):
+    """Search across all content types."""
+    config = resolve_config()
+    filter_parts: list[str] = []
+    if type_:
+        types = type_.split(",")
+        if len(types) == 1:
+            filter_parts.append(f"type:eq:{types[0]}")
+        else:
+            filter_parts.append(f"type:in:[{','.join(types)}]")
+
+    def fn(api):
+        response = api.search_content(
+            terms=terms,
+            page=0,
+            limit=limit,
+            order_by=order_by,
+            filter_=",".join(filter_parts) if filter_parts else None,
+        )
+        return reduce_search_content_response(response)
+
+    result = with_auth(config, fn)
+    output(result, fmt)

tableau_cli/commands/views_cmd.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from ..auth.with_auth import with_auth
+from ..config.store import resolve_config
+from ..output.format import output
+from ..utils.paginate import paginate
+
+
+@click.group("views")
+def views_group():
+    """Manage views."""
+
+
+@views_group.command("list")
+@click.option("--filter", "filter_", default=None, help="Filter string (e.g., name:has:Sales)")
+@click.option("--page-size", default=None, type=int, help="Page size for API requests")
+@click.option("--limit", default=None, type=int, help="Max total results")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def views_list(filter_, page_size, limit, fmt):
+    """List views on the site."""
+    config = resolve_config()
+
+    def fn(api):
+        def get_data_fn(ps, pn):
+            result = api.query_views_for_site(
+                site_id=api.site_id,
+                filter_=filter_ or "",
+                page_size=ps,
+                page_number=pn,
+            )
+            return {"pagination": result["pagination"], "data": result["views"]}
+
+        return paginate(page_size=page_size, limit=limit, get_data_fn=get_data_fn)
+
+    result = with_auth(config, fn)
+    output(result, fmt)
+
+
+@views_group.command("data")
+@click.argument("view_id")
+def views_data(view_id):
+    """Get view data as CSV."""
+    config = resolve_config()
+    csv = with_auth(config, lambda api: api.query_view_data(view_id=view_id, site_id=api.site_id))
+    sys.stdout.write(csv)
+
+
+@views_group.command("image")
+@click.argument("view_id")
+@click.option("--width", default=None, type=int, help="Image width in pixels")
+@click.option("--height", default=None, type=int, help="Image height in pixels")
+@click.option("--img-format", default="PNG", help="Image format: PNG | SVG")
+@click.option("-o", "--output", "output_path", default=None, help="Output file path")
+def views_image(view_id, width, height, img_format, output_path):
+    """Download view image."""
+    config = resolve_config()
+
+    image_data = with_auth(
+        config,
+        lambda api: api.query_view_image(
+            view_id=view_id,
+            site_id=api.site_id,
+            width=width,
+            height=height,
+            format_=img_format,
+        ),
+    )
+
+    if output_path:
+        with open(output_path, "wb") as f:
+            f.write(image_data)
+        abs_path = os.path.abspath(output_path)
+        sys.stderr.write(f"Image saved to {abs_path}\n")
+        output({"filePath": abs_path}, "json")
+    else:
+        import base64
+
+        sys.stdout.write(base64.b64encode(image_data).decode("ascii"))

tableau_cli/commands/workbooks_cmd.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import click
+
+from ..auth.with_auth import with_auth
+from ..config.store import resolve_config
+from ..output.format import output
+from ..utils.paginate import paginate
+
+
+@click.group("workbooks")
+def workbooks_group():
+    """Manage workbooks."""
+
+
+@workbooks_group.command("list")
+@click.option("--filter", "filter_", default=None, help="Filter string (e.g., name:eq:Finance)")
+@click.option("--page-size", default=None, type=int, help="Page size for API requests")
+@click.option("--limit", default=None, type=int, help="Max total results")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def workbooks_list(filter_, page_size, limit, fmt):
+    """List workbooks on the site."""
+    config = resolve_config()
+
+    def fn(api):
+        def get_data_fn(ps, pn):
+            result = api.query_workbooks_for_site(
+                site_id=api.site_id,
+                filter_=filter_ or "",
+                page_size=ps,
+                page_number=pn,
+            )
+            return {"pagination": result["pagination"], "data": result["workbooks"]}
+
+        return paginate(page_size=page_size, limit=limit, get_data_fn=get_data_fn)
+
+    result = with_auth(config, fn)
+    output(result, fmt)
+
+
+@workbooks_group.command("get")
+@click.argument("workbook_id")
+@click.option("--format", "fmt", default="json", help="Output format: json | table")
+def workbooks_get(workbook_id, fmt):
+    """Get workbook details."""
+    config = resolve_config()
+
+    def fn(api):
+        workbook = api.get_workbook(workbook_id=workbook_id, site_id=api.site_id)
+
+        # Enrich views with usage statistics (consistent with MCP behavior)
+        if workbook.get("views"):
+            views = api.query_views_for_workbook(workbook_id=workbook_id, site_id=api.site_id)
+            workbook["views"]["view"] = views
+
+        return workbook
+
+    result = with_auth(config, fn)
+    output(result, fmt)

tableau_cli/config/store.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .types import Config, PartialConfig
+
+CONFIG_PATH = Path.home() / ".tableau-cli.json"
+
+
+def load_file_config() -> PartialConfig:
+    try:
+        raw = CONFIG_PATH.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        return PartialConfig(
+            server=data.get("server"),
+            site_name=data.get("siteName"),
+            pat_name=data.get("patName"),
+            pat_value=data.get("patValue"),
+        )
+    except (FileNotFoundError, json.JSONDecodeError):
+        return PartialConfig()
+
+
+def save_file_config(config: PartialConfig) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data: dict = {}
+    if config.server is not None:
+        data["server"] = config.server
+    if config.site_name is not None:
+        data["siteName"] = config.site_name
+    if config.pat_name is not None:
+        data["patName"] = config.pat_name
+    if config.pat_value is not None:
+        data["patValue"] = config.pat_value
+    CONFIG_PATH.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def resolve_config() -> Config:
+    file = load_file_config()
+
+    server = os.environ.get("SERVER") or file.server
+    site_name = os.environ.get("SITE_NAME") or file.site_name or ""
+    pat_name = os.environ.get("PAT_NAME") or file.pat_name
+    pat_value = os.environ.get("PAT_VALUE") or file.pat_value
+
+    if not server:
+        raise RuntimeError(
+            "Missing required config: server. Set via `tableau-cli config set --server <url>` or SERVER env var."
+        )
+    if not pat_name or not pat_value:
+        raise RuntimeError(
+            "Missing required config: patName/patValue. "
+            "Set via `tableau-cli config set --pat-name <name> --pat-value <value>` "
+            "or PAT_NAME/PAT_VALUE env vars."
+        )
+
+    return Config(server=server, site_name=site_name, pat_name=pat_name, pat_value=pat_value)

tableau_cli/config/types.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    server: str
+    site_name: str
+    pat_name: str
+    pat_value: str
+
+
+@dataclass
+class PartialConfig:
+    server: str | None = None
+    site_name: str | None = None
+    pat_name: str | None = None
+    pat_value: str | None = None

tableau_cli/errors/cli_error.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class CliError(Exception):
+    def __init__(
+        self,
+        *,
+        error_type: str,
+        message: str,
+        details: str | None = None,
+        hint: str | None = None,
+    ):
+        super().__init__(message)
+        self.error_type = error_type
+        self.details = details
+        self.hint = hint
+
+    def to_output(self) -> dict[str, Any]:
+        output: dict[str, Any] = {
+            "isError": True,
+            "errorType": self.error_type,
+            "message": str(self),
+        }
+        if self.details:
+            output["details"] = self.details
+        if self.hint:
+            output["hint"] = self.hint
+        return output
+
+
+class FeatureDisabledError(CliError):
+    def __init__(self, message: str, hint: str | None = None):
+        super().__init__(error_type="feature-disabled", message=message, hint=hint)
+
+
+class AuthenticationError(CliError):
+    def __init__(self, message: str):
+        super().__init__(
+            error_type="authentication-error",
+            message=message,
+            hint=("Check your PAT credentials with `tableau-cli config show`. Ensure the token has not expired."),
+        )