py-tbparse 0.1.1a0__py3-none-any.whl

twbparser_py/batch.py

@@ -0,0 +1,62 @@
+"""Batch/folder analysis: run a table across every workbook in a directory.
+
+Not part of the R package, which operates on one workbook at a time --
+this is a natural Python-side extension (glob + pandas.concat).
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import warnings
+
+import pandas as pd
+
+from ._tables import TABLE_SPECS
+from .parser import TwbParser
+
+DEFAULT_PATTERNS = ("*.twb", "*.twbx")
+
+
+def scan_folder(
+    directory: str,
+    table: str = "overview",
+    patterns=DEFAULT_PATTERNS,
+    **kwargs,
+) -> pd.DataFrame:
+    """Run `table` (see `_tables.TABLE_SPECS`) over every `.twb`/`.twbx`
+    file in `directory`, concatenating the results with a `workbook`
+    column identifying the source file.
+
+    A workbook that fails to load or fails to extract `table` is skipped
+    with a warning rather than aborting the whole batch -- one corrupt
+    file in a folder of fifty shouldn't block the other forty-nine.
+    """
+    if table not in TABLE_SPECS:
+        raise ValueError(f"unknown table '{table}'")
+    getter = TABLE_SPECS[table]
+
+    paths: list[str] = []
+    for pattern in patterns:
+        paths.extend(glob.glob(os.path.join(directory, pattern)))
+    paths = sorted(set(paths))
+
+    if not paths:
+        return pd.DataFrame(columns=["workbook"])
+
+    frames = []
+    for path in paths:
+        try:
+            parser = TwbParser(path)
+            df = getter(parser, **kwargs)
+        except Exception as e:  # noqa: BLE001 - genuinely want to skip any failure
+            warnings.warn(f"skipping {path}: {e}")
+            continue
+        df = df.copy()
+        df.insert(0, "workbook", os.path.basename(path))
+        frames.append(df)
+
+    if not frames:
+        return pd.DataFrame(columns=["workbook"])
+
+    return pd.concat(frames, ignore_index=True)

twbparser_py/calculated_fields.py

@@ -0,0 +1,113 @@
+"""Calculated-field and raw-field (non-calc, non-parameter) extraction.
+
+Ports of R/calculated_fields.R (`extract_calculated_fields`,
+`extract_raw_fields`).
+"""
+
+from __future__ import annotations
+
+import re
+
+import pandas as pd
+
+from ._clean import attr_safe_get, clean_table, strip_brackets
+
+_DATASOURCE_XPATH = (
+    "/workbook/datasources/datasource[@name and not(ancestor::view)]"
+)
+
+_TABLE_CALC_RE = re.compile(
+    r"\b(WINDOW_|LOOKUP\(|INDEX\(|RUNNING_|RANK\(|PREVIOUS_VALUE\()"
+)
+
+_CALC_COLUMNS = [
+    "datasource", "name", "tableau_internal_name", "datatype", "role",
+    "formula", "calc_class", "is_table_calc", "table", "table_clean",
+]
+
+_RAW_COLUMNS = [
+    "datasource", "name", "tableau_internal_name", "datatype", "role",
+    "is_hidden", "is_parameter", "table", "table_clean",
+]
+
+
+def extract_calculated_fields(xml_doc, include_parameters: bool = False) -> pd.DataFrame:
+    """Port of `extract_calculated_fields()`."""
+    ds_nodes = xml_doc.xpath(_DATASOURCE_XPATH)
+    if not ds_nodes:
+        return pd.DataFrame(columns=_CALC_COLUMNS)
+
+    rows = []
+    for ds in ds_nodes:
+        ds_name = ds.get("name")
+        if not include_parameters and ds_name == "Parameters":
+            continue
+
+        cols = ds.xpath(".//column[@name and not(@param-domain-type)][.//calculation]")
+        for col in cols:
+            ca = dict(col.attrib)
+            calc = col.find(".//calculation")
+            fa = dict(calc.attrib) if calc is not None else {}
+
+            internal = attr_safe_get(ca, "name")
+            caption = attr_safe_get(ca, "caption")
+            raw_tbl = attr_safe_get(ca, "table")
+
+            formula = attr_safe_get(fa, "formula")
+            calc_class = attr_safe_get(fa, "class")
+
+            is_tbl = bool(formula) and bool(_TABLE_CALC_RE.search(formula))
+
+            rows.append(
+                {
+                    "datasource": ds_name,
+                    "name": caption if caption else strip_brackets(internal),
+                    "tableau_internal_name": internal,
+                    "datatype": attr_safe_get(ca, "datatype"),
+                    "role": attr_safe_get(ca, "role"),
+                    "formula": formula,
+                    "calc_class": calc_class,
+                    "is_table_calc": is_tbl,
+                    "table": raw_tbl,
+                    "table_clean": clean_table(raw_tbl),
+                }
+            )
+
+    if not rows:
+        return pd.DataFrame(columns=_CALC_COLUMNS)
+    return pd.DataFrame(rows, columns=_CALC_COLUMNS).drop_duplicates()
+
+
+def extract_raw_fields(xml_doc) -> pd.DataFrame:
+    """Port of `extract_raw_fields()`."""
+    ds_nodes = xml_doc.xpath(_DATASOURCE_XPATH)
+    if not ds_nodes:
+        return pd.DataFrame(columns=_RAW_COLUMNS)
+
+    rows = []
+    for ds in ds_nodes:
+        ds_name = ds.get("name")
+        nodes = ds.xpath(".//column[@name and not(.//calculation) and not(@param-domain-type)]")
+        for node in nodes:
+            a = dict(node.attrib)
+            internal = attr_safe_get(a, "name")
+            caption = attr_safe_get(a, "caption")
+            raw_tbl = attr_safe_get(a, "table")
+
+            rows.append(
+                {
+                    "datasource": ds_name,
+                    "name": caption if caption else strip_brackets(internal),
+                    "tableau_internal_name": internal,
+                    "datatype": attr_safe_get(a, "datatype"),
+                    "role": attr_safe_get(a, "role"),
+                    "is_hidden": attr_safe_get(a, "hidden", "false") in ("true", "1"),
+                    "is_parameter": False,
+                    "table": raw_tbl,
+                    "table_clean": clean_table(raw_tbl),
+                }
+            )
+
+    if not rows:
+        return pd.DataFrame(columns=_RAW_COLUMNS)
+    return pd.DataFrame(rows, columns=_RAW_COLUMNS).drop_duplicates()

twbparser_py/cli.py

@@ -0,0 +1,207 @@
+"""Command-line interface: `twbparser WORKBOOK [TABLE] [options]`.
+
+Two reserved subcommands, dispatched on the first argument before the
+normal single-workbook parser runs: `twbparser diff A.twb B.twb [TABLE]`
+and `twbparser batch DIR [TABLE]`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from ._tables import TABLE_NAMES, TABLE_SPECS
+from .batch import scan_folder
+from .diff import diff_workbooks
+from .parser import TwbParser
+
+
+def _df_text(df: pd.DataFrame, fmt: str) -> str:
+    if fmt == "csv":
+        return df.to_csv(index=False)
+    if fmt == "json":
+        return df.to_json(orient="records", indent=2)
+    if df.empty:
+        return "(empty)"
+    with pd.option_context(
+        "display.max_rows", None, "display.max_columns", None, "display.width", 200
+    ):
+        return df.to_string(index=False)
+
+
+def _write(text: str, output: str | None) -> None:
+    if output:
+        Path(output).write_text(text)
+    else:
+        print(text)
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="twbparser",
+        description="Parse a Tableau .twb/.twbx workbook and print one of its tables. "
+        "See also: 'twbparser diff A.twb B.twb [TABLE]' and 'twbparser batch DIR [TABLE]'.",
+    )
+    ap.add_argument("workbook", help="path to a .twb or .twbx file")
+    ap.add_argument(
+        "table",
+        nargs="?",
+        default="overview",
+        choices=[*TABLE_NAMES, "validate", "tables", "graph"],
+        help="which table to print (default: overview); 'tables' lists options; "
+        "'validate' checks relationships; 'graph' prints a Graphviz DOT digraph "
+        "of joins/relationships",
+    )
+    ap.add_argument(
+        "--format", "-f", choices=["table", "csv", "json"], default="table",
+        help="output format (default: table)",
+    )
+    ap.add_argument("--output", "-o", help="write to this file instead of stdout")
+    ap.add_argument(
+        "--dashboard", help="restrict 'dashboard-sheets' to one dashboard by name"
+    )
+    ap.add_argument(
+        "--include-parameters", action="store_true",
+        help="include the 'Parameters' datasource in 'calculated-fields'",
+    )
+    ap.add_argument(
+        "--include-inferred", action="store_true",
+        help="for 'graph': also include dashed edges from inferred_relationships",
+    )
+    return ap
+
+
+def build_diff_arg_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="twbparser diff",
+        description="Diff one table between two workbooks (row-level added/removed).",
+    )
+    ap.add_argument("workbook_a", help="the 'before' .twb/.twbx file")
+    ap.add_argument("workbook_b", help="the 'after' .twb/.twbx file")
+    ap.add_argument("table", nargs="?", default="datasources", choices=TABLE_NAMES)
+    ap.add_argument("--format", "-f", choices=["table", "csv", "json"], default="table")
+    ap.add_argument("--output", "-o", help="write to this file instead of stdout")
+    ap.add_argument("--dashboard", help="restrict 'dashboard-sheets' to one dashboard by name")
+    ap.add_argument(
+        "--include-parameters", action="store_true",
+        help="include the 'Parameters' datasource in 'calculated-fields'",
+    )
+    return ap
+
+
+def _run_diff(argv: list[str]) -> int:
+    args = build_diff_arg_parser().parse_args(argv)
+    try:
+        a = TwbParser(args.workbook_a)
+        b = TwbParser(args.workbook_b)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    df = diff_workbooks(
+        a, b, table=args.table, dashboard=args.dashboard, include_parameters=args.include_parameters
+    )
+    _write(_df_text(df, args.format), args.output)
+    return 0
+
+
+def build_batch_arg_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="twbparser batch",
+        description="Run one table across every .twb/.twbx file in a directory.",
+    )
+    ap.add_argument("directory", help="folder to scan for .twb/.twbx files")
+    ap.add_argument("table", nargs="?", default="overview", choices=TABLE_NAMES)
+    ap.add_argument("--format", "-f", choices=["table", "csv", "json"], default="table")
+    ap.add_argument("--output", "-o", help="write to this file instead of stdout")
+    ap.add_argument("--dashboard", help="restrict 'dashboard-sheets' to one dashboard by name")
+    ap.add_argument(
+        "--include-parameters", action="store_true",
+        help="include the 'Parameters' datasource in 'calculated-fields'",
+    )
+    return ap
+
+
+def _run_batch(argv: list[str]) -> int:
+    args = build_batch_arg_parser().parse_args(argv)
+    if not Path(args.directory).is_dir():
+        print(f"error: not a directory: {args.directory}", file=sys.stderr)
+        return 1
+
+    df = scan_folder(
+        args.directory,
+        table=args.table,
+        dashboard=args.dashboard,
+        include_parameters=args.include_parameters,
+    )
+    _write(_df_text(df, args.format), args.output)
+    return 0
+
+
+def _is_reserved_subcommand(argv: list[str], name: str) -> bool:
+    """True if `argv` invokes the `name` subcommand -- but don't let that
+    shadow an actual workbook that happens to be named exactly "diff" or
+    "batch" (no extension) sitting in the current directory."""
+    return argv[:1] == [name] and not Path(name).exists()
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw_argv = sys.argv[1:] if argv is None else list(argv)
+    if _is_reserved_subcommand(raw_argv, "diff"):
+        return _run_diff(raw_argv[1:])
+    if _is_reserved_subcommand(raw_argv, "batch"):
+        return _run_batch(raw_argv[1:])
+
+    args = build_arg_parser().parse_args(argv)
+
+    if args.table == "tables":
+        for name in TABLE_NAMES:
+            print(name)
+        return 0
+
+    try:
+        parser = TwbParser(args.workbook)
+    except (FileNotFoundError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    if args.table == "graph":
+        dot = parser.get_relationship_graph_dot(include_inferred=args.include_inferred)
+        _write(dot, args.output)
+        return 0
+
+    if args.table == "validate":
+        result = parser.validate()
+        if args.format == "json":
+            payload = {
+                "ok": result["ok"],
+                "issues": {
+                    name: df.to_dict(orient="records")
+                    for name, df in result["issues"].items()
+                },
+            }
+            _write(json.dumps(payload, indent=2, default=str), args.output)
+        else:
+            lines = [f"ok: {result['ok']}"]
+            for name, df in result["issues"].items():
+                lines.append(f"\n{name}:")
+                lines.append(df.to_string(index=False))
+            _write("\n".join(lines), args.output)
+        return 0 if result["ok"] else 2
+
+    getter = TABLE_SPECS[args.table]
+    df = getter(
+        parser,
+        dashboard=args.dashboard,
+        include_parameters=args.include_parameters,
+    )
+    _write(_df_text(df, args.format), args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

twbparser_py/dashboards.py

@@ -0,0 +1,101 @@
+"""Dashboard listing and worksheet-placement extraction.
+
+Port of R/dashboard_details.R (`twb_dashboard_sheets`). `list_dashboards`
+is a deliberately simplified name-only lister for this v1 subset, not a
+full port of R's `.ins_dashboards` (which also reports per-dashboard
+worksheet/zone counts) -- see AGENTS.md's v2 scope.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pandas as pd
+
+_DASHBOARD_COLUMNS = ["name"]
+_SHEETS_COLUMNS = ["dashboard", "sheet", "zone_id", "x", "y", "w", "h"]
+
+
+def _int_attr(node, name) -> Optional[int]:
+    """Port of `.int_attr`.
+
+    R's `as.integer(xml_attr(...))` parses the string as a double first and
+    truncates, so a fractional coordinate like "682.666" (Tableau does emit
+    these for some floating-layout zones) becomes 682 rather than failing.
+    """
+    val = node.get(name)
+    if val is None:
+        return None
+    try:
+        return int(val)
+    except ValueError:
+        try:
+            return int(float(val))
+        except (TypeError, ValueError):
+            return None
+
+
+def _xpath_string_literal(s: str) -> str:
+    """Build an XPath 1.0 string literal for `s`, safe for names containing
+    a `'`, a `"`, or both.
+
+    XPath 1.0 has no in-literal escape character, so a value containing
+    both quote characters can't be wrapped in either on its own -- it has
+    to be assembled with `concat()`, splitting on `'` and substituting a
+    double-quoted `'` for each occurrence.
+    """
+    if "'" not in s:
+        return f"'{s}'"
+    if '"' not in s:
+        return f'"{s}"'
+    parts = s.split("'")
+    pieces = []
+    for i, part in enumerate(parts):
+        if part:
+            pieces.append(f"'{part}'")
+        if i < len(parts) - 1:
+            pieces.append("\"'\"")
+    return f"concat({','.join(pieces)})"
+
+
+def _dashboard_xpath(dashboard: Optional[str]) -> str:
+    if dashboard is None:
+        return ".//dashboard"
+    return f".//dashboard[@name={_xpath_string_literal(dashboard)}]"
+
+
+def list_dashboards(xml_doc) -> pd.DataFrame:
+    """List dashboard names in the workbook."""
+    nodes = xml_doc.xpath(".//dashboard")
+    names = [n.get("name") for n in nodes if n.get("name")]
+    return pd.DataFrame({"name": sorted(set(names))}, columns=_DASHBOARD_COLUMNS)
+
+
+def dashboard_sheets(xml_doc, dashboard: Optional[str] = None) -> pd.DataFrame:
+    """Port of `twb_dashboard_sheets()` / `.ins_dashboard_sheets`."""
+    d_nodes = xml_doc.xpath(_dashboard_xpath(dashboard))
+    if not d_nodes:
+        return pd.DataFrame(columns=_SHEETS_COLUMNS)
+
+    rows = []
+    for d in d_nodes:
+        d_name = d.get("name")
+        ws_zones = d.xpath(".//zone[@worksheet]")
+        for z in ws_zones:
+            rows.append(
+                {
+                    "dashboard": d_name,
+                    "sheet": z.get("worksheet"),
+                    "zone_id": z.get("id"),
+                    "x": _int_attr(z, "x"),
+                    "y": _int_attr(z, "y"),
+                    "w": _int_attr(z, "w"),
+                    "h": _int_attr(z, "h"),
+                }
+            )
+
+    if not rows:
+        return pd.DataFrame(columns=_SHEETS_COLUMNS)
+
+    df = pd.DataFrame(rows, columns=_SHEETS_COLUMNS)
+    return df.sort_values(["dashboard", "sheet"]).reset_index(drop=True)