shp: add InlineShape.width, height getters

Steve Canny · Steve Canny · commit c5b921ef1a7d · 2013-12-30T20:31:20.000-08:00
Along the way:

* extract tests/parts/test_shape.py
diff --git a/docs/dev/analysis/features/shapes-inline-size.rst b/docs/dev/analysis/features/shapes-inline-size.rst
@@ -11,24 +11,6 @@ inline with, however its dimensions can be specified. For some shape types,
 both the contained shape and the shape container specify a width and height.
 
 
-Acceptance tests
-----------------
-
-  Feature: Query and change dimensions of inline shape
-    In order to adjust the display size of an inline shape
-    As a python-docx developer
-    I need to query and change the width and height of an inline shape
-
-    Scenario: Query inline shape dimensions
-      Given an inline shape of known dimensions
-       Then the dimensions of the inline shape match the known values
-
-    Scenario: Change inline shape dimensions
-      Given an inline shape of known dimensions
-       When I change the dimensions of the inline shape
-       Then the dimensions of the inline shape match the new values
-
-
 Unit tests
 ----------
 
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -23,13 +23,14 @@ class ValidationError(Exception):
 
 from docx.oxml.shape import (
     CT_Blip, CT_BlipFillProperties, CT_GraphicalObject,
-    CT_GraphicalObjectData, CT_Inline, CT_Picture
+    CT_GraphicalObjectData, CT_Inline, CT_Picture, CT_PositiveSize2D
 )
 register_custom_element_class('a:blip', CT_Blip)
 register_custom_element_class('a:graphic', CT_GraphicalObject)
 register_custom_element_class('a:graphicData', CT_GraphicalObjectData)
 register_custom_element_class('pic:blipFill', CT_BlipFillProperties)
 register_custom_element_class('pic:pic', CT_Picture)
+register_custom_element_class('wp:extent', CT_PositiveSize2D)
 register_custom_element_class('wp:inline', CT_Inline)
 
 from docx.oxml.parts.document import CT_Body, CT_Document
diff --git a/docx/oxml/shape.py b/docx/oxml/shape.py
@@ -7,6 +7,7 @@
 from docx.oxml.shared import (
     nsmap, nspfxmap, OxmlBaseElement, OxmlElement, qn
 )
+from docx.shared import Emu
 
 
 class CT_Blip(OxmlBaseElement):
@@ -84,6 +85,10 @@ class CT_Inline(OxmlBaseElement):
     """
     ``<w:inline>`` element, container for an inline shape.
     """
+    @property
+    def extent(self):
+        return self.find(qn('wp:extent'))
+
     @property
     def graphic(self):
         return self.find(qn('a:graphic'))
@@ -183,12 +188,24 @@ class CT_PositiveSize2D(OxmlBaseElement):
     Used for ``<wp:extent>`` element, and perhaps others later. Specifies the
     size of a DrawingML drawing.
     """
+    @property
+    def cx(self):
+        cx_str = self.get('cx')
+        cx = int(cx_str)
+        return Emu(cx)
+
+    @property
+    def cy(self):
+        cy_str = self.get('cy')
+        cy = int(cy_str)
+        return Emu(cy)
+
     @classmethod
     def new(cls, nsptagname_str, cx, cy):
-        elt = OxmlElement(nsptagname_str)
-        elt.set('cx', str(cx))
-        elt.set('cy', str(cy))
-        return elt
+        elm = OxmlElement(nsptagname_str)
+        elm.set('cx', str(cx))
+        elm.set('cy', str(cy))
+        return elm
 
 
 class CT_PresetGeometry2D(OxmlBaseElement):
diff --git a/docx/shape.py b/docx/shape.py
@@ -23,6 +23,20 @@ def __init__(self, inline):
         super(InlineShape, self).__init__()
         self._inline = inline
 
+    @property
+    def height(self):
+        """
+        Return the display height of this inline shape as an |Emu| instance.
+        Length instances such as this behave like an int, but also have
+        built-in conversion properties, e.g.::
+
+            \>>> inline_shape.height
+            914400
+            \>>> inline_shape.height.inches
+            1.0
+        """
+        return self._inline.extent.cy
+
     @classmethod
     def new_picture(cls, r, image_part, rId, shape_id):
         """
@@ -41,6 +55,10 @@ def new_picture(cls, r, image_part, rId, shape_id):
 
     @property
     def type(self):
+        """
+        Return the member of ``docx.enum.shape.WD_INLINE_SHAPE`` denoting the
+        inline shape type, e.g. ``LINKED_PICTURE``.
+        """
         graphicData = self._inline.graphic.graphicData
         uri = graphicData.uri
         if uri == nsmap['pic']:
