tableau-inspector 0.1.0__tar.gz

tableau_inspector-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+reports/*.html
+!reports/.gitkeep
+*.log
+.DS_Store

tableau_inspector-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Bowen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tableau_inspector-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: tableau-inspector
+Version: 0.1.0
+Summary: Analyze Tableau workbooks (.twb, .twbx) for common issues before publishing.
+Author: Joshua Bowen
+License: MIT License
+        
+        Copyright (c) 2026 Joshua Bowen
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: linter,static-analysis,tableau,twb,twbx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tableau-inspector (Python)
+
+Local-first CLI that statically analyzes Tableau workbooks (`.twb` / `.twbx`) for common issues —
+dev-only DB connections, hidden worksheets, unused calculations/parameters, duplicate calculations,
+default filters, blank dashboard titles, missing captions, duplicate field aliases — before you
+publish. Everything is parsed from the workbook's embedded XML; no network calls are made.
+
+This is a Python port of the Node.js `tableau-inspector` CLI, with the same functionality and
+zero runtime dependencies (stdlib only).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# Lint a workbook for common publishing issues
+tableau-inspector analyze workbook.twbx
+
+# Trace what a field/calculation depends on and what depends on it
+tableau-inspector lineage workbook.twbx --field "Customer Segment"
+
+# Search calculated fields by name or formula text
+tableau-inspector search workbook.twbx "profit"
+
+# Diff two versions of a workbook
+tableau-inspector compare old.twbx new.twbx
+```
+
+Every command also supports `--json` for machine-readable output, and `analyze`/`compare` support
+`--html` for a shareable, self-contained HTML report.
+
+## Documentation
+
+Run `tableau-inspector --help` or `tableau-inspector <command> --help` for the full option
+reference and the complete list of rules `analyze` checks.
+
+## License
+
+MIT © Joshua Bowen

tableau_inspector-0.1.0/README.md

@@ -0,0 +1,43 @@
+# tableau-inspector (Python)
+
+Local-first CLI that statically analyzes Tableau workbooks (`.twb` / `.twbx`) for common issues —
+dev-only DB connections, hidden worksheets, unused calculations/parameters, duplicate calculations,
+default filters, blank dashboard titles, missing captions, duplicate field aliases — before you
+publish. Everything is parsed from the workbook's embedded XML; no network calls are made.
+
+This is a Python port of the Node.js `tableau-inspector` CLI, with the same functionality and
+zero runtime dependencies (stdlib only).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# Lint a workbook for common publishing issues
+tableau-inspector analyze workbook.twbx
+
+# Trace what a field/calculation depends on and what depends on it
+tableau-inspector lineage workbook.twbx --field "Customer Segment"
+
+# Search calculated fields by name or formula text
+tableau-inspector search workbook.twbx "profit"
+
+# Diff two versions of a workbook
+tableau-inspector compare old.twbx new.twbx
+```
+
+Every command also supports `--json` for machine-readable output, and `analyze`/`compare` support
+`--html` for a shareable, self-contained HTML report.
+
+## Documentation
+
+Run `tableau-inspector --help` or `tableau-inspector <command> --help` for the full option
+reference and the complete list of rules `analyze` checks.
+
+## License
+
+MIT © Joshua Bowen

tableau_inspector-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tableau-inspector"
+dynamic = ["version"]
+description = "Analyze Tableau workbooks (.twb, .twbx) for common issues before publishing."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Joshua Bowen" }]
+keywords = ["tableau", "linter", "static-analysis", "twb", "twbx"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+tableau-inspector = "tableau_inspector.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build", "twine"]
+
+[tool.hatch.version]
+path = "src/tableau_inspector/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tableau_inspector"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/examples", "/tests", "/reports"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tableau_inspector-0.1.0/src/tableau_inspector/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tableau_inspector-0.1.0/src/tableau_inspector/analyzer.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+
+from tableau_inspector.models import AnalysisResult, Workbook, WorkbookInventory, WorkbookSummary
+from tableau_inspector.parser.workbook_loader import WorkbookLoader
+from tableau_inspector.parser.workbook_parser import WorkbookParser
+from tableau_inspector.rules import RULES
+from tableau_inspector.utils.timestamps import iso_timestamp
+from tableau_inspector.utils.version import read_tool_version
+
+
+def _compute_summary(workbook: Workbook) -> WorkbookSummary:
+    return WorkbookSummary(
+        dashboards=len(workbook.dashboards),
+        worksheets=len(workbook.worksheets),
+        calculations=len(workbook.calculations),
+        parameters=len(workbook.parameters),
+        filters=len(workbook.filters),
+        datasources=len(workbook.datasources),
+    )
+
+
+def _compute_inventory(workbook: Workbook) -> WorkbookInventory:
+    return WorkbookInventory(
+        dashboards=[d.name for d in workbook.dashboards],
+        worksheets=[w.name for w in workbook.worksheets],
+        calculations=[c.caption for c in workbook.calculations],
+        parameters=[p.caption for p in workbook.parameters],
+        connections=[
+            f"{c.class_}: {c.server if c.server is not None else (c.dbname if c.dbname is not None else 'n/a')}"
+            for c in workbook.connections
+        ],
+    )
+
+
+def analyze(file_path: str) -> AnalysisResult:
+    loader = WorkbookLoader()
+    loader.load(file_path)
+    xml = loader.get_xml()
+
+    workbook_name = os.path.splitext(os.path.basename(file_path))[0]
+    workbook = WorkbookParser().parse(xml, workbook_name)
+
+    issues = [issue for rule in RULES for issue in rule.run(workbook)]
+
+    return AnalysisResult(
+        workbook_name=workbook.name,
+        file_path=file_path,
+        analyzed_at=iso_timestamp(),
+        tool_version=read_tool_version(),
+        summary=_compute_summary(workbook),
+        inventory=_compute_inventory(workbook),
+        issues=issues,
+    )

tableau_inspector-0.1.0/src/tableau_inspector/cli.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from tableau_inspector import __version__
+from tableau_inspector.analyzer import analyze
+from tableau_inspector.compare import compare_workbooks
+from tableau_inspector.docs import generate_documentation
+from tableau_inspector.lineage import generate_lineage
+from tableau_inspector.models.serialization import to_json_value
+from tableau_inspector.report.console_compare_reporter import ConsoleCompareReporter
+from tableau_inspector.report.console_lineage_reporter import ConsoleLineageReporter
+from tableau_inspector.report.console_reporter import ConsoleReporter
+from tableau_inspector.report.console_search_reporter import ConsoleSearchReporter
+from tableau_inspector.search import generate_search
+from tableau_inspector.utils.errors import InvalidLineageOptionsError, TableauInspectorError
+from tableau_inspector.utils.timestamps import iso_timestamp
+
+
+def _default_report_path(workbook_name: str) -> str:
+    timestamp = re.sub(r"[:.]", "-", iso_timestamp())
+    safe_name = re.sub(r"[^a-zA-Z0-9_-]+", "_", workbook_name)
+    return str(Path("reports") / f"{safe_name}-{timestamp}.html")
+
+
+def _default_docs_path(workbook_name: str, ext: str) -> str:
+    safe_name = re.sub(r"[^a-zA-Z0-9_-]+", "_", workbook_name)
+    return str(Path("docs") / f"{safe_name}.{ext}")
+
+
+def _print_error(error: Exception, verbose: bool) -> None:
+    if isinstance(error, TableauInspectorError):
+        print(f"Error: {error}", file=sys.stderr)
+    else:
+        print(f"Unexpected error: {error}", file=sys.stderr)
+    if verbose:
+        import traceback
+
+        traceback.print_exc()
+
+
+def _cmd_analyze(args: argparse.Namespace) -> int:
+    try:
+        result = analyze(args.file)
+
+        if args.json:
+            print(json.dumps(to_json_value(result), indent=2))
+        else:
+            ConsoleReporter().report(result)
+
+        if args.html or args.output:
+            from tableau_inspector.report.html_reporter import HtmlReporter
+
+            output_path = args.output or _default_report_path(result.workbook_name)
+            HtmlReporter(output_path).report(result)
+            print(f"\nHTML report written to {output_path}")
+
+        has_critical = any(issue.severity == "critical" for issue in result.issues)
+        return 1 if has_critical else 0
+    except Exception as error:  # noqa: BLE001
+        _print_error(error, args.verbose)
+        return 2
+
+
+def _cmd_lineage(args: argparse.Namespace) -> int:
+    try:
+        if args.field and args.calculation:
+            raise InvalidLineageOptionsError("Pass either --field or --calculation, not both.")
+
+        result = generate_lineage(args.file, args.field or args.calculation)
+
+        if args.json:
+            print(json.dumps(to_json_value(result), indent=2))
+        else:
+            ConsoleLineageReporter().report(result)
+
+        return 0
+    except Exception as error:  # noqa: BLE001
+        _print_error(error, args.verbose)
+        return 2
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    try:
+        result = generate_search(args.file, args.query, formula_only=args.formula)
+
+        if args.json:
+            print(json.dumps(to_json_value(result), indent=2))
+        else:
+            ConsoleSearchReporter().report(result)
+
+        return 0
+    except Exception as error:  # noqa: BLE001
+        _print_error(error, args.verbose)
+        return 2
+
+
+def _cmd_compare(args: argparse.Namespace) -> int:
+    try:
+        result = compare_workbooks(args.old_file, args.new_file)
+
+        if args.json:
+            print(json.dumps(to_json_value(result), indent=2))
+        else:
+            ConsoleCompareReporter().report(result)
+
+        if args.html or args.output:
+            from tableau_inspector.report.html_compare_reporter import HtmlCompareReporter
+
+            output_path = args.output or _default_report_path(result.workbook_name)
+            HtmlCompareReporter(output_path).report(result)
+            print(f"\nHTML report written to {output_path}")
+
+        return 0
+    except Exception as error:  # noqa: BLE001
+        _print_error(error, args.verbose)
+        return 2
+
+
+def _cmd_docs(args: argparse.Namespace) -> int:
+    try:
+        documentation = generate_documentation(args.file)
+
+        if args.json:
+            print(json.dumps(to_json_value(documentation), indent=2))
+            return 0
+
+        fmt = "html" if args.html else "md"
+        output_path = args.output or _default_docs_path(documentation.workbook.name, fmt)
+        if fmt == "html":
+            from tableau_inspector.report.html_doc_reporter import HtmlDocReporter
+
+            HtmlDocReporter(output_path).report(documentation)
+        else:
+            from tableau_inspector.report.markdown_doc_reporter import MarkdownDocReporter
+
+            MarkdownDocReporter(output_path).report(documentation)
+        print(f"Documentation written to {output_path}")
+        return 0
+    except Exception as error:  # noqa: BLE001
+        _print_error(error, args.verbose)
+        return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tableau-inspector",
+        description="Analyze Tableau workbooks (.twb, .twbx) for common issues before publishing.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=__version__)
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    analyze_parser = subparsers.add_parser(
+        "analyze", help="Analyze a Tableau workbook and report issues"
+    )
+    analyze_parser.add_argument("file", help="Path to a .twb or .twbx workbook")
+    analyze_parser.add_argument("--html", action="store_true", help="Generate an HTML report")
+    analyze_parser.add_argument(
+        "--output", help="Output path for the HTML report (implies --html)"
+    )
+    analyze_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the analysis result as JSON instead of formatted console output",
+    )
+    analyze_parser.add_argument(
+        "--verbose", action="store_true", help="Print full error details on failure"
+    )
+    analyze_parser.set_defaults(func=_cmd_analyze)
+
+    docs_parser = subparsers.add_parser(
+        "docs", help="Generate structured Markdown or HTML documentation for a Tableau workbook"
+    )
+    docs_parser.add_argument("file", help="Path to a .twb or .twbx workbook")
+    docs_parser.add_argument(
+        "--html", action="store_true", help="Write HTML documentation instead of Markdown"
+    )
+    docs_parser.add_argument(
+        "--output", help="Output path for the generated documentation file"
+    )
+    docs_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the raw documentation JSON to stdout instead of writing a file",
+    )
+    docs_parser.add_argument(
+        "--verbose", action="store_true", help="Print full error details on failure"
+    )
+    docs_parser.set_defaults(func=_cmd_docs)
+
+    lineage_parser = subparsers.add_parser(
+        "lineage", help="Show upstream dependencies and downstream usage for a field or calculation"
+    )
+    lineage_parser.add_argument("file", help="Path to a .twb or .twbx workbook")
+    lineage_parser.add_argument(
+        "--field", help="Show lineage for a specific field or calculation"
+    )
+    lineage_parser.add_argument(
+        "--calculation", help="Show lineage for a specific field or calculation"
+    )
+    lineage_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the lineage result as JSON instead of formatted console output",
+    )
+    lineage_parser.add_argument(
+        "--verbose", action="store_true", help="Print full error details on failure"
+    )
+    lineage_parser.set_defaults(func=_cmd_lineage)
+
+    search_parser = subparsers.add_parser(
+        "search",
+        help="Search calculated fields by name and/or formula text (case-insensitive substring match)",
+    )
+    search_parser.add_argument("file", help="Path to a .twb or .twbx workbook")
+    search_parser.add_argument("query", help="Substring to search for")
+    search_parser.add_argument(
+        "--formula",
+        action="store_true",
+        help="Restrict matching to formula text only (excludes calculation-name matches)",
+    )
+    search_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the search result as JSON instead of formatted console output",
+    )
+    search_parser.add_argument(
+        "--verbose", action="store_true", help="Print full error details on failure"
+    )
+    search_parser.set_defaults(func=_cmd_search)
+
+    compare_parser = subparsers.add_parser(
+        "compare",
+        help="Compare two Tableau workbooks and report added, removed, and modified entities",
+    )
+    compare_parser.add_argument("old_file", help="Path to the baseline .twb or .twbx workbook")
+    compare_parser.add_argument("new_file", help="Path to the updated .twb or .twbx workbook")
+    compare_parser.add_argument("--html", action="store_true", help="Generate an HTML report")
+    compare_parser.add_argument(
+        "--output", help="Output path for the HTML report (implies --html)"
+    )
+    compare_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the comparison result as JSON instead of formatted console output",
+    )
+    compare_parser.add_argument(
+        "--verbose", action="store_true", help="Print full error details on failure"
+    )
+    compare_parser.set_defaults(func=_cmd_compare)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tableau_inspector-0.1.0/src/tableau_inspector/compare/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+
+from tableau_inspector.models import CompareResult, Workbook
+from tableau_inspector.parser.workbook_loader import WorkbookLoader
+from tableau_inspector.parser.workbook_parser import WorkbookParser
+from tableau_inspector.utils.timestamps import iso_timestamp
+from tableau_inspector.utils.version import read_tool_version
+from .build_compare import CompareMeta, build_compare_result
+
+__all__ = ["compare_workbooks", "build_compare_result", "CompareMeta"]
+
+
+def _load_workbook(file_path: str) -> Workbook:
+    loader = WorkbookLoader()
+    loader.load(file_path)
+    xml = loader.get_xml()
+    workbook_name = os.path.splitext(os.path.basename(file_path))[0]
+    return WorkbookParser().parse(xml, workbook_name)
+
+
+def compare_workbooks(old_file_path: str, new_file_path: str) -> CompareResult:
+    old_workbook = _load_workbook(old_file_path)
+    new_workbook = _load_workbook(new_file_path)
+
+    return build_compare_result(
+        old_workbook,
+        new_workbook,
+        CompareMeta(
+            old_file_path=old_file_path,
+            new_file_path=new_file_path,
+            generated_at=iso_timestamp(),
+            tool_version=read_tool_version(),
+        ),
+    )