py-tbparse

Reads Tableau workbooks (.twb and .twbx) and gives you what's in them as pandas DataFrames: datasources, fields, calculated fields, joins, relationships, dashboards, custom SQL. It's plain Python. You don't need Tableau or R installed.

It began as a port of PrigasG's R package twbparser. The browser GUI, the command-line tool, workbook diffing and folder scanning are new here.

Install

git clone https://github.com/DDSNA/py-tbparse.git
cd py-tbparse
pip install -e .

The project got renamed but the module and commands didn't, so: import twbparser_py, run twbparser or twbparser-gui.

Using it from Python

from twbparser_py import TwbParser

p = TwbParser("workbook.twb")    # or a .twbx
p.get_overview()                 # counts of everything
p.get_calculated_fields()        # each calculation and its formula
p.get_relationships()            # how the tables connect

Every getter returns a DataFrame. The rest are get_datasources, get_parameters, get_fields, get_raw_fields, get_joins, get_relations, get_inferred_relationships, get_dashboards, get_dashboard_sheets, get_custom_sql, get_initial_sql and get_published_refs. get_relationship_graph_dot() returns the data model as Graphviz text, and validate() looks for problems in the relationships. In Jupyter, a bare p shows the overview.

Two helpers work across workbooks:

from twbparser_py import diff_workbooks, scan_folder

diff_workbooks(TwbParser("v1.twb"), TwbParser("v2.twb"), table="datasources")
scan_folder("./workbooks", table="datasources")   # one table, every workbook in the folder

.twbx files

A .twbx is read directly from the zip and nothing gets written to disk. That means p.twbx_dir is None, and p.path is a made-up <file>.twbx/<name>.twb that you can't open. If you want the files out, extract them yourself:

from twbparser_py import extract_twb_from_twbx, twbx_extract_files

extract_twb_from_twbx("workbook.twbx", extract_dir="out/")
twbx_extract_files("workbook.twbx", exdir="out/")    # everything in the package

Command line

twbparser workbook.twb                        # overview
twbparser workbook.twb tables                 # list the tables
twbparser workbook.twb calculated-fields
twbparser workbook.twb fields --format csv -o fields.csv
twbparser workbook.twbx dashboard-sheets --dashboard "Sales Overview"
twbparser workbook.twb validate               # exit code 2 if it finds a problem
twbparser workbook.twb graph > model.dot      # --include-inferred adds the guessed links
twbparser diff old.twb new.twb datasources
twbparser batch ./workbooks datasources

Tables: overview, datasources, parameters, fields, raw-fields, calculated-fields, joins, relations, relationships, inferred-relationships, dashboards, dashboard-sheets, custom-sql, initial-sql, published-refs.

--format takes table (default), csv or json. graph always prints Graphviz text. diff and batch accept the same table names except graph, validate and tables.

GUI

twbparser-gui workbook.twb               # opens your browser with it loaded
twbparser-gui                            # starts empty, paste a path and hit Load
twbparser-gui --no-browser --port 8765   # server only, for a machine with no display

It uses only the standard library, so there's nothing more to install.

The sidebar lists every table with its row count. Click a column header to sort, type in the filter box to narrow rows (/ jumps to it), click a row to see a long formula or SQL statement in full. The tiles on the overview open their tables. The graph view lets you copy or download the DOT text. Everything else exports as CSV. It has a dark theme and works in a narrow window.

It's meant to run on your own machine for one person. It refuses requests that come from other websites, but there's no login, so don't put it on a shared network.

Tests

pip install -e ".[test]"
pytest

The sample workbooks in tests/fixtures/ come from the R package.

The GUI tests run the page in headless Chromium through Playwright and fail on any JavaScript error. They skip if the browser isn't installed. To run them:

pip install -e ".[test,browser]"
playwright install chromium         # add --with-deps if you have root
./scripts/setup-browser-libs.sh     # without root, this unpacks the system libraries locally
pytest tests/test_gui_browser.py

Compared with the R package

The code follows the R original function by function, and the aim is the same output. Not everything is ported. Missing so far: formatting, tooltips, colors, axes and sorts, dashboard layout and actions, the analytics helpers (calculation complexity, field usage, replication brief) and the Shiny inspector. The GUI covers some of what the inspector did.

Where the R version has a bug, this one doesn't copy it. That currently covers joins and relationships on more than one key, nested joins, the include-parameters option, and calculations with brackets inside brackets.

Why a Tableau parser

A .twb is XML and a .twbx is a zip containing one, so reading them from Python isn't hard. Power BI's .pbix is a binary format built on a proprietary storage engine, and getting into it from code took reverse-engineering projects like PBIXRay and pbi-tools. On the server side it goes the other way: Tableau's own Python tooling (tableauserverclient and tabcmd) is more mature and more open than what Microsoft has for the Power BI REST API.

Credit

Based on twbparser by George Arthur, MIT licensed.