rfctr: Run type-checks clean

Author: scanny

src/docx/image/image.py

@@ -4,26 +4,31 @@
 them in a document.
 """
 
+from __future__ import annotations
+
 import hashlib
 import io
 import os
+from typing import IO, Tuple
+
+from typing_extensions import Self
 
 from docx.image.exceptions import UnrecognizedImageError
-from docx.shared import Emu, Inches, lazyproperty
+from docx.shared import Emu, Inches, Length, lazyproperty
 
 
-class Image(object):
+class Image:
     """Graphical image stream such as JPEG, PNG, or GIF with properties and methods
     required by ImagePart."""
 
-    def __init__(self, blob, filename, image_header):
+    def __init__(self, blob: bytes, filename: str, image_header: BaseImageHeader):
         super(Image, self).__init__()
         self._blob = blob
         self._filename = filename
         self._image_header = image_header
 
     @classmethod
-    def from_blob(cls, blob):
+    def from_blob(cls, blob: bytes) -> Self:
         """Return a new |Image| subclass instance parsed from the image binary contained
         in `blob`."""
         stream = io.BytesIO(blob)
@@ -73,60 +78,66 @@ def filename(self):
         return self._filename
 
     @property
-    def px_width(self):
+    def px_width(self) -> int:
         """The horizontal pixel dimension of the image."""
         return self._image_header.px_width
 
     @property
-    def px_height(self):
+    def px_height(self) -> int:
         """The vertical pixel dimension of the image."""
         return self._image_header.px_height
 
     @property
-    def horz_dpi(self):
+    def horz_dpi(self) -> int:
         """Integer dots per inch for the width of this image.
 
         Defaults to 72 when not present in the file, as is often the case.
         """
         return self._image_header.horz_dpi
 
     @property
-    def vert_dpi(self):
+    def vert_dpi(self) -> int:
         """Integer dots per inch for the height of this image.
 
         Defaults to 72 when not present in the file, as is often the case.
         """
         return self._image_header.vert_dpi
 
     @property
-    def width(self):
+    def width(self) -> Inches:
         """A |Length| value representing the native width of the image, calculated from
         the values of `px_width` and `horz_dpi`."""
         return Inches(self.px_width / self.horz_dpi)
 
     @property
-    def height(self):
+    def height(self) -> Inches:
         """A |Length| value representing the native height of the image, calculated from
         the values of `px_height` and `vert_dpi`."""
         return Inches(self.px_height / self.vert_dpi)
 
-    def scaled_dimensions(self, width=None, height=None):
-        """Return a (cx, cy) 2-tuple representing the native dimensions of this image
-        scaled by applying the following rules to `width` and `height`.
-
-        If both `width` and `height` are specified, the return value is (`width`,
-        `height`); no scaling is performed. If only one is specified, it is used to
-        compute a scaling factor that is then applied to the unspecified dimension,
-        preserving the aspect ratio of the image. If both `width` and `height` are
-        |None|, the native dimensions are returned. The native dimensions are calculated
-        using the dots-per-inch (dpi) value embedded in the image, defaulting to 72 dpi
-        if no value is specified, as is often the case. The returned values are both
-        |Length| objects.
+    def scaled_dimensions(
+        self, width: int | None = None, height: int | None = None
+    ) -> Tuple[Length, Length]:
+        """(cx, cy) pair representing scaled dimensions of this image.
+
+        The native dimensions of the image are scaled by applying the following rules to
+        the `width` and `height` arguments.
+
+        * If both `width` and `height` are specified, the return value is (`width`,
+        `height`); no scaling is performed.
+        * If only one is specified, it is used to compute a scaling factor that is then
+        applied to the unspecified dimension, preserving the aspect ratio of the image.
+        * If both `width` and `height` are |None|, the native dimensions are returned.
+
+        The native dimensions are calculated using the dots-per-inch (dpi) value
+        embedded in the image, defaulting to 72 dpi if no value is specified, as is
+        often the case. The returned values are both |Length| objects.
         """
         if width is None and height is None:
             return self.width, self.height
 
         if width is None:
+            assert height is not None
             scaling_factor = float(height) / float(self.height)
             width = round(self.width * scaling_factor)
 
@@ -142,7 +153,12 @@ def sha1(self):
         return hashlib.sha1(self._blob).hexdigest()
 
     @classmethod
-    def _from_stream(cls, stream, blob, filename=None):
+    def _from_stream(
+        cls,
+        stream: IO[bytes],
+        blob: bytes,
+        filename: str | None = None,
+    ) -> Image:
         """Return an instance of the |Image| subclass corresponding to the format of the
         image in `stream`."""
         image_header = _ImageHeaderFactory(stream)

src/docx/opc/part.py

@@ -11,7 +11,7 @@
 from docx.oxml.parser import parse_xml
 
 if TYPE_CHECKING:
-    from docx.opc.package import OpcPackage
+    from docx.package import Package
 
 
 class Part(object):
@@ -26,7 +26,7 @@ def __init__(
         partname: str,
         content_type: str,
         blob: bytes | None = None,
-        package: OpcPackage | None = None,
+        package: Package | None = None,
     ):
         super(Part, self).__init__()
         self._partname = partname

src/docx/oxml/__init__.py