@@ -53,3 +71,10 @@ def type(self):
         if uri == nsmap['dgm']:
             return WD_INLINE_SHAPE.SMART_ART
         return WD_INLINE_SHAPE.NOT_IMPLEMENTED
+
+    @property
+    def width(self):
+        """
+        Return the display width of this inline shape as an |Emu| instance.
+        """
+        return self._inline.extent.cx
diff --git a/features/shp-inline-shape-size.feature b/features/shp-inline-shape-size.feature
@@ -3,7 +3,6 @@ Feature: Query and change dimensions of inline shape
   As a python-docx developer
   I need to query and change the width and height of an inline shape
 
-  @wip
   Scenario: Query inline shape dimensions
     Given an inline shape of known dimensions
      Then the dimensions of the inline shape match the known values
diff --git a/features/steps/shape.py b/features/steps/shape.py
@@ -13,6 +13,7 @@
 from docx import Document
 from docx.enum.shape import WD_INLINE_SHAPE
 from docx.parts.document import InlineShape, InlineShapes
+from docx.shared import Inches
 
 from .helpers import test_docx, test_file_path
 
@@ -71,6 +72,13 @@ def when_add_inline_picture_to_document(context):
     )
 
 
+@when('I change the dimensions of the inline shape')
+def when_change_dimensions_of_inline_shape(context):
+    inline_shape = context.inline_shape
+    inline_shape.width = Inches(1)
+    inline_shape.height = Inches(0.5)
+
+
 # then =====================================================
 
 @then('I can access each inline shape by index')
@@ -115,9 +123,16 @@ def then_inline_shape_type_is_shape_type(context, shape_type):
 
 @then('the dimensions of the inline shape match the known values')
 def then_dimensions_of_inline_shape_match_known_values(context):
+    inline_shape = context.inline_shape
+    assert inline_shape.width == 1778000, 'got %s' % inline_shape.width
+    assert inline_shape.height == 711200, 'got %s' % inline_shape.height
+
+
+@then('the dimensions of the inline shape match the new values')
+def then_dimensions_of_inline_shape_match_new_values(context):
     inline_shape = context.inline_shape
     assert inline_shape.width == 914400, 'got %s' % inline_shape.width
-    assert inline_shape.height == 914400, 'got %s' % inline_shape.height
+    assert inline_shape.height == 457200, 'got %s' % inline_shape.height
 
 
 @then('the document contains the inline picture')
diff --git a/tests/parts/test_document.py b/tests/parts/test_document.py
@@ -10,12 +10,10 @@
 
 from mock import Mock
 
-from docx.enum.shape import WD_INLINE_SHAPE
 from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
 from docx.opc.package import PartFactory
 from docx.opc.packuri import PackURI
 from docx.oxml.parts.document import CT_Body, CT_Document
-from docx.oxml.shared import nsmap
 from docx.oxml.text import CT_R
 from docx.package import ImageParts, Package
 from docx.parts.document import _Body, DocumentPart, InlineShapes
@@ -24,11 +22,7 @@
 from docx.table import Table
 from docx.text import Paragraph
 
