rfctr: bulk best-efforts PEP 257 docstrings

Done by `docformatter`, it can't get the summary line right if it's too
long, but adjusts the description block width and gets the shorter
docstrings right, so a lot better than doing them all by hand. The rest
will have to wait for hand curation as we go.

Author: scanny

src/docx/blkcntnr.py

@@ -13,20 +13,22 @@ class BlockItemContainer(Parented):
     """Base class for proxy objects that can contain block items.
 
     These containers include _Body, _Cell, header, footer, footnote, endnote, comment,
-    and text box objects. Provides the shared functionality to add a block item like
-    a paragraph or table.
+    and text box objects. Provides the shared functionality to add a block item like a
+    paragraph or table.
     """
 
     def __init__(self, element, parent):
         super(BlockItemContainer, self).__init__(parent)
         self._element = element
 
     def add_paragraph(self, text="", style=None):
-        """
-        Return a paragraph newly added to the end of the content in this
-        container, having `text` in a single run if present, and having
-        paragraph style `style`. If `style` is |None|, no paragraph style is
-        applied, which has the same effect as applying the 'Normal' style.
+        """Return paragraph newly added to the end of the content in this container.
+
+        The paragraph has `text` in a single run if present, and is given paragraph
+        style `style`.
+
+        If `style` is |None|, no paragraph style is applied, which has the same effect
+        as applying the 'Normal' style.
         """
         paragraph = self._add_paragraph()
         if text:
@@ -36,38 +38,36 @@ def add_paragraph(self, text="", style=None):
         return paragraph
 
     def add_table(self, rows, cols, width):
+        """Return table of `width` having `rows` rows and `cols` columns.
+
+        The table is appended appended at the end of the content in this container.
+
+        `width` is evenly distributed between the table columns.
         """
-        Return a table of `width` having `rows` rows and `cols` columns,
-        newly appended to the content in this container. `width` is evenly
-        distributed between the table columns.
-        """
-        from .table import Table
+        from docx.table import Table
 
         tbl = CT_Tbl.new_tbl(rows, cols, width)
         self._element._insert_tbl(tbl)
         return Table(tbl, self)
 
     @property
     def paragraphs(self):
-        """
-        A list containing the paragraphs in this container, in document
-        order. Read-only.
+        """A list containing the paragraphs in this container, in document order.
+
+        Read-only.
         """
         return [Paragraph(p, self) for p in self._element.p_lst]
 
     @property
     def tables(self):
-        """
-        A list containing the tables in this container, in document order.
+        """A list containing the tables in this container, in document order.
+
         Read-only.
         """
         from .table import Table
 
         return [Table(tbl, self) for tbl in self._element.tbl_lst]
 
     def _add_paragraph(self):
-        """
-        Return a paragraph newly added to the end of the content in this
-        container.
-        """
+        """Return paragraph newly added to the end of the content in this container."""
         return Paragraph(self._element.add_p(), self)

src/docx/dml/color.py

@@ -6,10 +6,8 @@
 
 
 class ColorFormat(ElementProxy):
-    """
-    Provides access to color settings such as RGB color, theme color, and
-    luminance adjustments.
-    """
+    """Provides access to color settings such as RGB color, theme color, and luminance
+    adjustments."""
 
     __slots__ = ()
 
@@ -18,22 +16,19 @@ def __init__(self, rPr_parent):
 
     @property
     def rgb(self):
