tableau_tools Python Library

You can manage permissions for projects, workbooks, and datasources using Permissions objects. To avoid manual configuration, you can create a permissions object for a group or user and then reuse or transform it using copy methods.

Reusing Permissions

If you have a Permissions object and want to apply similar settings to a different group or user, use these methods on a PublishedContent instance (often a Project object):

• PublishedContent.copy_permissions_obj_for_group(perms_obj, group_name_or_luid): Creates a new object for a different group.
• PublishedContent.copy_permissions_obj_for_user(perms_obj, username_or_luid): Creates a new object for a specific user.

Applying Permissions

Use set_permissions or set_permissions_by_permissions_obj_list to apply these objects to a project or its defaults.

# Create a base permissions object for a group
best_group_perms_obj = proj.create_datasource_permissions_object_for_group('Best Group', role='Editor')

# Reuse it for a second group
second_best_group_perms_obj = proj.copy_permissions_obj_for_group(best_group_perms_obj, 'Second Best Group')

# Transform it for a specific user
my_user_perms_obj = proj.copy_permissions_obj_for_user(second_best_group_perms_obj, 'My User Name')

# Apply the list of permissions to the project
proj.clear_all_permissions()
proj.set_permissiosn_by_permissions_obj_list([best_group_perms_obj, second_best_group_perms_obj, my_user_perms_obj])

The TableauServerRest object is the primary entry point for the library. It is a composite object that exposes various 'endpoint' methods (like .projects, .workbooks, .users, etc.) for interacting with Tableau Server.

Key architectural details:

• Endpoint Classes: Methods are organized into classes based on the Tableau REST API endpoint (e.g., GroupMethods, UserMethods). These classes do not represent data objects themselves but are collections of methods.
• Inheritance: TableauServerRest inherits from TableauRestApiBase, which contains the core logic for connection management, basic REST API actions, and LUID lookups.
• Endpoint Initialization: When you create a TableauServerRest instance, all sub-objects (endpoints) are instantiated and passed a reference to the main TableauServerRest object via self.rest. This allows endpoint methods to access shared connection details and base methods.

The TableauDatasource class is the core of the library. It encapsulates a <datasource> XML element and provides access to its internal components:

• TableauConnection: Represents the <connection> element. It contains properties related to the native Tableau connector. You can access raw XML attributes using connection.xml_obj.get('property-name') or set them using connection.xml_obj.set('property-name', 'value').
• TableauColumn: Represents fields (either <col> or <column> elements). You can modify names, datatypes, and other properties. The TableauColumns container provides get_column_by_name() which searches both the name and the alias.
• TableTableRelations: Encapsulates the original Tableau JOIN paradigm. Note that this does not support the newer Tableau 'Relationships' model introduced in version 2020.2.

Important Implementation Detail: All component classes (TableauConnection, TableauColumn, etc.) hold an internal self.xml_obj that references a specific part of the parent TableauDatasource.xml object. Because these are all part of the same underlying ElementTree structure, changes made to a column or connection are automatically reflected in the parent datasource when it is saved.

In tableau_tools 6.0+, the tableau_rest_api sub-package uses TableauServerRest classes to organize methods into logical sub-objects (e.g., t.groups.create_group() instead of t.create_group()).

Key behaviors:

• Method Organization: Basic functionalities (like signin() or LUID lookups) remain on the base object, but most actions are grouped into sub-objects (e.g., projects, users, groups).
• API Versioning: You can target specific Tableau Server API versions by instantiating versioned classes. For example, TableauServerRest311 targets API Version 3.11 (Tableau Server 2021.1).
• Legacy Compatibility: Older versions (4.0 series) used TableauRestApiConnection, which placed all methods directly on the main object. Modern TableauServerRest objects are more organized but require using the correct sub-object.

# Example: Using a specific API version (3.6 / 2019.4)
t = TableauServerRest36(server="http://127.0.0.1", pat_name="my_pat", pat_secret="my_secret", site_content_url="my_site")

# Accessing methods via sub-objects
t.projects.update_project(project_id="...")

# Basic methods remain on the base object
t.signin()

The tableau_documents module is designed to modify existing Tableau XML files (TWB, TDS, TWBX, TDSX). It uses a factory pattern via TableauFileManager to return the appropriate object type based on the file extension.

Key abstractions include:

• DatasourceFileInterface: The primary entry point for XML modification, providing a .datasources() method that returns a list of TableauDatasource objects.
• TableauXmlFile: Handles converting in-memory XML objects back into string XML for saving to disk via the .tableau_document property.
• TableauPackagedFile: Manages ZIP-based files (TWBX, TDSX). It allows access to the internal XML via .tableau_xml_file and handles the complex process of repackaging files (including substituting new Hyper files) when saving.

Note on Memory and Scope: To minimize memory usage, especially for large TWB files, the library only loads the <datasources> section into memory. Consequently, you can only modify datasource properties; you cannot access or change other XML elements in the workbook.

from tableau_documents import TableauFileManager

# TableauFileManager acts as a factory
file_obj = TableauFileManager('path/to/my_workbook.twbx')

# Access datasources via the DatasourceFileInterface
for ds in file_obj.datasources():
    # Perform modifications
    pass

file_obj.save_new_file('path/to/new_workbook.twbx')