-from ..oxml.unitdata.dml import (
-    a_blip, a_blipFill, a_cNvPr, a_cNvPicPr, a_docPr, a_drawing, a_fillRect,
-    a_graphic, a_graphicData, a_pic, a_prstGeom, a_stretch, an_ext,
-    an_extent, an_inline, an_nvPicPr, an_off, an_spPr, an_xfrm
-)
+from ..oxml.unitdata.dml import a_drawing, an_inline
 from ..oxml.parts.unitdata.document import a_body, a_document
 from ..oxml.unitdata.table import (
     a_gridCol, a_tbl, a_tblGrid, a_tblPr, a_tc, a_tr
@@ -393,136 +387,6 @@ def _tr_bldr(self, cols):
         return tr_bldr
 
 
-class DescribeInlineShape(object):
-
-    def it_knows_what_type_of_shape_it_is(self, shape_type_fixture):
-        inline_shape, inline_shape_type = shape_type_fixture
-        assert inline_shape.type == inline_shape_type
-
-    def it_can_contruct_a_new_inline_picture_shape(
-            self, new_picture_fixture):
-        inline_shape, r, image_part_, rId, shape_id, expected_inline_xml = (
-            new_picture_fixture
-        )
-        picture = inline_shape.new_picture(r, image_part_, rId, shape_id)
-        assert picture._inline.xml == expected_inline_xml
-        assert r[0][0] is picture._inline
-
-    # fixtures -------------------------------------------------------
-
-    @pytest.fixture
-    def image_params(self):
-        filename = 'foobar.garf'
-        rId = 'rId42'
-        cx, cy = 914422, 223344
-        return filename, rId, cx, cy
-
-    @pytest.fixture
-    def image_part_(self, request, image_params):
-        filename, rId, cx, cy = image_params
-        image_part_ = instance_mock(request, ImagePart)
-        image_part_.default_cx = cx
-        image_part_.default_cy = cy
-        image_part_.filename = filename
-        return image_part_
-
-    @pytest.fixture
-    def new_picture_fixture(self, request, image_part_, image_params):
-        filename, rId, cx, cy = image_params
-        inline_shape = InlineShape(None)
-        r = an_r().with_nsdecls().element
-        shape_id = 7
-        name = 'Picture %d' % shape_id
-        uri = nsmap['pic']
-        expected_inline = (
-            an_inline().with_nsdecls('r', 'wp', 'w').with_child(
-                an_extent().with_cx(cx).with_cy(cy)).with_child(
-                a_docPr().with_id(shape_id).with_name(name)).with_child(
-                a_graphic().with_nsdecls().with_child(
-                    a_graphicData().with_uri(uri).with_child(
-                        self._pic_bldr(filename, rId, cx, cy))))
-        ).element
-        expected_inline_xml = expected_inline.xml
-        return (
-            inline_shape, r, image_part_, rId, shape_id, expected_inline_xml
-        )
-
-    @pytest.fixture(params=[
-        'embed pic', 'link pic', 'link+embed pic', 'chart', 'smart art',
-        'not implemented'
-    ])
-    def shape_type_fixture(self, request):
-        if request.param == 'embed pic':
-            inline = self._inline_with_picture(embed=True)
-            shape_type = WD_INLINE_SHAPE.PICTURE
-
-        elif request.param == 'link pic':
-            inline = self._inline_with_picture(link=True)
-            shape_type = WD_INLINE_SHAPE.LINKED_PICTURE
-
-        elif request.param == 'link+embed pic':
-            inline = self._inline_with_picture(embed=True, link=True)
-            shape_type = WD_INLINE_SHAPE.LINKED_PICTURE
-
-        elif request.param == 'chart':
-            inline = self._inline_with_uri(nsmap['c'])
-            shape_type = WD_INLINE_SHAPE.CHART
-
-        elif request.param == 'smart art':
-            inline = self._inline_with_uri(nsmap['dgm'])
-            shape_type = WD_INLINE_SHAPE.SMART_ART
-
-        elif request.param == 'not implemented':
-            inline = self._inline_with_uri('foobar')
-            shape_type = WD_INLINE_SHAPE.NOT_IMPLEMENTED
-
-        return InlineShape(inline), shape_type
-
-    def _inline_with_picture(self, embed=False, link=False):
-        picture_ns = nsmap['pic']
-
-        blip_bldr = a_blip()
-        if embed:
-            blip_bldr.with_embed('rId1')
-        if link:
-            blip_bldr.with_link('rId2')
-
-        inline = (
-            an_inline().with_nsdecls('wp', 'r').with_child(
-                a_graphic().with_nsdecls().with_child(
-                    a_graphicData().with_uri(picture_ns).with_child(
-                        a_pic().with_nsdecls().with_child(
-                            a_blipFill().with_child(
-                                blip_bldr)))))
-        ).element
-        return inline
-
-    def _inline_with_uri(self, uri):
-        inline = (
-            an_inline().with_nsdecls('wp').with_child(
-                a_graphic().with_nsdecls().with_child(
-                    a_graphicData().with_uri(uri)))
-        ).element
-        return inline
-
-    def _pic_bldr(self, name, rId, cx, cy):
-        return (
-            a_pic().with_nsdecls().with_child(
-                an_nvPicPr().with_child(
-                    a_cNvPr().with_id(0).with_name(name)).with_child(
-                    a_cNvPicPr())).with_child(
-                a_blipFill().with_child(
-                    a_blip().with_embed(rId)).with_child(
-                    a_stretch().with_child(
-                        a_fillRect()))).with_child(
-                an_spPr().with_child(
-                    an_xfrm().with_child(
-                        an_off().with_x(0).with_y(0)).with_child(
-                        an_ext().with_cx(cx).with_cy(cy))).with_child(
-                    a_prstGeom().with_prst('rect')))
-        )
-
-
 class DescribeInlineShapes(object):
 
     def it_knows_how_many_inline_shapes_it_contains(
diff --git a/tests/test_shape.py b/tests/test_shape.py
