part

part

Open Packaging Convention (OPC) objects related to package parts.

Part

Part(
    partname: PackURI,
    content_type: str,
    blob: bytes | None = None,
    package: Package | None = None,
)

Base class for package parts.

Provides common properties and methods, but intended to be subclassed in client code to implement specific part behaviors.

Source code in src/docx/opc/part.py

def __init__(
    self,
    partname: PackURI,
    content_type: str,
    blob: bytes | None = None,
    package: Package | None = None,
):
    super(Part, self).__init__()
    self._partname = partname
    self._content_type = content_type
    self._blob = blob
    self._package = package

blob property

blob: bytes

Contents of this package part as a sequence of bytes.

May be text or binary. Intended to be overridden by subclasses. Default behavior is to return load blob.

content_type property writable

content_type

Content type of this part.

Writable, because a part can legitimately change what it is without its bytes changing — a Word document and a Word template hold identical markup and differ only here.

package property

package

OpcPackage instance this part belongs to.

partname property writable

partname

PackURI instance holding partname of this part, e.g. '/ppt/slides/slide1.xml'.

related_parts property

related_parts

Dictionary mapping related parts by rId, so child objects can resolve explicit relationships present in the part XML, e.g. sldIdLst to a specific Slide instance.

after_unmarshal

after_unmarshal()

Entry point for post-unmarshaling processing, for example to parse the part XML.

May be overridden by subclasses without forwarding call to super.

Source code in src/docx/opc/part.py

def after_unmarshal(self):
    """Entry point for post-unmarshaling processing, for example to parse the part
    XML.

    May be overridden by subclasses without forwarding call to super.
    """
    # don't place any code here, just catch call if not overridden by
    # subclass
    pass

before_marshal

before_marshal()

Entry point for pre-serialization processing, for example to finalize part naming if necessary.

May be overridden by subclasses without forwarding call to super.

Source code in src/docx/opc/part.py

def before_marshal(self):
    """Entry point for pre-serialization processing, for example to finalize part
    naming if necessary.

    May be overridden by subclasses without forwarding call to super.
    """
    # don't place any code here, just catch call if not overridden by
    # subclass
    pass

drop_rel

drop_rel(rId: str)

Remove the relationship identified by rId if its reference count is less than 2.

Relationships with a reference count of 0 are implicit relationships.

Source code in src/docx/opc/part.py

def drop_rel(self, rId: str):
    """Remove the relationship identified by `rId` if its reference count is less
    than 2.

    Relationships with a reference count of 0 are implicit relationships.
    """
    if self._rel_ref_count(rId) < 2:
        del self.rels[rId]

load_rel

load_rel(
    reltype: str,
    target: Part | str,
    rId: str,
    is_external: bool = False,
)

Return newly added _Relationship instance of reltype.

The new relationship relates the target part to this part with key rId.

Target mode is set to RTM.EXTERNAL if is_external is True. Intended for use during load from a serialized package, where the rId is well-known. Other methods exist for adding a new relationship to a part when manipulating a part.

Source code in src/docx/opc/part.py

def load_rel(self, reltype: str, target: Part | str, rId: str, is_external: bool = False):
    """Return newly added |_Relationship| instance of `reltype`.

    The new relationship relates the `target` part to this part with key `rId`.

    Target mode is set to ``RTM.EXTERNAL`` if `is_external` is |True|. Intended for
    use during load from a serialized package, where the rId is well-known. Other
    methods exist for adding a new relationship to a part when manipulating a part.
    """
    return self.rels.add_relationship(reltype, target, rId, is_external)

part_related_by

part_related_by(reltype: str) -> Part

Return part to which this part has a relationship of reltype.

Raises KeyError if no such relationship is found and ValueError if more than one such relationship is found. Provides ability to resolve implicitly related part, such as Slide -> SlideLayout.

Source code in src/docx/opc/part.py

def part_related_by(self, reltype: str) -> Part:
    """Return part to which this part has a relationship of `reltype`.

    Raises |KeyError| if no such relationship is found and |ValueError| if more than
    one such relationship is found. Provides ability to resolve implicitly related
    part, such as Slide -> SlideLayout.
    """
    return self.rels.part_with_reltype(reltype)

relate_to

relate_to(
    target: Part | str,
    reltype: str,
    is_external: bool = False,
) -> str

Return rId key of relationship of reltype to target.

The returned rId is from an existing relationship if there is one, otherwise a new relationship is created.

Source code in src/docx/opc/part.py

def relate_to(self, target: Part | str, reltype: str, is_external: bool = False) -> str:
    """Return rId key of relationship of `reltype` to `target`.

    The returned `rId` is from an existing relationship if there is one, otherwise a
    new relationship is created.
    """
    if is_external:
        return self.rels.get_or_add_ext_rel(reltype, cast(str, target))
    else:
        rel = self.rels.get_or_add(reltype, cast(Part, target))
        return rel.rId

rels

rels()

Relationships instance holding the relationships for this part.

Source code in src/docx/opc/part.py

@lazyproperty
def rels(self):
    """|Relationships| instance holding the relationships for this part."""
    # -- prevent breakage in `python-docx-template` by retaining legacy `._rels` attribute --
    self._rels = Relationships(self._partname.baseURI)
    return self._rels

target_ref

target_ref(rId: str) -> str

Return URL contained in target ref of relationship identified by rId.

Source code in src/docx/opc/part.py

def target_ref(self, rId: str) -> str:
    """Return URL contained in target ref of relationship identified by `rId`."""
    rel = self.rels[rId]
    return rel.target_ref

PartFactory

Provides a way for client code to specify a subclass of Part to be constructed by Unmarshaller based on its content type and/or a custom callable.

Setting PartFactory.part_class_selector to a callable object will cause that object to be called with the parameters content_type, reltype, once for each part in the package. If the callable returns an object, it is used as the class for that part. If it returns None, part class selection falls back to the content type map defined in PartFactory.part_type_for. If no class is returned from either of these, the class contained in PartFactory.default_part_type is used to construct the part, which is by default opc.package.Part.

XmlPart

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

Bases: Part

Base class for package parts containing an XML payload, which is most of them.

Provides additional methods to the Part base class that take care of parsing and reserializing the XML payload and managing relationships to other parts.

Source code in src/docx/opc/part.py

def __init__(
    self, partname: PackURI, content_type: str, element: BaseOxmlElement, package: Package
):
    super(XmlPart, self).__init__(partname, content_type, package=package)
    self._element = element

element property

element

The root XML element of this XML part.

part property

part

Part of the parent protocol, "children" of the document will not know the part that contains them so must ask their parent object.

That chain of delegation ends here for child objects.