Added the ability to create and modify fields, including aliases and …

tableaudocumentapi/datasource.py

@@ -262,14 +262,14 @@ def _get_column_objects(self):
         return [_column_object_from_column_xml(self._datasourceTree, xml)
                 for xml in self._datasourceTree.findall('.//column')]
 
-    def add_field(self, name, datatype, role, type, caption):
+    def add_field(self, name, datatype, role, field_type, caption):
         """ Adds a base field object with the given values.
 
         Args:
             name: Name of the new Field. String.
             datatype:  Datatype of the new field. String.
             role:  Role of the new field. String.
-            type:  Type of the new field. String.
+            field_type:  Type of the new field. String.
             caption:  Caption of the new field. String.
 
         Returns:
@@ -284,12 +284,7 @@ def add_field(self, name, datatype, role, type, caption):
             caption = name.replace('[', '').replace(']', '').title()
 
         # Create the elements
-        column = ET.Element('column')
-        column.set('caption', caption)
-        column.set('datatype', datatype)
-        column.set('role', role)
-        column.set('type', type)
-        column.set('name', name)
+        column = xfile.create_column(caption, datatype, role, field_type, name)
 
         self._datasourceTree.getroot().append(column)
 
@@ -319,8 +314,6 @@ def remove_field(self, field):
     def calculations(self):
         """ Returns all calculated fields.
         """
-        # TODO: There is a default [Number of Records] calculation.
-        # Should this be excluded so users can't meddle with it?
         return {k: v for k, v in self.fields.items() if v.calculation is not None}
 
     def add_calculation(self, caption, formula, datatype, role, type):

tableaudocumentapi/field.py

@@ -1,6 +1,7 @@
 import functools
 import xml.etree.ElementTree as ET
-from functools import wraps
+
+from tableaudocumentapi.property_decorators import argument_is_one_of
 
 _ATTRIBUTES = [
     'id',           # Name of the field as specified in the file, usually surrounded by [ ]
@@ -24,21 +25,6 @@
 ]
 
 
-def argument_is_one_of(*allowed_values):
-    def property_type_decorator(func):
-        @wraps(func)
-        def wrapper(self, value):
-            if value not in allowed_values:
-                error = "Invalid argument: {0}. {1} must be one of {2}."
-                msg = error.format(value, func.__name__, allowed_values)
-                raise ValueError(error)
-            return func(self, value)
-
-        return wrapper
-
-    return property_type_decorator
-
-
 def _find_metadata_record(record, attrib):
     element = record.find('.//{}'.format(attrib))
     if element is None:
@@ -58,8 +44,6 @@ def __init__(self, column_xml=None, metadata_xml=None):
             setattr(self, '_{}'.format(attrib), None)
         self._worksheets = set()
 
-        self._xml = None
-
         if column_xml is not None:
             self._initialize_from_column_xml(column_xml)
             self._xml = column_xml
@@ -225,17 +209,17 @@ def type(self):
 
     @type.setter
     @argument_is_one_of('quantitative', 'ordinal', 'nominal')
-    def type(self, type):
+    def type(self, field_type):
         """ Set the type of a field
 
             Args:
-                type:  New type. String.
+                field_type:  New type. String.
 
             Returns:
                 Nothing.
         """
-        self._type = type
-        self._xml.set('type', type)
+        self._type = field_type
+        self._xml.set('type', field_type)
 
     ########################################
     # Aliases getter and setter

tableaudocumentapi/property_decorators.py

@@ -0,0 +1,15 @@
+from functools import wraps
+
+def argument_is_one_of(*allowed_values):
+    def property_type_decorator(func):
+        @wraps(func)
+        def wrapper(self, value):
+            if value not in allowed_values:
+                error = "Invalid argument: {0}. {1} must be one of {2}."
+                msg = error.format(value, func.__name__, allowed_values)
+                raise ValueError(error)
+            return func(self, value)
+
+        return wrapper
+
+    return property_type_decorator

tableaudocumentapi/xfile.py

@@ -70,6 +70,16 @@ def get_xml_from_archive(filename):
     return xml_tree
 
 
+def create_column(caption, datatype, role, field_type, name):
+    column = ET.Element('column')
+    column.set('caption', caption)
+    column.set('datatype', datatype)
+    column.set('role', role)
+    column.set('type', field_type)
+    column.set('name', name)
+    return column
+
+
 def build_archive_file(archive_contents, zip_file):
     for root_dir, _, files in os.walk(archive_contents):
         relative_dir = os.path.relpath(root_dir, archive_contents)

test/test_field_change.py

@@ -63,11 +63,31 @@ def current_hash(self):
         """
         return hash(ET.tostring(self.tds._datasourceTree.getroot()))
 
+    def check_state_change(self, should_change, msg, field_name):
+        """ Check whether the XML has changed and update the current state.
+
+            Args:
+                should_change: Whether the XML is supposed to have changed or not. Boolean.
+                msg: The message to be displayed in an error case, as key for the MESSAGES dict. String.
+                field_name: The field name that will be displayed in the error message. String.
+
+            Returns:
+                Nothing.
+        """
+        new_state = self.current_hash()
+        compare_func = self.assertNotEqual if should_change else self.assertEqual
+        compare_func(
+            self.state,
+            new_state,
+            msg=MESSAGES[msg].format(field_name)
+        )
+        self.state = new_state
+
     def test_change_values(self):
         """ Test if the value changes of a field are reflected in the object and in the underlying XML structure.
         """
         field_to_test = "[amount]"
-        state = self.current_hash()
+        self.state = self.current_hash()
         # change all fields
         for key, value in NEW_VALUES.items():
             setattr(self.tds.fields[field_to_test], key, value)
@@ -78,19 +98,13 @@ def test_change_values(self):
                 msg=MESSAGES['test_change_values1'].format(key)
             )
             # the new value must be reflected in the xml
-            new_state = self.current_hash()
-            self.assertNotEqual(
-                state,
-                new_state,
-                msg=MESSAGES['test_change_values2'].format(key)
-            )
-            state = new_state
+            self.check_state_change(True, 'test_change_values2', key)
 
     def test_change_values_fail(self):
         """ Test if the value changes of a field are rejected if the wrong arguments are passed.
         """
         field_to_test = "[amount]"
-        state = self.current_hash()
+        self.state = self.current_hash()
         # change all fields
         for key, value in WRONG_VALUES.items():
 
@@ -104,42 +118,29 @@ def test_change_values_fail(self):
                 value,
                 msg=MESSAGES['test_change_valuesFail1'].format(key)
             )
-
             # the new value must NOT be reflected in the xml
-            new_state = self.current_hash()
-            self.assertEqual(
-                state,
-                new_state,
-                msg=MESSAGES['test_change_valuesFail2'].format(key)
-            )
-            state = new_state
+            self.check_state_change(False, 'test_change_valuesFail2', key)
 
     def test_remove_field(self):
         """ Test if a Field can be removed.
         """
         field_to_test = "[amount]"
-        state = self.current_hash()
+        self.state = self.current_hash()
         # change all fields
         field = self.tds.fields["[amount]"]
         self.tds.remove_field(field)
-        self.assertNotEqual(state, self.current_hash())
+        self.assertNotEqual(self.state, self.current_hash())
 
     def test_change_aliases(self):
         """ Test if the alias changes of a field are reflected in the object and in the underlying XML structure.
         """
         field_to_test = "[amount]"
-        state = self.current_hash()
+        self.state = self.current_hash()
         # change all fields
         for key, value in ALIASES.items():
             self.tds.fields[field_to_test].add_alias(key, value)
             # the new value must be reflected in the xml
-            new_state = self.current_hash()
-            self.assertNotEqual(
-                state,
-                new_state,
-                msg=MESSAGES['test_change_aliases1'].format(field_to_test)
-            )
-            state = new_state
+            self.check_state_change(True, 'test_change_aliases1', field_to_test)
 
         # check whether all fields of ALIASES have been applied
         self.assertEqual(
@@ -165,7 +166,7 @@ def test_calculation_base(self):
     def test_calculation_change(self):
         """ Test whether changing calculations of a field works.
         """
-        state = self.current_hash()
+        self.state = self.current_hash()
         new_calc = '33 * 44'
         fld_name = '[Calculation_357754699576291328]'
         self.tds.calculations[fld_name].calculation = new_calc
@@ -175,7 +176,7 @@ def test_calculation_change(self):
 
         # Check XML representation
         new_state = self.current_hash()
-        self.assertNotEqual(state, new_state)
+        self.assertNotEqual(self.state, new_state)
 
     def test_calculation_new(self):
         """ Test if creating a new calculation works.