repository·master·Indexed 26 days ago
https://github.com/python-openxml/python-docxA Python library for reading, creating, and updating Microsoft Word 2007+ (.docx) files. It provides tools for managing documents via the Document class, handling core properties, and manipulating elements such as paragraphs, tables, comments, and DrawingML colors. The library includes a comprehensive set of enumerations for controlling paragraph alignment, line spacing, page orientation, table cell vertical alignment, and built-in Word styles.
Word uses section elements to define distinct page layout settings (e.g., switching between portrait and landscape).
Key implementation details:
<w:sectPr> element as the last child of <w:body>.<w:sectPr> element within the paragraph properties (<w:p><w:pPr><w:sectPr>) of the last paragraph in that section. The subsequent paragraph begins the next section.<w:sectPr> in paragraph properties, whereas line, page, and column breaks use the <w:br> element within a run.Word documents consist of two layers:
shapes (or floating shapes), are placed at arbitrary positions.A picture can exist in either layer:
Note: As of the current version, python-docx primarily supports inline pictures. Floating pictures can be added, but users with specific requirements should submit a feature request on the issue tracker.
A paragraph style in python-docx combines character formatting and paragraph-specific formatting:
CharacterStyle and primarily accessed via the font property.ParagraphFormat object available via the paragraph_format property.next_paragraph_style.Styles allow you to apply a group of formatting properties consistently to paragraphs, runs, tables, or numbering schemes. In the underlying OpenXML structure, styles are defined in the styles.xml package part and are linked to document elements using a styleId string.
Key concepts:
styles.xml part.<w:style> element in the styles.xml part that defines specific attributes.styleId. The styleId is used for internal linking and may be transformed by Word (e.g., by removing spaces from the name).In python-docx, graphical objects are categorized into two main types based on how they interact with text:
Note that the placement is determined by the container (the InlineShapes or Shapes collection) rather than the graphical object itself. The same object can be changed from inline to floating by moving it to a different container.
In python-docx, a Run is the object representing inline content. It contains elements that flow between block-item boundaries (like paragraphs), such as text, pictures, and other inline items.
Common child elements found within a run include:
<w:t> (Text)<w:br> (Line breaks)<w:drawing> (Drawings/Images)<w:tab> (Tabs)<w:cr> (Carriage returns)To create a new document, instantiate the Document class without passing any arguments. This creates a new document based on the built-in default template. You can then use the .save() method to write it to a file.
from docx import Document
document = Document()
document.save('test.docx')The Document object is the primary entry point for creating or opening a .docx file. You can build a document by adding block-level objects to the end of the document sequentially. Block-level objects include:
Most common use cases involve adding content from top to bottom using methods on the Document instance.
You can add comments to a document using the Document.add_comment() method or the Run.add_comment() method. A comment requires a range of text (the 'comment reference') to anchor it to the document. This range must start and end at even run boundaries. You can specify the range by providing a list of runs or a single run.
Optional parameters include text, author, and initials (both author and initials default to an empty string).
>>> paragraph = document.add_paragraph("Hello, world!")
>>> document.add_comment(
... runs=paragraph.runs,
... text="I have this to say about that",
... author="Steve Canny",
... initials="SC",
... )
<docx.comments.Comment object at 0x02468ACE>
>>> paragraph = document.add_paragraph("Summary: ")
>>> run = paragraph.add_run("{{place-summary-here}}")
>>> document.add_comment(
... run, text="The AI model will replace this placeholder with a summary"
... )
<docx.comments.Comment object at 0x02468ACE>Document object that add block-level elements (such as add_paragraph()) return the newly created object. While you can often call these methods without capturing the return value, you must capture the reference if you need to perform further granular or inline modifications to that specific object.You can work with documents using file-like objects (such as io.BytesIO or io.StringIO) instead of direct file paths. This is useful for handling documents from network connections or databases without interacting with the local file system.
When opening a file directly using Python's open(), it is recommended to use binary mode ('rb') to ensure compatibility with the underlying Zipfile implementation, especially on Windows and certain Linux distributions.
from io import StringIO
# Opening from a file stream
f = open('foobar.docx', 'rb')
document = Document(f)
f.close()
# Using a StringIO stream
with open('foobar.docx', 'rb') as f:
source_stream = StringIO(f.read())
document = Document(source_stream)
source_stream.close()
# Saving to a stream
target_stream = StringIO()
document.save(target_stream)