0
# Python-docx
1

2
A comprehensive Python library for creating, reading, and updating Microsoft Word 2007+ (.docx) files. Python-docx provides a high-level API for document manipulation including paragraph creation, text formatting, table management, and image insertion without requiring Microsoft Word to be installed.
3

4
## Package Information
5

6
- **Package Name**: python-docx
7
- **Language**: Python
8
- **Installation**: `pip install python-docx`
9
- **Version**: 1.2.0
10

11
## Core Imports
12

13
```python
14
from docx import Document
15
```
16

17
For specific components:
18

19
```python
20
from docx import Document
21
from docx.shared import Inches, Cm, Mm, Pt, Emu, RGBColor
22
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_BREAK_TYPE
23
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT
24
```
25

26
## Basic Usage
27

28
```python
29
from docx import Document
30
from docx.shared import Inches
31

32
# Create a new document
33
doc = Document()
34

35
# Add a heading
36
doc.add_heading('Document Title', 0)
37

38
# Add a paragraph
39
p = doc.add_paragraph('This is a paragraph with some ')
40
p.add_run('bold').bold = True
41
p.add_run(' and some ')
42
p.add_run('italic.').italic = True
43

44
# Add a table
45
table = doc.add_table(rows=1, cols=3)
46
hdr_cells = table.rows[0].cells
47
hdr_cells[0].text = 'Name'
48
hdr_cells[1].text = 'Age'
49
hdr_cells[2].text = 'City'
50

51
# Add data to table
52
row_cells = table.add_row().cells
53
row_cells[0].text = 'John Doe'
54
row_cells[1].text = '30'
55
row_cells[2].text = 'New York'
56

57
# Add an image
58
doc.add_picture('image.png', width=Inches(1.25))
59

60
# Save the document
61
doc.save('demo.docx')
62
```
63

64
## Architecture
65

66
Python-docx follows a hierarchical document model based on the Office Open XML format:
67

68
- **Document**: Top-level container managing the entire Word document
69
- **Sections**: Page layout and formatting containers with headers/footers
70
- **Block-level Elements**: Paragraphs, tables, and images that form document content
71
- **Inline Elements**: Runs of text, hyperlinks, and inline shapes within paragraphs
72
- **Formatting Objects**: Styles, fonts, and formatting properties
73

74
The library abstracts the complexity of the underlying XML structure while providing full access to document manipulation capabilities through an intuitive object-oriented interface.
75

76
## Capabilities
77

78
### Document Operations
79

80
Core document creation, opening, and management functionality including document properties, sections, and saving.
81

82
```python { .api }
83
def Document(docx=None):
84
    """Create or open a Word document.
85
    
86
    Args:
87
        docx (str or file-like, optional): Path to .docx file or file-like object
88
        
89
    Returns:
90
        Document: Document object for manipulation
91
    """
92

93
class Document:
94
    def save(self, path_or_stream):
95
        """Save document to file or stream."""
96
    
97
    def add_section(self, start_type=WD_SECTION_START.NEW_PAGE):
98
        """Add a new section to the document."""
99
    
100
    @property
101
    def core_properties(self):
102
        """Core document properties (title, author, etc.)."""
103
```
104

105
[Document Operations](./document-operations.md)
106

107
### Text and Paragraphs
108

109
Text manipulation including paragraphs, runs, character formatting, and text alignment. Handles rich text formatting with fonts, colors, and styling.
110

111
```python { .api }
112
class Document:
113
    def add_paragraph(self, text='', style=None):
114
        """Add a paragraph to the document."""
115
    
116
    def add_heading(self, text='', level=1):
117
        """Add a heading paragraph."""
118

119
class Paragraph:
120
    def add_run(self, text=None, style=None):
121
        """Add a run of text to the paragraph."""
122
    
123
    def clear(self):
124
        """Remove all content from paragraph."""
125
    
126
    @property
127
    def text(self):
128
        """Plain text content of paragraph."""
129

130
class Run:
131
    @property
132
    def font(self):
133
        """Font formatting object."""
134
    
135
    @property
136
    def bold(self):
137
        """Get/set bold formatting."""
138
```
139

140
[Text and Paragraphs](./text-paragraphs.md)
141

142
### Tables
143

144
Comprehensive table creation and manipulation including rows, columns, cells, and table formatting with merge capabilities.
145

