1
1
"""Paragraph-related proxy types."""
2
2
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
3
10
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
4
13
from docx .shared import Parented
14
+ from docx .styles .style import CharacterStyle , ParagraphStyle
5
15
from docx .text .parfmt import ParagraphFormat
6
16
from docx .text .run import Run
7
17
8
18
9
19
class Paragraph (Parented ):
10
20
"""Proxy object wrapping a `<w:p>` element."""
11
21
12
- def __init__ (self , p , parent ):
22
+ def __init__ (self , p : CT_P , parent : t . StoryChild ):
13
23
super (Paragraph , self ).__init__ (parent )
14
24
self ._p = self ._element = p
15
25
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`.
19
30
20
31
`text` can contain tab (``\\ t``) characters, which are converted to the
21
32
appropriate XML form for a tab. `text` can also include newline (``\\ n``) or
22
33
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.
24
35
"""
25
36
r = self ._p .add_r ()
26
37
run = Run (r , self )
@@ -31,7 +42,7 @@ def add_run(self, text=None, style=None):
31
42
return run
32
43
33
44
@property
34
- def alignment (self ):
45
+ def alignment (self ) -> WD_PARAGRAPH_ALIGNMENT | None :
35
46
"""A member of the :ref:`WdParagraphAlignment` enumeration specifying the
36
47
justification setting for this paragraph.
37
48
@@ -42,7 +53,7 @@ def alignment(self):
42
53
return self ._p .alignment
43
54
44
55
@alignment .setter
45
- def alignment (self , value ):
56
+ def alignment (self , value : WD_PARAGRAPH_ALIGNMENT ):
46
57
self ._p .alignment = value
47
58
48
59
def clear (self ):
@@ -53,7 +64,9 @@ def clear(self):
53
64
self ._p .clear_content ()
54
65
return self
55
66
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 :
57
70
"""Return a newly created paragraph, inserted directly before this paragraph.
58
71
59
72
If `text` is supplied, the new paragraph contains that text in a single run. If
@@ -73,13 +86,13 @@ def paragraph_format(self):
73
86
return ParagraphFormat (self ._element )
74
87
75
88
@property
76
- def runs (self ):
89
+ def runs (self ) -> List [ Run ] :
77
90
"""Sequence of |Run| instances corresponding to the <w:r> elements in this
78
91
paragraph."""
79
92
return [Run (r , self ) for r in self ._p .r_lst ]
80
93
81
94
@property
82
- def style (self ):
95
+ def style (self ) -> ParagraphStyle | None :
83
96
"""Read/Write.
84
97
85
98
|_ParagraphStyle| object representing the style assigned to this paragraph. If
@@ -92,7 +105,7 @@ def style(self):
92
105
return self .part .get_style (style_id , WD_STYLE_TYPE .PARAGRAPH )
93
106
94
107
@style .setter
95
- def style (self , style_or_name ):
108
+ def style (self , style_or_name : str | ParagraphStyle | None ):
96
109
style_id = self .part .get_style_id (style_or_name , WD_STYLE_TYPE .PARAGRAPH )
97
110
self ._p .style = style_id
98
111
@@ -115,7 +128,7 @@ def text(self) -> str:
115
128
return text
116
129
117
130
@text .setter
118
- def text (self , text ):
131
+ def text (self , text : str | None ):
119
132
self .clear ()
120
133
self .add_run (text )
121
134
0 commit comments