0
# Document Operations
1

2
Core document creation, opening, and management functionality. This includes document properties, core metadata, section management, and document persistence operations.
3

4
## Capabilities
5

6
### Document Creation and Opening
7

8
Create new Word documents or open existing ones with flexible input options.
9

10
```python { .api }
11
def Document(docx=None):
12
    """Create or open a Word document.
13
    
14
    Args:
15
        docx (str, file-like, or None): Path to .docx file, file-like object, or None for new document
16
        
17
    Returns:
18
        Document: Document object for manipulation
19
        
20
    Raises:
21
        ValueError: If file is not a valid Word document
22
    """
23
```
24

25
**Usage Examples:**
26

27
```python
28
from docx import Document
29

30
# Create a new document
31
doc = Document()
32

33
# Open an existing document from file path
34
doc = Document('existing_document.docx')
35

36
# Open from file-like object
37
with open('document.docx', 'rb') as f:
38
    doc = Document(f)
39
```
40

41
### Document Saving
42

43
Save documents to files or file-like objects.
44

45
```python { .api }
46
class Document:
47
    def save(self, path_or_stream):
48
        """Save document to file or stream.
49
        
50
        Args:
51
            path_or_stream (str or file-like): File path or file-like object to save to
52
        """
53
```
54

55
**Usage Examples:**
56

57
```python
58
# Save to file path
59
doc.save('output.docx')
60

61
# Save to file-like object
62
from io import BytesIO
63
buffer = BytesIO()
64
doc.save(buffer)
65
buffer.seek(0)
66
```
67

68
### Core Document Properties
69

70
Access and modify document metadata and core properties.
71

72
```python { .api }
73
class Document:
74
    @property
75
    def core_properties(self):
76
        """Core document properties for metadata.
77
        
78
        Returns:
79
            CoreProperties: Object with title, author, subject, etc.
80
        """
81

82
class CoreProperties:
83
    @property
84
    def title(self):
85
        """Document title."""
86
    
87
    @title.setter
88
    def title(self, value):
89
        """Set document title."""
90
    
91
    @property
92
    def author(self):
93
        """Document author."""
94
    
95
    @author.setter
96
    def author(self, value):
97
        """Set document author."""
98
    
99
    @property
100
    def subject(self):
101
        """Document subject."""
102
    
103
    @subject.setter
104
    def subject(self, value):
105
        """Set document subject."""
106
    
107
    @property
108
    def created(self):
109
        """Document creation datetime."""
110
    
111
    @property
112
    def modified(self):
113
        """Document last modified datetime."""
114
    
115
    @property
116
    def last_modified_by(self):
117
        """User who last modified document."""
118
    
119
    @property
120
    def revision(self):
121
        """Document revision number."""
122
    
123
    @property
124
    def keywords(self):
125
        """Document keywords."""
126
    
127
    @keywords.setter
128
    def keywords(self, value):
129
        """Set document keywords."""
130
    
131
    @property
132
    def comments(self):
133
        """Document comments/description."""
134
    
135
    @comments.setter
136
    def comments(self, value):
137
        """Set document comments."""
138
    
139
    @property
140
    def category(self):
141
        """Document category."""
142
    
143
    @category.setter
144
    def category(self, value):
145
        """Set document category."""
146
```
147

148
**Usage Examples:**
149

150
```python
151
# Access and modify document properties
152
props = doc.core_properties
153
props.title = 'My Document Title'
154
props.author = 'John Doe'
155
props.subject = 'Document Subject'
156
props.keywords = 'keyword1, keyword2, keyword3'
157
props.comments = 'This is a sample document'
158

159
# Read existing properties
160
print(f"Created: {props.created}")
161
print(f"Modified: {props.modified}")
162
print(f"Revision: {props.revision}")
163
```
164

165
### Section Management
166

167
Add and manage document sections for page layout control.
168

169
```python { .api }
170
class Document:
171
    def add_section(self, start_type=None):
172
        """Add a new section to the document.
173
        
174
        Args:
175
            start_type (WD_SECTION_START, optional): How section should start
176
            
177
        Returns:
178
            Section: New section object
179
        """
180
    
181
    @property
182
    def sections(self):
183
        """Collection of document sections.
184
        
185
        Returns:
186
            Sections: Sequence of Section objects
187
        """
188
```
189

190
**Usage Examples:**
191

192
```python
193
from docx.enum.section import WD_SECTION_START
194

195
# Add a new section with page break
196
new_section = doc.add_section(WD_SECTION_START.NEW_PAGE)
197

198
# Add continuous section (no page break)
199
continuous_section = doc.add_section(WD_SECTION_START.CONTINUOUS)
200

201
# Access all sections
202
for i, section in enumerate(doc.sections):
203
    print(f"Section {i+1}: {section.page_width} x {section.page_height}")
204
```
205

206
### Document Structure Access
207

208
Access major document components and collections.
209

210
```python { .api }
211
class Document:
212
    @property
213
    def paragraphs(self):
214
        """All paragraphs in document body.
215
        
216
        Returns:
217
            list[Paragraph]: List of paragraph objects
218
        """
219
    
220
    @property
221
    def tables(self):
222
        """All tables in document body.
223
        
224
        Returns:
225
            list[Table]: List of table objects
226
        """
227
    
228
    @property
229
    def inline_shapes(self):
230
        """All inline shapes in document.
231
        
232
        Returns:
233
            InlineShapes: Collection of inline shape objects
234
        """
235
    
236
    @property
237
    def styles(self):
238
        """Document styles collection.
239
        
240
        Returns:
241
            Styles: Collection of document styles
242
        """
243
    
244
    @property
245
    def settings(self):
246
        """Document settings.
247
        
248
        Returns:
249
            Settings: Document settings object
250
        """
251
    
252
    @property
253
    def comments(self):
254
        """Document comments collection.
255
        
256
        Returns:
257
            Comments: Collection of comment objects
258
        """
259
```
260

261
**Usage Examples:**
262

263
```python
264
# Access document structure
265
print(f"Document has {len(doc.paragraphs)} paragraphs")
266
print(f"Document has {len(doc.tables)} tables")
267
print(f"Document has {len(doc.inline_shapes)} shapes")
268

269
# Iterate through paragraphs
270
for para in doc.paragraphs:
271
    if para.text.strip():  # Skip empty paragraphs
272
        print(f"Paragraph: {para.text[:50]}...")
273

274
# Access styles
275
for style in doc.styles:
276
    print(f"Style: {style.name} ({style.type})")
277
```
278

279
### Page Break Operations
280

281
Add page breaks to document flow.
282

283
```python { .api }
284
class Document:
285
    def add_page_break(self):
286
        """Add a page break to the document.
287
        
288
        Returns:
289
            Paragraph: Empty paragraph containing the page break
290
        """
291
```
292

293
**Usage Examples:**
294

295
```python
296
# Add content
297
doc.add_paragraph("Content on page 1")
298

299
# Add page break
300
doc.add_page_break()
301

302
# Add content on new page
303
doc.add_paragraph("Content on page 2")
304
```
305

306
## Types
307

308
```python { .api }
309
from docx.enum.section import WD_SECTION_START
310

311
class WD_SECTION_START:
312
    """Section start types."""
313
    CONTINUOUS = 0
314
    NEW_COLUMN = 1  
315
    NEW_PAGE = 2
316
    EVEN_PAGE = 3
317
    ODD_PAGE = 4
318
```