tbl: add Table._cells

Steve Canny · Steve Canny · commit 22752a9aac98 · 2014-11-28T21:22:23.000-05:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -115,9 +115,10 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 
 from docx.oxml.table import (
     CT_Row, CT_Tbl, CT_TblGrid, CT_TblGridCol, CT_TblLayoutType, CT_TblPr,
-    CT_TblWidth, CT_Tc, CT_TcPr
+    CT_TblWidth, CT_Tc, CT_TcPr, CT_VMerge
 )
 register_element_cls('w:gridCol',   CT_TblGridCol)
+register_element_cls('w:gridSpan',  CT_DecimalNumber)
 register_element_cls('w:tbl',       CT_Tbl)
 register_element_cls('w:tblGrid',   CT_TblGrid)
 register_element_cls('w:tblLayout', CT_TblLayoutType)
@@ -127,6 +128,7 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:tcPr',      CT_TcPr)
 register_element_cls('w:tcW',       CT_TblWidth)
 register_element_cls('w:tr',        CT_Row)
+register_element_cls('w:vMerge',    CT_VMerge)
 
 from docx.oxml.text import (
     CT_Br, CT_Jc, CT_P, CT_PPr, CT_R, CT_RPr, CT_Text, CT_Underline
diff --git a/docx/oxml/simpletypes.py b/docx/oxml/simpletypes.py
@@ -54,34 +54,45 @@ def validate_string(cls, value):
         )
 
 
-class BaseStringType(BaseSimpleType):
+class BaseIntType(BaseSimpleType):
 
     @classmethod
     def convert_from_xml(cls, str_value):
-        return str_value
+        return int(str_value)
 
     @classmethod
     def convert_to_xml(cls, value):
-        return value
+        return str(value)
 
     @classmethod
     def validate(cls, value):
-        cls.validate_string(value)
+        cls.validate_int(value)
 
 
-class BaseIntType(BaseSimpleType):
+class BaseStringType(BaseSimpleType):
 
     @classmethod
     def convert_from_xml(cls, str_value):
-        return int(str_value)
+        return str_value
 
     @classmethod
     def convert_to_xml(cls, value):
-        return str(value)
+        return value
 
     @classmethod
     def validate(cls, value):
-        cls.validate_int(value)
+        cls.validate_string(value)
+
+
+class BaseStringEnumerationType(BaseStringType):
+
+    @classmethod
+    def validate(cls, value):
+        cls.validate_string(value)
+        if value not in cls._members:
+            raise ValueError(
+                "must be one of %s, got '%s'" % (cls._members, value)
+            )
 
 
 class XsdAnyUri(BaseStringType):
@@ -144,6 +155,12 @@ class XsdString(BaseStringType):
     pass
 
 
+class XsdStringEnumeration(BaseStringEnumerationType):
+    """
+    Set of enumerated xsd:string values.
+    """
+
+
 class XsdToken(BaseStringType):
     """
     xsd:string with whitespace collapsing, e.g. multiple spaces reduced to
@@ -218,6 +235,16 @@ class ST_DrawingElementId(XsdUnsignedInt):
     pass
 
 
+class ST_Merge(XsdStringEnumeration):
+    """
+    Valid values for <w:xMerge val=""> attribute
+    """
+    CONTINUE = 'continue'
+    RESTART = 'restart'
+
+    _members = (CONTINUE, RESTART)
+
+
 class ST_OnOff(XsdBoolean):
 
     @classmethod
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
@@ -10,7 +10,7 @@
 from .ns import nsdecls
 from ..shared import Emu, Twips
 from .simpletypes import (
-    ST_TblLayoutType, ST_TblWidth, ST_TwipsMeasure, XsdInt
+    ST_Merge, ST_TblLayoutType, ST_TblWidth, ST_TwipsMeasure, XsdInt
 )
 from .xmlchemy import (
     BaseOxmlElement, OneAndOnlyOne, OneOrMore, OptionalAttribute,
@@ -44,6 +44,16 @@ class CT_Tbl(BaseOxmlElement):
     tblGrid = OneAndOnlyOne('w:tblGrid')
     tr = ZeroOrMore('w:tr')
 
+    def iter_tcs(self):
+        """
+        Generate each of the `w:tc` elements in this table, left to right and
+        top to bottom. Each cell in the first row is generated, followed by
+        each cell in the second row, etc.
+        """
+        for tr in self.tr_lst:
+            for tc in tr.tc_lst:
+                yield tc
+
     @classmethod
     def new(cls):
         """
@@ -182,18 +192,6 @@ class CT_Tc(BaseOxmlElement):
     p = OneOrMore('w:p')
     tbl = OneOrMore('w:tbl')
 
-    def _insert_tcPr(self, tcPr):
-        """
-        ``tcPr`` has a bunch of successors, but it comes first if it appears,
-        so just overriding and using insert(0, ...) rather than spelling out
-        successors.
-        """
-        self.insert(0, tcPr)
-        return tcPr
-
-    def _new_tbl(self):
-        return CT_Tbl.new()
-
     def clear_content(self):
         """
         Remove all content child elements, preserving the ``<w:tcPr>``
@@ -208,6 +206,17 @@ def clear_content(self):
             new_children.append(tcPr)
         self[:] = new_children
 
+    @property
+    def grid_span(self):
+        """
+        The integer number of columns this cell spans. Determined by
+        ./w:tcPr/w:gridSpan/@val, it defaults to 1.
+        """
+        tcPr = self.tcPr
+        if tcPr is None:
+            return 1
+        return tcPr.grid_span
+
     @classmethod
     def new(cls):
         """
