Skip to content

story

story

StoryPart and related objects.

StoryPart 

StoryPart(
    partname: PackURI,
    content_type: str,
    element: BaseOxmlElement,
    package: Package,
)

Bases: XmlPart

Base class for story parts.

A story part is one that can contain textual content, such as the document-part and header or footer parts. These all share content behaviors like .paragraphs, .add_paragraph(), .add_table() etc.

Source code in src/docx/opc/part.py 
223
224
225
226
227
def __init__(
    self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
):
    super(XmlPart, self).__init__(partname, content_type, package=package)
    self._element = element

next_bookmark_id property 

next_bookmark_id: int

Next available w:id for a bookmark in this story.

A bookmark id pairs a w:bookmarkStart with its w:bookmarkEnd, so it needs to be unique only among the bookmarks of this part; next_id does not see these, because it looks at unprefixed id attributes and a bookmark's is w:id.

next_id property 

next_id: int

Next available positive integer id value in this story XML document.

The value is determined by incrementing the maximum existing id value. Gaps in the existing id sequence are not filled. The id attribute value is unique in the document, without regard to the element type it appears on.

document_part property 

document_part: DocumentPart

The DocumentPart of this package.

A story part is not always the document part — a header or footnote is a story too — but the parts they share, styles and numbering among them, hang off the document part. This is how a paragraph in any story reaches them.

get_or_add_image 

get_or_add_image(
    image_descriptor: str | PathLike[str] | IO[bytes],
) -> Tuple[str, Image]

Return (rId, image) pair for image identified by image_descriptor.

rId is the str key (often like "rId7") for the relationship between this story part and the image part, reused if already present, newly created if not. image is an Image instance providing access to the properties of the image, such as dimensions and image type.

Source code in src/docx/parts/story.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def get_or_add_image(
    self, image_descriptor: str | os.PathLike[str] | IO[bytes]
) -> Tuple[str, Image]:
    """Return (rId, image) pair for image identified by `image_descriptor`.

    `rId` is the str key (often like "rId7") for the relationship between this story
    part and the image part, reused if already present, newly created if not.
    `image` is an |Image| instance providing access to the properties of the image,
    such as dimensions and image type.
    """
    package = self._package
    assert package is not None
    image_part = package.get_or_add_image_part(image_descriptor)
    rId = self.relate_to(image_part, RT.IMAGE)
    return rId, image_part.image

get_style 

get_style(
    style_id: str | None, style_type: WD_STYLE_TYPE
) -> BaseStyle

Return the style in this document matching style_id.

Returns the default style for style_type if style_id is None or does not match a defined style of style_type.

Source code in src/docx/parts/story.py 
45
46
47
48
49
50
51
def get_style(self, style_id: str | None, style_type: WD_STYLE_TYPE) -> BaseStyle:
    """Return the style in this document matching `style_id`.

    Returns the default style for `style_type` if `style_id` is |None| or does not
    match a defined style of `style_type`.
    """
    return self._document_part.get_style(style_id, style_type)

get_style_id 

get_style_id(
    style_or_name: BaseStyle | str | None,
    style_type: WD_STYLE_TYPE,
) -> str | None

Return str style_id for style_or_name of style_type.

Returns None if the style resolves to the default style for style_type or if style_or_name is itself None. Raises if style_or_name is a style of the wrong type or names a style not present in the document.

Source code in src/docx/parts/story.py 
53
54
55
56
57
58
59
60
61
62
def get_style_id(
    self, style_or_name: BaseStyle | str | None, style_type: WD_STYLE_TYPE
) -> str | None:
    """Return str style_id for `style_or_name` of `style_type`.

    Returns |None| if the style resolves to the default style for `style_type` or if
    `style_or_name` is itself |None|. Raises if `style_or_name` is a style of the
    wrong type or names a style not present in the document.
    """
    return self._document_part.get_style_id(style_or_name, style_type)

new_pic_inline 

