oxml中创建CT_Document类

概述

本文基于python-docx源码，详细记录CT_Document类创建的过程，以此来加深对Python中元类 、以及CT_Document元素类的认识。

元类简介

元类 （MetaClass）是Python中的高级特性。元类是什么呢 ？Python是面向对象编程语言，在Python中一切事物都是对象。如实例 是类 对象的实例化结果，而类则是元类实例化的结果。简而言之，元类是创建"类"的"类" ------通过元类的__new__与__init__特殊方法管理类的创建过程 。其中type对象是Python中内置的元类对象。

那为什么需要元类呢？元类有很强大的功能，本文仅从"为新创建的类自动创建方法"为例进行记录。

元类的定义与使用

通过继承type对象来创建自己的元类：

class MyMetaClass(type):
    def __new__(cls, name, bases, attrs):
       print(f"Creating new class: {name}")
       return super().__new__(cls, name, bases, attrs)

name参数是新创建类的类名称，bases参数是新创建类的父类元祖，attrs是新创建类的属性字典。自定义完元类后，可以在类定义中通过"metaclass"关键字参数明使用自定义的元类，如果不指定，默认值为type对象：

class MyNewClass(metaclass=MyMetaClass):
	pass

当python解释器创建"基于自定义元类定义的新建类"时，就会调用自定义元类的__new__与__init__特殊方法，从而管理类的创建过程。

新建CT_Document元素类

CT_Document源码定义

CT_Document源码定义于"docx.oxml.document"模块，表示一个XML文档元素类（类别lxml.etree.ElementBase）。

class CT_Document(BaseOxmlElement):
    """``<w:document>`` element, the root element of a document.xml file."""

    body: CT_Body = ZeroOrOne("w:body")  # pyright: ignore[reportAssignmentType]

    @property
    def sectPr_lst(self) -> List[CT_SectPr]:
        """All `w:sectPr` elements directly accessible from document element.

        Note this does not include a `sectPr` child in a paragraphs wrapped in
        revision marks or other intervening layer, perhaps `w:sdt` or customXml
        elements.

        `w:sectPr` elements appear in document order. The last one is always
        `w:body/w:sectPr`, all preceding are `w:p/w:pPr/w:sectPr`.
        """
        xpath = "./w:body/w:p/w:pPr/w:sectPr | ./w:body/w:sectPr"
        return self.xpath(xpath)

1. CT_Document类定义两个属性，其中body属性值是"CT_Body"类型，其取值为"ZeroOrOne"类型。注意限定性属性名为"w:body"。
2. 除了sectpr_lst与body属性被显示定义外，其它属性继承于BaseOxmlElement类。

接下来本文将详细记录，python中的元类功能，如何自动为CT_Document添加许多方法。

BaseOxmlElement 基层类

BaseOxmlElement基础元素类是一种类似于lxml.etree.ElementBase的类对象，只是其遵循的是Office Open XML标准。首先看docx.oxml.xmlchemy源码定义：

# -- lxml typing isn't quite right here, just ignore this error on _Element --
class BaseOxmlElement(etree.ElementBase, metaclass=MetaOxmlElement):
    """Effective base class for all custom element classes.

    Adds standardized behavior to all classes in one place.
    """

    def __repr__(self):
        return "<%s '<%s>' at 0x%0x>" % (
            self.__class__.__name__,
            self._nsptag,
            id(self),
        )

BaseOxmlElement类的定义比较简单，关于XML的元素类功能大部分继承自etree.ElementBase------作为BaseOxmlElement的父类，而其"类型"是MetaOxmlElement元类。

MetaOxmlElement元类

MetaOxmlElement元类定义于docx.oxml.xmlchemy模块：

