py-tbparse 0.1.1a0__py3-none-any.whl

py_tbparse-0.1.1a0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: py-tbparse
+Version: 0.1.1a0
+Summary: Native Python port of the twbparser R package: parse Tableau .twb/.twbx workbooks into pandas DataFrames.
+Author: DDSNA
+License: MIT
+Keywords: tableau,twb,twbx,workbook,parser,pandas
+Classifier: Development Status :: 4 - Beta
+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.9
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=4.9
+Requires-Dist: pandas>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# twbparser-py
+
+A native Python port of the [`twbparser`](https://github.com/PrigasG/twbparser)
+R package: parses Tableau `.twb`/`.twbx` workbook files into `pandas`
+DataFrames. No R runtime required — pure `lxml` XML parsing.
+
+This is a v1 subset covering the parser's core: workbook loading,
+datasources, parameters, fields, calculated fields, joins, relationships
+(legacy and 2020.2+), inferred relationships, dashboards, relationship
+validation, custom/initial SQL, and published-source detection.
+Formatting/tooltips/colors/axes/sorts, dashboard layout/actions,
+analytics helpers (calc complexity, field usage, replication brief), and
+the Shiny-inspector equivalent are not yet ported.
+
+Beyond the R original, this port also adds a few Python-native extras: a
+Graphviz DOT export of the relationship graph, a workbook-to-workbook
+diff, folder/batch analysis across many workbooks, and Jupyter rich
+display (`_repr_html_`).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```python
+from twbparser_py import TwbParser
+
+p = TwbParser("workbook.twb")  # or .twbx
+p.get_datasources()
+p.get_fields()
+p.get_calculated_fields()
+p.get_joins()
+p.get_relationships()
+p.get_inferred_relationships()
+p.get_dashboards()
+p.get_dashboard_sheets()
+p.get_custom_sql()
+p.get_initial_sql()
+p.get_published_refs()
+p.get_relationship_graph_dot()   # Graphviz DOT string
+p.validate()
+p.get_overview()
+p  # in Jupyter: renders get_overview() via _repr_html_
+
+from twbparser_py import diff_workbooks, scan_folder
+
+diff_workbooks(TwbParser("v1.twb"), TwbParser("v2.twb"), table="datasources")
+scan_folder("./workbooks", table="datasources")  # one row per workbook x datasource
+```
+
+### CLI
+
+```bash
+twbparser workbook.twb                              # overview (default table)
+twbparser workbook.twb tables                        # list available tables
+twbparser workbook.twb calculated-fields             # print a table
+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 invalid
+twbparser workbook.twb graph --include-inferred > relationships.dot
+twbparser diff old.twb new.twb datasources             # row-level added/removed
+twbparser batch ./workbooks datasources                # one table, every workbook in a folder
+```
+
+Tables: `overview`, `datasources`, `parameters`, `fields`, `raw-fields`,
+`calculated-fields`, `joins`, `relations`, `relationships`,
+`inferred-relationships`, `dashboards`, `dashboard-sheets`,
+`custom-sql`, `initial-sql`, `published-refs`. `--format` is `table`
+(default), `csv`, or `json` (`graph` always prints Graphviz DOT text
+regardless of `--format`). `diff`/`batch` accept most of the same table
+names, minus `graph`/`validate`/`tables`.
+
+### GUI
+
+A local, browser-based GUI — standard library only (`http.server` +
+vanilla JS), no GUI toolkit or extra dependency required:
+
+```bash
+twbparser-gui workbook.twb   # opens your default browser
+twbparser-gui                # opens with an empty path field; paste one and click Load
+twbparser-gui --no-browser --port 8765   # just run the server, e.g. for a headless box
+```
+
+Pick a table from the dropdown, filter `dashboard-sheets` by dashboard,
+toggle "include Parameters" for `calculated-fields`, pick `graph` to
+preview/export a Graphviz DOT digraph of the relationships, and export
+any tabular view as CSV. All state lives server-side in memory for the
+life of the process — it's a single-user local tool, not something to
+expose on a shared network.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Fixtures in `tests/fixtures/` are the same tiny sample workbooks used by
+the original R package's test suite (`inst/extdata/`).
+
+The GUI additionally has end-to-end tests that drive the page in a real
+headless Chromium (via Playwright) and fail on any uncaught JavaScript
+error. They're opt-in — without the browser installed they skip and the
+rest of the suite runs normally:
+
+```bash
+pip install -e ".[test,browser]"
+playwright install chromium          # add --with-deps if you have root
+./scripts/setup-browser-libs.sh      # no-root alternative to --with-deps
+pytest tests/test_gui_browser.py
+```
+
+## Background
+
+`.twb` is plain XML, and `.twbx` is just a zip wrapper around one, which
+is why parsing it natively in Python — no R, no reverse-engineering —
+was tractable at this scale. Power BI's equivalent format, `.pbix`, is a
+binary container built around the proprietary VertiPaq storage engine,
+which is why reading it programmatically needed dedicated
+reverse-engineering projects like
+[PBIXRay](https://github.com/Hugoberry/pbixray) and
+[pbi-tools](https://github.com/pbi-tools/pbi-tools). The comparison
+isn't one-sided, though: Tableau's own official Python tooling for
+*server* automation
+([`tableauserverclient`](https://pypi.org/project/tableauserverclient/),
+`tabcmd`) is more mature and more open than anything Microsoft ships for
+Power BI's REST API.
+
+## Credit
+
+Ported from the R implementation by George Arthur
+([`PrigasG/twbparser`](https://github.com/PrigasG/twbparser)), MIT licensed.

py_tbparse-0.1.1a0.dist-info/RECORD

@@ -0,0 +1,26 @@
+py_tbparse-0.1.1a0.dist-info/licenses/LICENSE,sha256=y8NSwuzSKYNP-QLxH5gd8cYj3m_yNcufgRWRjaC-NCM,1252
+twbparser_py/__init__.py,sha256=Mj5SX7NFlXweWg23nmV9sI6sz34-YtfbAsNlBFAFSps,1856
+twbparser_py/_clean.py,sha256=moCudA2sxmlVI5HBM5EI8BMus_fcMKPOVomeycbOkVY,2313
+twbparser_py/_tables.py,sha256=r-4rXT7Z71XQxn1oz75DC-4wIh2ejTi3UkwgTd2ahwI,2550
+twbparser_py/_xml.py,sha256=C_EjP58cav713GnWrfENga9UZqCVnBRL51H0WcSAcMw,5568
+twbparser_py/batch.py,sha256=WetmMfNYpSGP8cCFCKsP6wYG-lq-wAO-ZS4bCd4APUA,1804
+twbparser_py/calculated_fields.py,sha256=tRo4zCRTJ-4LiMp9QSlq1OTN-Co-snNjLaTALYfvQDo,3859
+twbparser_py/cli.py,sha256=awMN7NnkNX-fQpmnN-Rf3g9KyGQKUD-YLx8t2ztK6I8,7181
+twbparser_py/dashboards.py,sha256=g3fQrqLIc88J6ug3PrCUIXoP8TJV8VZhlG6Av8SM4_U,3282
+twbparser_py/datasources.py,sha256=c924vxYR9_lQKX0GRNQFGuZ3bHXpxQZ7V2Q9PQUoxHA,8790
+twbparser_py/diff.py,sha256=CB1WJUF7cb7H7KOZPObS__SELHmlbL1J3QOb5aHMs1g,3303
+twbparser_py/fields.py,sha256=MlWpdXessuW_mZ8qLZFl6d9-G9coMRz8rxiakEvLKHc,5378
+twbparser_py/graph.py,sha256=sMbh4wayhRxpA7hBNBGiyOF4lGSd_cEKW8sXjdwfw8c,2955
+twbparser_py/joins.py,sha256=Df0O5edFQ9pXjGPgrT8Q4TPOzDP6qNJm0nJ3cGAPewI,3503
+twbparser_py/parser.py,sha256=Ip4hPMCzi8vWeCYCG45kIXt8y6SL0RSngqsYBs4NvQk,8967
+twbparser_py/published.py,sha256=vIFKBI4pw-m9vqXFa5dqY2nGJWsTjN6pAhysj8D2RLI,1472
+twbparser_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+twbparser_py/relationships.py,sha256=uj2k67NEeNG-dCs-uZsVc8ghCtPFeK-Zbfnc8q5KRlk,5669
+twbparser_py/sql.py,sha256=lQonS9GXSAU7pR7yhjCK0WdGBtMTP3bsCXdDkIeWVwI,2443
+twbparser_py/validators.py,sha256=1rG2-1hORa7joNy7cr3PhVfQsASZZjV30PfhItyCSN8,3492
+twbparser_py/webgui.py,sha256=flrdhxf-s0mzOwSKYHIl-r2CZXDYuqtyosUk8-71NdI,14040
+py_tbparse-0.1.1a0.dist-info/METADATA,sha256=OQU06QCv-7AlG9EzCOwVXfWbX1S9yeRW1YqWstv04XU,6402
+py_tbparse-0.1.1a0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+py_tbparse-0.1.1a0.dist-info/entry_points.txt,sha256=VIH-RDvE5jddcwiDat_CO4nQVLcnTFxfgx4D4vQS39A,93
+py_tbparse-0.1.1a0.dist-info/top_level.txt,sha256=ZEo8_tUfoJEe1tKN5aJCS-mvL_3QAnu8qfELdfaDSnQ,13
+py_tbparse-0.1.1a0.dist-info/RECORD,,

py_tbparse-0.1.1a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_tbparse-0.1.1a0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+twbparser = twbparser_py.cli:main
+twbparser-gui = twbparser_py.webgui:main

py_tbparse-0.1.1a0.dist-info/licenses/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+This project is a Python port of logic originally implemented in the R
+package "twbparser" (https://github.com/PrigasG/twbparser),
+Copyright (c) 2025 George Arthur.
+
+Copyright (c) 2026 the twbparser-py contributors
+
+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.

py_tbparse-0.1.1a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+twbparser_py

twbparser_py/__init__.py

@@ -0,0 +1,54 @@
+"""twbparser_py: a native Python port of the twbparser R package.
+
+Parses Tableau .twb/.twbx workbook files into pandas DataFrames. Ported
+from https://github.com/PrigasG/twbparser (MIT licensed).
+"""
+
+from .batch import scan_folder
+from .calculated_fields import extract_calculated_fields, extract_raw_fields
+from .dashboards import dashboard_sheets, list_dashboards
+from .datasources import extract_datasource_details, extract_named_connections, extract_parameters
+from .diff import diff_tables, diff_workbooks
+from .fields import extract_columns_with_table_source, infer_implicit_relationships
+from .graph import to_dot
+from .joins import extract_joins
+from .parser import TwbParser
+from .published import extract_published_refs
+from .relationships import extract_relations, extract_relationships
+from .sql import extract_custom_sql, extract_initial_sql
+from .validators import validate_relationships
+from ._xml import extract_twb_from_twbx, twbx_extract_files, twbx_list
+
+__all__ = [
+    "TwbParser",
+    "extract_calculated_fields",
+    "extract_raw_fields",
+    "dashboard_sheets",
+    "list_dashboards",
+    "extract_datasource_details",
+    "extract_named_connections",
+    "extract_parameters",
+    "extract_columns_with_table_source",
+    "infer_implicit_relationships",
+    "extract_joins",
+    "to_dot",
+    "extract_relations",
+    "extract_relationships",
+    "extract_custom_sql",
+    "extract_initial_sql",
+    "extract_published_refs",
+    "validate_relationships",
+    "extract_twb_from_twbx",
+    "twbx_extract_files",
+    "twbx_list",
+    "diff_tables",
+    "diff_workbooks",
+    "scan_folder",
+]
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("twbparser-py")
+except PackageNotFoundError:  # pragma: no cover - not installed, e.g. running from source
+    __version__ = "0.0.0+unknown"

twbparser_py/_clean.py

@@ -0,0 +1,87 @@
+"""Name-cleaning helpers, ported from twbparser's R/utils.R."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+import pandas as pd
+
+_TRAILING_HEX32 = re.compile(r"_[0-9A-Fa-f]{32}$")
+_LEADING_BRACKET_PREFIX = re.compile(r"^\[.*?\]\.")
+_BRACKETS = re.compile(r"[\[\]]")
+_DERIVATION_WRAPPER = re.compile(r"^[a-z]+:(.+):[a-z]{1,3}$")
+
+
+def clean_table(x: Optional[str]) -> Optional[str]:
+    """Port of `.twb_clean_table`.
+
+    Drops `[Extract].`/`[Connection].` prefixes, strips `[]`, and removes
+    Tableau's trailing 32-char hex suffix.
+    """
+    if x is None:
+        return None
+    s = str(x)
+    s = _LEADING_BRACKET_PREFIX.sub("", s)
+    s = _BRACKETS.sub("", s)
+    s = _TRAILING_HEX32.sub("", s)
+    s = s.strip()
+    return s if s else None
+
+
+def clean_field(x: Optional[str]) -> Optional[str]:
+    """Port of `.twb_clean_field`.
+
+    Strips `[]`, takes the last dot-separated token, then unwraps a
+    Tableau column-instance wrapper like `none:Category:nk` -> `Category`.
+    """
+    if x is None:
+        return None
+    s = str(x)
+    s = _BRACKETS.sub("", s)
+
+    parts = [p for p in s.split(".") if p]
+    token = parts[-1] if parts else None
+    if token is None:
+        return None
+
+    m = _DERIVATION_WRAPPER.match(token)
+    if m:
+        return m.group(1)
+    return token
+
+
+def is_missing(x) -> bool:
+    """True for any "missing" scalar (`None`, float `NaN`, `NaT`, `pd.NA`,
+    ...) -- not a port of an R function, but a shared helper so callers
+    (`diff.py`, `validators.py`) don't each reimplement `pd.isna()`'s
+    edge cases (e.g. it raises on array-likes) slightly differently."""
+    if x is None:
+        return True
+    try:
+        return bool(pd.isna(x))
+    except (TypeError, ValueError):
+        return False
+
+
+def attr_safe_get(attrs: dict, name: str, default=None):
+    """Port of `attr_safe_get`."""
+    if attrs is None:
+        return default
+    return attrs.get(name, default)
+
+
+def strip_brackets(x: Optional[str]) -> Optional[str]:
+    """Port of `.strip_brackets`."""
+    if x is None:
+        return None
+    return _BRACKETS.sub("", x)
+
+
+def basename_safe(x: Optional[str], fallback: str = "<unknown>") -> str:
+    """Port of `basename_safe`."""
+    if not x:
+        return fallback
+    import os
+
+    return os.path.basename(x)

twbparser_py/_tables.py

@@ -0,0 +1,97 @@
+"""Shared table registry used by both the CLI and the web GUI.
+
+Keeping this in one place means the CLI and GUI can never drift out of
+sync on which tables exist or how their optional parameters
+(`dashboard`, `include_parameters`) are threaded through to `TwbParser`.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import pandas as pd
+
+from .parser import TwbParser
+
+
+def _overview(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_overview()
+
+
+def _datasources(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_datasources()
+
+
+def _parameters(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_parameters()
+
+
+def _fields(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_fields()
+
+
+def _raw_fields(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_raw_fields()
+
+
+def _calculated_fields(p: TwbParser, include_parameters: bool = False, **_kw) -> pd.DataFrame:
+    return p.get_calculated_fields(include_parameters=include_parameters)
+
+
+def _joins(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_joins()
+
+
+def _relations(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_relations()
+
+
+def _relationships(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_relationships()
+
+
+def _inferred_relationships(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_inferred_relationships()
+
+
+def _dashboards(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_dashboards()
+
+
+def _dashboard_sheets(p: TwbParser, dashboard: str | None = None, **_kw) -> pd.DataFrame:
+    return p.get_dashboard_sheets(dashboard=dashboard or None)
+
+
+def _custom_sql(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_custom_sql()
+
+
+def _initial_sql(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_initial_sql()
+
+
+def _published_refs(p: TwbParser, **_kw) -> pd.DataFrame:
+    return p.get_published_refs()
+
+
+# Order here is display order in both the CLI's `tables` listing and the
+# GUI's table dropdown.
+TABLE_SPECS: dict[str, Callable[..., pd.DataFrame]] = {
+    "overview": _overview,
+    "datasources": _datasources,
+    "parameters": _parameters,
+    "fields": _fields,
+    "raw-fields": _raw_fields,
+    "calculated-fields": _calculated_fields,
+    "joins": _joins,
+    "relations": _relations,
+    "relationships": _relationships,
+    "inferred-relationships": _inferred_relationships,
+    "dashboards": _dashboards,
+    "dashboard-sheets": _dashboard_sheets,
+    "custom-sql": _custom_sql,
+    "initial-sql": _initial_sql,
+    "published-refs": _published_refs,
+}
+
+TABLE_NAMES = list(TABLE_SPECS)

twbparser_py/_xml.py

@@ -0,0 +1,172 @@
+"""Workbook loading and .twbx archive helpers.
+
+Ports of `twbx_list`, `extract_twb_from_twbx`, `twbx_extract_files`, and the
+`.twbx_classify` logic from R/utils.R.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Iterable, Optional
+
+import pandas as pd
+from lxml import etree
+
+_WORKBOOK_EXT = {"twb"}
+_EXTRACT_EXT = {"hyper", "tde"}
+_IMAGE_EXT = {"png", "jpg", "jpeg", "gif", "svg"}
+_TEXT_EXT = {"csv", "txt", "tsv"}
+_EXCEL_EXT = {"xlsx", "xls"}
+
+
+def _classify(name: str) -> str:
+    """Port of `.twbx_classify`."""
+    ext = Path(name).suffix.lower().lstrip(".")
+    if ext in _WORKBOOK_EXT:
+        return "workbook"
+    if ext in _EXTRACT_EXT:
+        return "extract"
+    if ext in _IMAGE_EXT:
+        return "image"
+    if ext in _TEXT_EXT:
+        return "text"
+    if ext in _EXCEL_EXT:
+        return "excel"
+    return "other"
+
+
+def twbx_list(twbx_path: str) -> pd.DataFrame:
+    """Port of `twbx_list()`. Lists the contents of a .twbx archive."""
+    if not twbx_path or not os.path.exists(twbx_path):
+        raise FileNotFoundError(f"File not found: {twbx_path}")
+
+    rows = []
+    with zipfile.ZipFile(twbx_path) as zf:
+        for info in zf.infolist():
+            if info.is_dir():
+                continue
+            modified = _dt.datetime(*info.date_time)
+            rows.append(
+                {
+                    "name": info.filename,
+                    "size_bytes": float(info.file_size),
+                    "modified": modified,
+                    "type": _classify(info.filename),
+                }
+            )
+    return pd.DataFrame(rows, columns=["name", "size_bytes", "modified", "type"])
+
+
+def extract_twb_from_twbx(
+    twbx_path: str,
+    extract_dir: Optional[str] = None,
+    extract_all: bool = False,
+) -> dict:
+    """Port of `extract_twb_from_twbx()`.
+
+    Extracts the largest `.twb` member (or the whole archive) from a
+    `.twbx` file. Returns a dict with `twb_path`, `exdir`, `twbx_path`,
+    and `manifest`.
+    """
+    if not twbx_path or not os.path.exists(twbx_path):
+        raise FileNotFoundError(f"File not found: {twbx_path}")
+
+    manifest = twbx_list(twbx_path)
+    twb_rows = manifest[manifest["type"] == "workbook"].sort_values(
+        "size_bytes", ascending=False
+    )
+    if twb_rows.empty:
+        raise ValueError("No .twb file found inside .twbx")
+
+    twb_rel = twb_rows.iloc[0]["name"]
+
+    if extract_dir is None:
+        stamp = _dt.datetime.now().strftime("%Y%m%d%H%M%S")
+        stem = Path(twbx_path).stem
+        extract_dir = os.path.join(tempfile.gettempdir(), f"twbx_{stem}_{stamp}")
+
+    os.makedirs(extract_dir, exist_ok=True)
+    with zipfile.ZipFile(twbx_path) as zf:
+        if extract_all:
+            zf.extractall(extract_dir)
+        # extract() sanitizes '..'/absolute segments out of `name` before
+        # writing, and returns the *actual* destination path -- computing
+        # it ourselves via os.path.join(extract_dir, twb_rel) would
+        # silently diverge from where the file really landed for a member
+        # name like "../../evil.twb". Calling it again when extract_all
+        # already wrote this same member is redundant I/O but harmless
+        # (identical bytes), and keeps this one code path authoritative.
+        twb_path = zf.extract(twb_rel, extract_dir)
+
+    return {
+        "twb_path": twb_path,
+        "exdir": extract_dir,
+        "twbx_path": os.path.abspath(twbx_path),
+        "manifest": manifest,
+    }
+
+
+def twbx_extract_files(
+    twbx_path: str,
+    files: Optional[Iterable[str]] = None,
+    pattern: Optional[str] = None,
+    types: Optional[Iterable[str]] = None,
+    exdir: Optional[str] = None,
+) -> pd.DataFrame:
+    """Port of `twbx_extract_files()`."""
+    import re as _re
+
+    if not twbx_path or not os.path.exists(twbx_path):
+        raise FileNotFoundError(f"File not found: {twbx_path}")
+
+    man = twbx_list(twbx_path)
+    sel = man
+    if types is not None:
+        sel = sel[sel["type"].isin(list(types))]
+    if pattern is not None:
+        sel = sel[sel["name"].str.contains(pattern, regex=True, na=False)]
+    if files is not None:
+        sel = sel[sel["name"].isin(list(files))]
+
+    if sel.empty:
+        return pd.DataFrame(columns=["name", "out_path", "type"])
+
+    if exdir is None:
+        stamp = _dt.datetime.now().strftime("%Y%m%d%H%M%S")
+        exdir = os.path.join(tempfile.gettempdir(), f"twbx_extract_{stamp}")
+    os.makedirs(exdir, exist_ok=True)
+
+    with zipfile.ZipFile(twbx_path) as zf:
+        # extract() returns the sanitized destination path -- see the
+        # comment in extract_twb_from_twbx() for why os.path.join(exdir, n)
+        # would diverge from it for a member name containing '..'.
+        out_paths = [zf.extract(name, exdir) for name in sel["name"]]
+
+    return pd.DataFrame(
+        {
+            "name": sel["name"].tolist(),
+            "type": sel["type"].tolist(),
+            "out_path": out_paths,
+        }
+    )
+
+
+def load_workbook_xml(path: str) -> etree._ElementTree:
+    """Load a .twb/.twbx path into a parsed lxml ElementTree."""
+    ext = Path(path).suffix.lower().lstrip(".")
+    if ext == "twbx":
+        info = extract_twb_from_twbx(path, extract_all=False)
+        twb_path = info["twb_path"]
+    elif ext == "twb":
+        twb_path = path
+    else:
+        raise ValueError(f"Unsupported file type: {ext}")
+
+    if not os.path.exists(twb_path):
+        raise FileNotFoundError(f"File not found: {twb_path}")
+
+    return etree.parse(str(twb_path))