tessl/pypi-python-docx

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

—

Pending

Overview

Eval results

Files

Document Operations

Name: tessl/pypi-python-docx
Author: tessl

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

Capabilities

Document Creation and Opening

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

def Document(docx=None):
    """Create or open a Word document.
    
    Args:
        docx (str, file-like, or None): Path to .docx file, file-like object, or None for new document
        
    Returns:
        Document: Document object for manipulation
        
    Raises:
        ValueError: If file is not a valid Word document
    """

Usage Examples:

from docx import Document

# Create a new document
doc = Document()

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

# Open from file-like object
with open('document.docx', 'rb') as f:
    doc = Document(f)

Document Saving

Save documents to files or file-like objects.

class Document:
    def save(self, path_or_stream):
        """Save document to file or stream.
        
        Args:
            path_or_stream (str or file-like): File path or file-like object to save to
        """

Usage Examples:

# Save to file path
doc.save('output.docx')

# Save to file-like object
from io import BytesIO
buffer = BytesIO()
doc.save(buffer)
buffer.seek(0)

Core Document Properties

Access and modify document metadata and core properties.

class Document:
    @property
    def core_properties(self):
        """Core document properties for metadata.
        
        Returns:
            CoreProperties: Object with title, author, subject, etc.
        """

class CoreProperties:
    @property
    def title(self):
        """Document title."""
    
    @title.setter
    def title(self, value):
        """Set document title."""
    
    @property
    def author(self):
        """Document author."""
    
    @author.setter
    def author(self, value):
        """Set document author."""
    
    @property
    def subject(self):
        """Document subject."""
    
    @subject.setter
    def subject(self, value):
        """Set document subject."""
    
    @property
    def created(self):
        """Document creation datetime."""
    
    @property
    def modified(self):
        """Document last modified datetime."""
    
    @property
    def last_modified_by(self):
        """User who last modified document."""
    
    @property
    def revision(self):
        """Document revision number."""
    
    @property
    def keywords(self):
        """Document keywords."""
    
    @keywords.setter
    def keywords(self, value):
        """Set document keywords."""
    
    @property
    def comments(self):
        """Document comments/description."""
    
    @comments.setter
    def comments(self, value):
        """Set document comments."""
    
    @property
    def category(self):
        """Document category."""
    
    @category.setter
    def category(self, value):
        """Set document category."""

Usage Examples:

# Access and modify document properties
props = doc.core_properties
props.title = 'My Document Title'
props.author = 'John Doe'
props.subject = 'Document Subject'
props.keywords = 'keyword1, keyword2, keyword3'
props.comments = 'This is a sample document'

# Read existing properties
print(f"Created: {props.created}")
print(f"Modified: {props.modified}")
print(f"Revision: {props.revision}")

Section Management

Add and manage document sections for page layout control.

class Document:
    def add_section(self, start_type=None):
        """Add a new section to the document.
        
        Args:
            start_type (WD_SECTION_START, optional): How section should start
            
        Returns:
            Section: New section object
        """
    
    @property
    def sections(self):
        """Collection of document sections.
        
        Returns:
            Sections: Sequence of Section objects
        """

Usage Examples:

from docx.enum.section import WD_SECTION_START

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

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

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

Document Structure Access

Access major document components and collections.

class Document:
    @property
    def paragraphs(self):
        """All paragraphs in document body.
        
        Returns:
            list[Paragraph]: List of paragraph objects
        """
    
    @property
    def tables(self):
        """All tables in document body.
        
        Returns:
            list[Table]: List of table objects
        """
    
    @property
    def inline_shapes(self):
        """All inline shapes in document.
        
        Returns:
            InlineShapes: Collection of inline shape objects
        """
    
    @property
    def styles(self):
        """Document styles collection.
        
        Returns:
            Styles: Collection of document styles
        """
    
    @property
    def settings(self):
        """Document settings.
        
        Returns:
            Settings: Document settings object
        """
    
    @property
    def comments(self):
        """Document comments collection.
        
        Returns:
            Comments: Collection of comment objects
        """

Usage Examples:

# Access document structure
print(f"Document has {len(doc.paragraphs)} paragraphs")
print(f"Document has {len(doc.tables)} tables")
print(f"Document has {len(doc.inline_shapes)} shapes")

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

# Access styles
for style in doc.styles:
    print(f"Style: {style.name} ({style.type})")

Page Break Operations

Add page breaks to document flow.

class Document:
    def add_page_break(self):
        """Add a page break to the document.
        
        Returns:
            Paragraph: Empty paragraph containing the page break
        """

Usage Examples:

# Add content
doc.add_paragraph("Content on page 1")

# Add page break
doc.add_page_break()

# Add content on new page
doc.add_paragraph("Content on page 2")

Types

from docx.enum.section import WD_SECTION_START

class WD_SECTION_START:
    """Section start types."""
    CONTINUOUS = 0
    NEW_COLUMN = 1  
    NEW_PAGE = 2
    EVEN_PAGE = 3
    ODD_PAGE = 4

Install with Tessl CLI