Skip to content

Commit 1a493cc

Browse files
author
Steve Canny
committed
reorg: extract docx.text.paragraph module
1 parent c1215cf commit 1a493cc

File tree

13 files changed

+138
-132
lines changed

13 files changed

+138
-132
lines changed

‎docs/api/text.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,20 @@
44
Text-related objects
55
====================
66

7-
.. currentmodule:: docx.text
8-
97

108
|Paragraph| objects
119
-------------------
1210

11+
.. currentmodule:: docx.text.paragraph
12+
1313
.. autoclass:: Paragraph
1414
:members:
1515

1616

1717
|Run| objects
1818
-------------
1919

20+
.. currentmodule:: docx.text.run
21+
2022
.. autoclass:: Run
2123
:members:

‎docs/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@
129129
130130
.. |Table| replace:: :class:`.Table`
131131
132-
.. |Text| replace:: :class:`Text`
132+
.. |_Text| replace:: :class:`._Text`
133133
134134
.. |True| replace:: ``True``
135135

‎docx/blkcntnr.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from __future__ import absolute_import, print_function
1010

1111
from .shared import Parented
12-
from .text import Paragraph
12+
from .text.paragraph import Paragraph
1313

1414

1515
class BlockItemContainer(Parented):

‎docx/text/__init__.py‎

Lines changed: 0 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +0,0 @@
1-
# encoding: utf-8
2-
3-
"""
4-
Text-related proxy types for python-docx, such as Paragraph and Run.
5-
"""
6-
7-
from __future__ import absolute_import, print_function, unicode_literals
8-
9-
from .run import Run
10-
from ..shared import Parented
11-
12-
13-
class Paragraph(Parented):
14-
"""
15-
Proxy object wrapping ``<w:p>`` element.
16-
"""
17-
def __init__(self, p, parent):
18-
super(Paragraph, self).__init__(parent)
19-
self._p = p
20-
21-
def add_run(self, text=None, style=None):
22-
"""
23-
Append a run to this paragraph containing *text* and having character
24-
style identified by style ID *style*. *text* can contain tab
25-
(``\\t``) characters, which are converted to the appropriate XML form
26-
for a tab. *text* can also include newline (``\\n``) or carriage
27-
return (``\\r``) characters, each of which is converted to a line
28-
break.
29-
"""
30-
r = self._p.add_r()
31-
run = Run(r, self)
32-
if text:
33-
run.text = text
34-
if style:
35-
run.style = style
36-
return run
37-
38-
@property
39-
def alignment(self):
40-
"""
41-
A member of the :ref:`WdParagraphAlignment` enumeration specifying
42-
the justification setting for this paragraph. A value of |None|
43-
indicates the paragraph has no directly-applied alignment value and
44-
will inherit its alignment value from its style hierarchy. Assigning
45-
|None| to this property removes any directly-applied alignment value.
46-
"""
47-
return self._p.alignment
48-
49-
@alignment.setter
50-
def alignment(self, value):
51-
self._p.alignment = value
52-
53-
def clear(self):
54-
"""
55-
Return this same paragraph after removing all its content.
56-
Paragraph-level formatting, such as style, is preserved.
57-
"""
58-
self._p.clear_content()
59-
return self
60-
61-
def insert_paragraph_before(self, text=None, style=None):
62-
"""
63-
Return a newly created paragraph, inserted directly before this
64-
paragraph. If *text* is supplied, the new paragraph contains that
65-
text in a single run. If *style* is provided, that style is assigned
66-
to the new paragraph.
67-
"""
68-
p = self._p.add_p_before()
69-
paragraph = Paragraph(p, self._parent)
70-
if text:
71-
paragraph.add_run(text)
72-
if style is not None:
73-
paragraph.style = style
74-
return paragraph
75-
76-
@property
77-
def runs(self):
78-
"""
79-
Sequence of |Run| instances corresponding to the <w:r> elements in
80-
this paragraph.
81-
"""
82-
return [Run(r, self) for r in self._p.r_lst]
83-
84-
@property
85-
def style(self):
86-
"""
87-
Paragraph style for this paragraph. Read/Write.
88-
"""
89-
style = self._p.style
90-
return style if style is not None else 'Normal'
91-
92-
@style.setter
93-
def style(self, style):
94-
self._p.style = None if style == 'Normal' else style
95-
96-
@property
97-
def text(self):
98-
"""
99-
String formed by concatenating the text of each run in the paragraph.
100-
Tabs and line breaks in the XML are mapped to ``\\t`` and ``\\n``
101-
characters respectively.
102-
103-
Assigning text to this property causes all existing paragraph content
104-
to be replaced with a single run containing the assigned text.
105-
A ``\\t`` character in the text is mapped to a ``<w:tab/>`` element
106-
and each ``\\n`` or ``\\r`` character is mapped to a line break.
107-
Paragraph-level formatting, such as style, is preserved. All
108-
run-level formatting, such as bold or italic, is removed.
109-
"""
110-
text = ''
111-
for run in self.runs:
112-
text += run.text
113-
return text
114-
115-
@text.setter
116-
def text(self, text):
117-
self.clear()
118-
self.add_run(text)

‎docx/text/paragraph.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# encoding: utf-8
2+
3+
"""
4+
Paragraph-related proxy types.
5+
"""
6+
7+
from __future__ import absolute_import, print_function, unicode_literals
8+
9+
from .run import Run
10+
from ..shared import Parented
11+
12+
13+
class Paragraph(Parented):
14+
"""
15+
Proxy object wrapping ``<w:p>`` element.
16+
"""
17+
def __init__(self, p, parent):
18+
super(Paragraph, self).__init__(parent)
19+
self._p = p
20+
21+
def add_run(self, text=None, style=None):
22+
"""
23+
Append a run to this paragraph containing *text* and having character
24+
style identified by style ID *style*. *text* can contain tab
25+
(``\\t``) characters, which are converted to the appropriate XML form
26+
for a tab. *text* can also include newline (``\\n``) or carriage
27+
return (``\\r``) characters, each of which is converted to a line
28+
break.
29+
"""
30+
r = self._p.add_r()
31+
run = Run(r, self)
32+
if text:
33+
run.text = text
34+
if style:
35+
run.style = style
36+
return run
37+
38+
@property
39+
def alignment(self):
40+
"""
41+
A member of the :ref:`WdParagraphAlignment` enumeration specifying
42+
the justification setting for this paragraph. A value of |None|
43+
indicates the paragraph has no directly-applied alignment value and
44+
will inherit its alignment value from its style hierarchy. Assigning
45+
|None| to this property removes any directly-applied alignment value.
46+
"""
47+
return self._p.alignment
48+
49+
@alignment.setter
50+
def alignment(self, value):
51+
self._p.alignment = value
52+
53+
def clear(self):
54+
"""
55+
Return this same paragraph after removing all its content.
56+
Paragraph-level formatting, such as style, is preserved.
57+
"""
58+
self._p.clear_content()
59+
return self
60+
61+
def insert_paragraph_before(self, text=None, style=None):
62+
"""
63+
Return a newly created paragraph, inserted directly before this
64+
paragraph. If *text* is supplied, the new paragraph contains that
65+
text in a single run. If *style* is provided, that style is assigned
66+
to the new paragraph.
67+
"""
68+
p = self._p.add_p_before()
69+
paragraph = Paragraph(p, self._parent)
70+
if text:
71+
paragraph.add_run(text)
72+
if style is not None:
73+
paragraph.style = style
74+
return paragraph
75+
76+
@property
77+
def runs(self):
78+
"""
79+
Sequence of |Run| instances corresponding to the <w:r> elements in
80+
this paragraph.
81+
"""
82+
return [Run(r, self) for r in self._p.r_lst]
83+
84+
@property
85+
def style(self):
86+
"""
87+
Paragraph style for this paragraph. Read/Write.
88+
"""
89+
style = self._p.style
90+
return style if style is not None else 'Normal'
91+
92+
@style.setter
93+
def style(self, style):
94+
self._p.style = None if style == 'Normal' else style
95+
96+
@property
97+
def text(self):
98+
"""
99+
String formed by concatenating the text of each run in the paragraph.
100+
Tabs and line breaks in the XML are mapped to ``\\t`` and ``\\n``
101+
characters respectively.
102+
103+
Assigning text to this property causes all existing paragraph content
104+
to be replaced with a single run containing the assigned text.
105+
A ``\\t`` character in the text is mapped to a ``<w:tab/>`` element
106+
and each ``\\n`` or ``\\r`` character is mapped to a line break.
107+
Paragraph-level formatting, such as style, is preserved. All
108+
run-level formatting, such as bold or italic, is removed.
109+
"""
110+
text = ''
111+
for run in self.runs:
112+
text += run.text
113+
return text
114+
115+
@text.setter
116+
def text(self, text):
117+
self.clear()
118+
self.add_run(text)

‎features/steps/paragraph.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
from docx.enum.text import WD_ALIGN_PARAGRAPH
1111
from docx.oxml import parse_xml
1212
from docx.oxml.ns import nsdecls
13-
from docx.text import Paragraph
13+
from docx.text.paragraph import Paragraph
1414

1515
from helpers import saved_docx_path, test_docx, test_text
1616

‎features/steps/text.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
from docx.enum.text import WD_BREAK, WD_UNDERLINE
1515
from docx.oxml import parse_xml
1616
from docx.oxml.ns import nsdecls, qn
17-
from docx.text import Run
17+
from docx.text.run import Run
1818

1919
from helpers import test_docx, test_file, test_text
2020

‎tests/parts/test_document.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@
1818
from docx.section import Section
1919
from docx.shape import InlineShape
2020
from docx.table import Table
21-
from docx.text import Paragraph, Run
21+
from docx.text.paragraph import Paragraph
22+
from docx.text.run import Run
2223

2324
from ..oxml.parts.unitdata.document import a_body, a_document
2425
from ..oxml.unitdata.text import a_p

‎tests/test_api.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@
2121
from docx.section import Section
2222
from docx.shape import InlineShape
2323
from docx.table import Table
24-
from docx.text import Paragraph, Run
24+
from docx.text.paragraph import Paragraph
25+
from docx.text.run import Run
2526

2627
from .unitutil.mock import (
2728
instance_mock, class_mock, method_mock, property_mock, var_mock
@@ -203,7 +204,7 @@ def add_picture_fixture(self, request, run_, picture_):
203204
document = Document()
204205
image_path_ = instance_mock(request, str, name='image_path_')
205206
width, height = 100, 200
206-
class_mock(request, 'docx.text.Run', return_value=run_)
207+
class_mock(request, 'docx.text.paragraph.Run', return_value=run_)
207208
run_.add_picture.return_value = picture_
208209
return (document, image_path_, width, height, run_, picture_)
209210

‎tests/test_blkcntnr.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
from docx.blkcntnr import BlockItemContainer
1212
from docx.table import Table
13-
from docx.text import Paragraph
13+
from docx.text.paragraph import Paragraph
1414

1515
from .unitutil.cxml import element, xml
1616

0 commit comments

Comments
 (0)