api: rewrite docx.Document()

Steve Canny · Steve Canny · commit eadd73759eee · 2015-02-14T14:15:30.000-08:00
* retrofit add api-open-document.feature to drive integration of
  document open call
* extract _default_docx_path() to make testing seam
diff --git a/docx/__init__.py b/docx/__init__.py
@@ -1,6 +1,7 @@
 # encoding: utf-8
 
-from docx.api import Document  # noqa
+from docx.api import Document     # noqa
+from docx.api import DocumentNew  # noqa
 
 __version__ = '0.8.1'
 
diff --git a/docx/api.py b/docx/api.py
@@ -18,8 +18,27 @@
 from docx.shared import lazyproperty
 
 
-_thisdir = os.path.split(__file__)[0]
-_default_docx_path = os.path.join(_thisdir, 'templates', 'default.docx')
+def DocumentNew(docx=None):
+    """
+    Return a |Document| object loaded from *docx*, where *docx* can be
+    either a path to a ``.docx`` file (a string) or a file-like object. If
+    *docx* is missing or ``None``, the built-in default document "template"
+    is loaded.
+    """
+    docx = _default_docx_path() if docx is None else docx
+    document_part = Package.open(docx).main_document_part
+    if document_part.content_type != CT.WML_DOCUMENT_MAIN:
+        tmpl = "file '%s' is not a Word file, content type is '%s'"
+        raise ValueError(tmpl % (docx, document_part.content_type))
+    return document_part.document
+
+
+def _default_docx_path():
+    """
+    Return the path to the built-in default .docx package.
+    """
+    _thisdir = os.path.split(__file__)[0]
+    return os.path.join(_thisdir, 'templates', 'default.docx')
 
 
 class Document(object):
@@ -30,10 +49,9 @@ class Document(object):
     is loaded.
     """
     def __init__(self, docx=None):
-        super(Document, self).__init__()
-        document_part, package = self._open(docx)
-        self._document_part = document_part
-        self._package = package
+        document = DocumentNew(docx)
+        self._document_part = document._part
+        self._package = document._part.package
 
     def add_heading(self, text='', level=1):
         """
@@ -172,19 +190,3 @@ def tables(self):
         such as ``<w:ins>`` or ``<w:del>`` do not appear in this list.
         """
         return self._document_part.tables
-
-    @staticmethod
-    def _open(docx):
-        """
-        Return a (document_part, package) 2-tuple loaded from *docx*, where
-        *docx* can be either a path to a ``.docx`` file (a string) or a
-        file-like object. If *docx* is ``None``, the built-in default
-        document "template" is loaded.
-        """
-        docx = _default_docx_path if docx is None else docx
-        package = Package.open(docx)
-        document_part = package.main_document
-        if document_part.content_type != CT.WML_DOCUMENT_MAIN:
-            tmpl = "file '%s' is not a Word file, content type is '%s'"
-            raise ValueError(tmpl % (docx, document_part.content_type))
-        return document_part, package
diff --git a/docx/document.py b/docx/document.py
@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+"""
+|Document| and closely related objects
+"""
+
+from __future__ import (
+    absolute_import, division, print_function, unicode_literals
+)
+
+from .shared import ElementProxy
+
+
+class Document(ElementProxy):
+    """
+    WordprocessingML (WML) document.
+    """
+
+    __slots__ = ('_part',)
+
+    def __init__(self, element, part):
+        super(Document, self).__init__(element)
+        self._part = part
diff --git a/docx/opc/package.py b/docx/opc/package.py
@@ -98,7 +98,7 @@ def load_rel(self, reltype, target, rId, is_external=False):
         return self.rels.add_relationship(reltype, target, rId, is_external)
 
     @property
-    def main_document(self):
+    def main_document_part(self):
         """
         Return a reference to the main document part for this package.
         Examples include a document part for a WordprocessingML package, a
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -11,6 +11,7 @@
 from collections import Sequence
 
 from ..blkcntnr import BlockItemContainer
+from ..document import Document
 from ..enum.section import WD_SECTION
 from ..opc.constants import RELATIONSHIP_TYPE as RT
 from ..opc.part import XmlPart
