使用python-docx操作Word文档指南

需积分: 10 58 浏览量更新于2024-07-18 收藏 1013KB PDF 举报

"Python原版英文文档，主要关注Python在大数据和机器学习中的应用，特别是`python-docx`库的使用，版本0.8.6。这个库用于创建和修改Microsoft Word（.docx）文件。" `python-docx`是Python中一个用于处理Microsoft Word文档的库，它允许程序员通过编程方式生成、读取和修改.docx文件。这个库对于那些需要自动化生成报告、处理大量文本数据或者与Word文档交互的应用场景非常有用。以下将详细介绍`python-docx`的主要功能、用户指南、API文档以及贡献者指南。 1. **主要功能**： - 创建新的Word文档：通过`Document()`类可以创建一个新的Word文档。 - 添加标题：使用`add_heading()`方法添加不同级别的标题，级别参数控制标题的层级。 - 插入段落：使用`add_paragraph()`方法插入普通段落，并可以设置段落样式，如添加加粗或斜体文本。 - 图片处理：`add_picture()`方法用于在文档中插入图片，支持指定图片路径。 - 列表操作：可以创建无序列表和有序列表，通过`style`参数设置列表样式。 - 样式控制：可以对文本应用预定义的样式，例如'IntenseQuote'或'ListBullet'等。 2. **用户指南**：用户指南通常会包含如何初始化文档对象，如何添加各种元素（如标题、段落、列表和图片），以及如何设置样式和属性等详细步骤。此外，还会介绍如何保存和读取已有的.docx文件。 3. **API文档**： `python-docx`的API文档详细列出了所有可供使用的类、方法和属性，包括`Document`、`Paragraph`、`Run`等核心类。这些类提供了丰富的接口来操作文档的各个部分。例如，`Run`类用于表示段落中的一个连续文本片段，可以设置其样式属性。 4. **贡献者指南**：对于开发者来说，贡献者指南提供了关于如何参与项目开发、提交代码、测试以及遵循编码规范的信息。这有助于社区成员为`python-docx`库做出贡献，比如修复bug、增加新功能或改进文档。在大数据和机器学习领域，`python-docx`可能被用于自动化报告生成，例如在模型训练完成后自动生成包含结果和分析的Word文档。同时，由于Python在数据分析中的广泛使用，`python-docx`也能帮助处理和输出分析过程中的文本和图像数据。 `python-docx`库是Python生态系统中一个强大的工具，它简化了与Microsoft Word文档的交互，使得在编程环境中处理文本内容变得更加便捷。无论是个人还是团队，都可以利用这个库提高工作效率，特别是在需要大量文档处理的项目中。

python-docx Documentation, Release 0.8.6

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' ﬁle 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

Zipﬁle to open the ﬁle.

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 ...

Working with Text

To work effectively with text, it’s important to ﬁrst understand a little about block-level elements like paragraphs and

inline-level objects like runs.

Block-level vs. inline text objects

The paragraph is the primary block-level object in Word.

A block-level item ﬂows the text it contains between its left and right edges, adding an additional line each time the

text extends beyond its right boundary. For a paragraph, the boundaries are generally the page margins, but they can

also be column boundaries if the page is laid out in columns, or cell boundaries if the paragraph occurs inside a table

cell.

A table is also a block-level object.

An inline object is a portion of the content that occurs inside a block-level item. An example would be a word that

appears in bold or a sentence in all-caps. The most common inline object is a run. All content within a block container

is inside of an inline object. Typically, a paragraph contains one or more runs, each of which contain some part of the

paragraph’s text.

The attributes of a block-level item specify its placement on the page, such items as indentation and space before and

after a paragraph. The attributes of an inline item generally specify the font in which the content appears, things like

typeface, font size, bold, and italic.

Paragraph properties

A paragraph has a variety of properties that specify its placement within its container (typically a page) and the way it

divides its content into separate lines.

In general, it’s best to deﬁne a paragraph style collecting these attributes into a meaningful group and apply the

appropriate style to each paragraph, rather than repeatedly apply those properties directly to each paragraph. This is

analogous to how Cascading Style Sheets (CSS) work with HTML. All the paragraph properties described here can

be set using a style as well as applied directly to a paragraph.

The formatting properties of a paragraph are accessed using the ParagraphFormat object available using the

paragraph’s paragraph_format property.

12 Chapter 2. User Guide

