Class PackURI

src/docx/opc/packuri.py:12–105

Provides access to pack URI components such as the baseURI and the filename slice. Behaves as |str| otherwise.

class PackURI(str):
    """Provides access to pack URI components such as the baseURI and the filename slice.

    Behaves as |str| otherwise.
    """

    _filename_re = re.compile("([a-zA-Z]+)([1-9][0-9]*)?")

    def __new__(cls, pack_uri_str: str):
        if pack_uri_str[0] != "/":
            tmpl = "PackURI must begin with slash, got '%s'"
            raise ValueError(tmpl % pack_uri_str)
        return str.__new__(cls, pack_uri_str)

    @staticmethod
    def from_rel_ref(baseURI: str, relative_ref: str) -> PackURI:
        """The absolute PackURI formed by translating `relative_ref` onto `baseURI`."""
        joined_uri = posixpath.join(baseURI, relative_ref)
        abs_uri = posixpath.abspath(joined_uri)
        return PackURI(abs_uri)

    @property
    def baseURI(self) -> str:
        """The base URI of this pack URI, the directory portion, roughly speaking.

        E.g. ``'/ppt/slides'`` for ``'/ppt/slides/slide1.xml'``. For the package pseudo-
        partname '/', baseURI is '/'.
        """
        return posixpath.split(self)[0]

    @property
    def ext(self) -> str:
        """The extension portion of this pack URI, e.g. ``'xml'`` for ``'/word/document.xml'``.

        Note the period is not included.
        """
        # raw_ext is either empty string or starts with period, e.g. '.xml'
        raw_ext = posixpath.splitext(self)[1]
        return raw_ext[1:] if raw_ext.startswith(".") else raw_ext

    @property
    def filename(self):
        """The "filename" portion of this pack URI, e.g. ``'slide1.xml'`` for
        ``'/ppt/slides/slide1.xml'``.

        For the package pseudo-partname '/', filename is ''.
        """
        return posixpath.split(self)[1]

    @property
    def idx(self):
        """Return partname index as integer for tuple partname or None for singleton
        partname, e.g. ``21`` for ``'/ppt/slides/slide21.xml'`` and |None| for
        ``'/ppt/presentation.xml'``."""
        filename = self.filename
        if not filename:
            return None
        name_part = posixpath.splitext(filename)[0]  # filename w/ext removed