num: add Document.numbering_part

Steve Canny · Steve Canny · commit b0adbe6ff886 · 2014-02-02T01:38:48.000-08:00
diff --git a/docx/api.py b/docx/api.py
@@ -11,8 +11,10 @@
 import os
 
 from docx.enum.text import WD_BREAK
-from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
 from docx.package import Package
+from docx.parts.numbering import NumberingPart
+from docx.shared import lazyproperty
 
 
 _thisdir = os.path.split(__file__)[0]
@@ -115,6 +117,19 @@ def inline_shapes(self):
         """
         return self._document_part.inline_shapes
 
+    @lazyproperty
+    def numbering_part(self):
+        """
+        Instance of |NumberingPart| for this document. Creates an empty
+        numbering part if one is not present.
+        """
+        try:
+            return self._document_part.part_related_by(RT.NUMBERING)
+        except KeyError:
+            numbering_part = NumberingPart.new()
+            self._document_part.relate_to(numbering_part, RT.NUMBERING)
+            return numbering_part
+
     @property
     def paragraphs(self):
         """
diff --git a/docx/parts/numbering.py b/docx/parts/numbering.py
@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+"""
+|NumberingPart| and closely related objects
+"""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from ..opc.package import Part
+
+
+class NumberingPart(Part):
+    """
+    Proxy for the numbering.xml part containing numbering definitions for
+    a document or glossary.
+    """
+    @classmethod
+    def new(cls):
+        """
+        Return newly created empty numbering part, containing only the root
+        ``<w:numbering>`` element.
+        """
+        raise NotImplementedError
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -12,9 +12,10 @@
 
 from docx.api import Document
 from docx.enum.text import WD_BREAK
-from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
 from docx.package import Package
 from docx.parts.document import DocumentPart, InlineShapes
+from docx.parts.numbering import NumberingPart
 from docx.table import Table
 from docx.text import Paragraph, Run
 
@@ -123,6 +124,24 @@ def it_can_save_the_package(self, save_fixture):
         document.save(file_)
         package_.save.assert_called_once_with(file_)
 
+    def it_provides_access_to_the_numbering_part(self, num_part_get_fixture):
+        document, document_part_, numbering_part_ = num_part_get_fixture
+        numbering_part = document.numbering_part
+        document_part_.part_related_by.assert_called_once_with(RT.NUMBERING)
+        assert numbering_part is numbering_part_
+
+    def it_creates_numbering_part_on_first_access_if_not_present(
+            self, num_part_create_fixture):
+        document, NumberingPart_, document_part_, numbering_part_ = (
+            num_part_create_fixture
+        )
+        numbering_part = document.numbering_part
+        NumberingPart_.new.assert_called_once_with()
+        document_part_.relate_to.assert_called_once_with(
+            numbering_part_, RT.NUMBERING
+        )
+        assert numbering_part is numbering_part_
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[0, 1, 2, 5, 9])
@@ -220,6 +239,27 @@ def init_fixture(self, docx_, open_):
     def inline_shapes_(self, request):
         return instance_mock(request, InlineShapes)
 
+    @pytest.fixture
+    def num_part_create_fixture(
+            self, document, NumberingPart_, document_part_, numbering_part_):
+        document_part_.part_related_by.side_effect = KeyError
+        return document, NumberingPart_, document_part_, numbering_part_
+
+    @pytest.fixture
+    def num_part_get_fixture(self, document, document_part_, numbering_part_):
+        document_part_.part_related_by.return_value = numbering_part_
+        return document, document_part_, numbering_part_
+
+    @pytest.fixture
+    def NumberingPart_(self, request, numbering_part_):
+        NumberingPart_ = class_mock(request, 'docx.api.NumberingPart')
+        NumberingPart_.new.return_value = numbering_part_
+        return NumberingPart_
+
+    @pytest.fixture
+    def numbering_part_(self, request):
+        return instance_mock(request, NumberingPart)
+
     @pytest.fixture
     def open_(self, request, document_part_, package_):
         return method_mock(