python-docx Documentation, Release 0.8.6

Horizontal alignment (justiﬁcation)

Also known as justiﬁcation, the horizontal alignment of a paragraph can be set to left, centered, right, or fully justiﬁed

(aligned on both the left and right sides) using values from the enumeration WD_PARAGRAPH_ALIGNMENT:

>>> from docx.enum.text import WD_ALIGN_PARAGRAPH

>>> document = Document()

>>> paragraph = document.add_paragraph()

>>> paragraph_format = paragraph.paragraph_format

>>> paragraph_format.alignment

None # indicating alignment is inherited from the style hierarchy

>>> paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER

>>> paragraph_format.alignment

CENTER (1)

Indentation

Indentation is the horizontal space between a paragraph and edge of its container, typically the page margin. A

paragraph can be indented separately on the left and right side. The ﬁrst line can also have a different indentation than

the rest of the paragraph. A ﬁrst line indented further than the rest of the paragraph has ﬁrst line indent. A ﬁrst line

indented less has a hanging indent.

Indentation is speciﬁed using a Length value, such as Inches, Pt, or Cm. Negative values are valid and cause the

paragraph to overlap the margin by the speciﬁed amount. A value of None indicates the indentation value is inherited

from the style hierarchy. Assigning None to an indentation property removes any directly-applied indentation setting

and restores inheritance from the style hierarchy:

>>> from docx.shared import Inches

>>> paragraph = document.add_paragraph()

>>> paragraph_format = paragraph.paragraph_format

>>> paragraph_format.left_indent

None # indicating indentation is inherited from the style hierarchy

>>> paragraph_format.left_indent = Inches(0.5)

>>> paragraph_format.left_indent

457200

>>> paragraph_format.left_indent.inches

0.5

Right-side indent works in a similar way:

>>> from docx.shared import Pt

>>> paragraph_format.right_indent

None

>>> paragraph_format.right_indent = Pt(24)

>>> paragraph_format.right_indent

304800

>>> paragraph_format.right_indent.pt

24.0

First-line indent is speciﬁed using the first_line_indent property and is interpreted relative to the left indent.

A negative value indicates a hanging indent:

>>> paragraph_format.first_line_indent

None

2.4. Working with Text 13

python-docx Documentation, Release 0.8.6

>>> paragraph_format.first_line_indent = Inches(-0.25)

>>> paragraph_format.first_line_indent

-228600

>>> paragraph_format.first_line_indent.inches

-0.25

Tab stops

A tab stop determines the rendering of a tab character in the text of a paragraph. In particular, it speciﬁes the position

where the text following the tab character will start, how it will be aligned to that position, and an optional leader

character that will ﬁll the horizontal space spanned by the tab.

The tab stops for a paragraph or style are contained in a TabStops object accessed using the tab_stops property

on ParagraphFormat:

>>> tab_stops = paragraph_format.tab_stops

>>> tab_stops

<docx.text.tabstops.TabStops object at 0x106b802d8>

A new tab stop is added using the add_tab_stop() method:

>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5))

>>> tab_stop.position

1371600

>>> tab_stop.position.inches

1.5

Alignment defaults to left, but may be speciﬁed by providing a member of the WD_TAB_ALIGNMENT enumeration.

The leader character defaults to spaces, but may be speciﬁed by providing a member of the WD_TAB_LEADER

enumeration:

>>> from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER

>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_

,!LEADER.DOTS)

>>> print(tab_stop.alignment)

RIGHT (2)

>>> print(tab_stop.leader)

DOTS (1)

Existing tab stops are accessed using sequence semantics on TabStops:

>>> tab_stops[0]

<docx.text.tabstops.TabStop object at 0x1105427e8>

More details are available in the TabStops and TabStop API documentation

Paragraph spacing

The space_before and space_after properties control the spacing between subsequent paragraphs, controlling

the spacing before and after a paragraph, respectively. Inter-paragraph spacing is collapsed during page layout, mean-

ing the spacing between two paragraphs is the maximum of the space_after for the ﬁrst paragraph and the space_before

of the second paragraph. Paragraph spacing is speciﬁed as a Length value, often using Pt:

14 Chapter 2. User Guide

python-docx Documentation, Release 0.8.6

>>> paragraph_format.space_before, paragraph_format.space_after

(None, None) # inherited by default

