Conceptually, Word documents have two layers, a text layer and a drawing layer. In the text layer, text objects are flowed from left to right and from top to bottom, starting a new page when the prior one is filled. In the drawing layer, drawing objects, called shapes, are placed at arbitrary positions. These are sometimes referred to as floating shapes.

A picture is a shape that can appear in either the text or drawing layer. When it appears in the text layer it is called an inline shape, or more specifically, an inline picture.

Inline shapes are treated like a big text character (a character glyph). The line height is increased to accomodate the shape and the shape is wrapped to a line it will fit on width-wise, just like text. Inserting text in front of it will cause it to move to the right. Often, a picture is placed in a paragraph by itself, but this is not required. It can have text before and after it in the paragraph in which it's placed.

At the time of writing, |docx| only supports inline pictures. Floating pictures can be added. If you have an active use case, submit a feature request on the issue tracker. The Document.add_picture() method adds a specified picture to the end of the document in a paragraph of its own. However, by digging a little deeper into the API you can place text on either side of the picture in its paragraph, or both.

Use the returned |InlineShape| to describe an image for readers who cannot see it:

picture = document.add_picture("revenue.png")
picture.description = "Quarterly revenue increased by 20 percent."
picture.title = "Quarterly revenue"

description maps to wp:docPr/@descr and title maps to wp:docPr/@title. Both properties accept Unicode strings. A missing attribute returns |None|. Assign |None| to remove it, or "" to store an explicitly empty value. An empty description does not mark the image as decorative.

These properties belong to each placed shape. Two uses of the same image can have different descriptions. They do not change the image bytes, filename, internal object name, dimensions, or one another. They also leave any metadata on the nested pic:cNvPr element unchanged and do not use it as a fallback.

The same properties are available on shapes returned by Run.add_picture(), including pictures in table cells, headers, and footers. The optional title is separate from the description and is not a replacement for it. This API does not add floating-shape or decorative-image support.