python Word 文档

利用 python-docx 模块， Python 可以创建和修改 Word 文档，它带有.docx 文件扩展名。运行 pip install python-docx，可以安装该模块。

注意：OSI 参考模型最初是在 1983 年由国际标准化组织出版，标准号为 ISO 7498。在第一次用 pip 安装 python-docx 时，注意要安装 python-docx，而不是 docx。安装名称 docx 是指另一个模块，本书没有介绍。但是，在导入 python-docx 模块时，需要执行 import docx，而不是 import python-docx。

如果你没有 Word 软件， LibreOffice Writer 和 OpenOffice Writer 都是免费的替代软件，它们可以在 Windows、 OS X 和 Linux 上打开.docx 文件。可以分别从https://www.libreoffice.org 和 http://openoffice.org 下载它们。 python-docx 的完整文档在 https://python-docx.readthedocs.org/。尽管有针对 OS X 平台的 Word 版本， 但本章将使用 Windows 平台的 Word。和纯文本相比， .docx 文件有很多结构。这些结构在 python-docx 中用 3 种不同的类型来表示。在最高一层， Document 对象表示整个文档。 Document 对象包含一个 Paragraph 对象的列表，表示文档中的段落（用户在 Word 文档中输入时，如果按下回车，新的段落就开始了）。每个 Paragraph 对象都包含一个 Run 对象的列表。图 13-4 中的单句段落有 4 个 Run 对象。

Word 文档中的文本不仅仅是字符串。它包含与之相关的字体、大小、颜色和其他样式信息。在 Word 中，样式是这些属性的集合。一个 Run 对象是相同样式文本的延续。当文本样式发生改变时，就需要一个新的 Run 对象。
 

读取 Word 文档
让我们尝试使用 python-docx 模块。从 http://nostarch.com/automatestuff/下载demo.docx，并将它保存在当前工作目录中。然后在交互式环境中输入以下代码：

>>> import docx
>>> doc = docx.Document('demo.docx')
>>> len(doc.paragraphs)
7
>>> doc.paragraphs[0].text
'Document Title'
>>> doc.paragraphs[1].text
'A plain paragraph with some bold and some italic'
>>> len(doc.paragraphs[1].runs)
4
>>> doc.paragraphs[1].runs[0].text
'A plain paragraph with some '
>>> doc.paragraphs[1].runs[1].text
'bold'
>>> doc.paragraphs[1].runs[2].text
' and some '
>>> doc.paragraphs[1].runs[3].text
'italic'

在1行，我们在 Python 中打开了一个.docx 文件，调用 docx.Document()，传入文件名 demo.docx。这将返回一个 Document 对象，它有 paragraphs 属性，是 Paragraph对象的列表。如果我们对 doc.paragraphs 调用 len()，将返回 7。这告诉我们，该文档有 7 个 Paragraph 对象。每个 Paragraph 对象都有一个 text 属性，包含该段中文本的字符串（没有样式信息）。这里，第一个 text 属性包含'DocumentTitle'，第二个包含'A plain paragraph with some bold and some italic'。每个 Paragraph 对象也有一个 runs 属性，它是 Run 对象的列表。 Run 对象也有一个 text 属性，包含那个延续中的文本。我们看看第二个 Paragraph 对象中的 text属性， 'A plain paragraph with some bold and some italic'。对这个 Paragraph 对象调用 len()，结果告诉我们有 4 个 Run 对象。第一个对象包含'A plain paragraph with some '。然后，文本变为粗体样式，所以’bold’开始了一个新的 Run 对象。在这之后，文本又回到了非粗体的样式，这导致了第三个 Run 对象， ' and some '。最后，第四个对象包含'italic'，是斜体样式。有了 python-docx， Python 程序就能从.docx 文件中读取文本，像其他的字符串值一样使用它。
 

从.docx 文件中取得完整的文本
如果你只关心 Word 文档中的文本，不关心样式信息，就可以利用 getText()函数。它接受一个.docx 文件名，返回其中文本的字符串。打开一个新的文件编辑器窗口，输入以下代码，并保存为 readDocx.py：

!# python3

import docx

def getText(filename):
	doc = docx.Document(filename)
	fullText = []
	for para in doc.paragraphs:
		fullText.append(para.text)
	return '\n'.join(fullText)

getText()函数打开了 Word 文档，循环遍历 paragraphs 列表中的所有 Paragraph对象，然后将它们的文本添加到 fullText 列表中。循环结束后， fullText 中的字符串连接在一起，中间以换行符分隔。readDocx.py 程序可以像其他模块一样导入。现在如果你只需要 Word 文档中的文本，就可以输入以下代码：

>>> import readDocx
>>> print(readDocx.getText('demo.docx'))
Document Title
A plain paragraph with some bold and some italic
Heading, level 1
Intense quote
first item in unordered list
first item in ordered list

也可以调整 getText()，在返回字符串之前进行修改。例如，要让每一段缩进，就将文件中的 append()调用替换为：

fullText.append(' ' + para.text)

