Tableau Document API

The Tableau Document API is a Python SDK designed to programmatically update Tableau workbook (.twb, .twbx) and data source (.tds, .tdsx) files. It serves as a safer alternative to manual XML manipulation ('XML hacking').

Key Capabilities:

• File Support: Works with .twb, .twbx, .tds, and .tdsx files (dating back to Tableau 9.x).
• Connection Inspection: Extract connection details including Server Name, Username, Database Name, Authentication Type, and Connection Type.
• Connection Updates: Programmatically update Server Name, Username, and Database Name within workbooks and data sources.
• Field Inspection: Retrieve all fields in a data source or identify fields currently in use by specific sheets within a workbook.

Limitations:

• It cannot create files from scratch.
• It cannot add extracts into workbooks or data sources.
• It cannot update field information.
• It does not support .hyper files (use the Tableau Hyper API instead).
• It no longer supports Python 2 (Python 3+ required).

The Tableau Document API Python SDK provides a programmatic way to update Tableau workbook (.twb, .twbx) and data source (.tds, .tdsx) files. It is designed as an alternative to manual 'XML hacking' for modifying file contents.

Key Capabilities:

• File Support: Works with .twb, .twbx, .tds, and .tdsx files (dating back to Tableau 9.x).
• Connection Inspection: Retrieve connection details including Server Name, Username, Database Name, Authentication Type, and Connection Type.
• Connection Updates: Programmatically update Server Name, Username, and Database Name.
• Field Inspection: Retrieve all fields in a data source or identify fields used by specific sheets within a workbook.

Limitations:

• Does not support creating files from scratch.
• Does not support adding extracts into workbooks or data sources.
• Does not support updating field information.
• For working with .hyper files, use the Tableau Hyper API instead.

To contribute to the project, follow the 'Fork and Pull' model.

1. Prerequisites: Ensure you have signed the CLA.
2. Setup: Fork the repository and clone your fork locally.
3. Branching: Always check out the development branch before creating a new feature or fix branch. Use the naming convention issue#-type-description (e.g., 13-feature-new-stuff).
4. Coding Standards:
   • Use 4-space indentation.
   • Use Unix line endings.
   • Follow PEP8 style guides. You can verify this by running pycodestyle . in the repository root.
   • Keep commit messages clean and descriptive (they will be squashed into a single commit upon merge).
5. Testing: Add new tests to the test/ folder. If your test requires static files (like .twb or .twbx files), place them in test/assets/.
6. Documentation: Documentation is written in Markdown and located in docs/docs. For simple typo fixes or wording improvements, you can use the GitHub UI 'Edit this file' feature.

# Clone your fork
git clone http://github.com/<your_username>/document-api-python

# Switch to the development branch
git checkout development

# Create a new branch for your work
git checkout -b 13-feature-new-stuff

The Workbook class is the primary entry point for interacting with Tableau workbook files (.twb or .twbx). The library automatically handles the packaging and unpackaging of .twbx files.

Initialization: Pass the path to the workbook file as a string to the constructor.

Common Operations:

• Save changes to the original file using .save().
• Save changes to a new file using .save_as(new_filename).

Available Properties:

• worksheets: List of worksheets in the workbook.
• datasources: List of Datasource objects.
• filename: The path to the workbook.
• shapes: List of shape names.
• dashboards: List of dashboard names.

Exceptions:

• TableauVersionNotSupportedException: Raised if the workbook version is not supported.
• TableauInvalidFileException: Raised if the file is not a valid Tableau workbook.

workbook = Workbook("path/to/my_workbook.twbx")
# ... perform modifications ...
workbook.save_as("path/to/new_workbook.twbx")

The Datasource class represents Tableau Data Sources, which can be embedded within a workbook or exist as standalone .tds files.

Methods:

• save(): Saves changes to the existing file.
• save_as(new_filename): Saves changes to a new file.
• add_field(name, datatype, role, field_type, caption, hidden): Adds a new base field object.
• remove_field(field): Removes a specific field.
• add_calculation(caption, formula, datatype, role, type, hidden): Adds a calculated field.

Properties:

• name: The name of the datasource.
• version: The datasource version string.
• caption: The user-defined name (if it exists).
• connections: A list of connections used by this datasource.
• fields: A dictionary-like result mapping field names to their attributes.
• calculations: A list of calculated fields in the datasource.

# Example: Adding a calculation to a datasource
datasource.add_calculation(
    caption="Profit Ratio",
    formula="SUM([Profit]) / SUM([Sales])",
    datatype="float",
    role="measure",
    type="quantitative",
    hidden=False
)