or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

comments.mddocument-operations.mdimages-shapes.mdindex.mdsections-layout.mdstyles-formatting.mdtables.mdtext-paragraphs.md
tile.json

tessl/pypi-python-docx

Create, read, and update Microsoft Word .docx files.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-docx@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-python-docx@1.2.0

index.mddocs/

Python-docx

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.

Package Information

  • Package Name: python-docx
  • Language: Python
  • Installation: pip install python-docx
  • Version: 1.2.0

Core Imports

from docx import Document

For specific components:

from docx import Document
from docx.shared import Inches, Cm, Mm, Pt, Emu, RGBColor
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_BREAK_TYPE
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT

Basic Usage

from docx import Document
from docx.shared import Inches

# Create a new document
doc = Document()

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

# Add a paragraph
p = doc.add_paragraph('This is a paragraph with some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True

# Add a table
table = doc.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Name'
hdr_cells[1].text = 'Age'
hdr_cells[2].text = 'City'

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

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

# Save the document
doc.save('demo.docx')

Architecture

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

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

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

Capabilities

Document Operations

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

def Document(docx=None):
    """Create or open a Word document.
    
    Args:
        docx (str or file-like, optional): Path to .docx file or file-like object
        
    Returns:
        Document: Document object for manipulation
    """

class Document:
    def save(self, path_or_stream):
        """Save document to file or stream."""
    
    def add_section(self, start_type=WD_SECTION_START.NEW_PAGE):
        """Add a new section to the document."""
    
    @property
    def core_properties(self):
        """Core document properties (title, author, etc.)."""

Document Operations

Text and Paragraphs

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

class Document:
    def add_paragraph(self, text='', style=None):
        """Add a paragraph to the document."""
    
    def add_heading(self, text='', level=1):
        """Add a heading paragraph."""

class Paragraph:
    def add_run(self, text=None, style=None):
        """Add a run of text to the paragraph."""
    
    def clear(self):
        """Remove all content from paragraph."""
    
    @property
    def text(self):
        """Plain text content of paragraph."""

class Run:
    @property
    def font(self):
        """Font formatting object."""
    
    @property
    def bold(self):
        """Get/set bold formatting."""

Text and Paragraphs

Tables

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

class Document:
    def add_table(self, rows, cols, style=None):
        """Add a table to the document."""

class Table:
    def add_row(self):
        """Add a row to the table."""
    
    def add_column(self, width):
        """Add a column to the table."""
    
    def cell(self, row_idx, col_idx):
        """Access specific table cell."""
    
    @property
    def rows(self):
        """Collection of table rows."""
    
    @property
    def columns(self):
        """Collection of table columns."""

Tables

Styles and Formatting

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

class Document:
    @property
    def styles(self):
        """Document styles collection."""

class Font:
    @property
    def name(self):
        """Font name."""
    
    @property
    def size(self):
        """Font size in points."""
    
    @property
    def color(self):
        """Font color."""

class ParagraphFormat:
    @property
    def alignment(self):
        """Paragraph alignment."""
    
    @property
    def line_spacing(self):
        """Line spacing."""

Styles and Formatting

Images and Shapes

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

class Document:
    def add_picture(self, image_path_or_stream, width=None, height=None):
        """Add an image to the document."""
    
    @property
    def inline_shapes(self):
        """Collection of inline shapes in document."""

class InlineShape:
    @property
    def width(self):
        """Shape width."""
    
    @property
    def height(self):
        """Shape height."""

Images and Shapes

Sections and Page Layout

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

class Section:
    @property
    def page_width(self):
        """Page width."""
    
    @property
    def page_height(self):
        """Page height."""
    
    @property
    def orientation(self):
        """Page orientation (portrait/landscape)."""
    
    @property
    def header(self):
        """Section header."""
    
    @property
    def footer(self):
        """Section footer."""

Sections and Page Layout

Comments

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

class Document:
    def add_comment(self, runs, text='', author='', initials=''):
        """Add a comment to the document.
        
        Args:
            runs (Run or list[Run]): Run or sequence of runs to anchor comment to
            text (str, optional): Comment text content
            author (str, optional): Comment author name  
            initials (str, optional): Author initials
            
        Returns:
            Comment: New comment object
        """
    
    @property
    def comments(self):
        """Collection of document comments."""

class Comment:
    @property
    def text(self):
        """Comment text content."""
    
    @property
    def author(self):
        """Comment author."""

Comments

Measurement Classes

class Length(int):
    """Base measurement class in English Metric Units."""
    
    @property
    def inches(self):
        """Value in inches."""
    
    @property
    def cm(self):
        """Value in centimeters."""

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

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

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

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

class RGBColor(tuple):
    """RGB color specification."""
    
    def __init__(self, r, g, b):
        """Create RGB color from 0-255 values."""

Core Enumerations

Key enumeration values for document formatting:

from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
# Values: LEFT, CENTER, RIGHT, JUSTIFY, DISTRIBUTE

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

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

from docx.enum.section import WD_ORIENTATION
# Values: PORTRAIT, LANDSCAPE