num: add numbering oxml classes

Steve Canny · Steve Canny · commit a27d14c2558d · 2014-02-02T20:23:44.000-08:00
diff --git a/docx/oxml/__init__.py b/docx/oxml/__init__.py
@@ -12,7 +12,7 @@
 # custom element class mappings
 # ===========================================================================
 
-from docx.oxml.shared import CT_OnOff, CT_String
+from docx.oxml.shared import CT_DecimalNumber, CT_OnOff, CT_String
 
 from docx.oxml.shape import (
     CT_Blip, CT_BlipFillProperties, CT_GraphicalObject,
@@ -30,7 +30,10 @@
 register_custom_element_class('w:body', CT_Body)
 register_custom_element_class('w:document', CT_Document)
 
-from docx.oxml.parts.numbering import CT_Numbering
+from docx.oxml.parts.numbering import CT_Num, CT_Numbering, CT_NumLvl
+register_custom_element_class('w:abstractNumId', CT_DecimalNumber)
+register_custom_element_class('w:lvlOverride', CT_NumLvl)
+register_custom_element_class('w:num', CT_Num)
 register_custom_element_class('w:numbering', CT_Numbering)
 
 from docx.oxml.table import CT_Row, CT_Tbl, CT_TblGrid, CT_TblPr, CT_Tc
diff --git a/docx/oxml/parts/numbering.py b/docx/oxml/parts/numbering.py
@@ -4,17 +4,121 @@
 Custom element classes related to the numbering part
 """
 
-from docx.oxml.shared import OxmlBaseElement, qn
+from docx.oxml.shared import (
+    CT_DecimalNumber, nsmap, OxmlBaseElement, OxmlElement, qn
+)
+
+
+class CT_Num(OxmlBaseElement):
+    """
+    ``<w:num>`` element, which represents a concrete list definition
+    instance, having a required child <w:abstractNumId> that references an
+    abstract numbering definition that defines most of the formatting details.
+    """
+    @property
+    def abstractNumId(self):
+        return self.find(qn('w:abstractNumId'))
+
+    def add_lvlOverride(self, ilvl):
+        """
+        Return a newly added CT_NumLvl (<w:lvlOverride>) element having its
+        ``ilvl`` attribute set to *ilvl*.
+        """
+        lvlOverride = CT_NumLvl.new(ilvl)
+        self.append(lvlOverride)
+        return lvlOverride
+
+    @classmethod
+    def new(cls, num_id, abstractNum_id):
+        """
+        Return a new ``<w:num>`` element having numId of *num_id* and having
+        a ``<w:abstractNumId>`` child with val attribute set to
+        *abstractNum_id*.
+        """
+        abstractNumId = CT_DecimalNumber.new(
+            'w:abstractNumId', abstractNum_id
+        )
+        num = OxmlElement('w:num', {qn('w:numId'): str(num_id)})
+        num.append(abstractNumId)
+        return num
+
+    @property
+    def numId(self):
+        numId_str = self.get(qn('w:numId'))
+        return int(numId_str)
+
+
+class CT_NumLvl(OxmlBaseElement):
+    """
+    ``<w:lvlOverride>`` element, which identifies a level in a list
+    definition to override with settings it contains.
+    """
+    def add_startOverride(self, val):
+        """
+        Return a newly added CT_DecimalNumber element having tagname
+        ``w:startOverride`` and ``val`` attribute set to *val*.
+        """
+        startOverride = CT_DecimalNumber.new('w:startOverride', val)
+        self.insert(0, startOverride)
+        return startOverride
+
+    @classmethod
+    def new(cls, ilvl):
+        """
+        Return a new ``<w:lvlOverride>`` element having its ``ilvl``
+        attribute set to *ilvl*.
+        """
+        return OxmlElement('w:lvlOverride', {qn('w:ilvl'): str(ilvl)})
 
 
 class CT_Numbering(OxmlBaseElement):
     """
     ``<w:numbering>`` element, the root element of a numbering part, i.e.
     numbering.xml
     """
+    def add_num(self, abstractNum_id):
+        """
+        Return a newly added CT_Num (<w:num>) element that references
+        the abstract numbering definition having id *abstractNum_id*.
+        """
+        next_num_id = self._next_numId
+        num = CT_Num.new(next_num_id, abstractNum_id)
+        # insert in proper sequence among children ---------
+        successor = self.first_child_found_in('w:numIdMacAtCleanup')
+        if successor is not None:
+            successor.addprevious(num)
+        else:
+            self.append(num)
+        return num
+
     @property
     def num_lst(self):
         """
         List of <w:num> child elements.
         """
         return self.findall(qn('w:num'))
+
+    def num_having_numId(self, numId):
+        """
+        Return the ``<w:num>`` child element having ``numId`` attribute
+        matching *numId*.
+        """
+        xpath = './w:num[@w:numId="%d"]' % numId
+        try:
+            return self.xpath(xpath, namespaces=nsmap)[0]
+        except IndexError:
+            raise KeyError('no <w:num> element with numId %d' % numId)
+
+    @property
+    def _next_numId(self):
+        """
+        The first ``numId`` unused by a ``<w:num>`` element, starting at
+        1 and filling any gaps in numbering between existing ``<w:num>``
+        elements.
+        """
+        numId_strs = self.xpath('./w:num/@w:numId', namespaces=nsmap)
+        num_ids = [int(numId_str) for numId_str in numId_strs]
+        for num in range(1, len(num_ids)+2):
+            if num not in num_ids:
+                break
+        return num
diff --git a/docx/oxml/shared.py b/docx/oxml/shared.py
@@ -229,6 +229,17 @@ class OxmlBaseElement(etree.ElementBase):
     Base class for all custom element classes, to add standardized behavior
     to all classes in one place.
     """
+    def first_child_found_in(self, *tagnames):
+        """
+        Return the first child found with tag in *tagnames*, or None if
+        not found.
+        """
+        for tagname in tagnames:
+            child = self.find(qn(tagname))
+            if child is not None:
+                return child
+        return None
+
     @property
     def xml(self):
         """
@@ -239,6 +250,29 @@ def xml(self):
         return serialize_for_reading(self)
 
 
+class CT_DecimalNumber(OxmlBaseElement):
+    """
+    Used for ``<w:numId>``, ``<w:ilvl>``, ``<w:abstractNumId>`` and several
+    others, containing a text representation of a decimal number (e.g. 42) in
+    its ``val`` attribute.
+    """
+    @classmethod
+    def new(cls, nsptagname, val):
+        """
+        Return a new ``CT_DecimalNumber`` element having tagname *nsptagname*
+        and ``val`` attribute set to *val*.
+        """
+        return OxmlElement(nsptagname, attrs={qn('w:val'): str(val)})
+
+    @property
+    def val(self):
+        """
+        Required attribute containing a decimal integer
+        """
+        number_str = self.get(qn('w:val'))
+        return int(number_str)
+
+
 class CT_OnOff(OxmlBaseElement):
     """
     Used for ``<w:b>``, ``<w:i>`` elements and others, containing a bool-ish
