### Install python-docx using easy_install
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/install.rst
This command installs python-docx using easy_install. However, using pip is generally recommended over easy_install.
```bash
easy_install python-docx
```
--------------------------------
### Install python-docx
Source: https://github.com/python-openxml/python-docx/blob/master/README.md
Install the python-docx library using pip.
```bash
pip install python-docx
```
--------------------------------
### Manual installation of python-docx
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/install.rst
Install python-docx manually by downloading the distribution, unpacking it, and running the setup script. Ensure you install dependencies like lxml separately if using this method.
```bash
tar xvzf python-docx-{version}.tar.gz
cd python-docx-{version}
python setup.py install
```
--------------------------------
### Get and Set style.quick_style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Demonstrates retrieving and setting the quick_style property for a style. This property controls the element.
```python
>>> style = document.styles['Foo']
>>> style.quick_style
False
>>> style.quick_style = True
>>> style.quick_style
True
```
--------------------------------
### MS API: Create Footer
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/header.rst
Example of creating a default footer and setting its text using the MS API.
```python
section = Document.Sections(1)
footers = section.Footers # a HeadersFooters collection object
default_footer = footers(wdHeaderFooterPrimary)
default_footer.Range.Text = "Footer text"
```
--------------------------------
### Alternate XML for style.quick_style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
These examples show alternative XML constructions for setting the quick_style state, though they are not preferred for writing.
```xml
```
```xml
```
--------------------------------
### Create a new blank document
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Start by importing the Document class and creating an instance. This opens a blank document based on the default template.
```python
from docx import Document
document = Document()
```
--------------------------------
### XML Specimen for Line Spacing
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example XML showing paragraph properties for line spacing. 'w:line' is in twips.
```xml
```
```xml
```
--------------------------------
### Add a table with data
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Create a table and populate it with data from a tuple of tuples. This example demonstrates creating a table with a specific number of columns and populating it.
```python
# get table data -------------
items = (
(7, '1024', 'Plush kittens'),
(3, '2042', 'Furbees'),
(1, '1288', 'French Poodle Collars, Deluxe'),
)
# add table ------------------
table = document.add_table(1, 3)
```
--------------------------------
### Modifying Section Start Type
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/sections.rst
Illustrates how to get and set the start type of a section, which determines the type of break that precedes it. Values are members of the WdSectionStart enumeration.
```python
from docx.enum.section import WD_SECTION
# Assuming 'section' is a Section object
# print(section.start_type)
section.start_type = WD_SECTION.ODD_PAGE
print(section.start_type)
```
--------------------------------
### Example Core Properties XML
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/coreprops.rst
Illustrates the structure of a core.xml file as produced by Microsoft Word, showing various Dublin Core and Open Packaging Conventions properties.
```xml
Core Document Properties Exploration
PowerPoint core document properties
Steve Canny
powerpoint; open xml; dublin core; microsoft office
One thing I\'d like to discover is just how line wrapping is handled
in the comments. This paragraph is all on a single
line._x000d__x000d_This is a second paragraph separated from the
first by two line feeds.
Steve Canny
2
2013-04-06T06:03:36Z
2013-06-15T06:09:18Z
analysis
```
--------------------------------
### Accessing Style Type
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/enum/WdStyleType.rst
Demonstrates how to access and assert the type of a style using the WD_STYLE_TYPE enumeration. Ensure the docx library is installed.
```python
from docx import Document
from docx.enum.style import WD_STYLE_TYPE
styles = Document().styles
assert styles[0].type == WD_STYLE_TYPE.PARAGRAPH
```
--------------------------------
### XML Specimen for Page Placement
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example XML for paragraph page placement properties like keep-with-next, keep-lines, page-break-before, and widow-control.
```xml
```
--------------------------------
### Create and Save a New Document
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/documents.rst
Creates a new, blank document from the default template and saves it to a specified file. This is useful for starting a document from scratch.
```python
from docx import Document
document = Document()
document.save('test.docx')
```
--------------------------------
### XML Specimen for Indentation
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example XML demonstrating paragraph indentation using 'w:ind' element attributes. Values are in twips.
```xml
```
```xml
```
--------------------------------
### XML Specimen: Red text on Green Highlight
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font-highlight-color.rst
Example of XML structure for a run with red text and a green highlight.
```xml
Red text on green background
```
--------------------------------
### XML Specimen: Blue text on Bright Green Highlight
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font-highlight-color.rst
Example of XML structure for a run with blue text and a bright green highlight.
```xml
Blue text on bright green background
```
--------------------------------
### Alternate XML for style.locked
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
These examples show alternative XML constructions for setting the locked state, though they are not preferred for writing.
```xml
```
```xml
```
--------------------------------
### Alternate XML for style.unhide_when_used
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
These examples show alternative XML constructions for setting the unhide_when_used state, though they are not preferred for writing.
```xml
```
```xml
```
--------------------------------
### Example Styles XML
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/index.rst
This XML snippet illustrates the structure of the styles part of a Word document, including default settings and custom style definitions.
```xml
```
--------------------------------
### Alternate XML for style.hidden
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
These examples show alternative XML constructions for setting the hidden state, though they are not preferred for writing.
```xml
```
```xml
```
--------------------------------
### Accessing and Modifying Core Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/coreprops.rst
Demonstrates how to get and set core document properties like the author. Requires an initialized Document object.
```python
from docx import Document
document = Document()
core_properties = document.core_properties
print(core_properties.author)
core_properties.author = 'Brian'
print(core_properties.author)
```
--------------------------------
### Get and Set Line Spacing
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Illustrates retrieving and setting line spacing for a paragraph. Different values result in different line spacing rules (EXACTLY, SINGLE, MULTIPLE).
```python
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(None, None)
>>> paragraph_format.line_spacing = Pt(18)
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(228600, WD_LINE_SPACING.EXACTLY (4))
>>> paragraph_format.line_spacing = 1
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(152400, WD_LINE_SPACING.SINGLE (0))
>>> paragraph_format.line_spacing = 0.9
>>> paragraph_format.line_spacing, paragraph_format.line_spacing_rule
(137160, WD_LINE_SPACING.MULTIPLE (5))
```
--------------------------------
### Example Paragraph Style XML
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/paragraph-style.rst
This XML snippet illustrates a paragraph style with a 'Foo' styleId and specifies 'Bar' as the next paragraph style.
```xml
```
--------------------------------
### Querying and Applying Boolean Run Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font.rst
Demonstrates the protocol for setting and getting boolean run properties like bold. The property can be set to True, False, or None, affecting how the formatting is applied and inherited from styles.
```python
>>> run = p.add_run()
>>> run.bold
None
>>> run.bold = True
>>> run.bold
True
>>> run.bold = False
>>> run.bold
False
>>> run.bold = None
>>> run.bold
None
```
--------------------------------
### Run Formatting Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font.rst
Demonstrates how to get and set boolean run properties like bold, italics, and strikethrough. These properties are tri-state, accepting True, False, or None.
```APIDOC
## Run Formatting Properties
### Description
This section details the API for directly manipulating text formatting properties on a `Run` object. These properties control visual aspects of the text, such as boldness, italics, and strikethrough.
### Protocol
Each boolean run property is a read/write 'tri-state' property with possible values of `True`, `False`, and `None`.
- **True**: The property is unconditionally enabled.
- **False**: The property is unconditionally disabled.
- **None**: The property is not explicitly set, and its value is inherited from the style hierarchy. If no style value is found, it defaults to off.
### Example Usage
```python
# Assuming 'p' is a Paragraph object
run = p.add_run()
# Get initial state (likely None)
print(run.bold) # Output: None
# Set to True
run.bold = True
print(run.bold) # Output: True
# Set to False
run.bold = False
print(run.bold) # Output: False
# Reset to inherited state
run.bold = None
print(run.bold) # Output: None
```
### Available Properties
The following properties are available for direct manipulation:
- **bold**: Controls whether the text is bold.
- **complex_script_bold**: Controls bolding for complex script text.
- **caps**: Displays all characters as capital letters.
- **complex_script**: Applies complex script formatting.
- **double_strikethrough**: Applies double strikethrough.
- **emboss**: Applies embossing effect.
- **italics**: Controls whether the text is italic.
- **complex_script_italics**: Controls italics for complex script text.
- **imprint**: Applies imprinting effect.
- **no_proof**: Disables spell and grammar checking for the text.
- **math**: Indicates Office Open XML Math content.
- **outline**: Displays character outline.
- **right_to_left**: Enables right-to-left text direction.
- **shadow**: Applies shadow effect.
- **small_caps**: Displays text in small caps.
- **snap_to_grid**: Uses document grid settings for character spacing.
- **spec_vanish**: Hides the paragraph mark.
- **strikethrough**: Applies single strikethrough.
- **vanish**: Hides the text.
- **web_hidden**: Hides the text when viewed on the web.
```
--------------------------------
### Accessing and Setting Style Priority
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Demonstrates how to get and set the priority attribute of a style object. Note that negative values are treated as 0.
```python
>>> style = document.styles['Foobar']
>>> style.priority
None
>>> style.priority = 7
>>> style.priority
7
>>> style.priority = -42
>>> style.priority
0
```
--------------------------------
### XML Structure for Paragraph Style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Example of the XML representation for a paragraph style, including its name, base style, and formatting attributes.
```xml
```
--------------------------------
### Accessing Document Sections
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/sections.rst
Demonstrates how to access the collection of sections in a document and iterate through them to inspect their start types. It's advisable to handle potential IndexErrors for documents with no explicit sections.
```python
from docx import Document
document = Document()
sections = document.sections
print(sections)
print(len(sections))
section = sections[0]
print(section)
for section in sections:
print(section.start_type)
```
--------------------------------
### Accessing a Section's Header
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/header.rst
Demonstrates how to get the header object for a given section. The header object provides access to header content and properties.
```python
>>> header = section.header
>>> header
```
--------------------------------
### Setting and Getting Font Highlight Color
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font-highlight-color.rst
Demonstrates how to set and retrieve the highlight color of a font object. The highlight_color property can be set to a member of WD_COLOR_INDEX or None to remove highlighting.
```python
font = paragraph.add_run().font
font.highlight_color
None
font.highlight_color = WD_COLOR_INDEX.YELLOW
font.highlight_color
YELLOW (7)
font.highlight_color = WD_COLOR_INDEX.TURQUOISE
font.highlight_color
TURQUOISE (3)
font.highlight_color = None
font.highlight_color
None
```
--------------------------------
### Access the comments collection
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/comments.rst
Get the collection of all comments in the document via `document.comments`. The collection supports getting a comment by its ID.
```python
comments = document.comments
comment = comments.get(0)
```
--------------------------------
### Accessing and Modifying Tab Stops
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/tab-stops.rst
Demonstrates how to get the TabStops object for a paragraph, add new tab stops with specific alignment and leader styles, and modify existing tab stop properties. It also shows how tab stops are automatically sorted by position.
```python
tab_stops = paragraph.paragraph_format.tab_stops
tab_stop = tab_stops.add_tab_stop(Inches(2), WD_TAB_ALIGNMENT.LEFT, WD_TAB_LEADER.DOTS)
# add_tab_stop defaults to WD_TAB_ALIGNMENT.LEFT, WD_TAB_LEADER.SPACES
tab_stop = tab_stops.add_tab_stop(Inches(0.5))
tab_stop.alignment
WD_TAB_ALIGNMENT.LEFT
tab_stop.leader
WD_TAB_LEADER.SPACES
# TabStop properties are read/write
tab_stop.position = Inches(2.5)
tab_stop.alignment = WD_TAB_ALIGNMENT.CENTER
tab_stop.leader = WD_TAB_LEADER.DASHES
# Tab stops are sorted into position order as created or modified
[(t.position, t.alignment) for t in tab_stops]
[(914400, WD_TAB_ALIGNMENT.LEFT), (2286000, WD_TAB_ALIGNMENT.CENTER)]
```
--------------------------------
### Get table row and column counts
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Use the len() function on the table's rows and columns collections to get the number of rows and columns.
```python
row_count = len(table.rows)
col_count = len(table.columns)
```
--------------------------------
### Illegal Merge Operation Example
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/table/cell-merge.rst
Shows an example of an illegal cell merge operation, highlighting constraints on merging non-rectangular regions or overlapping merges.
```python
a.merge(b)
```
--------------------------------
### Paragraph Text with Hyperlink
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/hyperlink.rst
Example of how paragraph text containing a hyperlink is represented.
```python
>>> paragraph.text
'A paragraph having a link to: github'
```
--------------------------------
### CT_NumLvl Complex Type
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/numbering.rst
Defines a numbering level, supporting start overrides and level-specific formatting.
```xml
```
--------------------------------
### RGBColor Initialization with Hexadecimal
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/shared.rst
Shows how to create an RGBColor object using hexadecimal integer notation for enhanced readability.
```python
>>> lavender = RGBColor(0xff, 0x99, 0xcc)
```
--------------------------------
### Get Styles Collection Length
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/styles.rst
Determine the number of styles available in the document's styles collection.
```python
>>> len(styles)
10
```
--------------------------------
### Create and Save a Word Document
Source: https://github.com/python-openxml/python-docx/blob/master/README.md
Demonstrates how to create a new Word document, add a paragraph, and save it.
```python
from docx import Document
document = Document()
document.add_paragraph("It was a dark and stormy night.")
document.save("dark-and-stormy.docx")
```
--------------------------------
### Get Run Style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/character-style.rst
Retrieve the current character style applied to a run. This shows the object representation and its name.
```python
>>> run = p.add_run()
>>> run.style
>>> run.style.name
'Default Paragraph Font'
```
--------------------------------
### Get and Set Paragraph Alignment
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Demonstrates how to retrieve and set the alignment for a paragraph. Assigning None removes the alignment setting.
```python
>>> paragraph = body.add_paragraph()
>>> paragraph.alignment
None
>>> paragraph.alignment = WD_ALIGN_PARAGRAPH.RIGHT
>>> paragraph.alignment
RIGHT (2)
>>> paragraph.alignment = None
>>> paragraph.alignment
None
```
--------------------------------
### Import and Use MSO_COLOR_TYPE
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/enum/MsoColorType.rst
Demonstrates how to import the MSO_COLOR_TYPE enumeration and assert a font's color type against a theme color.
```python
from docx.enum.dml import MSO_COLOR_TYPE
assert font.color.type == MSO_COLOR_TYPE.THEME
```
--------------------------------
### Get and Set style.locked
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Demonstrates retrieving and setting the locked property for a style. This property controls the element.
```python
>>> style = document.styles['Foo']
>>> style.locked
False
>>> style.locked = True
>>> style.locked
True
```
--------------------------------
### Set style.quick_style to True
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
This XML snippet shows how the element is added to a style definition when the quick_style property is set to True.
```xml
```
--------------------------------
### Underline Formatting
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/text.rst
Shows how to apply single underline using True, no underline using False or None, and other underline styles using WD_UNDERLINE enumeration.
```python
>>> font.underline
None
>>> font.underline = True
>>> # or perhaps
>>> font.underline = WD_UNDERLINE.DOT_DASH
```
--------------------------------
### Get and Set style.unhide_when_used
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Demonstrates retrieving and setting the unhide_when_used property for a style. This property controls the element.
```python
>>> style = document.styles['Foo']
>>> style.unhide_when_used
False
>>> style.unhide_when_used = True
>>> style.unhide_when_used
True
```
--------------------------------
### XML Specimen for Inherited Alignment
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example XML showing a paragraph with inherited alignment, indicated by the absence of a justification element.
```xml
Inherited paragraph alignment.
```
--------------------------------
### Add Paragraph with Runs and Bold Formatting
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Illustrates creating a paragraph without initial text and then adding runs with bold formatting.
```python
paragraph = document.add_paragraph()
paragraph.add_run('Lorem ipsum ')
paragraph.add_run('dolor').bold = True
paragraph.add_run(' sit amet.')
```
--------------------------------
### Create a Word Document with Various Elements
Source: https://github.com/python-openxml/python-docx/blob/master/docs/index.rst
This snippet demonstrates how to create a .docx file using python-docx. It includes adding headings, paragraphs with styled text, lists, images, and tables. Save the document to a file named 'demo.docx'.
```python
from docx import Document
from docx.shared import Inches
document = Document()
document.add_heading('Document Title', 0)
p = document.add_paragraph('A plain paragraph having some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True
document.add_heading('Heading, level 1', level=1)
document.add_paragraph('Intense quote', style='Intense Quote')
document.add_paragraph(
'first item in unordered list',
style='List Bullet'
)
document.add_paragraph(
'first item in ordered list',
style='List Number'
)
document.add_picture('monty-truth.png', width=Inches(1.25))
records = (
(3, '101', 'Spam'),
(7, '422', 'Eggs'),
(4, '631', 'Spam, spam, eggs, and spam')
)
table = document.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'
for qty, id, desc in records:
row_cells = table.add_row().cells
row_cells[0].text = str(qty)
row_cells[1].text = id
row_cells[2].text = desc
document.add_page_break()
document.save('demo.docx')
```
--------------------------------
### Accessing Document Settings
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/settings.rst
Demonstrates how to access the Settings proxy object for a document. This object provides access to the document's settings.
```python
from docx import Document
document = Document()
print(document.settings)
```
--------------------------------
### Setting Font Typeface and Size
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/text.rst
Demonstrates how to set the font's typeface (name) and size using the Font object. Size is specified in points using the Pt class.
```python
>>> from docx.shared import Pt
>>> font.name = 'Calibri'
>>> font.size = Pt(12)
```
--------------------------------
### Set Paragraph Indentation
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Get and set various indentation properties for a paragraph. Indentation can be specified in points (Pt) or inches (Inches).
```python
>>> paragraph_format.left_indent
None
>>> paragraph_format.right_indent
None
>>> paragraph_format.first_line_indent
None
>>> paragraph_format.left_indent = Pt(36)
>>> paragraph_format.left_indent.pt
36.0
>>> paragraph_format.right_indent = Inches(0.25)
>>> paragraph_format.right_indent.pt
18.0
>>> paragraph_format.first_line_indent = Pt(-18)
>>> paragraph_format.first_line_indent.pt
-18.0
```
--------------------------------
### Get and Set Paragraph Spacing
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Shows how to access and modify the space before a paragraph. The spacing is set using a Pt (point) object.
```python
>>> paragraph_format = document.styles['Normal'].paragraph_format
>>> paragraph_format.space_before
None
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.space_before.pt
12.0
```
--------------------------------
### Applying Underline Styles to Text
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/underline.rst
Demonstrates how to set underline styles for a text run. You can use `True` for default single underline, `False` to remove it, or specific values from the `WD_UNDERLINE` enumeration for advanced styles.
```python
run = paragraph.add_run()
run.underline
None
run.underline = True
run.underline
True
run.underline = WD_UNDERLINE.SINGLE
run.underline
True
run.underline = WD_UNDERLINE.DOUBLE
str(run.underline)
DOUBLE (3)
run.underline = False
run.underline
False
run.underline = WD_UNDERLINE.NONE
run.underline
False
run.underline = None
run.underline
None
```
--------------------------------
### Paragraph Spacing XML Semantics
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example of the XML structure for setting 12 points of space before and 0 points of space after a paragraph.
```xml
```
--------------------------------
### Apply Bold Directly to Added Run
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Shows a concise way to add a run and immediately apply bold formatting without needing a separate variable for the run.
```python
paragraph.add_run('dolor').bold = True
```
--------------------------------
### XML Structure for Locked Style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Example of an XML element defining a paragraph style that is locked, preventing modification through the user interface.
```xml
```
--------------------------------
### Specimen XML for Table Cell
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/table/table-cell.rst
An example of the XML structure for a table cell, including properties like width and vertical alignment.
```xml
Amy earned her BA in American Studies
```
--------------------------------
### Add a table with specified dimensions
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/quickstart.rst
Create a table with a given number of rows and columns. The table object can then be populated.
```python
table = document.add_table(rows=2, cols=2)
```
--------------------------------
### Access Hyperlink Address
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/hyperlink.rst
Get the network address (URL) of an external hyperlink. This attribute holds the base URL without any fragment identifier.
```python
>>> hyperlink.address
'https://google.com/'
```
--------------------------------
### Specimen XML for Run Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font.rst
This XML snippet demonstrates the structure of run properties, including bold, italic, small caps, strike, font size, and underline.
```xml
bold, italic, small caps, strike, 14 pt, and underline
```
--------------------------------
### Using WD_STYLE Enum for Built-in Styles
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/enum/WdBuiltinStyle.rst
Demonstrates how to import and use the WD_STYLE enum to access and apply built-in Word styles like BODY_TEXT.
```python
from docx import Document
from docx.enum.style import WD_STYLE
document = Document()
styles = document.styles
style = styles[WD_STYLE.BODY_TEXT]
```
--------------------------------
### XML Specimen for Right-Aligned Paragraph
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Example XML for a right-aligned paragraph, using the 'w:jc' element with 'val="right"'.
```xml
Right-aligned paragraph.
```
--------------------------------
### Setting Font Name and Size
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/styles-using.rst
Set the typeface and size for a font using 'Calibri' and 12pt. Requires importing Pt from docx.shared.
```python
from docx import Document
from docx.shared import Pt
document = Document()
style = document.styles['Normal']
font = style.font
font.name = 'Calibri'
font.size = Pt(12)
```
--------------------------------
### Setting Underline Property
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/styles-using.rst
Shows how to set the underline property to True for single underline, False, or None. For other underline types, use WD_UNDERLINE enumeration.
```python
from docx.enum.text import WD_UNDERLINE
font.underline
font.underline = True
font.underline = WD_UNDERLINE.DOT_DASH
```
--------------------------------
### Access Hyperlink Runs
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/hyperlink.rst
Get a list of all runs that constitute the visible text of a hyperlink. This allows for detailed manipulation of the hyperlink's text formatting.
```python
>>> hyperlink.runs
[
]
```
--------------------------------
### Accessing Run and Font Objects
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/font-color.rst
Demonstrates how to obtain Run and Font objects from a Document. The Font object provides access to text formatting properties.
```python
>>> from docx import Document
>>> from docx.text.run import Font, Run
>>> run = Document().add_paragraph().add_run()
>>> isinstance(run, Run)
True
>>> font = run.font
>>> isinstance(font, Font)
True
```
--------------------------------
### Set Table Row Height
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/table/table-row.rst
Demonstrates how to set the height of a table row using the `height_rule` and `height` properties. Requires importing `WD_ROW_HEIGHT` and `Pt`.
```python
from docx.enum.table import WD_ROW_HEIGHT
from docx.shared import Pt
row = table.add_row()
row.height_rule = WD_ROW_HEIGHT.EXACTLY
row.height = Pt(24)
```
--------------------------------
### Managing Tri-State Font Properties (Bold, Italic)
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/styles-using.rst
Demonstrates setting and checking tri-state font properties like italic to True, False, or None (inherit).
```python
font.bold, font.italic
font.italic = True
font.italic
font.italic = False
font.italic
font.italic = None
font.italic
```
--------------------------------
### Semantics of CT_TblWidth Element
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/table/table-props.rst
Examples illustrating the different ways cell widths (tcW) can be specified in WordprocessingML, including absolute measurements, percentages, and auto-sizing.
```xml
```
--------------------------------
### Specimen XML for Comments
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/comments.rst
Example XML structure for the comments part of a Word document, showing a single comment with its author, date, and text content.
```xml
>
I have this to say about that
```
--------------------------------
### Display a Style in the Style Gallery
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/styles-using.rst
Use this code to make a specific paragraph style, like 'Body Text', appear in the Word style gallery. Set 'hidden' to False, 'quick_style' to True, and assign a 'priority'.
```python
>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Body Text']
>>> style.hidden = False
>>> style.quick_style = True
>>> style.priorty = 1
```
--------------------------------
### MS API: PageSetup Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/header.rst
Read/write properties of the PageSetup object related to header/footer variations.
```python
DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED}
OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED}
```
--------------------------------
### Accessing and Setting Style Hidden Property
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/style.rst
Shows how to get and set the hidden property of a style object. This property controls the visibility of the style in the user interface.
```python
>>> style = document.styles['Foo']
>>> style.hidden
False
>>> style.hidden = True
>>> style.hidden
True
```
--------------------------------
### Setting Table Alignment
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/enum/WdRowAlignment.rst
Demonstrates how to set the alignment of a table to center using the WD_TABLE_ALIGNMENT enum. Requires importing WD_TABLE_ALIGNMENT from docx.enum.table.
```python
from docx.enum.table import WD_TABLE_ALIGNMENT
table = document.add_table(3, 3)
table.alignment = WD_TABLE_ALIGNMENT.CENTER
```
--------------------------------
### Set Section Start Type to New Page
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/enum/WdSectionStart.rst
Assigns the WD_SECTION.NEW_PAGE value to the start_type of a document's section. This requires importing the WD_SECTION enum from docx.enum.section.
```python
from docx.enum.section import WD_SECTION
section = document.sections[0]
section.start_type = WD_SECTION.NEW_PAGE
```
--------------------------------
### Changing Page Orientation and Dimensions
Source: https://github.com/python-openxml/python-docx/blob/master/docs/user/sections.rst
Demonstrates how to change a section's page orientation (portrait/landscape) and its page width and height. Note that changing orientation requires swapping width and height values.
```python
from docx.enum.section import WD_ORIENT
# Assuming 'section' is a Section object
# print(section.orientation, section.page_width, section.page_height)
new_width, new_height = section.page_height, section.page_width
section.orientation = WD_ORIENT.LANDSCAPE
section.page_width = new_width
section.page_height = new_height
# print(section.orientation, section.page_width, section.page_height)
```
--------------------------------
### Default settings.xml Structure
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/settings.rst
Shows the XML structure of a default settings.xml part for a new Word 2016 document. This illustrates the various optional settings available.
```xml
```
--------------------------------
### Set Paragraph Page Placement Properties
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/text/paragraph-format.rst
Get and set page placement properties for a paragraph. These properties control line and paragraph pagination. A value of None indicates inheritance.
```python
>>> paragraph_format.keep_with_next
None
>>> paragraph_format.keep_together
None
>>> paragraph_format.page_break_before
None
>>> paragraph_format.widow_control
None
>>> paragraph_format.keep_with_next = True
>>> paragraph_format.keep_with_next
True
>>> paragraph_format.keep_together = False
>>> paragraph_format.keep_together
False
>>> paragraph_format.page_break_before = True
>>> paragraph_format.widow_control = None
```
--------------------------------
### Settings()
Source: https://github.com/python-openxml/python-docx/blob/master/docs/api/settings.rst
Represents the collection of settings for a Word document. It provides access to various document properties and configurations.
```APIDOC
## Settings()
### Description
Represents the collection of settings for a Word document. It provides access to various document properties and configurations.
### Class
`docx.settings.Settings`
### Methods
This class has members that can be accessed directly. Refer to the `Settings` class documentation for a full list of available members.
```
--------------------------------
### Accessing and Setting Next Paragraph Style
Source: https://github.com/python-openxml/python-docx/blob/master/docs/dev/analysis/features/styles/paragraph-style.rst
Demonstrates how to access the current next paragraph style and how to set it to another style or None. The default behavior returns the current style if the next style is not specified or invalid.
```python
>>> styles = document.styles
>>> paragraph_style = styles['Foo']
>>> paragraph_style.next_paragraph_style == paragraph_style
True
>>> paragraph_style.next_paragraph_style = styles['Bar']
>>> paragraph_style.next_paragraph_style == styles['Bar']
True
>>> paragraph_style.next_paragraph_style = None
>>> paragraph_style.next_paragraph_style == paragraph_style
True
```