tableau-cli 0.1.3__tar.gz → 0.1.4__tar.gz

tableau_cli-0.1.4/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(command -v uv)",
+      "Bash(uv --version)"
+    ]
+  }
+}

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tableau-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: CLI for Tableau Server/Cloud, designed for AI agent integration
 Project-URL: Repository, https://github.com/i-richardwang/tableau-cli
 Author: Richard Wang
@@ -166,7 +166,12 @@ tableau-cli views image <viewId> --vf "Region=West" -o west.png
 
 ### Convert
 
-Convert local TDSX/HYPER files to Parquet or CSV. Requires `pip install tableau-cli[convert]`.
+Convert local TDSX/HYPER files to Parquet or CSV.
+
+Conversion needs heavier packages (`pantab`, `polars`, `pyarrow`). You have two options:
+
+- Install them into the CLI: `pip install tableau-cli[convert]`.
+- Don't install anything: if [uv](https://docs.astral.sh/uv/) is on your `PATH`, conversion transparently falls back to running the step in an ephemeral `uv run --with ...` environment, so those packages never land in your host Python. The first run provisions the environment (a few seconds); later runs use uv's cache. This is the recommended path when the CLI itself was installed via `uv tool install tableau-cli`.
 
 For most use cases, `ds download --to parquet` (or `--to csv`) is simpler — it downloads and converts in one step. The `convert` command is useful when you already have a `.tdsx` or `.hyper` file on disk.
 

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/README.md

@@ -136,7 +136,12 @@ tableau-cli views image <viewId> --vf "Region=West" -o west.png
 
 ### Convert
 
-Convert local TDSX/HYPER files to Parquet or CSV. Requires `pip install tableau-cli[convert]`.
+Convert local TDSX/HYPER files to Parquet or CSV.
+
+Conversion needs heavier packages (`pantab`, `polars`, `pyarrow`). You have two options:
+
+- Install them into the CLI: `pip install tableau-cli[convert]`.
+- Don't install anything: if [uv](https://docs.astral.sh/uv/) is on your `PATH`, conversion transparently falls back to running the step in an ephemeral `uv run --with ...` environment, so those packages never land in your host Python. The first run provisions the environment (a few seconds); later runs use uv's cache. This is the recommended path when the CLI itself was installed via `uv tool install tableau-cli`.
 
 For most use cases, `ds download --to parquet` (or `--to csv`) is simpler — it downloads and converts in one step. The `convert` command is useful when you already have a `.tdsx` or `.hyper` file on disk.
 

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tableau-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "CLI for Tableau Server/Cloud, designed for AI agent integration"
 license = "Apache-2.0"
 requires-python = ">=3.10"

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/src/tableau_cli/cli.py

@@ -123,7 +123,7 @@ class TableauCli(click.Group):
 
 
 @click.group(cls=TableauCli)
-@click.version_option("0.1.3")
+@click.version_option("0.1.4")
 def cli():
     """CLI tool for interacting with Tableau Server/Cloud."""
 

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/src/tableau_cli/commands/convert_cmd.py

@@ -11,10 +11,8 @@ from ..errors.cli_error import CliError
 from ..output.format import output
 from ..utils.convert import (
     SUPPORTED_FORMATS,
-    check_convert_deps,
     extract_hyper_from_tdsx,
-    read_hyper,
-    write_df,
+    run_conversion,
 )
 
 
@@ -26,8 +24,6 @@ from ..utils.convert import (
 @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()
 
@@ -47,15 +43,13 @@ def convert_command(input_path, to_fmt, output_path):
     else:
         out_p = Path(output_path)
 
-    # Read hyper data
+    # Convert (in-process if deps present, else via an ephemeral uv environment)
     if suffix == ".hyper":
-        df = read_hyper(input_p)
+        run_conversion(input_p, out_p, to_fmt)
     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)
+            run_conversion(hyper_path, out_p, to_fmt)
 
     abs_path = os.path.abspath(out_p)
     sys.stderr.write(f"Converted to {abs_path}\n")

{tableau_cli-0.1.3 → tableau_cli-0.1.4}/src/tableau_cli/commands/datasources_cmd.py

@@ -65,9 +65,9 @@ def datasources_download(datasource_id, output_path, to_fmt):
     config = resolve_config()
 
     if to_fmt != "tdsx":
