drawing: add image extraction from Drawing

Author: scanny

features/cmt-props.feature

@@ -30,7 +30,6 @@ Feature: Get comment properties
      Then para_text is the text of the first paragraph in the comment
 
 
-  @wip
   Scenario: Retrieve embedded image from a comment
     Given a Comment object containing an embedded image
      Then I can extract the image from the comment

src/docx/drawing/__init__.py

@@ -9,6 +9,7 @@
 
 if TYPE_CHECKING:
     import docx.types as t
+    from docx.image.image import Image
 
 
 class Drawing(Parented):
@@ -18,3 +19,41 @@ def __init__(self, drawing: CT_Drawing, parent: t.ProvidesStoryPart):
         super().__init__(parent)
         self._parent = parent
         self._drawing = self._element = drawing
+
+    @property
+    def has_picture(self) -> bool:
+        """True when `drawing` contains an embedded picture.
+
+        A drawing can contain a picture, but it can also contain a chart, SmartArt, or a
+        drawing canvas. Methods related to a picture, like `.image`, will raise when the drawing
+        does not contain a picture. Use this value to determine whether image methods will succeed.
+
+        This value is `False` when a linked picture is present. This should be relatively rare and
+        the image would only be retrievable from the filesystem.
+
+        Note this does not distinguish between inline and floating images. The presence of either
+        one will cause this value to be `True`.
+        """
+        xpath_expr = (
+            # -- an inline picture --
+            "./wp:inline/a:graphic/a:graphicData/pic:pic"
+            # -- a floating picture --
+            " | ./wp:anchor/a:graphic/a:graphicData/pic:pic"
+        )
+        # -- xpath() will return a list, empty if there are no matches --
+        return bool(self._drawing.xpath(xpath_expr))
+
+    @property
+    def image(self) -> Image:
+        """An `Image` proxy object for the image in this (picture) drawing.
+
+        Raises `ValueError` when this drawing does contains something other than a picture. Use
+        `.has_picture` to qualify drawing objects before using this property.
+        """
+        picture_rIds = self._drawing.xpath(".//pic:blipFill/a:blip/@r:embed")
+        if not picture_rIds:
+            raise ValueError("drawing does not contain a picture")
+        rId = picture_rIds[0]
+        doc_part = self.part
+        image_part = doc_part.related_parts[rId]
+        return image_part.image

tests/test_comments.py

@@ -1,6 +1,6 @@
 # pyright: reportPrivateUsage=false
 
-"""Unit test suite for the docx.comments module."""
+"""Unit test suite for the `docx.comments` module."""
 
 from __future__ import annotations
 
@@ -21,7 +21,7 @@
 
 
 class DescribeComments:
-    """Unit-test suite for `docx.comments.Comments`."""
+    """Unit-test suite for `docx.comments.Comments` objects."""
 
     @pytest.mark.parametrize(
         ("cxml", "count"),

tests/test_drawing.py

@@ -0,0 +1,74 @@
+# pyright: reportPrivateUsage=false
+
+"""Unit test suite for the `docx.drawing` module."""
+
+from __future__ import annotations
+
+from typing import cast
+
+import pytest
+
+from docx.drawing import Drawing
+from docx.image.image import Image
+from docx.oxml.drawing import CT_Drawing
+from docx.parts.document import DocumentPart
+from docx.parts.image import ImagePart
+
+from .unitutil.cxml import element
+from .unitutil.mock import FixtureRequest, Mock, instance_mock
+
+
+class DescribeDrawing:
+    """Unit-test suite for `docx.drawing.Drawing` objects."""
+
+    @pytest.mark.parametrize(
+        ("cxml", "expected_value"),
+        [
+            ("w:drawing/wp:inline/a:graphic/a:graphicData/pic:pic", True),
+            ("w:drawing/wp:anchor/a:graphic/a:graphicData/pic:pic", True),
+            ("w:drawing/wp:inline/a:graphic/a:graphicData/a:grpSp", False),
+            ("w:drawing/wp:anchor/a:graphic/a:graphicData/a:chart", False),
+        ],
+    )
+    def it_knows_when_it_contains_a_Picture(
+        self, cxml: str, expected_value: bool, document_part_: Mock
+    ):
+        drawing = Drawing(cast(CT_Drawing, element(cxml)), document_part_)
+        assert drawing.has_picture == expected_value
+
+    def it_provides_access_to_the_image_in_a_Picture_drawing(
+        self, document_part_: Mock, image_part_: Mock, image_: Mock
+    ):
+        image_part_.image = image_
+        document_part_.part.related_parts = {"rId1": image_part_}
+        cxml = (
+            "w:drawing/wp:inline/a:graphic/a:graphicData/pic:pic/pic:blipFill/a:blip{r:embed=rId1}"
+        )
+        drawing = Drawing(cast(CT_Drawing, element(cxml)), document_part_)
+
+        image = drawing.image
+
+        assert image is image_
+
+    def but_it_raises_when_the_drawing_does_not_contain_a_Picture(self, document_part_: Mock):
+        drawing = Drawing(
+            cast(CT_Drawing, element("w:drawing/wp:inline/a:graphic/a:graphicData/a:grpSp")),
+            document_part_,
+        )
+
+        with pytest.raises(ValueError, match="drawing does not contain a picture"):
+            drawing.image
+
+    # -- fixtures --------------------------------------------------------------------------------
+
+    @pytest.fixture
+    def document_part_(self, request: FixtureRequest):
+        return instance_mock(request, DocumentPart)
+
+    @pytest.fixture
+    def image_(self, request: FixtureRequest):
+        return instance_mock(request, Image)
+
+    @pytest.fixture
+    def image_part_(self, request: FixtureRequest):
+        return instance_mock(request, ImagePart)