class MetaOxmlElement(type):
    """Metaclass for BaseOxmlElement."""

    def __init__(cls, clsname: str, bases: Tuple[type, ...], namespace: Dict[str, Any]):
        dispatchable = (
            OneAndOnlyOne,
            OneOrMore,
            OptionalAttribute,
            RequiredAttribute,
            ZeroOrMore,
            ZeroOrOne,
            ZeroOrOneChoice,
        )
        for key, value in namespace.items():
            if isinstance(value, dispatchable):
                value.populate_class_members(cls, key)

MetaOxmlElement元类依然继承了type的__new__方法，但覆盖了__init__方法。__init__方法的逻辑也比较简单，如果namespace属性字典中的值是源码中指定的dispatchable类型，则调用对应类的populate_class_members方法。

_BaseChildElement类

_BaseChildElement类定义于docx.oxml.xmlchemy模块，为什么要在这里介绍此类 ？因为元类MetaOxmlElement的__init__方法中的dispatchable元组中，除了OptionalAttribute与RequiredAttribute外------但功能|角色有很大的相似性，其它类都是继承该基础类；并且后续许多自动为新创建的类添加方法，也与此类有关，因此在此处加以介绍。

class _BaseChildElement:
    """Base class for the child-element classes.

    The child-element sub-classes correspond to varying cardinalities, such as ZeroOrOne
    and ZeroOrMore.
    """

    def __init__(self, nsptagname: str, successors: Tuple[str, ...] = ()):
        super(_BaseChildElement, self).__init__()
        self._nsptagname = nsptagname
        self._successors = successors

    def populate_class_members(self, element_cls: MetaOxmlElement, prop_name: str) -> None:
        """Baseline behavior for adding the appropriate methods to `element_cls`."""
        self._element_cls = element_cls
        self._prop_name = prop_name

1. _BaseChildElement是一个典型的类定义，其父类是Python中的object对象。
2. 初始化该类需要传入元素"命名空间前缀标签名称"与successors前置元素对象列表------比如一个<w:r>元素，可能需要传入段落格式<w:pPr>等前置元素对象。
3. _BaseChildElement基础子类的populate_class_members方法的逻辑比较简单，将传入的参数值存储到实例属性中。
4. 注意：prop_name一般为新创建类的属性名，而element_cls一般为新建类**。**_BaseChildElement或者其子类一般是作为新建类（基于MetaOxmlElement元类）的属性。将会结合后面的实例进行说明。

CT_Document创建细节

step1.Python解释器收集必要信息

本文基于Pycharm & Debug模式，调试下列脚本------仅包含一行代码：

from docx.oxml.document import CT_Document

调试模式下，跳转到源码中的class CT_Document(BaseOxmlElement):行：

1. 由于CT_Document的继承自BaseOxmlElement，而BaseOxmlElement是基于MetaOxmlElement元类创建的，因此CT_Document的默认metaclass为MetaOxmlElement元类。创建CT_Document时，会自动调用MetaOxmlElement元类的__init__方法。

2. namespace属性字典中body属性值，存储的是一个ZeroOrOne实例对象。
   

step2. 执行MetaOxmlElement.init

在执行MetaOxmlElement.__init__的逻辑中，当key=body & value=ZeroOrOne()时，会执行ZeroOrOne.populate_class_members(cls, key)，此时的cls为"CT_Document "类。

此时许多私有方法显示状态异常，是因为"method_name"需要根据"prop_name"动态生成，而"prop_name"还未被ZeroOrOne实例引用。当执行完_BaseChildElement.populate_class_members后，异常状态就会消失。

step3. 执行ZeroOrOne.populate_class_members