要在段落之间增加空行，就将 join()调用代码改成

return '\n\n'.join(fullText)

可以看到，只需要几行代码，就可以写出函数，读取.docx 文件，根据需要返回它的内容字符串。
 

设置 Paragraph 和 Run 对象的样式

Windows 平台的 Word 中，你可以按下 Ctrl-Alt-Shift-S，显示样式窗口并查看样式，如图 13-5 所示。在 OS X 上，可以点击 ViewStyles 菜单项，查看样式窗口。Word 和其他文字处理软件利用样式，保持类似类型的文本在视觉展现上一致，并易于修改。 例如，也许你希望将内容段落设置为 11 点， Times New Roman，左对齐，右边不对齐的文本。可以用这些设置创建一样式，将它赋给所有的文本段落。然后，如果稍后想改变文档中所有内容段落的展现形式，只要改变这种样式，所有段落都会自动更新。

对于 Word 文档，有 3 种类型的样式：段落样式可以应用于 Paragraph 对象，字符样式可以应用于 Run 对象，链接的样式可以应用于这两种对象。可以将 Paragraph 和Run 对象的 style 属性设置为一个字符串，从而设置样式。这个字符串应该是一种样式的名称。如果 style 被设置为 None，就没有样式与 Paragraph 或 Run 对象关联。默认 Word 样式的字符串如下

在设置 style 属性时，不要在样式名称中使用空格。例如，样式名称可能是 SubtleEmphasis，你应该将属性设置为字符串'SubtleEmphasis'，而不是'Subtle Emphasis'。包含空格将导致 Word 误读样式名称，并且应用失败。如果对 Run 对象应用链接的样式，需要在样式名称末尾加上'Char'。例如，对Paragraph 对象设置 Quote 链接的样式，应该使用 paragraphObj.style = 'Quote'。 但对于Run 对象，应该使用 runObj.style = 'QuoteChar'。在当前版本的 python-docx (0.7.4)中，只能使用默认的 Word 样式，以及打开的文件中已有的样式，不能创建新的样式，但这一点在将来的模块版本中可能会改变。
 

创建带有非默认样式的 Word 文档
如果想要创建的 Word文档使用默认样式以外的样式，就需要打开一个空白 Word文档，通过点击样式窗口底部的 New Style 按钮，自己创建样式（图 13-6 展示了Windows 平台上的情形）。

这将打开“Creat New Style from Formatting”对话框，在这里可以输入新样式。然后，回到交互式环境，用 docx.Document()打开这个空白 Word 文档，利用它作为Word 文档的基础。这种样式的名称现在就可以被 python-docx 使用了

Run 属性

通过 text 属性， Run 可以进一步设置样式。每个属性都可以被设置为 3 个值之一： True（该属性总是启用，不论其他样式是否应用于该 Run）、 False（该属性总是禁用）或 None（默认使用该 Run 被设置的任何属性）。表 13-1 列出了可以在 Run 对象上设置的 text 属性。

例如，为了改变 demo.docx 的样式，在交互式环境中输入以下代码：

>>> doc = docx.Document('demo.docx')
>>> doc.paragraphs[0].text
'Document Title'
>>> doc.paragraphs[0].style
'Title'
>>> doc.paragraphs[0].style = 'Normal'
>>> doc.paragraphs[1].text
'A plain paragraph with some bold and some italic'
>>> (doc.paragraphs[1].runs[0].text, doc.paragraphs[1].runs[1].text, doc.
paragraphs[1].runs[2].text, doc.paragraphs[1].runs[3].text)
('A plain paragraph with some ', 'bold', ' and some ', 'italic')
>>> doc.paragraphs[1].runs[0].style = 'QuoteChar'
>>> doc.paragraphs[1].runs[1].underline = True
>>> doc.paragraphs[1].runs[3].underline = True
>>> doc.save('restyled.docx')

这里，我们使用了 text 和 style 属性，以便容易地看到文档的段落中有什么。我们可以看到，很容易将段落划分成 Run，并单独访问每个 Run。所以我们取得了第二段中的第一、第二和第四个 Run，设置每个 Run 的样式，将结果保存到一个新文档。文件顶部的单词 Document Title 将具有 Normal 样式，而不是 Title 样式。针对文本 A plain paragraph 的 Run 对象，将具有 QuoteChar 样式。针对单词 bold 和 italic的两个 Run 对象，它们的 underline 属性设置为 True。图 13-7 展示了文件中段落和Run 的样式看起来的样子。

访问 https://python-docx.readthedocs.org/en/latest/user/styles.html，你可以看到，python-docx 使用样式的更完整文档。
 

写入 Word 文档
在交互式环境中输入以下代码：

>>> import docx
>>> doc = docx.Document()
>>> doc.add_paragraph('Hello world!')
<docx.text.Paragraph object at 0x0000000003B56F60>
>>> doc.save('helloworld.docx')

