Merge pull request #78 from tableau/development

Release 0.3

.travis.yml

@@ -16,7 +16,7 @@ script:
   # pep8
   - pep8 .
   # Examples
-  - (cd "Examples/Replicate Workbook" && python replicateWorkbook.py)
-  - (cd "Examples/List TDS Info" && python listTDSInfo.py)
-  - (cd "Examples/GetFields" && python show_fields.py)
+  - (cd "samples/replicate-workbook" && python replicate_workbook.py)
+  - (cd "samples/list-tds-info" && python list_tds_info.py)
+  - (cd "samples/show-fields" && python show_fields.py)
 

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.3 (31 August 2016)
+
+* Added basic connection class retargeting (#65)
+* Added ability to create a new connection (#69)
+* Added description to the field object (#73)
+* Improved Test Coverage (#62, #67)
+
 ## 0.2 (22 July 2016)
 
 * Added support for loading twbx and tdsx files (#43, #44)

Examples/List TDS Info/listTDSInfo.py → samples/list-tds-info/list_tds_info.py

@@ -6,7 +6,7 @@
 ############################################################
 # Step 2)  Open the .tds we want to replicate
 ############################################################
-sourceTDS = Datasource.from_file('World.tds')
+sourceTDS = Datasource.from_file('world.tds')
 
 ############################################################
 # Step 3)  List out info from the TDS

Examples/Replicate Workbook/replicateWorkbook.py → samples/replicate-workbook/replicate_workbook.py

@@ -8,7 +8,7 @@
 ############################################################
 # Step 2)  Open the .twb we want to replicate
 ############################################################
-sourceWB = Workbook('Sample - Superstore.twb')
+sourceWB = Workbook('sample-superstore.twb')
 
 ############################################################
 # Step 3)  Use a database list (in CSV), loop thru and

Examples/GetFields/show_fields.py → samples/show-fields/show_fields.py

@@ -6,7 +6,7 @@
 ############################################################
 # Step 2)  Open the .tds we want to inspect
 ############################################################
-sourceTDS = Datasource.from_file('World.tds')
+sourceTDS = Datasource.from_file('world.tds')
 
 ############################################################
 # Step 3)  Print out all of the fields and what type they are
@@ -23,6 +23,8 @@
     if field.default_aggregation:
         print('      the default aggregation is {}'.format(field.default_aggregation))
         blank_line = True
+    if field.description:
+        print('      the description is {}'.format(field.description))
 
     if blank_line:
         print('')

samples/show-fields/world.tds

@@ -0,0 +1 @@
+../list-tds-info/world.tds

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name='tableaudocumentapi',
-    version='0.2',
+    version='0.3',
     author='Tableau Software',
     author_email='[email protected]',
     url='https://github.com/tableau/document-api-python',

tableaudocumentapi/connection.py

@@ -3,6 +3,8 @@
 # Connection - A class for writing connections to Tableau files
 #
 ###############################################################################
+import xml.etree.ElementTree as ET
+from tableaudocumentapi.dbclass import is_valid_dbclass
 
 
 class Connection(object):
@@ -32,6 +34,17 @@ def __init__(self, connxml):
     def __repr__(self):
         return "'<Connection server='{}' dbname='{}' @ {}>'".format(self._server, self._dbname, hex(id(self)))
 
+    @classmethod
+    def from_attributes(cls, server, dbname, username, dbclass, authentication=''):
+        root = ET.Element('connection', authentication=authentication)
+        xml = cls(root)
+        xml.server = server
+        xml.dbname = dbname
+        xml.username = username
+        xml.dbclass = dbclass
+
+        return xml
+
     ###########
     # dbname
     ###########
@@ -111,3 +124,12 @@ def authentication(self):
     @property
     def dbclass(self):
         return self._class
+
+    @dbclass.setter
+    def dbclass(self, value):
+
+        if not is_valid_dbclass(value):
+            raise AttributeError("'{}' is not a valid database type".format(value))
+
+        self._class = value
+        self._connectionXML.set('class', value)

tableaudocumentapi/datasource.py

@@ -5,8 +5,10 @@
 ###############################################################################
 import collections
 import itertools
+import random
 import xml.etree.ElementTree as ET
 import xml.sax.saxutils as sax
+from uuid import uuid4
 
 from tableaudocumentapi import Connection, xfile
 from tableaudocumentapi import Field
@@ -19,7 +21,7 @@
 # dropped, remove this and change the basestring references below to str
 try:
     basestring
-except NameError:
+except NameError:  # pragma: no cover
     basestring = str
 ########
 
@@ -38,6 +40,7 @@ def _is_used_by_worksheet(names, field):
 
 
 class FieldDictionary(MultiLookupDict):
+
     def used_by_sheet(self, name):
         # If we pass in a string, no need to get complicated, just check to see if name is in
         # the field's list of worksheets
@@ -63,7 +66,36 @@ def _column_object_from_metadata_xml(metadata_xml):
     return _ColumnObjectReturnTuple(field_object.id, field_object)
 
 
+def base36encode(number):
+    """Converts an integer into a base36 string."""
+
+    ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+    base36 = ''
+    sign = ''
+
+    if number < 0:
+        sign = '-'
+        number = -number
+
+    if 0 <= number < len(ALPHABET):
+        return sign + ALPHABET[number]
+
+    while number != 0:
+        number, i = divmod(number, len(ALPHABET))
+        base36 = ALPHABET[i] + base36
+
+    return sign + base36
+
+
+def make_unique_name(dbclass):
+    rand_part = base36encode(uuid4().int)
+    name = dbclass + '.' + rand_part
+    return name
+
+
 class ConnectionParser(object):
+
     def __init__(self, datasource_xml, version):
         self._dsxml = datasource_xml
         self._dsversion = version
@@ -113,9 +145,23 @@ def __init__(self, dsxml, filename=None):
     def from_file(cls, filename):
         """Initialize datasource from file (.tds)"""
 
-        dsxml = xml_open(filename).getroot()
+        dsxml = xml_open(filename, cls.__name__.lower()).getroot()
         return cls(dsxml, filename)
 
+    @classmethod
+    def from_connections(cls, caption, connections):
+        root = ET.Element('datasource', caption=caption, version='10.0', inline='true')
+        outer_connection = ET.SubElement(root, 'connection')
+        outer_connection.set('class', 'federated')
+        named_conns = ET.SubElement(outer_connection, 'named-connections')
+        for conn in connections:
+            nc = ET.SubElement(named_conns,
+                               'named-connection',
+                               name=make_unique_name(conn.dbclass),
+                               caption=conn.server)
+            nc.append(conn._connectionXML)
+        return cls(root)
+
     def save(self):
         """
         Call finalization code and save file.
@@ -143,6 +189,7 @@ def save_as(self, new_filename):
             Nothing.
 
         """
+
         xfile._save_file(self._filename, self._datasourceTree, new_filename)
 
     ###########

tableaudocumentapi/dbclass.py

@@ -0,0 +1,60 @@
+
+
+KNOWN_DB_CLASSES = ('msaccess',
+                    'msolap',
+                    'bigquery',
+                    'asterncluster',
+                    'bigsql',
+                    'aurora',
+                    'awshadoophive',
+                    'dataengine',
+                    'DataStax',
+                    'db2',
+                    'essbase',
+                    'exasolution',
+                    'excel',
+                    'excel-direct',
+                    'excel-reader',
+                    'firebird',
+                    'powerpivot',
+                    'genericodbc',
+                    'google-analytics',
+                    'googlecloudsql',
+                    'google-sheets',
+                    'greenplum',
+                    'saphana',
+                    'hadoophive',
+                    'hortonworkshadoophive',
+                    'maprhadoophive',
+                    'marklogic',
+                    'memsql',
+                    'mysql',
+                    'netezza',
+                    'oracle',
+                    'paraccel',
+                    'postgres',
+                    'progressopenedge',
+                    'redshift',
+                    'snowflake',
+                    'spark',
+                    'splunk',
+                    'kognitio',
+                    'sqlserver',
+                    'salesforce',
+                    'sapbw',
+                    'sybasease',
+                    'sybaseiq',
+                    'tbio',
+                    'teradata',
+                    'vectorwise',
+                    'vertica',
+                    'denormalized-cube',
+                    'csv',
+                    'textscan',
+                    'webdata',
+                    'webdata-direct',
+                    'cubeextract')
+
+
+def is_valid_dbclass(dbclass):
+    return dbclass in KNOWN_DB_CLASSES

tableaudocumentapi/field.py

@@ -1,4 +1,6 @@
 import functools
+import xml.etree.ElementTree as ET
+
 
 _ATTRIBUTES = [
     'id',           # Name of the field as specified in the file, usually surrounded by [ ]
@@ -8,6 +10,7 @@
     'type',         # three possible values: quantitative, ordinal, or nominal
     'alias',        # Name of the field as displayed in Tableau if the default name isn't wanted
     'calculation',  # If this field is a calculated field, this will be the formula
+    'description',  # If this field has a description, this will be the description (including formatting tags)
 ]
 
 _METADATA_ATTRIBUTES = [
@@ -42,8 +45,10 @@ def __init__(self, column_xml=None, metadata_xml=None):
 
         if column_xml is not None:
             self._initialize_from_column_xml(column_xml)
-            if metadata_xml is not None:
-                self.apply_metadata(metadata_xml)
+            # This isn't currently never called because of the way we get the data from the xml,
+            # but during the refactor, we might need it.  This is commented out as a reminder
+            # if metadata_xml is not None:
+            #     self.apply_metadata(metadata_xml)
 
         elif metadata_xml is not None:
             self._initialize_from_metadata_xml(metadata_xml)
@@ -162,6 +167,11 @@ def default_aggregation(self):
         """ The default type of aggregation on the field (e.g Sum, Avg)"""
         return self._aggregation
 
+    @property
+    def description(self):
+        """ The contents of the <desc> tag on a field """
+        return self._description
+
     @property
     def worksheets(self):
         return list(self._worksheets)
@@ -182,3 +192,11 @@ def _read_calculation(xmldata):
             return None
 
         return calc.attrib.get('formula', None)
+
+    @staticmethod
+    def _read_description(xmldata):
+        description = xmldata.find('.//desc')
+        if description is None:
+            return None
+
+        return u'{}'.format(ET.tostring(description, encoding='utf-8'))  # This is necessary for py3 support

tableaudocumentapi/multilookup_dict.py

@@ -13,6 +13,7 @@ def _resolve_value(key, value):
         if retval is None:
             retval = getattr(value, key, None)
     except AttributeError:
+        # We should never hit this.
         retval = None
     return retval
 
@@ -39,15 +40,18 @@ def _populate_indexes(self):
         self._indexes['alias'] = _build_index('alias', self)
         self._indexes['caption'] = _build_index('caption', self)
 
+    def _get_real_key(self, key):
+        if key in self._indexes['alias']:
+            return self._indexes['alias'][key]
+        if key in self._indexes['caption']:
+            return self._indexes['caption'][key]
+
+        return key
+
     def __setitem__(self, key, value):
-        alias = _resolve_value('alias', value)
-        caption = _resolve_value('caption', value)
-        if alias is not None:
-            self._indexes['alias'][alias] = key
-        if caption is not None:
-            self._indexes['caption'][caption] = key
+        real_key = self._get_real_key(key)
 
-        dict.__setitem__(self, key, value)
+        dict.__setitem__(self, real_key, value)
 
     def get(self, key, default_value=_no_default_value):
         try:
@@ -58,9 +62,5 @@ def get(self, key, default_value=_no_default_value):
             raise
 
     def __getitem__(self, key):
-        if key in self._indexes['alias']:
-            key = self._indexes['alias'][key]
-        elif key in self._indexes['caption']:
-            key = self._indexes['caption'][key]
-
-        return dict.__getitem__(self, key)
+        real_key = self._get_real_key(key)
+        return dict.__getitem__(self, real_key)

tableaudocumentapi/workbook.py

@@ -32,7 +32,7 @@ def __init__(self, filename):
 
         self._filename = filename
 
-        self._workbookTree = xml_open(self._filename)
+        self._workbookTree = xml_open(self._filename, self.__class__.__name__.lower())
 
         self._workbookRoot = self._workbookTree.getroot()
         # prepare our datasource objects