Understanding xmlchemy
¶
xmlchemy
is an object-XML mapping layer somewhat reminiscent of
SQLAlchemy, hence the name. Mapping XML elements to objects is not nearly as
challenging as mapping to a relational database, so this layer is
substantially more modest. Nevertheless, it provides a powerful and very
useful abstraction layer around lxml
, particularly well-suited to
providing access to the broad schema of XML elements involved in the Open XML
standard.
Additional topics to add …¶
- understanding complex types in Open XML
- understanding attribute definitions Open XML
- understanding simple types in Open XML
Adding support for a new element type¶
- add a new custom element mapping to
pptx.oxml.__init__
- add a new custom element class in the appropriate
pptx.oxml
subpackage module - Add element definition members to the class
- Add attribute definition members to the class
- Add simple type definitions to
pptx.oxml.simpletype
Example¶
from pptx.oxml.xmlchemy import BaseOxmlElement
class CT_Foobar(BaseOxmlElement):
"""
Custom element class corresponding to ``CT_Foobar`` complex type
definition in pml.xsd or other Open XML schema.
"""
hlink = ZeroOrOne('a:hlink', successors=('a:rtl', 'a:extLst'))
eg_fillProperties = ZeroOrOneChoice(
(Choice('a:noFill'), Choice('a:solidFill'), Choice('a:gradFill'),
Choice('a:blipFill'), Choice('a:pattFill')),
successors=(
'a:effectLst', 'a:effectDag', 'a:highlight', 'a:uLnTx',
'a:uLn', 'a:uFillTx' 'a:extLst'
)
)
sz = OptionalAttribute(
'sz', ST_SimpleType, default=ST_SimpleType.OPTION
)
anchor = OptionalAttribute('i', XsdBoolean)
rId = RequiredAttribute('r:id', XsdString)
Protocol¶
>>> assert isinstance(foobar, CT_Foobar)
>>> foobar.hlink
None
>>> hlink = foobar._add_hlink()
>>> hlink
<pptx.oxml.xyz.CT_Hyperlink object at 0x10ab4b2d0>
>>> assert foobar.hlink is hlink
>>> foobar.eg_fillProperties
None
>>> foobar.solidFill
None
>>> solidFill = foobar.get_or_change_to_solidFill()
>>> solidFill
<pptx.oxml.xyz.CT_SolidFill object at 0x10ab4b2d0>
>>> assert foobar.eg_fillProperties is solidFill
>>> assert foobar.solidFill is solidFill
>>> foobar.remove_eg_fillProperties()
>>> foobar.eg_fillProperties
None
>>> foobar.solidFill
None
OneAndOnlyOne
element declaration¶
The OneAndOnlyOne
callable generates the API for a required child
element:
childElement = OneAndOnlyOne('ns:localTagName')
Unlike the other element declarations, the call does not include
a successors
argument. Since no API for inserting a new element is
generated, a successors list is not required.
Generated API¶
childElement
property (read-only)- Holds a reference to the child element object. Raises
InvalidXmlError
on access if the required child element is not present.
Protocol¶
>>> foobar.childElement
<pptx.oxml.xyz.CT_ChildElement object at 0x10ab4b2d0>
RequiredAttribute
attribute declaration¶
reqAttr = RequiredAttribute('reqAtr', ST_SimpleType)
Generated API¶
childElement
property (read/write)- Referencing the property returns the type-converted value of the
attribute as determined by the
from_xml()
method of the simple type class appearing in the declaration (e.g. ST_SimpleType above). Assignments to the property are validated by thevalidate()
method of the simple type class, potentially raisingTypeError
orValueError
. Values are assigned in their natural Python type and are encoded to the appropriate string value by theto_xml()
method of the simple type class.
ZeroOrOne
element declaration¶
childElement = ZeroOrOne(
'ns:localTagName', successors=('ns:abc', 'ns:def')
)
Generated API¶
childElement
property (read-only)- Holds a reference to the child element object, or None if the element is not present.
get_or_add_childElement()
method- Returns the child element object, newly added if not present.
_add_childElement()
empty element adder method- Returns a newly added empty child element having the declared tag name.
Adding is unconditional and assumes the element is not already present.
This method is called by the
get_or_add_childElement()
method as needed and may be called by a hand-codedadd_childElement()
method as needed. May be overridden to produce customized behavior. _new_childElement()
empty element creator method- Returns a new “loose” child element of the declared tag name. Called by
_add_childElement()
to obtain a new child element, it may be overridden to customize the element creation process. _insert_childElement(childElement)
element inserter method- Returns the passed
childElement
after inserting it before any successor elements, as listed in thesuccessors
argument of the declaration. Called by_add_childElement()
to insert the new element it creates using_new_childElement()
. _remove_childElement()
element remover method- Removes all instances of the child element. Does not raise an error if no matching child elements are present.