Merge pull request #66 from openlawlibrary/aleksandarbos/sync-with-up…

…stream

sync with upstream

.gitignore

@@ -3,6 +3,7 @@
 /docs/.build/
 /*.egg-info
 *.pyc
+.pytest_cache/
 _scratch/
 Session.vim
 /.tox/

.travis.yml

@@ -1,9 +1,8 @@
 language: python
 python:
-  - "3.4"
-  - "3.3"
+  - "3.6"
+  - "3.5"
   - "2.7"
-  - "2.6"
 # command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors
 install: pip install -r requirements.txt
 # command to run tests, e.g. python setup.py test

HISTORY.rst

@@ -3,6 +3,39 @@
 Release History
 ---------------
 
+0.8.10 (2019-01-08)
++++++++++++++++++++
+
+- Revert use of expanded package directory for default.docx to work around setup.py
+  problem with filenames containing square brackets.
+
+
+0.8.9 (2019-01-08)
+++++++++++++++++++
+
+- Fix gap in MANIFEST.in that excluded default document template directory
+
+
+0.8.8 (2019-01-07)
+++++++++++++++++++
+
+- Add support for headers and footers
+
+
+0.8.7 (2018-08-18)
+++++++++++++++++++
+
+- Add _Row.height_rule
+- Add _Row.height
+- Add _Cell.vertical_alignment
+- Fix #455: increment next_id, don't fill gaps
+- Add #375: import docx failure on --OO optimization
+- Add #254: remove default zoom percentage
+- Add #266: miscellaneous documentation fixes
+- Add #175: refine MANIFEST.ini
+- Add #168: Unicode error on core-props in Python 2
+
+
 0.8.6 (2016-06-22)
 ++++++++++++++++++
 

MANIFEST.in

@@ -1,6 +1,9 @@
 include HISTORY.rst LICENSE README.rst tox.ini
-recursive-include tests *.py
-recursive-include features *
-recursive-include docx/templates *
-recursive-include tests/test_files *
-
+graft docx/templates
+graft features
+graft tests
+graft docs
+prune docs/.build
+global-exclude .DS_Store
+global-exclude __pycache__
+global-exclude *.py[co]

docs/api/enum/WdCellVerticalAlignment.rst

@@ -0,0 +1,32 @@
+.. _WdCellVerticalAlignment:
+
+``WD_CELL_VERTICAL_ALIGNMENT``
+==============================
+
+alias: **WD_ALIGN_VERTICAL**
+
+Specifies the vertical alignment of text in one or more cells of a table.
+
+Example::
+
+    from docx.enum.table import WD_ALIGN_VERTICAL
+
+    table = document.add_table(3, 3)
+    table.cell(0, 0).vertical_alignment = WD_ALIGN_VERTICAL.BOTTOM
+
+----
+
+TOP
+    Text is aligned to the top border of the cell.
+
+CENTER
+    Text is aligned to the center of the cell.
+
+BOTTOM
+    Text is aligned to the bottom border of the cell.
+
+BOTH
+    This is an option in the OpenXml spec, but not in Word itself. It's not
+    clear what Word behavior this setting produces. If you find out please let
+    us know and we'll update this documentation. Otherwise, probably best to
+    avoid this option.

docs/api/enum/WdRowHeightRule.rst

@@ -0,0 +1,26 @@
+.. _WdRowHeightRule:
+
+``WD_ROW_HEIGHT_RULE``
+======================
+
+alias: **WD_ROW_HEIGHT**
+
+Specifies the rule for determining the height of a table row
+
+Example::
+
+    from docx.enum.table import WD_ROW_HEIGHT_RULE
+
+    table = document.add_table(3, 3)
+    table.rows[0].height_rule = WD_ROW_HEIGHT_RULE.EXACTLY
+
+----
+
+AUTO
+    The row height is adjusted to accommodate the tallest value in the row.
+
+AT_LEAST
+    The row height is at least a minimum specified value.
+
+EXACTLY
+    The row height is an exact value.

docs/api/enum/index.rst

@@ -12,10 +12,12 @@ can be found here:
    MsoThemeColorIndex
    WdAlignParagraph
    WdBuiltinStyle
+   WdCellVerticalAlignment
    WdColorIndex
    WdLineSpacing
    WdOrientation
    WdRowAlignment
+   WdRowHeightRule
    WdSectionStart
    WdStyleType
    WdTabAlignment

docs/api/section.rst

@@ -22,4 +22,20 @@ Provides access to section properties such as margins and page orientation.
 
 
 .. autoclass:: Section
-   :members:
+   :members: 
+
+
+|_Header| and |_Footer| objects
+-------------------------------
+
+
+.. autoclass:: _Header()
+   :inherited-members: 
+   :members: 
+   :exclude-members: part
+
+
+.. autoclass:: _Footer()
+   :inherited-members: 
+   :members: 
+   :exclude-members: part

docs/conf.py

@@ -20,7 +20,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
 
-from docx import __version__
+from docx import __version__  # noqa
 
 
 # -- General configuration ---------------------------------------------------
@@ -107,6 +107,16 @@
 
 .. |Font| replace:: :class:`.Font`
 
+.. |_Footer| replace:: :class:`._Footer`
+
+.. |FooterPart| replace:: :class:`.FooterPart`
+
+.. |_Header| replace:: :class:`._Header`
+
+.. |HeaderPart| replace:: :class:`.HeaderPart`
+
+.. |ImageParts| replace:: :class:`.ImageParts`
+
 .. |Inches| replace:: :class:`.Inches`
 
 .. |InlineShape| replace:: :class:`.InlineShape`
@@ -371,4 +381,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'http://docs.python.org/3/': None}

docs/dev/analysis/features/header.rst

@@ -3,39 +3,54 @@
 Header and Footer
 =================
 
-In a WordprocessingML document, a page header is text that is separated from
-the main body of text and appears at the top of a printed page. The page
-headers in a document are often the same from page to page, with only small
-differences in content, such as a section title or page number. Such a header
-is also known as a running head.
-
-In book-printed documents, where pages are intended to be bound on the long
-edge and presented side-by-side, the header on a right-hand (recto) page is
-often different than that on a left-hand (verso) page. Supporting this
-difference gives rise to the option to have an even-page header that differs
-from the default odd-page header in a document.
-
-A page footer is analogous in every way to a page header except that it
-appears at the bottom of a page. It should not be confused with a footnote,
-which is not uniform between pages. For brevity's sake, the term *header* is
-often used below to refer to what may be either a header or footer object,
-trusting the reader to understand its applicability to both object types.
-
-In WordprocessingML, a header or footer appears within the margin area of
-a page. With a few exceptions, a header or footer may contain all the types
-of content that can appear in the main body, including text and images. Each
-header and footer has access to the styles defined in ``/word/styles.xml``.
-
-Each section has its own set of headers and footers, although a section can
-be configured to "inherit" headers and footers from the prior section. Each
-section can have three header definitions, the default header, even header,
-and first page header. When different even/odd headers are not enabled, the
-default header appears on both even and odd numbered pages. If even/odd
-headers are enabled, the default header is used for odd pages.
-A corresponding set of three footer definitions are also possible. All
+In a WordprocessingML document, a page header is text that is separated from the main
+body of text and appears at the top of a printed page. The page headers in a document
+are often the same from page to page, with only small differences in content, such as
+a section title or page number. Such a header is also known as a running head.
+
+A page footer is analogous in every way to a page header except that it appears at the
+bottom of a page. It should not be confused with a footnote, which is not uniform
+between pages. For brevity's sake, the term *header* is often used here to refer to what
+may be either a header or footer object, trusting the reader to understand its
+applicability to both object types.
+
+In book-printed documents, where pages are printed on both sides, when opened, the front
+or *recto* side of each page appears to the right of the bound edge and the back or
+*verso* side of each page appears on the left. The first printed page receives the
+page-number "1", and is always a recto page. Because pages are numbered consecutively,
+each recto page receives an *odd* page number and each verso page receives an *even*
+page number.
+
+The header appearing on a recto page often differs from that on a verso page. Supporting
+this difference gives rise to the option to have an even-page header that differs from
+the default odd-page header in a document. This "both odd-and-even headers" option is
+applied at the document level and affects all sections of the document.
+
+The header appearing on the first page of a section (e.g. a chapter) may differ from
+that appearing on subsequent pages. Supporting this difference gives rise to the option
+to set a distinct first-page header. This "different first-page-header" option is
+applied at the section level and may differ from section-to-section in the document.
+
+In WordprocessingML, a header or footer appears within the margin area of a page. With
+a few exceptions, a header or footer may contain all the types of content that can
+appear in the main body, including text and images. Each header and footer has access to
+the styles defined in ``/word/styles.xml``.
+
+Each section has its own set of headers and footers, although a section can be
+configured to "inherit" headers and footers from the prior section. Each section can
+have three header definitions, the default header, even header, and first page header.
+When different even/odd headers are not enabled, the default header appears on both even
+and odd numbered pages. If even/odd headers are enabled, the default header is used for
+odd pages. A corresponding set of three footer definitions are also possible. All
 header/footer definitions are optional.
 
 
+Open Questions
+--------------
+
+* What about a continuous section break? What is the header/footer behavior there?
+
+
 Candidate Protocol
 ------------------
 
@@ -96,12 +111,12 @@ Conversely, an existing header is deleted from a section by assigning True to
     >>> header.is_linked_to_previous
     True
 
-The document settings object has a read/write
-`.odd_and_even_pages_header_footer` property that indicates verso and recto
-pages will have a different header. An existing even page header definition is
-preserved when `.odd_and_even_pages_header_footer` is False; it is simply not
-rendered by Word. Assigning `True` to `.odd_and_even_pages_header_footer`
-does not automatically create a new even header definition::
+The document settings object has a read/write `.odd_and_even_pages_header_footer`
+property that indicates verso and recto pages will have a different header. Any existing
+even page header definitions are preserved when `.odd_and_even_pages_header_footer` is
+False; they are simply not rendered by Word. Assigning `True` to
+`.odd_and_even_pages_header_footer` does not automatically create new even header
+definitions::
 
     >>> document.settings.odd_and_even_pages_header_footer
     False
@@ -174,6 +189,19 @@ Distinct first, even, and odd page headers::
        ...
    </w:sectPr>
 
+A header part::
+
+   <w:hdr>
+     <w:p>
+       <w:pPr>
+         <w:pStyle w:val="Header"/>
+       </w:pPr>
+       <w:r>
+         <w:t>Header for section-1</w:t>
+       </w:r>
+     </w:p>
+   </w:hdr>
+
 
 Word Behavior
 -------------
@@ -250,7 +278,7 @@ Schema Excerpt
     </xsd:complexType>
 
     <xsd:complexType name="CT_HdrFtrRef">
-      <xsd:attribute  ref="r:id"                  use="required"/>
+      <xsd:attribute ref="r:id" use="required"/>
       <xsd:attribute name="type" type="ST_HdrFtr" use="required"/>
     </xsd:complexType>