-        """
-        An |RGBColor| value or |None| if no RGB color is specified.
-
-        When :attr:`type` is `MSO_COLOR_TYPE.RGB`, the value of this property
-        will always be an |RGBColor| value. It may also be an |RGBColor|
-        value if :attr:`type` is `MSO_COLOR_TYPE.THEME`, as Word writes the
-        current value of a theme color when one is assigned. In that case,
-        the RGB value should be interpreted as no more than a good guess
-        however, as the theme color takes precedence at rendering time. Its
-        value is |None| whenever :attr:`type` is either |None| or
-        `MSO_COLOR_TYPE.AUTO`.
-
-        Assigning an |RGBColor| value causes :attr:`type` to become
-        `MSO_COLOR_TYPE.RGB` and any theme color is removed. Assigning |None|
-        causes any color to be removed such that the effective color is
-        inherited from the style hierarchy.
+        """An |RGBColor| value or |None| if no RGB color is specified.
+
+        When :attr:`type` is `MSO_COLOR_TYPE.RGB`, the value of this property will
+        always be an |RGBColor| value. It may also be an |RGBColor| value if
+        :attr:`type` is `MSO_COLOR_TYPE.THEME`, as Word writes the current value of a
+        theme color when one is assigned. In that case, the RGB value should be
+        interpreted as no more than a good guess however, as the theme color takes
+        precedence at rendering time. Its value is |None| whenever :attr:`type` is
+        either |None| or `MSO_COLOR_TYPE.AUTO`.
+
+        Assigning an |RGBColor| value causes :attr:`type` to become `MSO_COLOR_TYPE.RGB`
+        and any theme color is removed. Assigning |None| causes any color to be removed
+        such that the effective color is inherited from the style hierarchy.
         """
         color = self._color
         if color is None:
@@ -53,18 +48,16 @@ def rgb(self, value):
 
     @property
     def theme_color(self):
-        """
-        A member of :ref:`MsoThemeColorIndex` or |None| if no theme color is
-        specified. When :attr:`type` is `MSO_COLOR_TYPE.THEME`, the value of
-        this property will always be a member of :ref:`MsoThemeColorIndex`.
-        When :attr:`type` has any other value, the value of this property is
-        |None|.
-
-        Assigning a member of :ref:`MsoThemeColorIndex` causes :attr:`type`
-        to become `MSO_COLOR_TYPE.THEME`. Any existing RGB value is retained
-        but ignored by Word. Assigning |None| causes any color specification
-        to be removed such that the effective color is inherited from the
-        style hierarchy.
+        """Member of :ref:`MsoThemeColorIndex` or |None| if no theme color is specified.
+
+        When :attr:`type` is `MSO_COLOR_TYPE.THEME`, the value of this property will
+        always be a member of :ref:`MsoThemeColorIndex`. When :attr:`type` has any other
+        value, the value of this property is |None|.
+
+        Assigning a member of :ref:`MsoThemeColorIndex` causes :attr:`type` to become
+        `MSO_COLOR_TYPE.THEME`. Any existing RGB value is retained but ignored by Word.
+        Assigning |None| causes any color specification to be removed such that the
+        effective color is inherited from the style hierarchy.
         """
         color = self._color
         if color is None or color.themeColor is None:
@@ -80,12 +73,13 @@ def theme_color(self, value):
         self._element.get_or_add_rPr().get_or_add_color().themeColor = value
 
     @property
-    def type(self):
-        """
-        Read-only. A member of :ref:`MsoColorType`, one of RGB, THEME, or
-        AUTO, corresponding to the way this color is defined. Its value is
-        |None| if no color is applied at this level, which causes the
-        effective color to be inherited from the style hierarchy.
+    def type(self) -> MSO_COLOR_TYPE:
+        """Read-only.
+
+        A member of :ref:`MsoColorType`, one of RGB, THEME, or AUTO, corresponding to
+        the way this color is defined. Its value is |None| if no color is applied at
+        this level, which causes the effective color to be inherited from the style
+        hierarchy.
         """
         color = self._color
         if color is None:
@@ -98,9 +92,9 @@ def type(self):
 
     @property
     def _color(self):
-        """
-        Return `w:rPr/w:color` or |None| if not present. Helper to factor out
-        repetitive element access.
+        """Return `w:rPr/w:color` or |None| if not present.
+
+        Helper to factor out repetitive element access.
         """
         rPr = self._element.rPr
         if rPr is None: