tbl: add _Column.width getter

Steve Canny · Steve Canny · commit e685394105b4 · 2014-06-17T20:20:10.000-07:00
Also, sequence Length methods in alpha order
diff --git a/docs/dev/analysis/features/table.rst b/docs/dev/analysis/features/table.rst
@@ -197,6 +197,16 @@ Schema Definitions
     <xsd:union memberTypes="ST_UnsignedDecimalNumber ST_PositiveUniversalMeasure"/>
   </xsd:simpleType>
 
+  <xsd:simpleType name="ST_UnsignedDecimalNumber">
+    <xsd:restriction base="xsd:unsignedLong"/>
+  </xsd:simpleType>
+
+  <xsd:simpleType name="ST_PositiveUniversalMeasure">
+    <xsd:restriction base="ST_UniversalMeasure">
+      <xsd:pattern value="[0-9]+(\.[0-9]+)?(mm|cm|in|pt|pc|pi)"/>
+    </xsd:restriction>
+  </xsd:simpleType>
+
   <xsd:group name="EG_ContentRowContent">
     <xsd:choice>
       <xsd:element name="tr"        type="CT_Row"          minOccurs="0" maxOccurs="unbounded"/>
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -107,7 +107,10 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:style',  CT_Style)
 register_element_cls('w:styles', CT_Styles)
 
-from docx.oxml.table import CT_Row, CT_Tbl, CT_TblGrid, CT_TblPr, CT_Tc
+from docx.oxml.table import (
+    CT_Row, CT_Tbl, CT_TblGrid, CT_TblGridCol, CT_TblPr, CT_Tc
+)
+register_element_cls('w:gridCol',  CT_TblGridCol)
 register_element_cls('w:tbl',      CT_Tbl)
 register_element_cls('w:tblGrid',  CT_TblGrid)
 register_element_cls('w:tblPr',    CT_TblPr)
diff --git a/docx/oxml/simpletypes.py b/docx/oxml/simpletypes.py
@@ -8,7 +8,7 @@
 
 from __future__ import absolute_import, print_function
 
-from ..shared import Emu
+from ..shared import Emu, Twips
 
 
 class BaseSimpleType(object):
@@ -153,6 +153,13 @@ def validate(cls, value):
         cls.validate_int_in_range(value, 0, 4294967295)
 
 
+class XsdUnsignedLong(BaseIntType):
+
+    @classmethod
+    def validate(cls, value):
+        cls.validate_int_in_range(value, 0, 18446744073709551615)
+
+
 class ST_BrClear(XsdString):
 
     @classmethod
@@ -231,6 +238,21 @@ class ST_String(XsdString):
     pass
 
 
+class ST_TwipsMeasure(XsdUnsignedLong):
+
+    @classmethod
+    def convert_from_xml(cls, str_value):
+        if 'i' in str_value or 'm' in str_value or 'p' in str_value:
+            return ST_UniversalMeasure.convert_from_xml(str_value)
+        return Twips(int(str_value))
+
+    @classmethod
+    def convert_to_xml(cls, value):
+        emu = Emu(value)
+        twips = emu.twips
+        return str(twips)
+
+
 class ST_UniversalMeasure(BaseSimpleType):
 
     @classmethod
diff --git a/docx/oxml/table.py b/docx/oxml/table.py
@@ -8,8 +8,10 @@
 
 from . import parse_xml
 from .ns import nsdecls
+from .simpletypes import ST_TwipsMeasure
 from .xmlchemy import (
-    BaseOxmlElement, OneAndOnlyOne, OneOrMore, ZeroOrOne, ZeroOrMore
+    BaseOxmlElement, OneAndOnlyOne, OneOrMore, OptionalAttribute, ZeroOrOne,
+    ZeroOrMore
 )
 
 
