tbl: add _Cell.width getter

Steve Canny · Steve Canny · commit fa30e11bbdf2 · 2014-07-13T17:10:28.000-07:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -115,7 +115,7 @@ 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_Tc
+    CT_TblWidth, CT_Tc, CT_TcPr
 )
 register_element_cls('w:gridCol',   CT_TblGridCol)
 register_element_cls('w:tbl',       CT_Tbl)
@@ -124,6 +124,8 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:tblPr',     CT_TblPr)
 register_element_cls('w:tblStyle',  CT_String)
 register_element_cls('w:tc',        CT_Tc)
+register_element_cls('w:tcPr',      CT_TcPr)
+register_element_cls('w:tcW',       CT_TblWidth)
 register_element_cls('w:tr',        CT_Row)
 
 from docx.oxml.text import (
diff --git a/docx/oxml/simpletypes.py b/docx/oxml/simpletypes.py
@@ -276,6 +276,18 @@ def validate(cls, value):
             )
 
 
+class ST_TblWidth(XsdString):
+
+    @classmethod
+    def validate(cls, value):
+        cls.validate_string(value)
+        valid_values = ('auto', 'dxa', 'nil', 'pct')
+        if value not in valid_values:
+            raise ValueError(
+                "must be one of %s, got '%s'" % (valid_values, value)
+            )
+
+
 class ST_TwipsMeasure(XsdUnsignedLong):
 
     @classmethod
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
@@ -8,10 +8,13 @@
 
 from . import parse_xml
 from .ns import nsdecls
-from .simpletypes import ST_TblLayoutType, ST_TwipsMeasure
+from ..shared import Emu, Twips
+from .simpletypes import (
+    ST_TblLayoutType, ST_TblWidth, ST_TwipsMeasure, XsdInt
+)
 from .xmlchemy import (
-    BaseOxmlElement, OneAndOnlyOne, OneOrMore, OptionalAttribute, ZeroOrOne,
-    ZeroOrMore
+    BaseOxmlElement, OneAndOnlyOne, OneOrMore, OptionalAttribute,
+    RequiredAttribute, ZeroOrOne, ZeroOrMore
 )
 
 
@@ -129,6 +132,33 @@ def style(self, value):
         self._add_tblStyle(val=value)
 
 
+class CT_TblWidth(BaseOxmlElement):
+    """
+    Used for ``<w:tblW>`` and ``<w:tcW>`` elements and many others, to
+    specify a table-related width.
+    """
+    # the type for `w` attr is actually ST_MeasurementOrPercent, but using
+    # XsdInt for now because only dxa (twips) values are being used. It's not
+    # entirely clear what the semantics are for other values like -01.4mm
+    w = RequiredAttribute('w:w', XsdInt)
+    type = RequiredAttribute('w:type', ST_TblWidth)
+
+    @property
+    def width(self):
+        """
+        Return the EMU length value represented by the combined ``w:w`` and
+        ``w:type`` attributes.
+        """
+        if self.type != 'dxa':
+            return None
+        return Twips(self.w)
+
+    @width.setter
+    def width(self, value):
+        self.type = 'dxa'
+        self.w = Emu(value).twips
+
+
 class CT_Tc(BaseOxmlElement):
     """
     ``<w:tc>`` table cell element
@@ -170,3 +200,42 @@ def new(cls):
             '  <w:p/>\n'
             '</w:tc>' % nsdecls('w')
         )
+
+    @property
+    def width(self):
+        """
+        Return the EMU length value represented in the ``./w:tcPr/w:tcW``
+        child element or |None| if not present.
+        """
+        tcPr = self.tcPr
+        if tcPr is None:
+            return None
+        return tcPr.width
+
+
+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'
+    ))
+
+    @property
+    def width(self):
+        """
+        Return the EMU length value represented in the ``<w:tcW>`` child
+        element or |None| if not present or its type is not 'dxa'.
+        """
+        tcW = self.tcW
+        if tcW is None:
+            return None
+        return tcW.width
+
+    @width.setter
+    def width(self, value):
+        tcW = self.get_or_add_tcW()
+        tcW.width = value
diff --git a/docx/table.py b/docx/table.py
@@ -126,6 +126,7 @@ def width(self):
         """
         The width of this cell in EMU, or |None| if no explicit width is set.
         """
+        return self._tc.width
 
 
 class _Column(Parented):
diff --git a/features/tbl-cell-props.feature b/features/tbl-cell-props.feature
@@ -4,7 +4,6 @@ Feature: Get and set table cell properties
   I need a way to get and set the properties of a table cell
 
 
-  @wip
   Scenario Outline: Get cell width
     Given a table cell having a width of <width-setting>
      Then the reported width of the cell is <reported-width>
diff --git a/tests/test_table.py b/tests/test_table.py
@@ -168,6 +168,10 @@ def it_can_replace_its_content_with_a_string_of_text(
         cell.text = text
         assert cell._tc.xml == expected_xml
 
+    def it_knows_its_width_in_EMU(self, width_get_fixture):
+        cell, expected_width = width_get_fixture
+        assert cell.width == expected_width
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture
@@ -188,6 +192,17 @@ def text_set_fixture(self, request):
         expected_xml = xml(expected_cxml)
         return cell, new_text, expected_xml
 
+    @pytest.fixture(params=[
+        ('w:tc',                                   None),
+        ('w:tc/w:tcPr',                            None),
+        ('w:tc/w:tcPr/w:tcW{w:w=25%,w:type=pct}',  None),
+        ('w:tc/w:tcPr/w:tcW{w:w=1440,w:type=dxa}', 914400),
+    ])
+    def width_get_fixture(self, request):
+        tc_cxml, expected_width = request.param
+        cell = _Cell(element(tc_cxml), None)
+        return cell, expected_width
+
 
 class Describe_Column(object):
 
diff --git a/tests/unitutil/cxml.py b/tests/unitutil/cxml.py
@@ -228,7 +228,7 @@ def grammar():
 
     # np:attr_name=attr_val ----------------------
     attr_name = Word(alphas + ':')
-    attr_val = Word(alphanums + '-.')
+    attr_val = Word(alphanums + '-.%')
     attr_def = Group(attr_name + equal + attr_val)
     attr_list = open_brace + delimitedList(attr_def) + close_brace
 