要创建自己的.docx 文件，就调用 docx.Document()，返回一个新的、空白的 WordDocument 对象。 Document 对象的 add_paragraph()方法将一段新文本添加到文档中，并返回添加的 Paragraph 对象的引用。在添加完文本之后，向 Document 对象的 save()方法传入一个文件名字符串，将 Document 对象保存到文件。这将在当前工作目录中创建一个文件，名为 helloworld.docx。如果打开它，就像图 13-8 的样子。

可以用新的段落文本，再次调用 add_paragraph()方法，添加段落。或者，要在已有段落的末尾添加文本，可以调用 Paragraph 对象的 add_run()方法，向它传入一个字符串。在交互式环境中输入以下代码：=

>>> import docx
>>> doc = docx.Document()
>>> doc.add_paragraph('Hello world!')
<docx.text.Paragraph object at 0x000000000366AD30>
>>> paraObj1 = doc.add_paragraph('This is a second paragraph.')
>>> paraObj2 = doc.add_paragraph('This is a yet another paragraph.')
>>> paraObj1.add_run(' This text is being added to the second paragraph.')
<docx.text.Run object at 0x0000000003A2C860>
>>> doc.save('multipleParagraphs.docx')

得到的文本如图 13-9 所示。请注意，文本 This text is being added to the secondparagraph.被添加到 paraObj1 中的 Paragraph 对象中，它是添加到 doc 中的第二段。add_paragraph()和 add_run()分别返回 Paragraph 和 Run 对象，这样你就不必多花一步来提取它们。

要记住，对于 python-docx 的 0.5.3 版本，新的 Paragraph 对象只能添加在文档的末尾，新的 Run 对象只能添加在 Paragraph 对象的末尾。可以再次调用 save()方法，保存所做的变更。add_paragraph()和 add_run()都接受可选的第二个参数，它是表示 Paragraph 或Run 对象样式的字符串。例如：

>>> doc.add_paragraph('Hello world!', 'Title')

这一行添加了一段，文本是 Hello world!，样式是 Title。
 

添加标题
调用 add_heading()将添加一个段落，并使用一种标题样式。在交互式环境中输入以下代码

>>> doc = docx.Document()
>>> doc.add_heading('Header 0', 0)
<docx.text.Paragraph object at 0x00000000036CB3C8>
>>> doc.add_heading('Header 1', 1)
<docx.text.Paragraph object at 0x00000000036CB630>
>>> doc.add_heading('Header 2', 2)
<docx.text.Paragraph object at 0x00000000036CB828>
>>> doc.add_heading('Header 3', 3)
<docx.text.Paragraph object at 0x00000000036CB2E8>
>>> doc.add_heading('Header 4', 4)
<docx.text.Paragraph object at 0x00000000036CB3C8>
>>> doc.save('headings.docx')

add_heading()的参数， 是一个标题文本的字符串，以及一个从 0 到 4 的整数。 整数 0 表示标题是 Title 样式，这用于文档的顶部。整数 1 到 4 是不同的标题层次， 1是主要的标题， 4 是最低层的子标题。 add_heading()返回一个 Paragraph 对象，让你不必多花一步从 Document 对象中提取它。得到的 headings.docx 文件如图 13-10 所示。

添加换行符和换页符
要添加换行符（而不是开始一个新的段落），可以在 Run 对象上调用 add_break()方法，换行符将出现在它后面。如果希望添加换页符，可以将 docx.enum.text.WD_BREAK.PAGE作为唯一的参数，传递给 add_break()，就像下面代码中间所做的一样：

>>> doc = docx.Document()
>>> doc.add_paragraph('This is on the first page!')
<docx.text.paragraph.Paragraph object at 0x0000023AC76E1CC0>
>>> doc.paragraphs[0].runs[0].add_break(docx.enum.text.WD_BREAK.PAGE)
>>> doc.add_paragraph('This is on the second page!')
<docx.text.paragraph.Paragraph object at 0x0000023AC76E1F60>
>>> doc.save('towPage.docx')

这创建了一个两页的 Word 文档，第一页上是 This is on the first page!，第二页上是 This is on the second page!。虽然在文本 This is on the first page!之后，第一页还有大量的空间，但是我们在第一段的第一个 Run 之后插入分页符，强制下一段落出现在新的页面中。

添加图像
Document 对象有一个 add_picture()方法，让你在文档末尾添加图像。假定当前工作目录中有一个文件 zophie.png，你可以输入以下代码，在文档末尾添加 zophie.png，宽度为 1 英寸，高度为 4 厘米（Word 可以同时使用英制和公制单位）：

>>> doc.add_picture('zophie.png', width=docx.shared.Inches(1),
height=docx.shared.Cm(4))
<docx.shape.InlineShape object at 0x00000000036C7D30>

第一个参数是一个字符串，表示图像的文件名。可选的 width 和 height 关键字参数，将设置该图像在文档中的宽度和高度。如果省略，宽度和高度将采用默认值，即该图像的正常尺寸。你可能愿意用熟悉的单位来指定图像的高度和宽度，诸如英寸或厘米。所以在指定 width 和 height 关键字参数时，可以使用 docx.shared.Inches()和 docx.shared.Cm()函数。