pytableau 0.1.0__py3-none-any.whl

pytableau/__init__.py

@@ -0,0 +1,93 @@
+"""pytableau — The unified Python SDK for Tableau workbook engineering.
+
+Quickstart::
+
+    from pytableau import Workbook
+
+    wb = Workbook.open("sales_dashboard.twbx")
+    print(wb.version)
+    wb.save_as("modified.twbx")
+"""
+
+from __future__ import annotations
+
+from pytableau._version import __version__
+from pytableau.constants import (
+    AggregationType,
+    ConnectionType,
+    DataType,
+    FilterType,
+    MarkType,
+    ParameterDomainType,
+    Role,
+    SortOrder,
+    ValidationLevel,
+)
+from pytableau.core.workbook import Workbook
+from pytableau.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    CorruptWorkbookError,
+    DatasourceError,
+    DatasourceNotFoundError,
+    DuplicateFieldError,
+    ExtractError,
+    FieldError,
+    FieldNotFoundError,
+    FileError,
+    FormulaError,
+    HyperError,
+    IncompatibleVersionError,
+    InvalidWorkbookError,
+    PackageError,
+    PublishError,
+    PyTableauError,
+    SchemaValidationError,
+    ServerError,
+    TemplateError,
+    TemplateNotFoundError,
+    UnmappedPlaceholderError,
+    ValidationIssue,
+    XMLError,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Top-level exceptions
+    "PyTableauError",
+    "FileError",
+    "InvalidWorkbookError",
+    "PackageError",
+    "CorruptWorkbookError",
+    "XMLError",
+    "SchemaValidationError",
+    "IncompatibleVersionError",
+    "FieldError",
+    "FieldNotFoundError",
+    "DuplicateFieldError",
+    "FormulaError",
+    "DatasourceError",
+    "DatasourceNotFoundError",
+    "ConnectionError",
+    "HyperError",
+    "ExtractError",
+    "ServerError",
+    "AuthenticationError",
+    "PublishError",
+    "TemplateError",
+    "UnmappedPlaceholderError",
+    "TemplateNotFoundError",
+    "ValidationIssue",
+    "Workbook",
+    # Enums
+    "MarkType",
+    "DataType",
+    "Role",
+    "AggregationType",
+    "FilterType",
+    "SortOrder",
+    "ConnectionType",
+    "ParameterDomainType",
+    "ValidationLevel",
+]

pytableau/_compat.py

