oxml

oxml

Temporary stand-in for main oxml module.

This module came across with the PackageReader transplant. Probably much will get replaced with objects from the pptx.oxml.core and then this module will either get deleted or only hold the package related custom element classes.

BaseOxmlElement

Bases: ElementBase

Base class for all custom element classes, to add standardized behavior to all classes in one place.

xml property

xml: str

Return XML string for this element, suitable for testing purposes.

Pretty printed for readability and without an XML declaration at the top.

CT_Default

Bases: BaseOxmlElement

<Default> element that appears in [Content_Types].xml part.

Used to specify a default content type to be applied to any part with the specified extension.

content_type property

content_type

String held in the ContentType attribute of this <Default> element.

extension property

extension

String held in the Extension attribute of this <Default> element.

new staticmethod

new(ext: str, content_type: str)

Return a new <Default> element with attributes set to parameter values.

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

@staticmethod
def new(ext: str, content_type: str):
    """Return a new ``<Default>`` element with attributes set to parameter values."""
    xml = '<Default xmlns="%s"/>' % nsmap["ct"]
    default = parse_xml(xml)
    default.set("Extension", ext)
    default.set("ContentType", content_type)
    return default

CT_Override

Bases: BaseOxmlElement

<Override> element, specifying the content type to be applied for a part with the specified partname.

content_type property

content_type

String held in the ContentType attribute of this <Override> element.

partname property

partname

String held in the PartName attribute of this <Override> element.

new staticmethod

new(partname, content_type)

Return a new <Override> element with attributes set to parameter values.

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

@staticmethod
def new(partname, content_type):
    """Return a new ``<Override>`` element with attributes set to parameter values."""
    xml = '<Override xmlns="%s"/>' % nsmap["ct"]
    override = parse_xml(xml)
    override.set("PartName", partname)
    override.set("ContentType", content_type)
    return override

CT_Relationship

Bases: BaseOxmlElement

<Relationship> element, representing a single relationship from source to target part.

rId property

rId

String held in the Id attribute of this <Relationship> element.

reltype property

reltype

String held in the Type attribute of this <Relationship> element.

target_ref property

target_ref

String held in the Target attribute of this <Relationship> element.

target_mode property

target_mode

String held in the TargetMode attribute of this <Relationship> element, either Internal or External.

Defaults to Internal.

new staticmethod

new(
    rId: str,
    reltype: str,
    target: str,
    target_mode: str = INTERNAL,
)

Return a new <Relationship> element.

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

@staticmethod
def new(rId: str, reltype: str, target: str, target_mode: str = RTM.INTERNAL):
    """Return a new ``<Relationship>`` element."""
    xml = '<Relationship xmlns="%s"/>' % nsmap["pr"]
    relationship = parse_xml(xml)
    relationship.set("Id", rId)
    relationship.set("Type", reltype)
    relationship.set("Target", target)
    if target_mode == RTM.EXTERNAL:
        relationship.set("TargetMode", RTM.EXTERNAL)
    return relationship

CT_Relationships

Bases: BaseOxmlElement

<Relationships> element, the root element in a .rels file.

Relationship_lst property

Relationship_lst

Return a list containing all the <Relationship> child elements.

xml property

xml

Return XML string for this element, suitable for saving in a .rels stream, not pretty printed and with an XML declaration at the top.

add_rel

add_rel(
    rId: str,
    reltype: str,
    target: str,
    is_external: bool = False,
)

Add a child <Relationship> element with attributes set according to parameter values.

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

def add_rel(self, rId: str, reltype: str, target: str, is_external: bool = False):
    """Add a child ``<Relationship>`` element with attributes set according to
    parameter values."""
    target_mode = RTM.EXTERNAL if is_external else RTM.INTERNAL
    relationship = CT_Relationship.new(rId, reltype, target, target_mode)
    self.append(relationship)

new staticmethod

new() -> CT_Relationships

Return a new <Relationships> element.

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

@staticmethod
def new() -> CT_Relationships:
    """Return a new ``<Relationships>`` element."""
    xml = '<Relationships xmlns="%s"/>' % nsmap["pr"]
    return cast(CT_Relationships, parse_xml(xml))

CT_Types

Bases: BaseOxmlElement

<Types> element, the container element for Default and Override elements in [Content_Types].xml.

add_default

add_default(ext, content_type)

Add a child <Default> element with attributes set to parameter values.

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

def add_default(self, ext, content_type):
    """Add a child ``<Default>`` element with attributes set to parameter values."""
    default = CT_Default.new(ext, content_type)
    self.append(default)

add_override

add_override(partname, content_type)

Add a child <Override> element with attributes set to parameter values.

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

def add_override(self, partname, content_type):
    """Add a child ``<Override>`` element with attributes set to parameter
    values."""
    override = CT_Override.new(partname, content_type)
    self.append(override)

new staticmethod

new()

Return a new <Types> element.

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

@staticmethod
def new():
    """Return a new ``<Types>`` element."""
    xml = '<Types xmlns="%s"/>' % nsmap["ct"]
    types = parse_xml(xml)
    return types

parse_xml

parse_xml(text: str) -> _Element

etree.fromstring() replacement that uses oxml parser.

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

def parse_xml(text: str) -> etree._Element:
    """`etree.fromstring()` replacement that uses oxml parser."""
    return etree.fromstring(text, oxml_parser)

qn

qn(tag: str) -> str

Stands for "qualified name", a utility function to turn a namespace prefixed tag name into a Clark-notation qualified tag name for lxml.

For example, qn('p:cSld') returns '{http://schemas.../main}cSld'.

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

def qn(tag: str) -> str:
    """Stands for "qualified name", a utility function to turn a namespace prefixed tag
    name into a Clark-notation qualified tag name for lxml.

    For
    example, ``qn('p:cSld')`` returns ``'{http://schemas.../main}cSld'``.
    """
    prefix, tagroot = tag.split(":")
    uri = nsmap[prefix]
    return "{%s}%s" % (uri, tagroot)

serialize_part_xml

serialize_part_xml(part_elm: _Element) -> bytes

Serialize part_elm etree element to XML suitable for storage as an XML part.

That is to say, no insignificant whitespace added for readability, and an appropriate XML declaration added with UTF-8 encoding specified.

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

def serialize_part_xml(part_elm: etree._Element) -> bytes:
    """Serialize `part_elm` etree element to XML suitable for storage as an XML part.

    That is to say, no insignificant whitespace added for readability, and an
    appropriate XML declaration added with UTF-8 encoding specified.
    """
    return etree.tostring(part_elm, encoding="UTF-8", standalone=True)

serialize_for_reading

serialize_for_reading(element: _Element) -> str

Serialize element to human-readable XML suitable for tests.

No XML declaration.

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

def serialize_for_reading(element: etree._Element) -> str:
    """Serialize `element` to human-readable XML suitable for tests.

    No XML declaration.
    """
    return etree.tostring(element, encoding="unicode", pretty_print=True)