#72 Add description to the field object (#73)

* Add description to the field object

Pull in the description if it exists on a `<column>` tag.
This change returns the entire `<desc>` tag including all subtags.
e.g.:

```
<desc>
  <formatted-text>
    <run>Total number of people in a country</run>
  </formatted-text>
</desc>
```

* improving the test code to use 'in'

Author: Russell Hay

Examples/GetFields/show_fields.py

@@ -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('')

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 = [
@@ -164,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)
@@ -184,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

test/assets/datasource_test.tds

@@ -75,7 +75,14 @@
   <column datatype='integer' name='[Number of Records]' role='measure' type='quantitative' user:auto-column='numrec'>
     <calculation class='tableau' formula='1' />
   </column>
-  <column caption='A' datatype='string' name='[a]' role='dimension' type='nominal' />
+  <column caption='A' datatype='string' name='[a]' role='dimension' type='nominal'>
+    <desc>
+      <formatted-text>
+        <run bold='true' fontsize='96'>A thing</run>
+        <run fontcolor='#686868'>&#10;Something will go here too, in a muted gray</run>
+      </formatted-text>
+    </desc>
+  </column>
   <column caption='Today&apos;s Date' datatype='string' name='[Today&apos;s Date]' role='dimension' type='nominal' />
   <column caption='X' datatype='integer' name='[x]' role='measure' type='ordinal' />
   <column caption='Y' datatype='integer' name='[y]' role='measure' type='quantitative' />

test/test_datasource.py

@@ -58,6 +58,11 @@ def test_datasource_field_datatype(self):
     def test_datasource_field_role(self):
         self.assertEqual(self.ds.fields['[x]'].role, 'measure')
 
+    def test_datasource_field_description(self):
+        actual = self.ds.fields['[a]'].description
+        self.assertIsNotNone(actual)
+        self.assertTrue(u'muted gray' in actual)
+
 
 class DataSourceFieldsTWB(unittest.TestCase):