_BaseChildElement实例方法	被封装的函数	自动为新建类添加的方法名模版	示例值	新建方法功能	说明
_add_getter	get_child_element	property_name	body	读取body子节点，如果不存在，则返回None	body作为可读特性，会覆盖CT_Document源码定义中的类属性值
_add_creator	new_child_element	"new%s" % property_name	_new_body	根据限定性标签名称，创建一个空的子节点	私有方法/辅助方法；创建空白子节点的能力继承lxml
_add_inserter	_insert_child	"insert%s" % property_name	_insert_body	将子节点插入到父节点中的指定为止	私有方法/辅助方法；插入子元素节点的能力继承自lxml
_add_adder	_add_child	"add%s" % property_name	_add_body	新建子节点，并将子节点插入到父节点中的指定为止	私有方法/辅助方法；可以看作是_add_creator & _add_inserter 功能的集成
_add_get_or_adder	get_or_add_child	"get_or_add_%s" % property_name	get_or_add_body	获取或者新建目标子节点	非私有方法；可以看作是_add_getter & _add_adder 功能的集成
_add_remover	_remove_child	"remove%s" % property_name	_remove_body	从父节点中删除目标子节点	私有方法/辅助方法；删除子节点的能力继承自lxml

"add%s"系列的实例方法均定义于 _BaseChildElement，被封装的函数、及新增方法模版名称也均定义于 _BaseChildElement。oxml子库中为新创建的元素类自动添加对应的方法的逻辑，就在"add%s"系列的方法中实现 。

执行_BaseChildElement.populate_class_members

创建对新建类、属性名的引用 。即第一行将"CT_Document"实例对象与"body"特性名称存储到ZeroOrOne实例对象属性中。第2-7行为CT_Documet类自动添加方法。

self._add_getter

_add_getter方法定义于_BaseChildElement类中，其源码如下：

   def _add_getter(self):
       """Add a read-only ``{prop_name}`` property to the element class for this child
       element."""
       property_ = property(self._getter, None, None)
       # -- assign unconditionally to overwrite element name definition --
       setattr(self._element_cls, self._prop_name, property_)

其中self.getter实例方法定义于_BaseChildElement类中，其源码如下：

@property
def _getter(self):
    """Return a function object suitable for the "get" side of the property
    descriptor.

    This default getter returns the child element with matching tag name or |None|
    if not present.
    """

    def get_child_element(obj: BaseOxmlElement):
        return obj.find(qn(self._nsptagname))

    get_child_element.__doc__ = (
        "``<%s>`` child element or |None| if not present." % self._nsptagname
    )
    return get_child_element

self.getter实例方法即根据限定性标签名称"w:body"在CT_Document元素节点内查找子节点对象。执行setattr(self._element_cls, self._prop_name, property_)之前，CT_Document的body数值存储的是ZeroOrOne实例对象------定义于源码，执行完成之后，CT_Document的body类属性就对应一个body特征了。

self._add_creator

self._add_creator方法的功能是为新创建的类------根据上下文就是CT_Document，添加一个方法------根据限定性标签名称（w:body），为新创建的类，创建一个空的新子节点元素对象。

    def _add_creator(self):
        """Add a ``_new_{prop_name}()`` method to the element class that creates a new,
        empty element of the correct type, having no attributes."""
        creator = self._creator
        creator.__doc__ = (
            'Return a "loose", newly created ``<%s>`` element having no attri'
            "butes, text, or children." % self._nsptagname
        )
        self._add_to_class(self._new_method_name, creator)

    @property
    def _creator(self) -> Callable[[BaseOxmlElement], BaseOxmlElement]:
        """Callable that creates an empty element of the right type, with no attrs."""
        from docx.oxml.parser import OxmlElement

        def new_child_element(obj: BaseOxmlElement):
            return OxmlElement(self._nsptagname)

        return new_child_element

注意"self._add_to_class"实例方法定义于_BaseChildElement类中，其功能是为新创建的类添加新方法：

    def _add_to_class(self, name: str, method: Callable[..., Any]):
        """Add `method` to the target class as `name`, unless `name` is already defined
        on the class."""
        if hasattr(self._element_cls, name):
            return
        setattr(self._element_cls, name, method)

结合上下文，self._element_cls=CT_Document & name=_new_body & method=self.creator。执行self._add_to_class的后，CT_Document类签名变化如下：

self._add_inserter

