API basics

The API for python-docx is designed to make doing simple things simple, while allowing more complex results to be achieved with a modest and incremental investment of understanding.

It’s possible to create a basic document using only a single object, the docx.api.Document object returned when opening a file. The methods on docx.api.Document allow block-level objects to be added to the end of the document. Block-level objects include paragraphs, inline pictures, and tables. Headings, bullets, and numbered lists are simply paragraphs with a particular style applied.

In this way, a document can be “written” from top to bottom, roughly like a person would if they knew exactly what they wanted to say This basic use case, where content is always added to the end of the document, is expected to account for perhaps 80% of actual use cases, so it’s a priority to make it as simple as possible without compromising the power of the overall API.

Inline objects

Each block-level method on docx.api.Document, such as add_paragraph(), returns the block-level object created. Often the reference is unneeded; but when inline objects must be created individually, you’ll need the block-item reference to do it.

... add example here as API solidifies ...