@@ -0,0 +1,46 @@
+"""Optional dependency import helpers.
+
+Provides clear error messages when optional extras are not installed.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+class _MissingDependency:
+    """Placeholder that raises ImportError on any attribute access."""
+
+    def __init__(self, name: str, extra: str) -> None:
+        self._name = name
+        self._extra = extra
+
+    def __getattr__(self, attr: str) -> Any:
+        raise ImportError(
+            f"{self._name} is required for this feature. "
+            f"Install it with: pip install pytableau[{self._extra}]"
+        )
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        raise ImportError(
+            f"{self._name} is required for this feature. "
+            f"Install it with: pip install pytableau[{self._extra}]"
+        )
+
+
+def import_optional(module_name: str, extra: str) -> Any:
+    """Import an optional dependency, returning a stub if unavailable.
+
+    Args:
+        module_name: Fully qualified module name (e.g. ``"tableauhyperapi"``).
+        extra: The pip extra that provides this dependency (e.g. ``"hyper"``).
+
+    Returns:
+        The imported module, or a :class:`_MissingDependency` stub that raises
+        a helpful :class:`ImportError` on first use.
+    """
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return _MissingDependency(module_name, extra)

pytableau/_version.py

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

pytableau/cli/__init__.py

@@ -0,0 +1,15 @@
+"""Optional CLI interface for pytableau.
+
+Provides the ``pytableau`` command-line tool.
+
+Usage::
+
+    pytableau inspect workbook.twbx
+    pytableau diff before.twb after.twb
+    pytableau swap workbook.twb --server prod-db.corp.com --db analytics_prod
+
+.. note::
+    Full implementation is tracked in Phase 1 of the development plan.
+"""
+
+from __future__ import annotations

pytableau/cli/main.py

@@ -0,0 +1,137 @@
+"""CLI entry point: ``pytableau inspect``, ``pytableau diff``, ``pytableau swap``.
+
+The CLI is built with `click <https://click.palletsprojects.com/>`_.
+
+.. note::
+    Full implementation is tracked in Phase 1 of the development plan.
+    Phase 0 ships a minimal skeleton so that the ``pytableau`` console
+    script entry point is importable.
+"""
+
+from __future__ import annotations
+
+import json
+
+try:
+    import click
+except ImportError as exc:
+    raise ImportError(
+        "The pytableau CLI requires 'click'. "
+        "Install it with: pip install click"
+    ) from exc
+
+from pytableau.core.workbook import Workbook
+
+
+@click.group()
+@click.version_option(package_name="pytableau")
+def app() -> None:
+    """pytableau — The unified Python SDK for Tableau workbook engineering."""
+
+
+@app.command()
+@click.argument("workbook", type=click.Path(exists=True))
+@click.option("--format", "fmt", default="table", type=click.Choice(["table", "json"]))
+def inspect(workbook: str, fmt: str) -> None:
+    """Inspect a Tableau workbook and print its contents."""
+    wb = Workbook.open(workbook)
+    payload = {
+        "path": str(workbook),
+        "version": wb.version,
+        "source_platform": wb.source_platform,
+        "datasource_count": len(wb.datasources),
+        "datasources": wb.datasources.names,
+        "worksheet_count": len(wb.worksheets),
+        "worksheets": wb.worksheets.names,
+        "dashboard_count": len(wb.dashboards),
+        "dashboards": wb.dashboards.names,
+    }
+
+    if fmt == "json":
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+        return
+
+    click.echo(f"Workbook: {workbook}")
+    click.echo(f"Version: {wb.version}")
+    if wb.source_platform:
+        click.echo(f"Source platform: {wb.source_platform}")
+    click.echo(f"Datasources ({payload['datasource_count']}):")
+    for name in payload["datasources"]:
+        click.echo(f"  - {name}")
+    click.echo(f"Worksheets ({payload['worksheet_count']}):")
+    for name in payload["worksheets"]:
+        click.echo(f"  - {name}")
+    click.echo(f"Dashboards ({payload['dashboard_count']}):")
+    for name in payload["dashboards"]:
+        click.echo(f"  - {name}")
+
+
+@app.command()
+@click.argument("before", type=click.Path(exists=True))
+@click.argument("after", type=click.Path(exists=True))
+def diff(before: str, after: str) -> None:
+    """Show semantic differences between two Tableau workbooks."""
+    before_wb = Workbook.open(before)
+    after_wb = Workbook.open(after)
+
+    before_xml = before_wb.to_xml_string().splitlines()
+    after_xml = after_wb.to_xml_string().splitlines()
+
+    if before_xml == after_xml:
+        click.echo("No differences detected.")
+        return
+
+    before_set = {line for line in before_xml}
+    after_set = {line for line in after_xml}
+    added = sorted(after_set - before_set)
+    removed = sorted(before_set - after_set)
+
+    click.echo(f"Added lines: {len(added)}")
+    for item in added[:40]:
+        click.echo(f"  + {item}")
+    if len(added) > 40:
+        click.echo(f"  ... ({len(added) - 40} more)")
+
+    click.echo(f"Removed lines: {len(removed)}")
+    for item in removed[:40]:
+        click.echo(f"  - {item}")
+    if len(removed) > 40:
+        click.echo(f"  ... ({len(removed) - 40} more)")
+
+
+@app.command()
+@click.argument("workbook", type=click.Path(exists=True))
+@click.option("--server", required=True, help="New database server hostname")
+@click.option("--db", required=False, help="New database name")
+@click.option("--username", required=False, help="New database username")
+@click.option("--output", "-o", required=False, help="Output path (default: overwrite)")
+def swap(
+    workbook: str,
+    server: str,
+    db: str | None,
+    username: str | None,
+    output: str | None,
+) -> None:
+    """Swap connection properties in a Tableau workbook."""
+    wb = Workbook.open(workbook)
+    updated = 0
+
+    for conn in wb.xml_tree.findall(".//connection"):
+        if server:
+            conn.set("server", server)
+            updated += 1
+        if db:
+            if "dbname" in conn.attrib:
+                conn.set("dbname", db)
+            elif "dbName" in conn.attrib:
+                conn.set("dbName", db)
+            else:
+                conn.set("dbname", db)
+            updated += 1
+        if username:
+            conn.set("username", username)
+            updated += 1
+
+    destination = output or workbook
+    wb.save_as(destination)
+    click.echo(f"Updated {updated} connection attributes.")

pytableau/constants.py

@@ -0,0 +1,212 @@
+"""Constants and enumerations for pytableau.
+
+All Tableau-level concepts (mark types, data types, roles, etc.) are
+represented as ``str`` enums so that values compare equal to the raw
+XML attribute strings used by Tableau.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MarkType(str, Enum):
+    """Viz mark types as they appear in Tableau XML."""
+
+    AUTOMATIC = "automatic"
+    BAR = "bar"
+    LINE = "line"
+    AREA = "area"
+    CIRCLE = "circle"
+    SQUARE = "square"
+    SHAPE = "shape"  # custom shapes palette
+    TEXT = "text"
+    MAP = "map"
+    PIE = "pie"
+    GANTT = "gantt_rounded"
+    GANTT_BAR = "gantt_rounded"  # alias — same XML value
+    POLYGON = "polygon"
+    DENSITY = "density"
+
+
+class DataType(str, Enum):
+    """Field data types as they appear in Tableau XML."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    REAL = "real"
+    BOOLEAN = "boolean"
+    DATE = "date"
+    DATETIME = "datetime"
+
+
+class Role(str, Enum):
+    """Semantic role of a field."""
+
+    DIMENSION = "dimension"
+    MEASURE = "measure"
+
+
+class AggregationType(str, Enum):
+    """Default aggregation types for measure fields."""
+
+    SUM = "Sum"
+    AVG = "Avg"
+    COUNT = "Count"
+    COUNTD = "CountD"
+    MIN = "Min"
+    MAX = "Max"
+    MEDIAN = "Median"
+    ATTR = "Attr"
+    STDEV = "Stdev"
+    VAR = "Var"
+    YEAR = "Year"
+    QUARTER = "Quarter"
+    MONTH = "Month"
+    WEEK = "Week"
+    DAY = "Day"
+    NONE = "None"
+
+
+class FilterType(str, Enum):
+    """Filter types as they appear in Tableau XML."""
+
+    CATEGORICAL = "categorical"
+    QUANTITATIVE = "quantitative"
+    RELATIVE_DATE = "relative-date"
+    RANGE = "range"
+    TOP = "top"
+    WILDCARD = "wildcard"
+    ALL = "all"
+
+
+class SortOrder(str, Enum):
+    """Sort direction options."""
+
+    ASCENDING = "asc"
+    DESCENDING = "desc"
+    NONE = "none"
+
+
+class SortType(str, Enum):
+    """Sort method options."""
+
+    ALPHABETIC = "alphabetic"
+    DATA_SOURCE = "data-source-order"
+    FIELD = "field"
+    MANUAL = "manual"
+    NONE = "none"
+
+
+class ConnectionType(str, Enum):
+    """Common Tableau connection class names (``class`` XML attribute)."""
+
+    HYPER = "hyper"
+    TEXTSCAN = "textscan"  # CSV / text files
+    EXCEL = "excel-direct"
+    SQLSERVER = "sqlserver"
+    MSSQL = "sqlserver"  # alias — same XML class value as SQLSERVER
+    POSTGRES = "postgres"
+    MYSQL = "mysql"
+    ORACLE = "oracle"
+    REDSHIFT = "redshift"
+    SNOWFLAKE = "snowflake"
+    BIGQUERY = "bigquery"
+    DATABRICKS = "spark"
+    ATHENA = "athena"
+    TABLEAU_SERVER = "tableau-server"  # published data source on Tableau Server/Cloud
+
+
+class DashboardSizeType(str, Enum):
+    """Dashboard size constraint modes."""
+
+    FIXED = "fixed"
+    AUTOMATIC = "automatic"
+    RANGE = "range"
+
+
+class ZoneType(str, Enum):
+    """Dashboard zone layout types."""
+
+    LAYOUT_BASIC = "layout-basic"
+    LAYOUT_FLOW = "layout-flow"
+    WORKSHEET = "worksheet"
+    TEXT = "text"
+    IMAGE = "image"
+    WEB = "web"
+    BLANK = "blank"
+    TITLE = "title"
+    LEGEND = "legend"
+    FILTER = "filter"
+    PARAMETER = "parameter"
+    EXTENSION = "extension"
+
+
+class ShelfType(str, Enum):
+    """Worksheet shelf identifiers."""
+
+    ROWS = "rows"
+    COLUMNS = "columns"
+    COLOR = "color"
+    SIZE = "size"
+    LABEL = "label"
+    DETAIL = "detail"
+    TOOLTIP = "tooltip"
+    PATH = "path"
+    SHAPE = "shape"
+    ANGLE = "angle"
+
+
+class ActionType(str, Enum):
+    """Dashboard action types."""
+
+    FILTER = "filter"
+    HIGHLIGHT = "highlight"
+    URL = "url"
+    GOTO_SHEET = "goto-sheet"
+    CHANGE_PARAMETER = "change-parameter"
+    CHANGE_SET_VALUES = "change-set-values"
+
+
+class ParameterDomainType(str, Enum):
+    """Parameter allowable values type."""
+
+    ALL = "all"
+    LIST = "list"
+    RANGE = "range"
+
+
+class ValidationLevel(str, Enum):
+    """Severity levels for validation issues."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+# ---------------------------------------------------------------------------
+# Tableau version mapping: version string → XML source-build attribute value
+# ---------------------------------------------------------------------------
+
+#: Maps human-readable Tableau version strings to the ``source-build``
+#: attribute value written in workbook XML headers.
+TABLEAU_VERSION_MAP: dict[str, str] = {
+    "2022.1": "20221.22.0418.1333",
+    "2022.2": "20222.22.0719.1543",
+    "2022.3": "20223.22.1007.0912",
+    "2022.4": "20224.23.0112.0803",
+    "2023.1": "20231.23.0309.0931",
+    "2023.2": "20232.23.0609.0906",
+    "2023.3": "20233.23.0921.0921",
+    "2023.4": "20234.24.0111.0824",
+    "2024.1": "20241.24.0312.0830",
+    "2024.2": "20242.24.0613.0835",
+    "2024.3": "20243.24.0912.0921",
+    "2025.1": "20251.25.0314.0930",
+}
+
+#: The minimum Tableau version supported by pytableau.
+MINIMUM_TABLEAU_VERSION = "2022.1"
+
+#: The default Tableau version used when creating new workbooks.
+DEFAULT_TABLEAU_VERSION = "2024.1"

pytableau/core/__init__.py

@@ -0,0 +1,38 @@
+"""Core object model for pytableau.
+
+Provides the high-level Python objects that map to Tableau workbook
+concepts: Workbook, Datasource, Worksheet, Dashboard, and field-like objects.
+"""
+
+from __future__ import annotations
+
+from .dashboard import Dashboard, DashboardCollection
+from .datasource import Datasource, DatasourceCollection
+from .fields import (
+    CalcFieldCollection,
+    CalculatedField,
+    Field,
+    FieldCollection,
+    FieldReference,
+    Parameter,
+)
+from .workbook import Workbook
+from .worksheet import MarkCard, Shelf, Worksheet, WorksheetCollection
+
+__all__ = [
+    "Workbook",
+    "Datasource",
+    "DatasourceCollection",
+    "Dashboard",
+    "DashboardCollection",
+    "Worksheet",
+    "WorksheetCollection",
+    "Field",
+    "FieldCollection",
+    "CalcFieldCollection",
+    "CalculatedField",
+    "FieldReference",
+    "Parameter",
+    "MarkCard",
+    "Shelf",
+]