Developer Guide

Before Starting

Before using NoMETA as a developer, you should be familiar with the Office Open XML (OOXML) properties defined in ECMA-376. So, you can understand the Microsoft implementation of app.xml and core.xml in docProps folder structure.

Introduction

The main class of NoMETA is Document, it’s responsible for opening and saving MS Office documents. It also agregates two classes, App and Core, to deal with XML tag values.

In context of NoMETA, App and Core are sheets that represents the XML files docProps/app.xml and docProps/core.xml, respectively. These classes have properties to deal with the most popular tags of each file. By convention, each property has the same name of the corresponding XML tag in snake_case format (eg. <cp:lastModifiedBy> is last_modified_by)

So, you can edit these properties and save a new version of the document like in the code snippet below:

1from nometa import Document, Core, App
2doc = Document("tests/resource/test.docx",Core,App)
3doc.core.creator = "Johnny Test"
4doc.save("test2.docx")

Tip

The constructor of Document class can accept, as first parameter, a string (which is the file path) or an in-memory buffer of bytes. The save method behaves similarly.

See the class documentation for more details.


How to handle a new XML tag?

If App or Core classes don’t handle some XML tag, you can extend them in order to handle the specific tag. As an example, suppose that a new tag called dc:unreal is present in docProps/core.xml, so you could access it as following:

 1from nometa import *
 2from typing import cast
 3from nometa.properties.text import TextProperty
 4
 5class UnrealCore(Core):
 6    def __init__(self, raw) -> None:
 7        super().__init__(raw)
 8        self._unreal=TextProperty.from_element("dc:unreal", self._xml_root)
 9
10    def to_element(self) -> None:
11        super().to_element()
12        self._unreal.to_element(self._xml_root)
13
14    @property
15    def unreal(self) -> str|None:
16        return self._unreal.value
17
18    @unreal.setter
19    def unreal(self, val: str) -> None:
20        self._unreal.value=val
21
22
23doc=Document("tests/resource/test.xlsx",UnrealCore,App)
24ucore=cast(UnrealCore, doc.core)
25print(ucore.unreal)

The attribute _xml_root of nometa.sheet.Sheet class keeps an instance of etree._Element class, and you must read from and write to it. Like above in lines 8 and 12.