@@ -220,6 +229,17 @@ def new(cls):
             '</w:tc>' % nsdecls('w')
         )
 
+    @property
+    def vMerge(self):
+        """
+        The value of the ./w:tcPr/w:vMerge/@val attribute, or |None| if the
+        w:vMerge element is not present.
+        """
+        tcPr = self.tcPr
+        if tcPr is None:
+            return None
+        return tcPr.vMerge_val
+
     @property
     def width(self):
         """
@@ -236,17 +256,55 @@ def width(self, value):
         tcPr = self.get_or_add_tcPr()
         tcPr.width = value
 
+    def _insert_tcPr(self, tcPr):
+        """
+        ``tcPr`` has a bunch of successors, but it comes first if it appears,
+        so just overriding and using insert(0, ...) rather than spelling out
+        successors.
+        """
+        self.insert(0, tcPr)
+        return tcPr
+
+    def _new_tbl(self):
+        return CT_Tbl.new()
+
 
 class CT_TcPr(BaseOxmlElement):
     """
     ``<w:tcPr>`` element, defining table cell properties
     """
-    tcW = ZeroOrOne('w:tcW', successors=(
-        'w:gridSpan', 'w:hMerge', 'w:vMerge', 'w:tcBorders', 'w:shd',
-        'w:noWrap', 'w:tcMar', 'w:textDirection', 'w:tcFitText', 'w:vAlign',
-        'w:hideMark', 'w:headers', 'w:cellIns', 'w:cellDel', 'w:cellMerge',
-        'w:tcPrChange'
-    ))
+    _tag_seq = (
+        'w:cnfStyle', 'w:tcW', 'w:gridSpan', 'w:hMerge', 'w:vMerge',
+        'w:tcBorders', 'w:shd', 'w:noWrap', 'w:tcMar', 'w:textDirection',
+        'w:tcFitText', 'w:vAlign', 'w:hideMark', 'w:headers', 'w:cellIns',
+        'w:cellDel', 'w:cellMerge', 'w:tcPrChange'
+    )
+    tcW = ZeroOrOne('w:tcW', successors=_tag_seq[2:])
+    gridSpan = ZeroOrOne('w:gridSpan', successors=_tag_seq[3:])
+    vMerge = ZeroOrOne('w:vMerge', successors=_tag_seq[5:])
+    del _tag_seq
+
+    @property
+    def grid_span(self):
+        """
+        The integer number of columns this cell spans. Determined by
+        ./w:gridSpan/@val, it defaults to 1.
+        """
+        gridSpan = self.gridSpan
+        if gridSpan is None:
+            return 1
+        return gridSpan.val
+
+    @property
+    def vMerge_val(self):
+        """
+        The value of the ./w:vMerge/@val attribute, or |None| if the
+        w:vMerge element is not present.
+        """
+        vMerge = self.vMerge
+        if vMerge is None:
+            return None
+        return vMerge.val
 
     @property
     def width(self):
@@ -263,3 +321,10 @@ def width(self):
     def width(self, value):
         tcW = self.get_or_add_tcW()
         tcW.width = value
+
+
+class CT_VMerge(BaseOxmlElement):
+    """
+    ``<w:vMerge>`` element, specifying vertical merging behavior of a cell.
+    """
+    val = OptionalAttribute('w:val', ST_Merge, default=ST_Merge.CONTINUE)
diff --git a/docx/table.py b/docx/table.py
@@ -7,6 +7,7 @@
 from __future__ import absolute_import, print_function, unicode_literals
 
 from .blkcntnr import BlockItemContainer
+from .oxml.simpletypes import ST_Merge
 from .shared import lazyproperty, Parented
 
 
@@ -113,7 +114,17 @@ def _cells(self):
         If the table contains a span, one or more |_Cell| object references
         are repeated.
         """
-        raise NotImplementedError
+        col_count = self._column_count
+        cells = []
+        for tc in self._tbl.iter_tcs():
+            for grid_span_idx in range(tc.grid_span):
+                if tc.vMerge == ST_Merge.CONTINUE:
+                    cells.append(cells[-col_count])
+                elif grid_span_idx > 0:
+                    cells.append(cells[-1])
+                else:
+                    cells.append(_Cell(tc, self))
+        return cells
 
     @property
     def _column_count(self):
diff --git a/features/tbl-cell-access.feature b/features/tbl-cell-access.feature
@@ -3,7 +3,6 @@ Feature: Access table cells
   As a developer using python-docx
   I need a way to access a cell from a table, row, or column
 
-  @wip
   Scenario Outline: Access cell sequence of a row
      Given a 3x3 table having <span-state>
       Then the row cells text is <expected-text>
diff --git a/tests/test_files/snippets/tbl-cells.txt b/tests/test_files/snippets/tbl-cells.txt
diff --git a/tests/test_table.py b/tests/test_table.py
