rel

rel

Relationship-related objects.

_RelatedParts

Bases: Dict[str, 'Part']

Mapping of rId to target part, reporting an unresolvable rId usefully.

A reference to an rId that has no target part is what a document looks like after a relationship to a missing part has been dropped on load: the w:drawing (or other referring element) is still there, but its rId no longer resolves. Subclasses dict and raises KeyError, so existing handling is unaffected; only the message improves.

Relationships

Relationships(baseURI: str)

Bases: Dict[str, '_Relationship']

Collection object for _Relationship instances, having list semantics.

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

def __init__(self, baseURI: str):
    super(Relationships, self).__init__()
    self._baseURI = baseURI
    self._target_parts_by_rId: dict[str, Any] = _RelatedParts()

related_parts property

related_parts

Dict mapping rIds to target parts for all the internal relationships in the collection.

xml property

xml: str

Serialize this relationship collection into XML suitable for storage as a .rels file in an OPC package.

add_relationship

add_relationship(
    reltype: str,
    target: Part | str,
    rId: str,
    is_external: bool = False,
) -> "_Relationship"

Return a newly added _Relationship instance.

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

def add_relationship(
    self, reltype: str, target: Part | str, rId: str, is_external: bool = False
) -> "_Relationship":
    """Return a newly added |_Relationship| instance."""
    rel = _Relationship(rId, reltype, target, self._baseURI, is_external)
    self[rId] = rel
    if not is_external:
        self._target_parts_by_rId[rId] = target
    return rel

get_or_add

get_or_add(
    reltype: str, target_part: Part
) -> _Relationship

Return relationship of reltype to target_part, newly added if not already present in collection.

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

def get_or_add(self, reltype: str, target_part: Part) -> _Relationship:
    """Return relationship of `reltype` to `target_part`, newly added if not already
    present in collection."""
    rel = self._get_matching(reltype, target_part)
    if rel is None:
        rId = self._next_rId
        rel = self.add_relationship(reltype, target_part, rId)
    return rel

get_or_add_ext_rel

get_or_add_ext_rel(reltype: str, target_ref: str) -> str

Return rId of external relationship of reltype to target_ref, newly added if not already present in collection.

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

def get_or_add_ext_rel(self, reltype: str, target_ref: str) -> str:
    """Return rId of external relationship of `reltype` to `target_ref`, newly added
    if not already present in collection."""
    rel = self._get_matching(reltype, target_ref, is_external=True)
    if rel is None:
        rId = self._next_rId
        rel = self.add_relationship(reltype, target_ref, rId, is_external=True)
    return rel.rId

part_with_reltype

part_with_reltype(reltype: str) -> Part

Return target part of rel with matching reltype, raising KeyError if not found and ValueError if more than one matching relationship is found.

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

def part_with_reltype(self, reltype: str) -> Part:
    """Return target part of rel with matching `reltype`, raising |KeyError| if not
    found and |ValueError| if more than one matching relationship is found."""
    rel = self._get_rel_of_type(reltype)
    return rel.target_part

_Relationship

_Relationship(
    rId: str,
    reltype: str,
    target: Part | str,
    baseURI: str,
    external: bool = False,
)

Value object for relationship to part.

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

def __init__(
    self, rId: str, reltype: str, target: Part | str, baseURI: str, external: bool = False
):
    super(_Relationship, self).__init__()
    self._rId = rId
    self._reltype = reltype
    self._target = target
    self._baseURI = baseURI
    self._is_external = bool(external)