8000 rfctr: add types to Paragraph and its tests · python-openxml/python-docx@ceb8cbe · GitHub
[go: up one dir, main page]

Skip to content

Commit ceb8cbe

Browse files
committed
rfctr: add types to Paragraph and its tests
1 parent 45bf74b commit ceb8cbe

File tree

1 file changed

+25
-12
lines changed

1 file changed

+25
-12
lines changed

src/docx/text/paragraph.py

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,37 @@
11
"""Paragraph-related proxy types."""
22

3+
from __future__ import annotations
4+
5+
from typing import List
6+
7+
from typing_extensions import Self
8+
9+
from docx import types as t
310
from docx.enum.style import WD_STYLE_TYPE
11+
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
12+
from docx.oxml.text.paragraph import CT_P
413
from docx.shared import Parented
14+
from docx.styles.style import CharacterStyle, ParagraphStyle
515
from docx.text.parfmt import ParagraphFormat
616
from docx.text.run import Run
717

818

919
class Paragraph(Parented):
1020
"""Proxy object wrapping a `<w:p>` element."""
1121

12-
def __init__(self, p, parent):
22+
def __init__(self, p: CT_P, parent: t.StoryChild):
1323
super(Paragraph, self).__init__(parent)
1424
self._p = self._element = p
1525

16-
def add_run(self, text=None, style=None):
17-
"""Append a run to this paragraph containing `text` and having character style
18-
identified by style ID `style`.
26+
def add_run(
27+
self, text: str | None = None, style: str | CharacterStyle | None = None
28+
) -> Run:
29+
"""Append run containing `text` and having character-style `style`.
1930
2031
`text` can contain tab (``\\t``) characters, which are converted to the
2132
appropriate XML form for a tab. `text` can also include newline (``\\n``) or
2233
carriage return (``\\r``) characters, each of which is converted to a line
23-
break.
34+
break. When `text` is `None`, the new run is empty.
2435
"""
2536
r = self._p.add_r()
2637
run = Run(r, self)
@@ -31,7 +42,7 @@ def add_run(self, text=None, style=None):
3142
return run
3243

3344
@property
34-
def alignment(self):
45+
def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None:
3546
"""A member of the :ref:`WdParagraphAlignment` enumeration specifying the
3647
justification setting for this paragraph.
3748
@@ -42,7 +53,7 @@ def alignment(self):
4253
return self._p.alignment
4354

4455
@alignment.setter
45-
def alignment(self, value):
56+
def alignment(self, value: WD_PARAGRAPH_ALIGNMENT):
4657
self._p.alignment = value
4758

4859
def clear(self):
@@ -53,7 +64,9 @@ def clear(self):
5364
self._p.clear_content()
5465
return self
5566

56-
def insert_paragraph_before(self, text=None, style=None):
67+
def insert_paragraph_before(
68+
self, text: str | None = None, style: str | ParagraphStyle | None = None
69+
) -> Self:
5770
"""Return a newly created paragraph, inserted directly before this paragraph.
5871
5972
If `text` is supplied, the new paragraph contains that text in a single run. If
@@ -73,13 +86,13 @@ def paragraph_format(self):
7386
return ParagraphFormat(self._element)
7487

7588
@property
76-
def runs(self):
89+
def runs(self) -> List[Run]:
7790
"""Sequence of |Run| instances corresponding to the <w:r> elements in this
7891
paragraph."""
7992
return [Run(r, self) for r in self._p.r_lst]
8093

8194
@property
82-
def style(self):
95+
def style(self) -> ParagraphStyle | None:
8396
"""Read/Write.
8497
8598
|_ParagraphStyle| object representing the style assigned to this paragraph. If
@@ -92,7 +105,7 @@ def style(self):
92105
return self.part.get_style(style_id, WD_STYLE_TYPE.PARAGRAPH)
93106

94107
@style.setter
95-
def style(self, style_or_name):
108+
def style(self, style_or_name: str | ParagraphStyle | None):
96109
style_id = self.part.get_style_id(style_or_name, WD_STYLE_TYPE.PARAGRAPH)
97110
self._p.style = style_id
98111

@@ -115,7 +128,7 @@ def text(self) -> str:
115128
return text
116129

117130
@text.setter
118-
def text(self, text):
131+
def text(self, text: str | None):
119132
self.clear()
120133
self.add_run(text)
121134

0 commit comments

Comments
 (0)
0