tbl: rewrite Table.style getter

* Add descriptive __repr__() for _TableStyle, otherwise it inherits the
  one from _ParagraphStyle.
* Rewrite portions of api-add-table.feature to work with new style
  interface.

Author: Steve Canny

docx/oxml/table.py

@@ -59,6 +59,13 @@ class CT_Tbl(BaseOxmlElement):
     tblGrid = OneAndOnlyOne('w:tblGrid')
     tr = ZeroOrMore('w:tr')
 
+    @property
+    def col_count(self):
+        """
+        The number of grid columns in this table.
+        """
+        return len(self.tblGrid.gridCol_lst)
+
     def iter_tcs(self):
         """
         Generate each of the `w:tc` elements in this table, left to right and
@@ -79,11 +86,15 @@ def new(cls):
         return tbl
 
     @property
-    def col_count(self):
+    def tblStyle_val(self):
         """
-        The number of grid columns in this table.
+        Value of `w:tblPr/w:tblStyle/@w:val` (a table style id) or |None| if
+        not present.
         """
-        return len(self.tblGrid.gridCol_lst)
+        tblStyle = self.tblPr.tblStyle
+        if tblStyle is None:
+            return None
+        return tblStyle.val
 
     @classmethod
     def _tbl_xml(cls):

docx/styles/style.py

@@ -253,6 +253,9 @@ class _TableStyle(_ParagraphStyle):
 
     __slots__ = ()
 
+    def __repr__(self):
+        return '_TableStyle(\'%s\') id: %s' % (self.name, id(self))
+
 
 class _NumberingStyle(BaseStyle):
     """

docx/table.py

@@ -7,6 +7,7 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 from .blkcntnr import BlockItemContainer
+from .enum.style import WD_STYLE_TYPE
 from .oxml.simpletypes import ST_Merge
 from .shared import lazyproperty, Parented
 
@@ -110,11 +111,18 @@ def rows(self):
     @property
     def style(self):
         """
-        String name of style to be applied to this table, e.g.
-        'LightShading-Accent1'. Name is derived by removing spaces from the
-        table style name displayed in the Word UI.
-        """
-        return self._tblPr.style
+        Read/write. A |_TableStyle| object representing the style applied to
+        this table. The default table style for the document (often `Normal
+        Table`) is returned if the table has no directly-applied style.
+        Assigning |None| to this property removes any directly-applied table
+        style causing it to inherit the default table style of the document.
+        Note that the style name of a table style differs slightly from that
+        displayed in the user interface; a hyphen, if it appears, must be
+        removed. For example, `Light Shading - Accent 1` becomes `Light
+        Shading Accent 1`.
+        """
+        style_id = self._tbl.tblStyle_val
+        return self.part.get_style(style_id, WD_STYLE_TYPE.TABLE)
 
     @style.setter
     def style(self, value):

features/api-add-table.feature

@@ -3,14 +3,17 @@ Feature: Add a table
   As a programmer using the basic python-docx API
   I need a method that adds a table at the end of the document
 
+
   Scenario: Add a table specifying only row and column count
     Given a document
      When I add a 2 x 2 table specifying only row and column count
      Then the document contains a 2 x 2 table
-      And the table style is 'LightShading-Accent1'
+      And table.style is styles['Light Shading Accent 1']
+
 
+  @wip
   Scenario: Add a table specifying style
     Given a document
-     When I add a 2 x 2 table specifying style 'foobar'
+     When I add a 2 x 2 table specifying style 'Table Grid'
      Then the document contains a 2 x 2 table
-      And the table style is 'foobar'
+      And table.style is styles['Table Grid']

features/steps/api.py

@@ -20,10 +20,10 @@ def when_add_2x2_table_specifying_only_row_and_col_count(context):
     document.add_table(rows=2, cols=2)
 
 
-@when('I add a 2 x 2 table specifying style \'foobar\'')
-def when_add_2x2_table_specifying_style_foobar(context):
+@when('I add a 2 x 2 table specifying style \'{style_name}\'')
+def when_add_2x2_table_specifying_style_name(context, style_name):
     document = context.document
-    document.add_table(rows=2, cols=2, style='foobar')
+    document.add_table(rows=2, cols=2, style=style_name)
 
 
 @when('I add a heading specifying level={level_str}')
@@ -159,9 +159,3 @@ def then_the_style_of_the_last_paragraph_is_style(context, style_name):
     assert paragraph.style.name == style_name, (
         'got %s' % paragraph.style.name
     )
-
-
-@then('the table style is \'{style}\'')
-def then_table_style_is_style(context, style):
-    table = context.table_
-    assert table.style == style

features/tbl-style.feature

@@ -4,7 +4,6 @@ Feature: Query and apply a table style
   I need the ability to get and set the style of a table
 
 
-  @wip
   Scenario Outline: Get the style of a table
     Given a table having <style> style
      Then table.style is styles['<value>']

tests/test_table.py

@@ -8,9 +8,11 @@
 
 import pytest
 
+from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.table import WD_TABLE_ALIGNMENT
 from docx.oxml import parse_xml
 from docx.oxml.table import CT_Tc
+from docx.parts.document import DocumentPart
 from docx.shared import Inches
 from docx.table import _Cell, _Column, _Columns, _Row, _Rows, Table
 from docx.text.paragraph import Paragraph
@@ -42,9 +44,13 @@ def it_can_change_its_autofit_setting(self, autofit_set_fixture):
         table.autofit = new_value
         assert table._tbl.xml == expected_xml
 
-    def it_knows_its_table_style(self, table_style_get_fixture):
-        table, style = table_style_get_fixture
-        assert table.style == style
+    def it_knows_its_table_style(self, style_get_fixture):
+        table, style_id_, style_ = style_get_fixture
+        style = table.style
+        table.part.get_style.assert_called_once_with(
+            style_id_, WD_STYLE_TYPE.TABLE
+        )
+        assert style is style_
 
     def it_can_apply_a_table_style_by_name(self, table_style_set_fixture):
         table, style_name, expected_xml = table_style_set_fixture
@@ -219,20 +225,19 @@ def row_cells_fixture(self, _cells_, _column_count_):
         expected_cells = [3, 4, 5]
         return table, row_idx, expected_cells
 
+    @pytest.fixture
+    def style_get_fixture(self, part_prop_):
+        style_id = 'Barbaz'
+        tbl_cxml = 'w:tbl/w:tblPr/w:tblStyle{w:val=%s}' % style_id
+        table = Table(element(tbl_cxml), None)
+        style_ = part_prop_.return_value.get_style.return_value
+        return table, style_id, style_
+
     @pytest.fixture
     def table_fixture(self):
         table = Table(None, None)
         return table
 
-    @pytest.fixture(params=[
-        ('w:tbl/w:tblPr', None),
-        ('w:tbl/w:tblPr/w:tblStyle{w:val=foobar}', 'foobar'),
-    ])
-    def table_style_get_fixture(self, request):
-        tbl_cxml, expected_style = request.param
-        table = Table(element(tbl_cxml), None)
-        return table, expected_style
-
     @pytest.fixture(params=[
         ('w:tbl/w:tblPr', 'foobar',
          'w:tbl/w:tblPr/w:tblStyle{w:val=foobar}'),
@@ -259,6 +264,16 @@ def _cells_(self, request):
     def _column_count_(self, request):
         return property_mock(request, Table, '_column_count')
 
+    @pytest.fixture
+    def document_part_(self, request):
+        return instance_mock(request, DocumentPart)
+
+    @pytest.fixture
+    def part_prop_(self, request, document_part_):
+        return property_mock(
+            request, Table, 'part', return_value=document_part_
+        )
+
     @pytest.fixture
     def table(self):
         tbl = _tbl_bldr(rows=2, cols=2).element