@@ -8,6 +8,7 @@
 from docx.oxml.drawing import CT_Drawing
 from docx.oxml.parser import register_element_cls
 from docx.oxml.shape import (
+    CT_Anchor,
     CT_Blip,
     CT_BlipFillProperties,
     CT_GraphicalObject,
@@ -48,6 +49,7 @@
 register_element_cls("pic:pic", CT_Picture)
 register_element_cls("pic:spPr", CT_ShapeProperties)
 register_element_cls("w:drawing", CT_Drawing)
+register_element_cls("wp:anchor", CT_Anchor)
 register_element_cls("wp:docPr", CT_NonVisualDrawingProps)
 register_element_cls("wp:extent", CT_PositiveSize2D)
 register_element_cls("wp:inline", CT_Inline)

src/docx/oxml/shape.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from docx.oxml.ns import nsdecls
 from docx.oxml.parser import parse_xml
 from docx.oxml.simpletypes import (
@@ -20,6 +22,13 @@
     ZeroOrOne,
 )
 
+if TYPE_CHECKING:
+    from docx.shared import Length
+
+
+class CT_Anchor(BaseOxmlElement):
+    """`<wp:anchor>` element, container for a "floating" shape."""
+
 
 class CT_Blip(BaseOxmlElement):
     """``<a:blip>`` element, specifies image source and adjustments such as alpha and
@@ -49,14 +58,14 @@ class CT_GraphicalObjectData(BaseOxmlElement):
 
 
 class CT_Inline(BaseOxmlElement):
-    """``<w:inline>`` element, container for an inline shape."""
+    """`<wp:inline>` element, container for an inline shape."""
 
     extent = OneAndOnlyOne("wp:extent")
     docPr = OneAndOnlyOne("wp:docPr")
     graphic = OneAndOnlyOne("a:graphic")
 
     @classmethod
-    def new(cls, cx, cy, shape_id, pic):
+    def new(cls, cx: Length, cy: Length, shape_id: int, pic: CT_Picture) -> CT_Inline:
         """Return a new ``<wp:inline>`` element populated with the values passed as
         parameters."""
         inline = parse_xml(cls._inline_xml())
@@ -71,9 +80,13 @@ def new(cls, cx, cy, shape_id, pic):
         return inline
 
     @classmethod
-    def new_pic_inline(cls, shape_id, rId, filename, cx, cy):
-        """Return a new `wp:inline` element containing the `pic:pic` element specified
-        by the argument values."""
+    def new_pic_inline(
+        cls, shape_id: int, rId: str, filename: str, cx: Length, cy: Length
+    ) -> CT_Inline:
+        """Create `wp:inline` element containing a `pic:pic` element.
+
+        The contents of the `pic:pic` element is taken from the argument values.
+        """
         pic_id = 0  # Word doesn't seem to use this, but does not omit it
         pic = CT_Picture.new(pic_id, filename, rId, cx, cy)
         inline = cls.new(cx, cy, shape_id, pic)

src/docx/oxml/simpletypes.py

@@ -5,21 +5,34 @@
 schema.
 """
 
-from ..exceptions import InvalidXmlError
-from ..shared import Emu, Pt, RGBColor, Twips
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from docx.exceptions import InvalidXmlError
+from docx.shared import Emu, Pt, RGBColor, Twips
+
+if TYPE_CHECKING:
+    from docx import types as t
 
 
 class BaseSimpleType(object):
+    """Base class for simple-types."""
+
     @classmethod
-    def from_xml(cls, str_value):
-        return cls.convert_from_xml(str_value)
+    def from_xml(cls, xml_value: str):
+        return cls.convert_from_xml(xml_value)
 
     @classmethod
     def to_xml(cls, value):
         cls.validate(value)
         str_value = cls.convert_to_xml(value)
         return str_value
 
+    @classmethod
+    def convert_from_xml(cls, str_value: str) -> t.AbstractSimpleTypeMember:
+        return int(str_value)
+
     @classmethod
     def validate_int(cls, value):
         if not isinstance(value, int):
@@ -35,15 +48,10 @@ def validate_int_in_range(cls, value, min_inclusive, max_inclusive):
             )
 
     @classmethod
-    def validate_string(cls, value):
-        if isinstance(value, str):
-            return value
-        try:
-            if isinstance(value, basestring):
-                return value
-        except NameError:  # means we're on Python 3
-            pass
-        raise TypeError("value must be a string, got %s" % type(value))
+    def validate_string(cls, value: Any) -> str:
+        if not isinstance(value, str):
+            raise TypeError("value must be a string, got %s" % type(value))
+        return value
 
 
 class BaseIntType(BaseSimpleType):
@@ -62,15 +70,15 @@ def validate(cls, value):
 
 class BaseStringType(BaseSimpleType):
     @classmethod
-    def convert_from_xml(cls, str_value):
+    def convert_from_xml(cls, str_value: str) -> str:
         return str_value
 
     @classmethod
-    def convert_to_xml(cls, value):
+    def convert_to_xml(cls, value: str) -> str:
         return value
 
     @classmethod
-    def validate(cls, value):
+    def validate(cls, value: str):
         cls.validate_string(value)
 
 
@@ -160,7 +168,7 @@ def validate(cls, value):
 
 class ST_BrClear(XsdString):
     @classmethod
-    def validate(cls, value):
+    def validate(cls, value: str) -> None:
         cls.validate_string(value)
         valid_values = ("none", "left", "right", "all")
         if value not in valid_values: