Skip to content

Commit c1215cf

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

3 files changed

Lines changed: 383 additions & 373 deletions

File tree

‎docx/text/__init__.py‎

Lines changed: 1 addition & 372 deletions
Original file line numberDiff line numberDiff line change
@@ -6,55 +6,10 @@
66

77
from __future__ import absolute_import, print_function, unicode_literals
88

9-
from ..enum.text import WD_BREAK
9+
from .run import Run
1010
from ..shared import Parented
1111

1212

13-
def boolproperty(f):
14-
"""
15-
@boolproperty decorator. Decorated method must return the XML element
16-
name of the boolean property element occuring under rPr. Causes
17-
a read/write tri-state property to be added to the class having the name
18-
of the decorated function.
19-
"""
20-
def _get_prop_value(parent, attr_name):
21-
return getattr(parent, attr_name)
22-
23-
def _remove_prop(parent, attr_name):
24-
remove_method_name = '_remove_%s' % attr_name
25-
remove_method = getattr(parent, remove_method_name)
26-
remove_method()
27-
28-
def _add_prop(parent, attr_name):
29-
add_method_name = '_add_%s' % attr_name
30-
add_method = getattr(parent, add_method_name)
31-
return add_method()
32-
33-
def getter(obj):
34-
r, attr_name = obj._r, f(obj)
35-
if r.rPr is None:
36-
return None
37-
prop_value = _get_prop_value(r.rPr, attr_name)
38-
if prop_value is None:
39-
return None
40-
return prop_value.val
41-
42-
def setter(obj, value):
43-
if value not in (True, False, None):
44-
raise ValueError(
45-
"assigned value must be True, False, or None, got '%s'"
46-
% value
47-
)
48-
r, attr_name = obj._r, f(obj)
49-
rPr = r.get_or_add_rPr()
50-
_remove_prop(rPr, attr_name)
51-
if value is not None:
52-
elm = _add_prop(rPr, attr_name)
53-
elm.val = value
54-
55-
return property(getter, setter, doc=f.__doc__)
56-
57-
5813
class Paragraph(Parented):
5914
"""
6015
Proxy object wrapping ``<w:p>`` element.
@@ -161,329 +116,3 @@ def text(self):
161116
def text(self, text):
162117
self.clear()
163118
self.add_run(text)
164-
165-
166-
class Run(Parented):
167-
"""
168-
Proxy object wrapping ``<w:r>`` element. Several of the properties on Run
169-
take a tri-state value, |True|, |False|, or |None|. |True| and |False|
170-
correspond to on and off respectively. |None| indicates the property is
171-
not specified directly on the run and its effective value is taken from
172-
the style hierarchy.
173-
"""
174-
def __init__(self, r, parent):
175-
super(Run, self).__init__(parent)
176-
self._r = r
177-
178-
def add_break(self, break_type=WD_BREAK.LINE):
179-
"""
180-
Add a break element of *break_type* to this run. *break_type* can
181-
take the values `WD_BREAK.LINE`, `WD_BREAK.PAGE`, and
182-
`WD_BREAK.COLUMN` where `WD_BREAK` is imported from `docx.enum.text`.
183-
*break_type* defaults to `WD_BREAK.LINE`.
184-
"""
185-
type_, clear = {
186-
WD_BREAK.LINE: (None, None),
187-
WD_BREAK.PAGE: ('page', None),
188-
WD_BREAK.COLUMN: ('column', None),
189-
WD_BREAK.LINE_CLEAR_LEFT: ('textWrapping', 'left'),
190-
WD_BREAK.LINE_CLEAR_RIGHT: ('textWrapping', 'right'),
191-
WD_BREAK.LINE_CLEAR_ALL: ('textWrapping', 'all'),
192-
}[break_type]
193-
br = self._r.add_br()
194-
if type_ is not None:
195-
br.type = type_
196-
if clear is not None:
197-
br.clear = clear
198-
199-
def add_picture(self, image_path_or_stream, width=None, height=None):
200-
"""
201-
Return an |InlineShape| instance containing the image identified by
202-
*image_path_or_stream*, added to the end of this run.
203-
*image_path_or_stream* can be a path (a string) or a file-like object
204-
containing a binary image. If neither width nor height is specified,
205-
the picture appears at its native size. If only one is specified, it
206-
is used to compute a scaling factor that is then applied to the
207-
unspecified dimension, preserving the aspect ratio of the image. The
208-
native size of the picture is calculated using the dots-per-inch
209-
(dpi) value specified in the image file, defaulting to 72 dpi if no
210-
value is specified, as is often the case.
211-
"""
212-
inline_shapes = self.part.inline_shapes
213-
picture = inline_shapes.add_picture(image_path_or_stream, self)
214-
215-
# scale picture dimensions if width and/or height provided
216-
if width is not None or height is not None:
217-
native_width, native_height = picture.width, picture.height
218-
if width is None:
219-
scaling_factor = float(height) / float(native_height)
220-
width = int(round(native_width * scaling_factor))
221-
elif height is None:
222-
scaling_factor = float(width) / float(native_width)
223-
height = int(round(native_height * scaling_factor))
224-
# set picture to scaled dimensions
225-
picture.width = width
226-
picture.height = height
227-
228-
return picture
229-
230-
def add_tab(self):
231-
"""
232-
Add a ``<w:tab/>`` element at the end of the run, which Word
233-
interprets as a tab character.
234-
"""
235-
self._r._add_tab()
236-
237-
def add_text(self, text):
238-
"""
239-
Returns a newly appended |Text| object (corresponding to a new
240-
``<w:t>`` child element) to the run, containing *text*. Compare with
241-
the possibly more friendly approach of assigning text to the
242-
:attr:`Run.text` property.
243-
"""
244-
t = self._r.add_t(text)
245-
return Text(t)
246-
247-
@boolproperty
248-
def all_caps(self):
249-
"""
250-
Read/write. Causes the text of the run to appear in capital letters.
251-
"""
252-
return 'caps'
253-
254-
@boolproperty
255-
def bold(self):
256-
"""
257-
Read/write. Causes the text of the run to appear in bold.
258-
"""
259-
return 'b'
260-
261-
def clear(self):
262-
"""
263-
Return reference to this run after removing all its content. All run
264-
formatting is preserved.
265-
"""
266-
self._r.clear_content()
267-
return self
268-
269-
@boolproperty
270-
def complex_script(self):
271-
"""
272-
Read/write tri-state value. When |True|, causes the characters in the
273-
run to be treated as complex script regardless of their Unicode
274-
values.
275-
"""
276-
return 'cs'
277-
278-
@boolproperty
279-
def cs_bold(self):
280-
"""
281-
Read/write tri-state value. When |True|, causes the complex script
282-
characters in the run to be displayed in bold typeface.
283-
"""
284-
return 'bCs'
285-
286-
@boolproperty
287-
def cs_italic(self):
288-
"""
289-
Read/write tri-state value. When |True|, causes the complex script
290-
characters in the run to be displayed in italic typeface.
291-
"""
292-
return 'iCs'
293-
294-
@boolproperty
295-
def double_strike(self):
296-
"""
297-
Read/write tri-state value. When |True|, causes the text in the run
298-
to appear with double strikethrough.
299-
"""
300-
return 'dstrike'
301-
302-
@boolproperty
303-
def emboss(self):
304-
"""
305-
Read/write tri-state value. When |True|, causes the text in the run
306-
to appear as if raised off the page in relief.
307-
"""
308-
return 'emboss'
309-
310-
@boolproperty
311-
def hidden(self):
312-
"""
313-
Read/write tri-state value. When |True|, causes the text in the run
314-
to be hidden from display, unless applications settings force hidden
315-
text to be shown.
316-
"""
317-
return 'vanish'
318-
319-
@boolproperty
320-
def italic(self):
321-
"""
322-
Read/write tri-state value. When |True|, causes the text of the run
323-
to appear in italics.
324-
"""
325-
return 'i'
326-
327-
@boolproperty
328-
def imprint(self):
329-
"""
330-
Read/write tri-state value. When |True|, causes the text in the run
331-
to appear as if pressed into the page.
332-
"""
333-
return 'imprint'
334-
335-
@boolproperty
336-
def math(self):
337-
"""
338-
Read/write tri-state value. When |True|, specifies this run contains
339-
WML that should be handled as though it was Office Open XML Math.
340-
"""
341-
return 'oMath'
342-
343-
@boolproperty
344-
def no_proof(self):
345-
"""
346-
Read/write tri-state value. When |True|, specifies that the contents
347-
of this run should not report any errors when the document is scanned
348-
for spelling and grammar.
349-
"""
350-
return 'noProof'
351-
352-
@boolproperty
353-
def outline(self):
354-
"""
355-
Read/write tri-state value. When |True| causes the characters in the
356-
run to appear as if they have an outline, by drawing a one pixel wide
357-
border around the inside and outside borders of each character glyph.
358-
"""
359-
return 'outline'
360-
361-
@boolproperty
362-
def rtl(self):
363-
"""
364-
Read/write tri-state value. When |True| causes the text in the run
365-
to have right-to-left characteristics.
366-
"""
367-
return 'rtl'
368-
369-
@boolproperty
370-
def shadow(self):
371-
"""
372-
Read/write tri-state value. When |True| causes the text in the run
373-
to appear as if each character has a shadow.
374-
"""
375-
return 'shadow'
376-
377-
@boolproperty
378-
def small_caps(self):
379-
"""
380-
Read/write tri-state value. When |True| causes the lowercase
381-
characters in the run to appear as capital letters two points smaller
382-
than the font size specified for the run.
383-
"""
384-
return 'smallCaps'
385-
386-
@boolproperty
387-
def snap_to_grid(self):
388-
"""
389-
Read/write tri-state value. When |True| causes the run to use the
390-
document grid characters per line settings defined in the docGrid
391-
element when laying out the characters in this run.
392-
"""
393-
return 'snapToGrid'
394-
395-
@boolproperty
396-
def spec_vanish(self):
397-
"""
398-
Read/write tri-state value. When |True|, specifies that the given run
399-
shall always behave as if it is hidden, even when hidden text is
400-
being displayed in the current document. The property has a very
401-
narrow, specialized use related to the table of contents. Consult the
402-
spec (§17.3.2.36) for more details.
403-
"""
404-
return 'specVanish'
405-
406-
@boolproperty
407-
def strike(self):
408-
"""
409-
Read/write tri-state value. When |True| causes the text in the run
410-
to appear with a single horizontal line through the center of the
411-
line.
412-
"""
413-
return 'strike'
414-
415-
@property
416-
def style(self):
417-
"""
418-
Read/write. The string style ID of the character style applied to
419-
this run, or |None| if it has no directly-applied character style.
420-
Setting this property to |None| causes any directly-applied character
421-
style to be removed such that the run inherits character formatting
422-
from its containing paragraph.
423-
"""
424-
return self._r.style
425-
426-
@style.setter
427-
def style(self, char_style):
428-
self._r.style = char_style
429-
430-
@property
431-
def text(self):
432-
"""
433-
String formed by concatenating the text equivalent of each run
434-
content child element into a Python string. Each ``<w:t>`` element
435-
adds the text characters it contains. A ``<w:tab/>`` element adds
436-
a ``\\t`` character. A ``<w:cr/>`` or ``<w:br>`` element each add
437-
a ``\\n`` character. Note that a ``<w:br>`` element can indicate
438-
a page break or column break as well as a line break. All ``<w:br>``
439-
elements translate to a single ``\\n`` character regardless of their
440-
type. All other content child elements, such as ``<w:drawing>``, are
441-
ignored.
442-
443-
Assigning text to this property has the reverse effect, translating
444-
each ``\\t`` character to a ``<w:tab/>`` element and each ``\\n`` or
445-
``\\r`` character to a ``<w:cr/>`` element. Any existing run content
446-
is replaced. Run formatting is preserved.
447-
"""
448-
return self._r.text
449-
450-
@text.setter
451-
def text(self, text):
452-
self._r.text = text
453-
454-
@property
455-
def underline(self):
456-
"""
457-
The underline style for this |Run|, one of |None|, |True|, |False|,
458-
or a value from :ref:`WdUnderline`. A value of |None| indicates the
459-
run has no directly-applied underline value and so will inherit the
460-
underline value of its containing paragraph. Assigning |None| to this
461-
property removes any directly-applied underline value. A value of
462-
|False| indicates a directly-applied setting of no underline,
463-
overriding any inherited value. A value of |True| indicates single
464-
underline. The values from :ref:`WdUnderline` are used to specify
465-
other outline styles such as double, wavy, and dotted.
466-
"""
467-
return self._r.underline
468-
469-
@underline.setter
470-
def underline(self, value):
471-
self._r.underline = value
472-
473-
@boolproperty
474-
def web_hidden(self):
475-
"""
476-
Read/write tri-state value. When |True|, specifies that the contents
477-
of this run shall be hidden when the document is displayed in web
478-
page view.
479-
"""
480-
return 'webHidden'
481-
482-
483-
class Text(object):
484-
"""
485-
Proxy object wrapping ``<w:t>`` element.
486-
"""
487-
def __init__(self, t_elm):
488-
super(Text, self).__init__()
489-
self._t = t_elm

0 commit comments

Comments
 (0)