new_pic_inline(
    image_descriptor: str | PathLike[str] | IO[bytes],
    width: int | Length | None = None,
    height: int | Length | None = None,
    description: str | None = None,
    title: str | None = None,
    svg_fallback: str
    | PathLike[str]
    | IO[bytes]
    | None = None,
    honor_exif_orientation: bool = True,
) -> CT_Inline

Return a newly-created w:inline element.

The element contains the image specified by image_descriptor and is scaled based on the values of width and height. description and title are the alternative text of the picture. svg_fallback is the raster image to show in place of an SVG where the SVG cannot be rendered.

honor_exif_orientation applies the image's EXIF Orientation as a rotation in the DrawingML; see Run.add_picture.

Source code in src/docx/parts/story.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def new_pic_inline(
    self,
    image_descriptor: str | os.PathLike[str] | IO[bytes],
    width: int | Length | None = None,
    height: int | Length | None = None,
    description: str | None = None,
    title: str | None = None,
    svg_fallback: str | os.PathLike[str] | IO[bytes] | None = None,
    honor_exif_orientation: bool = True,
) -> CT_Inline:
    """Return a newly-created `w:inline` element.

    The element contains the image specified by `image_descriptor` and is scaled
    based on the values of `width` and `height`. `description` and `title` are the
    alternative text of the picture. `svg_fallback` is the raster image to show in
    place of an SVG where the SVG cannot be rendered.

    `honor_exif_orientation` applies the image's EXIF `Orientation` as a rotation in
    the DrawingML; see :meth:`.Run.add_picture`.
    """
    rId, image, svg_rId = self._image_rIds(image_descriptor, svg_fallback)
    cx, cy = image.scaled_dimensions(
        width, height, honor_exif_orientation=honor_exif_orientation
    )
    transform = image.drawingml_transform if honor_exif_orientation else (0, False)
    shape_id, filename = self.next_id, image.filename
    return CT_Inline.new_pic_inline(
        shape_id,
        rId,
        filename,
        cx,
        cy,
        description=description,
        title=title,
        svg_rId=svg_rId,
        transform=transform,
    )

new_pic_anchor 

new_pic_anchor(
    image_descriptor: str | PathLike[str] | IO[bytes],
    width: int | Length | None = None,
    height: int | Length | None = None,
    pos_x: Length | int = 0,
    pos_y: Length | int = 0,
    description: str | None = None,
    title: str | None = None,
    svg_fallback: str
    | PathLike[str]
    | IO[bytes]
    | None = None,
    honor_exif_orientation: bool = True,
) -> CT_Anchor

Return a newly-created wp:anchor element for a floating picture.

The arguments match new_pic_inline, with pos_x and pos_y giving the offset from the column and paragraph the shape is anchored to.

Source code in src/docx/parts/story.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def new_pic_anchor(
    self,
    image_descriptor: str | os.PathLike[str] | IO[bytes],
    width: int | Length | None = None,
    height: int | Length | None = None,
    pos_x: Length | int = 0,
    pos_y: Length | int = 0,
    description: str | None = None,
    title: str | None = None,
    svg_fallback: str | os.PathLike[str] | IO[bytes] | None = None,
    honor_exif_orientation: bool = True,
) -> CT_Anchor:
    """Return a newly-created `wp:anchor` element for a floating picture.

    The arguments match :meth:`new_pic_inline`, with `pos_x` and `pos_y` giving the
    offset from the column and paragraph the shape is anchored to.
    """
    rId, image, svg_rId = self._image_rIds(image_descriptor, svg_fallback)
    cx, cy = image.scaled_dimensions(
        width, height, honor_exif_orientation=honor_exif_orientation
    )
    transform = image.drawingml_transform if honor_exif_orientation else (0, False)
    return CT_Anchor.new_pic_anchor(
        self.next_id,
        rId,
        image.filename,
        cx,
        cy,
        Emu(int(pos_x)),
        Emu(int(pos_y)),
        description=description,
        title=title,
        svg_rId=svg_rId,
        transform=transform,
    )