doc: add Document.core_properties

Author: Steve Canny

docs/conf.py

@@ -77,6 +77,8 @@
 
 .. |_Columns| replace:: :class:`_Columns`
 
+.. |CoreProperties| replace:: :class:`.CoreProperties`
+
 .. |Document| replace:: :class:`.Document`
 
 .. |docx| replace:: ``python-docx``

docx/api.py

@@ -108,6 +108,14 @@ def add_table(self, rows, cols, style='LightShading-Accent1'):
             table.style = style
         return table
 
+    @property
+    def core_properties(self):
+        """
+        A |CoreProperties| object providing read/write access to the core
+        properties of this document.
+        """
+        return self._package.core_properties
+
     @property
     def inline_shapes(self):
         """

docx/opc/package.py

@@ -35,6 +35,14 @@ def after_unmarshal(self):
         # subclass
         pass
 
+    @property
+    def core_properties(self):
+        """
+        |CoreProperties| object providing read/write access to the Dublin
+        Core properties for this document.
+        """
+        raise NotImplementedError
+
     def iter_rels(self):
         """
         Generate exactly one reference to each relationship in the package by

tests/test_api.py

@@ -13,6 +13,7 @@
 from docx.api import Document
 from docx.enum.text import WD_BREAK
 from docx.opc.constants import CONTENT_TYPE as CT, RELATIONSHIP_TYPE as RT
+from docx.opc.coreprops import CoreProperties
 from docx.package import Package
 from docx.parts.document import DocumentPart, InlineShapes
 from docx.parts.numbering import NumberingPart
@@ -131,6 +132,11 @@ 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_core_properties(self, core_props_fixture):
+        document, core_properties_ = core_props_fixture
+        core_properties = document.core_properties
+        assert core_properties is core_properties_
+
     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
@@ -214,6 +220,11 @@ def add_table_fixture(self, request, document, document_part_, table_):
             table_
         )
 
+    @pytest.fixture
+    def core_props_fixture(self, document, core_properties_):
+        document._package.core_properties = core_properties_
+        return document, core_properties_
+
     @pytest.fixture
     def init_fixture(self, docx_, open_):
         return docx_, open_
@@ -249,6 +260,10 @@ def add_paragraph_(self, request, paragraph_):
             request, Document, 'add_paragraph', return_value=paragraph_
         )
 
+    @pytest.fixture
+    def core_properties_(self, request):
+        return instance_mock(request, CoreProperties)
+
     @pytest.fixture
     def default_docx_(self, request):
         return var_mock(request, 'docx.api._default_docx_path')