2020-07_python-docx 0.8.10 User Guide_03_Working with Documents

python-docx 0.8.10 User Guide

说明：

1. 本文的内容来源python-docx官方文档，出于学习的目的借助于有道进行翻译。
2. 翻译的原则：只有在有道翻译出的内容不通顺或意义有误的情况下才使用个人翻译。

---

Working with Documents

python-docx allows you to create new documents as well as make changes to existing ones. Actually, it only lets you make changes to existing documents; it’s just that if you start with a document that doesn’t have any content, it might feel at first like you’re creating one from scratch.
python-docx允许您创建新文档以及对现有文档进行更改。实际上，它只允许您对现有的文档进行更改;只是，如果您从一个没有任何内容的文档开始，一开始可能会感觉像是从头开始创建一个文档。

This characteristic is a powerful one. A lot of how a document looks is determined by the parts that are left when you delete all the content. Things like styles and page headers and footers are contained separately from the main content, allowing you to place a good deal of customization in your starting document that then appears in the document you produce.
这是一个强大的特点。文档的外观在很大程度上取决于删除所有内容后剩下的部分。样式、页眉和页脚等内容与主要内容是分开包含的，允许您在开始文档中放置大量定制，然后出现在生成的文档中。

Let’s walk through the steps to create a document one example at a time, starting with two of the main things you can do with a document, open it and save it.
让我们一步一步地介绍创建文档的步骤，首先介绍可以对文档进行的两项主要操作:打开并保存文档。

Opening a document

The simplest way to get started is to open a new document without specifying a file to open:
最简单的开始方式是打开一个新文档，而不指定要打开的文件:

from docx import Document

document = Document()
document.save('test.docx')

This creates a new document from the built-in default template and saves it unchanged to a file named ‘test.docx’. The so-called “default template” is actually just a Word file having no content, stored with the installed python-docx package. It’s roughly the same as you get by picking the Word Document template after selecting Word’s File > New from Template… menu item.
这将从内置的默认模板创建一个新文档，并将其不加更改地保存到名为test.docx的文件中。所谓的“默认模板”实际上只是一个没有内容的Word文件，存储在已安装的python-docx包中。这与选择Word的文件> New from template…菜单项后选择Word文档模板大致相同。

REALLY opening a document

If you want more control over the final document, or if you want to change an existing document, you need to open one with a filename:
如果你想对最终的文档有更多的控制，或者你想改变一个现有的文档，你需要打开一个文件名:

document = Document('existing-document-file.docx')
document.save('new-file-name.docx')

Things to note:
注意事项:

1. You can open any Word 2007 or later file this way (.doc files from Word 2003 and earlier won’t work). While you might not be able to manipulate all the contents yet, whatever is already in there will load and save just fine. The feature set is still being built out, so you can’t add or change things like headers or footnotes yet, but if the document has them python-docx is polite enough to leave them alone and smart enough to save them without actually understanding what they are.您可以以这种方式打开任何Word 2007或更高版本的文件(Word 2003或更早版本的.doc文件不能工作)。虽然您可能还不能操作所有的内容，但无论已经在其中的是什么，都可以很好地加载和保存。特性集还在构建中，所以您还不能添加或更改诸如页眉或脚注之类的东西，但如果文档中有这些东西，python-docx会很有礼貌地不去管它们，也会很聪明地保存它们，而不需要真正理解它们是什么。
2. If you use the same filename to open and save the file, python-docx will obediently overwrite the original file without a peep. You’ll want to make sure that’s what you intend.如果您使用相同的文件名来打开和保存文件，python-docx将顺从地覆盖原始文件而不发出一点声音。你要确定这就是你的意图。

Opening a ‘file-like’ document

python-docx can open a document from a so-called file-like object. It can also save to a file-like object. This can be handy when you want to get the source or target document over a network connection or from a database and don’t want to (or aren’t allowed to) interact with the file system. In practice this means you can pass an open file or StringIO/BytesIO stream object to open or save a document like so:
python-docx可以从所谓的类文件对象中打开文档。它还可以保存到类文件的对象。当您希望通过网络连接或从数据库获取源或目标文档，并且不想(或不允许)与文件系统交互时，这一点非常方便。在实践中，这意味着你可以传递一个打开的文件或StringIO/BytesIO流对象来打开或保存一个文档，像这样:

f = open('foobar.docx', 'rb')
document = Document(f)
f.close()

# or

with open('foobar.docx', 'rb') as f:
    source_stream = StringIO(f.read())
document = Document(source_stream)
source_stream.close()
...
target_stream = StringIO()
document.save(target_stream)

The ‘rb’ file open mode parameter isn’t required on all operating systems. It defaults to ‘r’ which is enough sometimes, but the ‘b’ (selecting binary mode) is required on Windows and at least some versions of Linux to allow Zipfile to open the file.
“rb”文件打开模式参数不是所有操作系统都需要的。它的默认值是’r’，有时这就足够了，但是在Windows和至少一些版本的Linux中需要’ b '(选择二进制模式)来允许Zipfile打开文件。

Okay, so you’ve got a document open and are pretty sure you can save it somewhere later. Next step is to get some content in there …
你已经打开了一个文档并且确信以后可以把它保存到某个地方。下一步是在那里获得一些内容…