-        from ..utils.convert import check_convert_deps
+        from ..utils.convert import ensure_convert_available
 
-        check_convert_deps()
+        ensure_convert_available()
 
     data, filename = with_auth(
         config,

tableau_cli-0.1.4/src/tableau_cli/utils/_convert_worker.py

@@ -0,0 +1,55 @@
+"""Standalone hyper -> parquet/csv worker, run in an ephemeral uv environment.
+
+Invoked as:  python _convert_worker.py <hyper_path> <output_path> <parquet|csv>
+
+Must stay self-contained: only pantab / polars + stdlib, no `tableau_cli` imports,
+because it runs in a fresh `uv run --with ...` interpreter where this package is
+not installed. Known errors are reported as a single JSON line on stdout plus a
+non-zero exit; the parent process (utils/convert.py) turns them into CliError.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def _fail(error_type: str, message: str, hint: str = "") -> None:
+    payload = {"error_type": error_type, "message": message}
+    if hint:
+        payload["hint"] = hint
+    print(json.dumps(payload))
+    sys.exit(1)
+
+
+def main() -> None:
+    if len(sys.argv) != 4:
+        _fail("convert-error", "worker expects <hyper_path> <output_path> <format>")
+
+    hyper_path, output_path, to_fmt = sys.argv[1], sys.argv[2], sys.argv[3]
+    name = os.path.basename(hyper_path)
+
+    import pantab
+
+    frames = pantab.frames_from_hyper(hyper_path, return_type="polars")
+    if not frames:
+        _fail("convert-error", f"No tables found in {name}")
+    if len(frames) != 1:
+        _fail(
+            "convert-error",
+            f"Found {len(frames)} tables in {name}, expected 1",
+            "Multi-table hyper files are not supported yet.",
+        )
+
+    df = next(iter(frames.values()))
+    if to_fmt == "parquet":
+        df.write_parquet(output_path)
+    elif to_fmt == "csv":
+        df.write_csv(output_path)
+    else:
+        _fail("convert-error", f"Unsupported format: {to_fmt}")
+
+
+if __name__ == "__main__":
+    main()

tableau_cli-0.1.4/src/tableau_cli/utils/convert.py

@@ -0,0 +1,177 @@
+"""Shared helpers for converting TDSX / HYPER files to Parquet or CSV.
+
+The heavy conversion dependencies (pantab / polars / pyarrow) are optional. When
+they are not importable in the current interpreter — e.g. the CLI was installed
+via `uv tool install` without the `[convert]` extra — conversion transparently
+falls back to running a self-contained worker in an ephemeral `uv run --with ...`
+environment, so the heavy packages never land in the host Python.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import TYPE_CHECKING
+from zipfile import ZipFile
+
+from ..errors.cli_error import CliError
+
+if TYPE_CHECKING:
+    import polars as pl
+
+# Import names used to detect in-process availability.
+CONVERT_DEPS = ("pantab", "polars", "pyarrow")
+# PEP 508 requirements handed to `uv run --with` (keep in sync with pyproject [convert]).
+CONVERT_REQUIREMENTS = ("pantab>=4.0", "polars>=1.0", "pyarrow>=15.0")
+SUPPORTED_FORMATS = ("parquet", "csv")
+
+_WORKER = Path(__file__).parent / "_convert_worker.py"
+
+
+def _is_importable(name: str) -> bool:
+    try:
+        __import__(name)
+        return True
+    except ImportError:
+        return False
+
+
+def _deps_available() -> bool:
+    return all(_is_importable(pkg) for pkg in CONVERT_DEPS)
+
+
+def _uv_available() -> bool:
+    return shutil.which("uv") is not None
+
+
+def ensure_convert_available() -> None:
+    """Fail fast if conversion can run neither in-process nor via uv.
+
+    Used by callers that do expensive work (e.g. downloading a datasource) before
+    converting, so they can bail out before spending that effort.
+    """
+    if _deps_available() or _uv_available():
+        return
+    raise CliError(
+        error_type="missing-dependencies",
+        message=f"Convert requires packages not installed: {', '.join(CONVERT_DEPS)}",
+        hint=(
+            "Install uv (https://docs.astral.sh/uv/) to convert without installing these packages, "
+            "or run `pip install tableau-cli[convert]`."
+        ),
+    )
+
+
+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 (in-process path)."""
+    import pantab
+
+    frames = pantab.frames_from_hyper(str(hyper_path), return_type="polars")
+    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 next(iter(frames.values()))
+
+
+def write_df(df: pl.DataFrame, output_path: Path, to: str) -> None:
+    """Write DataFrame to the specified format (in-process path)."""
+    if to == "parquet":
+        df.write_parquet(output_path)
+    elif to == "csv":
+        df.write_csv(output_path)
+
+
+def _convert_via_uv(hyper_path: Path, output_path: Path, to_fmt: str) -> None:
+    """Convert by running the worker in an ephemeral uv environment.
+
+    uv's own progress (provisioning the environment on first run) is streamed to
+    stderr so long first runs are visible; only the worker's stdout is captured,
+    where it emits a structured JSON error on failure.
+    """
+    cmd = ["uv", "run"]
+    for req in CONVERT_REQUIREMENTS:
+        cmd += ["--with", req]
+    cmd += ["python", str(_WORKER), str(hyper_path), str(output_path), to_fmt]
+
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, text=True)
+    if proc.returncode == 0:
+        return
+
+    payload = None
+    out = (proc.stdout or "").strip()
+    if out:
+        try:
+            payload = json.loads(out.splitlines()[-1])
+        except (ValueError, IndexError):
+            payload = None
+
+    if isinstance(payload, dict) and payload.get("error_type"):
+        raise CliError(
+            error_type=payload["error_type"],
+            message=payload.get("message", "Conversion failed"),
+            hint=payload.get("hint", ""),
+        )
+    raise CliError(
+        error_type="convert-error",
+        message="Conversion via uv failed. See the uv output above for details.",
+    )
+
+
+def run_conversion(hyper_path: Path, output_path: Path, to_fmt: str) -> None:
+    """Convert a .hyper file to parquet/csv, in-process if deps are present,
+    otherwise via an ephemeral uv environment."""
+    if _deps_available():
+        df = read_hyper(hyper_path)
+        write_df(df, output_path, to_fmt)
+        return
+    if _uv_available():
+        _convert_via_uv(hyper_path, output_path, to_fmt)
+        return
+    ensure_convert_available()  # raises with an actionable hint
+
+
+def convert_tdsx_bytes(data: bytes, output_path: Path, to_fmt: str) -> None:
+    """Convert raw TDSX bytes directly to parquet/csv without persisting the intermediate file."""
+    with TemporaryDirectory() as td:
+        tmp_dir = Path(td)
+        tdsx_path = tmp_dir / "datasource.tdsx"
+        tdsx_path.write_bytes(data)
+        hyper_path = extract_hyper_from_tdsx(tdsx_path, tmp_dir)
+        # Keep the temp dir alive through conversion: the uv worker reads the file from disk.
+        run_conversion(hyper_path, output_path, to_fmt)

tableau_cli-0.1.3/src/tableau_cli/utils/convert.py

@@ -1,99 +0,0 @@
-"""Shared helpers for converting TDSX / HYPER files to Parquet or CSV."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from tempfile import TemporaryDirectory
-from typing import TYPE_CHECKING
-from zipfile import ZipFile
-
-from ..errors.cli_error import CliError
-
-if TYPE_CHECKING:
-    import polars as pl
-
-CONVERT_DEPS = ("pantab", "polars", "pyarrow")
-SUPPORTED_FORMATS = ("parquet", "csv")
-
-
-def _is_importable(name: str) -> bool:
-    try:
-        __import__(name)
-        return True
-    except ImportError:
-        return False
-
-
-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 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)
-
-
-def convert_tdsx_bytes(data: bytes, output_path: Path, to_fmt: str) -> None:
-    """Convert raw TDSX bytes directly to parquet/csv without persisting the intermediate file."""
-    with TemporaryDirectory() as td:
-        tmp_dir = Path(td)
-        tdsx_path = tmp_dir / "datasource.tdsx"
-        tdsx_path.write_bytes(data)
-        hyper_path = extract_hyper_from_tdsx(tdsx_path, tmp_dir)
-        df = read_hyper(hyper_path)
-    write_df(df, output_path, to_fmt)