>>> paragraph_format.space_before = Pt(18)

>>> paragraph_format.space_before.pt

18.0

>>> paragraph_format.space_after = Pt(12)

>>> paragraph_format.space_after.pt

12.0

Line spacing

Line spacing is the distance between subsequent baselines in the lines of a paragraph. Line spacing can be speciﬁed

either as an absolute distance or relative to the line height (essentially the point size of the font used). A typical

absolute measure would be 18 points. A typical relative measure would be double-spaced (2.0 line heights). The

default line spacing is single-spaced (1.0 line heights).

Line spacing is controlled by the interaction of the line_spacing and line_spacing_rule properties.

line_spacing is either a Length value, a (small-ish) float, or None. A Length value indicates an

absolute distance. A float indicates a number of line heights. None indicates line spacing is inherited.

line_spacing_rule is a member of the WD_LINE_SPACING enumeration or None:

>>> from docx.shared import Length

>>> paragraph_format.line_spacing

None

>>> paragraph_format.line_spacing_rule

None

>>> paragraph_format.line_spacing = Pt(18)

>>> isinstance(paragraph_format.line_spacing, Length)

True

>>> paragraph_format.line_spacing.pt

18.0

>>> paragraph_format.line_spacing_rule

EXACTLY (4)

>>> paragraph_format.line_spacing = 1.75

>>> paragraph_format.line_spacing

1.75

>>> paragraph_format.line_spacing_rule

MULTIPLE (5)

Pagination properties

Four paragraph properties, keep_together, keep_with_next, page_break_before, and

widow_control control aspects of how the paragraph behaves near page boundaries.

keep_together causes the entire paragraph to appear on the same page, issuing a page break before the paragraph

if it would otherwise be broken across two pages.

keep_with_next keeps a paragraph on the same page as the subsequent paragraph. This can be used, for example,

to keep a section heading on the same page as the ﬁrst paragraph of the section.

page_break_before causes a paragraph to be placed at the top of a new page. This could be used on a chapter

heading to ensure chapters start on a new page.

2.4. Working with Text 15

python-docx Documentation, Release 0.8.6

widow_control breaks a page to avoid placing the ﬁrst or last line of the paragraph on a separate page from the

rest of the paragraph.

All four of these properties are tri-state, meaning they can take the value True, False, or None. None indicates

the property value is inherited from the style hierarchy. True means “on” and False means “off”:

>>> paragraph_format.keep_together

None # all four inherit by default

>>> paragraph_format.keep_with_next = True

>>> paragraph_format.keep_with_next

True

>>> paragraph_format.page_break_before = False

>>> paragraph_format.page_break_before

False

Apply character formatting

Character formatting is applied at the Run level. Examples include font typeface and size, bold, italic, and underline.

A Run object has a read-only font property providing access to a Font object. A run’s Font object provides

properties for getting and setting the character formatting for that run.

Several examples are provided here. For a complete set of the available properties, see the Font API documentation.

The font for a run can be accessed like this:

>>> from docx import Document

>>> document = Document()

>>> run = document.add_paragraph().add_run()

>>> font = run.font

Typeface and size are set like this:

>>> from docx.shared import Pt

>>> font.name = 'Calibri'

>>> font.size = Pt(12)

Many font properties are tri-state, meaning they can take the values True, False, and None. True means the

property is “on”, False means it is “off”. Conceptually, the None value means “inherit”. A run exists in the style

inheritance hierarchy and by default inherits its character formatting from that hierarchy. Any character formatting

directly applied using the Font object overrides the inherited values.

Bold and italic are tri-state properties, as are all-caps, strikethrough, superscript, and many others. See the Font API

documentation for a full list:

>>> font.bold, font.italic

(None, None)

>>> font.italic = True

>>> font.italic

True

>>> font.italic = False

>>> font.italic

False

>>> font.italic = None

>>> font.italic

None

16 Chapter 2. User Guide

剩余185页未读，继续阅读

maplechen111

粉丝: 0
资源: 1

使用python-docx操作Word文档指南

python原文件

Python 3.6.5官方文档英文原版（包含python标准库）

python学习文档

python 2.7.15文档pdf版

python官方文档中文汉化版

python3.7离线帮助文档（英文原版）

think python 英文原版_人工智能PYTHON_thinkpython_python_基础_

think python英文原版二

python相关资料文档

python3.6官方文档

最新资源