@@ -65,6 +67,7 @@ class CT_TblGridCol(BaseOxmlElement):
     ``<w:gridCol>`` element, child of ``<w:tblGrid>``, defines a table
     column.
     """
+    w = OptionalAttribute('w:w', ST_TwipsMeasure)
 
 
 class CT_TblPr(BaseOxmlElement):
diff --git a/docx/shared.py b/docx/shared.py
@@ -18,23 +18,31 @@ class Length(int):
     _EMUS_PER_CM = 360000
     _EMUS_PER_MM = 36000
     _EMUS_PER_PX = 12700
+    _EMUS_PER_TWIP = 635
 
     def __new__(cls, emu):
         return int.__new__(cls, emu)
 
     @property
-    def inches(self):
+    def cm(self):
         """
-        The equivalent length expressed in inches (float).
+        The equivalent length expressed in centimeters (float).
         """
-        return self / float(self._EMUS_PER_INCH)
+        return self / float(self._EMUS_PER_CM)
 
     @property
-    def cm(self):
+    def emu(self):
         """
-        The equivalent length expressed in centimeters (float).
+        The equivalent length expressed in English Metric Units (int).
         """
-        return self / float(self._EMUS_PER_CM)
+        return self
+
+    @property
+    def inches(self):
+        """
+        The equivalent length expressed in inches (float).
+        """
+        return self / float(self._EMUS_PER_INCH)
 
     @property
     def mm(self):
@@ -50,11 +58,11 @@ def px(self):
         return int(round(self / float(self._EMUS_PER_PX)) + 0.1)
 
     @property
-    def emu(self):
+    def twips(self):
         """
-        The equivalent length expressed in English Metric Units (int).
+        The equivalent length expressed in twips (int).
         """
-        return self
+        return int(round(self / float(self._EMUS_PER_TWIP)) + 0.1)
 
 
 class Inches(Length):
@@ -116,6 +124,16 @@ def __new__(cls, px):
         return Length.__new__(cls, emu)
 
 
+class Twips(Length):
+    """
+    Convenience constructor for length in twips, e.g. ``width = Twips(42)``.
+    A twip is a twentieth of a point, 635 EMU.
+    """
+    def __new__(cls, twips):
+        emu = int(twips * Length._EMUS_PER_TWIP)
+        return Length.__new__(cls, emu)
+
+
 def lazyproperty(f):
     """
     @lazyprop decorator. Decorated method will be called only on first access
diff --git a/docx/table.py b/docx/table.py
@@ -132,6 +132,14 @@ def cells(self):
         """
         return _ColumnCells(self._tbl, self._gridCol)
 
+    @property
+    def width(self):
+        """
+        The width of this column in EMU, or |None| if no explicit width is
+        set.
+        """
+        return self._gridCol.w
+
 
 class _ColumnCells(object):
     """
diff --git a/features/tbl-col-props.feature b/features/tbl-col-props.feature
@@ -3,7 +3,7 @@ Feature: Get and set table column widths
   As an python-docx developer
   I need a way to get and set the width of a table's columns
 
-  @wip
+
   Scenario Outline: Get existing column width
     Given a table column having a width of <width>
      Then the reported column width is <width-emu>
diff --git a/tests/test_table.py b/tests/test_table.py
@@ -168,8 +168,31 @@ def it_provides_access_to_the_column_cells(self, column):
         cells = column.cells
         assert isinstance(cells, _ColumnCells)
 
+    def it_knows_its_width_in_EMU(self, width_fixture):
+        column, expected_width = width_fixture
+        assert column.width == expected_width
+
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        (4242,     2693670),
+        (1440,     914400),
+        ('2.54cm', 914400),
+        ('54mm',   1944000),
+        ('12.5pt', 158750),
+        (None,     None),
+    ])
+    def width_fixture(self, request):
+        w, expected_width = request.param
+        gridCol_bldr = a_gridCol().with_nsdecls()
+        if w is not None:
+            gridCol_bldr.with_w(w)
+        gridCol = gridCol_bldr.element
+        column = _Column(gridCol, None)
+        return column, expected_width
+
+    # fixture components ---------------------------------------------
+
     @pytest.fixture
     def column(self):
         return _Column(None, None)