146
```python { .api }
147
class Document:
148
    def add_table(self, rows, cols, style=None):
149
        """Add a table to the document."""
150

151
class Table:
152
    def add_row(self):
153
        """Add a row to the table."""
154
    
155
    def add_column(self, width):
156
        """Add a column to the table."""
157
    
158
    def cell(self, row_idx, col_idx):
159
        """Access specific table cell."""
160
    
161
    @property
162
    def rows(self):
163
        """Collection of table rows."""
164
    
165
    @property
166
    def columns(self):
167
        """Collection of table columns."""
168
```
169

170
[Tables](./tables.md)
171

172
### Styles and Formatting
173

174
Style management and formatting including paragraph styles, character styles, fonts, colors, and measurements.
175

176
```python { .api }
177
class Document:
178
    @property
179
    def styles(self):
180
        """Document styles collection."""
181

182
class Font:
183
    @property
184
    def name(self):
185
        """Font name."""
186
    
187
    @property
188
    def size(self):
189
        """Font size in points."""
190
    
191
    @property
192
    def color(self):
193
        """Font color."""
194

195
class ParagraphFormat:
196
    @property
197
    def alignment(self):
198
        """Paragraph alignment."""
199
    
200
    @property
201
    def line_spacing(self):
202
        """Line spacing."""
203
```
204

205
[Styles and Formatting](./styles-formatting.md)
206

207
### Images and Shapes
208

209
Image insertion and inline shape management with sizing and positioning controls.
210

211
```python { .api }
212
class Document:
213
    def add_picture(self, image_path_or_stream, width=None, height=None):
214
        """Add an image to the document."""
215
    
216
    @property
217
    def inline_shapes(self):
218
        """Collection of inline shapes in document."""
219

220
class InlineShape:
221
    @property
222
    def width(self):
223
        """Shape width."""
224
    
225
    @property
226
    def height(self):
227
        """Shape height."""
228
```
229

230
[Images and Shapes](./images-shapes.md)
231

232
### Sections and Page Layout
233

234
Page setup, margins, orientation, headers, footers, and section management for document layout control.
235

236
```python { .api }
237
class Section:
238
    @property
239
    def page_width(self):
240
        """Page width."""
241
    
242
    @property
243
    def page_height(self):
244
        """Page height."""
245
    
246
    @property
247
    def orientation(self):
248
        """Page orientation (portrait/landscape)."""
249
    
250
    @property
251
    def header(self):
252
        """Section header."""
253
    
254
    @property
255
    def footer(self):
256
        """Section footer."""
257
```
258

259
[Sections and Page Layout](./sections-layout.md)
260

261
### Comments
262

263
Document commenting system for adding and managing comments anchored to text ranges.
264

265
```python { .api }
266
class Document:
267
    def add_comment(self, runs, text='', author='', initials=''):
268
        """Add a comment to the document.
269
        
270
        Args:
271
            runs (Run or list[Run]): Run or sequence of runs to anchor comment to
272
            text (str, optional): Comment text content
273
            author (str, optional): Comment author name  
274
            initials (str, optional): Author initials
275
            
276
        Returns:
277
            Comment: New comment object
278
        """
279
    
280
    @property
281
    def comments(self):
282
        """Collection of document comments."""
283

284
class Comment:
285
    @property
286
    def text(self):
287
        """Comment text content."""
288
    
289
    @property
290
    def author(self):
291
        """Comment author."""
292
```
293

294
[Comments](./comments.md)
295

296
## Measurement Classes
297

298
```python { .api }
299
class Length(int):
300
    """Base measurement class in English Metric Units."""
301
    
302
    @property
303
    def inches(self):
304
        """Value in inches."""
305
    
306
    @property
307
    def cm(self):
308
        """Value in centimeters."""
309

310
def Inches(inches):
311
    """Create Length object from inches."""
312

313
def Cm(cm):
314
    """Create Length object from centimeters."""
315

316
def Mm(mm):
317
    """Create Length object from millimeters."""
318

319
def Pt(points):
320
    """Create Length object from points."""
321

322
class RGBColor(tuple):
323
    """RGB color specification."""
324
    
325
    def __init__(self, r, g, b):
326
        """Create RGB color from 0-255 values."""
327
```
328

329
## Core Enumerations
330

331
Key enumeration values for document formatting:
332

333
```python { .api }
334
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
335
# Values: LEFT, CENTER, RIGHT, JUSTIFY, DISTRIBUTE
336

337
from docx.enum.text import WD_BREAK_TYPE  
338
# Values: COLUMN, LINE, PAGE, TEXT_WRAPPING
339

340
from docx.enum.table import WD_TABLE_ALIGNMENT
341
# Values: LEFT, CENTER, RIGHT
342

343
from docx.enum.section import WD_ORIENTATION
344
# Values: PORTRAIT, LANDSCAPE
345
```