_add_inserter方法封装了_insert_child函数------为父节点插入一个子节点。为XML元素节点插入子节点的能力继承自lxml.etree.ElementBase。

    def _add_inserter(self):
        """Add an ``_insert_x()`` method to the element class for this child element."""

        def _insert_child(obj: BaseOxmlElement, child: BaseOxmlElement):
            obj.insert_element_before(child, *self._successors)
            return child

        _insert_child.__doc__ = (
            "Return the passed ``<%s>`` element after inserting it as a chil"
            "d in the correct sequence." % self._nsptagname
        )
        self._add_to_class(self._insert_method_name, _insert_child)

执行完self._add_to_class方法后，其中self._insert_method_name="_insert_body"，CT_Document签名中就包含新的方法"_insert_body":

self._add_adder

self._add_adder方法本质是"self._add_creator"与"self._add_inserter"二者的结合。self._add_adder方法封装了**_add_child函数**

    def _add_adder(self):
        """Add an ``_add_x()`` method to the element class for this child element."""

        def _add_child(obj: BaseOxmlElement, **attrs: Any):
            new_method = getattr(obj, self._new_method_name)
            child = new_method()
            for key, value in attrs.items():
                setattr(child, key, value)
            insert_method = getattr(obj, self._insert_method_name)
            insert_method(child)
            return child

        _add_child.__doc__ = (
            "Add a new ``<%s>`` child element unconditionally, inserted in t"
            "he correct sequence." % self._nsptagname
        )
        self._add_to_class(self._add_method_name, _add_child)

_add_child函数首先创建一个空的子节点，然后将"attr"属性字典写入到新建的空子节点，并将新建的子节点插入到目标父节点、返回新建的子节点。执行完self._add_to_class(self._add_method_name, _add_child)，其中self._add_method_name="_add_body"后，CT_Document多自动添加了一个新方法"_add_body"：

self._add_get_or_adder

"self._add_get_or_adder"方法对"get_or_add_child"函数进行了封装------如果父节点包含目标子节点，则直接取出目标子节点；如果不包含则新建一个目标子节点并返回，新建目标子节点依赖之前的"self._add_method_name"方法，即"self._add_body"

    def _add_get_or_adder(self):
        """Add a ``get_or_add_x()`` method to the element class for this child
        element."""

        def get_or_add_child(obj: BaseOxmlElement):
            child = getattr(obj, self._prop_name)
            if child is None:
                add_method = getattr(obj, self._add_method_name)
                child = add_method()
            return child

        get_or_add_child.__doc__ = (
            "Return the ``<%s>`` child element, newly added if not present."
        ) % self._nsptagname
        self._add_to_class(self._get_or_add_method_name, get_or_add_child)

self._get_or_add_method_name="get_or_add_body"， 执行完"self._add_to_class()"，CT_Document就自动添加了一个新的方法：

self.add_remover

"self.add_remover"方法封装了"_remove_child"函数------该函数根据限定性标签名称，从父节点中删除目标子节点。元素节点中删除子节点的能力继承自lxml.etree.ElementBase.

    def _add_remover(self):
        """Add a ``_remove_x()`` method to the element class for this child element."""

        def _remove_child(obj: BaseOxmlElement):
            obj.remove_all(self._nsptagname)

        _remove_child.__doc__ = ("Remove all ``<%s>`` child elements.") % self._nsptagname
        self._add_to_class(self._remove_method_name, _remove_child)

self._remove_method_name="_remove_body"， 执行完"self._add_to_class()"，CT_Document就自动添加了一个新的方法：

小结

在python-docx子库oxml中，虽然在源码中并未直接 定义诸多元素类对子节点元素管理的增删改查方法。但是通过利用Python元类、类继承、以及简洁直观的代码模式设计，为诸多新创建的元素类，如CT_Document，自动添加了对子元素节点的增删改查方法。这种利用Python元类来管理类方法自动创建的模式值得学习。