@@ -53,6 +54,13 @@ def body(self):
         """
         return _Body(self._element.body, self)
 
+    @property
+    def document(self):
+        """
+        A |Document| object providing access to the content of this document.
+        """
+        return Document(self._element, self)
+
     def get_or_add_image_part(self, image_descriptor):
         """
         Return an ``(image_part, rId)`` 2-tuple for the image identified by
diff --git a/features/api-open-document.feature b/features/api-open-document.feature
@@ -0,0 +1,16 @@
+Feature: Open a document
+  In order work on a document
+  As a developer using python-docx
+  I need a way to open a document
+
+
+  Scenario: Open a specified document
+    Given I have python-docx installed
+     When I call docx.Document() with the path of a .docx file
+     Then document is a Document object
+
+
+  Scenario: Open the default document
+    Given I have python-docx installed
+     When I call docx.Document() with no arguments
+     Then document is a Document object
diff --git a/features/steps/api.py b/features/steps/api.py
@@ -4,15 +4,25 @@
 Step implementations for basic API features
 """
 
-from behave import then, when
+from behave import given, then, when
 
+import docx
+
+from docx import DocumentNew
 from docx.shared import Inches
 from docx.table import Table
 
-from helpers import test_file
+from helpers import test_docx, test_file
+
+
+# given ====================================================
 
+@given('I have python-docx installed')
+def given_I_have_python_docx_installed(context):
+    pass
 
-# when ====================================================
+
+# when =====================================================
 
 @when('I add a 2 x 2 table specifying only row and column count')
 def when_add_2x2_table_specifying_only_row_and_col_count(context):
@@ -101,8 +111,24 @@ def when_add_picture_specifying_only_image_file(context):
     context.picture = document.add_picture(test_file('monty-truth.png'))
 
 
+@when('I call docx.Document() with no arguments')
+def when_I_call_docx_Document_with_no_arguments(context):
+    context.document = DocumentNew()
+
+
+@when('I call docx.Document() with the path of a .docx file')
+def when_I_call_docx_Document_with_the_path_of_a_docx_file(context):
+    context.document = DocumentNew(test_docx('doc-default'))
+
+
 # then =====================================================
 
+@then('document is a Document object')
+def then_document_is_a_Document_object(context):
+    document = context.document
+    assert isinstance(document, docx.document.Document)
+
+
 @then('the document contains a 2 x 2 table')
 def then_document_contains_2x2_table(context):
     document = context.document
diff --git a/features/steps/test_files/doc-default.docx b/features/steps/test_files/doc-default.docx
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -10,7 +10,9 @@
 
 import pytest
 
-from docx.api import Document
+import docx
+
+from docx.api import Document, DocumentNew
 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
@@ -25,34 +27,70 @@
 from docx.text.run import Run
 
 from .unitutil.mock import (
-    instance_mock, class_mock, method_mock, property_mock, var_mock
+    function_mock, instance_mock, class_mock, method_mock, property_mock
 )
 
 
 class DescribeDocument(object):
 
-    def it_opens_a_docx_on_construction(self, init_fixture):
-        docx_, open_ = init_fixture
-        document = Document(docx_)
-        open_.assert_called_once_with(docx_)
-        assert isinstance(document, Document)
-
-    def it_can_open_a_docx_file(self, open_fixture):
-        docx_, Package_, package_, document_part_ = open_fixture
-        document_part, package = Document._open(docx_)
-        Package_.open.assert_called_once_with(docx_)
-        assert document_part is document_part
-        assert package is package_
-
-    def it_opens_default_template_if_no_file_provided(
-            self, Package_, default_docx_):
-        Document._open(None)
-        Package_.open.assert_called_once_with(default_docx_)
-
-    def it_should_raise_if_not_a_Word_file(self, Package_, package_, docx_):
-        package_.main_document.content_type = 'foobar'
+    def it_opens_a_docx_file(self, open_fixture):
+        docx, Package_, document_ = open_fixture
+        document = DocumentNew(docx)
+        Package_.open.assert_called_once_with(docx)
+        assert document is document_
+
+    def it_opens_the_default_docx_if_none_specified(self, default_fixture):
+        docx, Package_, document_ = default_fixture
+        document = DocumentNew()
+        Package_.open.assert_called_once_with(docx)
+        assert document is document_
+
+    def it_raises_on_not_a_Word_file(self, raise_fixture):
+        not_a_docx = raise_fixture
         with pytest.raises(ValueError):
-            Document._open(docx_)
+            Document(not_a_docx)
+
+    # fixtures -------------------------------------------------------
+
+    @pytest.fixture
+    def default_fixture(self, _default_docx_path_, Package_, document_):
+        docx = 'barfoo.docx'
+        _default_docx_path_.return_value = docx
+        document_part = Package_.open.return_value.main_document_part
+        document_part.document = document_
+        document_part.content_type = CT.WML_DOCUMENT_MAIN
+        return docx, Package_, document_
+
+    @pytest.fixture
+    def open_fixture(self, Package_, document_):
+        docx = 'foobar.docx'
+        document_part = Package_.open.return_value.main_document_part
+        document_part.document = document_
+        document_part.content_type = CT.WML_DOCUMENT_MAIN
+        return docx, Package_, document_
+
+    @pytest.fixture
+    def raise_fixture(self, Package_):
+        not_a_docx = 'foobar.xlsx'
+        Package_.open.return_value.main_document_part.content_type = 'BOGUS'
+        return not_a_docx
+
+    # fixture components ---------------------------------------------
+
+    @pytest.fixture
+    def _default_docx_path_(self, request):
+        return function_mock(request, 'docx.api._default_docx_path')
+
+    @pytest.fixture
+    def document_(self, request):
+        return instance_mock(request, docx.document.Document)
+
+    @pytest.fixture
+    def Package_(self, request):
+        return class_mock(request, 'docx.api.Package')
+
+
+class DescribeDocumentOld(object):
 
     def it_can_add_a_heading(self, add_heading_fixture):
         document, text, level, style, paragraph_ = add_heading_fixture
@@ -219,10 +257,6 @@ 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 open_fixture(self, docx_, Package_, package_, document_part_):
-        return docx_, Package_, package_, document_part_
-
     @pytest.fixture
     def paragraphs_fixture(self, document, paragraphs_):
         return document, paragraphs_
@@ -254,10 +288,6 @@ def add_paragraph_(self, request, paragraph_):
     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')
-
     @pytest.fixture
     def Document_inline_shapes_(self, request, inline_shapes_):
         return property_mock(
@@ -268,6 +298,10 @@ def Document_inline_shapes_(self, request, inline_shapes_):
     def document(self, open_):
         return Document()
 
+    @pytest.fixture
+    def document_obj_(self, request):
+        return instance_mock(request, docx.document.Document)
+
     @pytest.fixture
     def document_part_(
             self, request, paragraph_, paragraphs_, section_, table_,
@@ -282,10 +316,6 @@ def document_part_(
         document_part_.tables = tables_
         return document_part_
 
-    @pytest.fixture
-    def docx_(self, request):
-        return instance_mock(request, str)
-
     @pytest.fixture
     def inline_shapes_(self, request):
         return instance_mock(request, InlineShapes)
@@ -307,10 +337,12 @@ def numbering_part_(self, request):
         return instance_mock(request, NumberingPart)
 
     @pytest.fixture
-    def open_(self, request, document_part_, package_):
-        return method_mock(
-            request, Document, '_open',
-            return_value=(document_part_, package_)
+    def open_(self, request, document_obj_, document_part_, package_):
+        document_part_.package = package_
+        document_obj_._part = document_part_
+        return function_mock(
+            request, 'docx.api.DocumentNew',
+            return_value=document_obj_
         )
 
     @pytest.fixture
@@ -322,7 +354,7 @@ def Package_(self, request, package_):
     @pytest.fixture
     def package_(self, request, document_part_):
         package_ = instance_mock(request, Package)
-        package_.main_document = document_part_
+        package_.main_document_part = document_part_
         return package_
 
     @pytest.fixture
