style: add _ParaStyle.next_paragraph_style getter

* add a more descriptive __repr__() for _ParagraphStyle

Author: Steve Canny

docx/oxml/__init__.py

@@ -119,6 +119,7 @@ def OxmlElement(nsptag_str, attrs=None, nsdecls=None):
 register_element_cls('w:locked',         CT_OnOff)
 register_element_cls('w:lsdException',   CT_LsdException)
 register_element_cls('w:name',           CT_String)
+register_element_cls('w:next',           CT_String)
 register_element_cls('w:qFormat',        CT_OnOff)
 register_element_cls('w:semiHidden',     CT_OnOff)
 register_element_cls('w:style',          CT_Style)

docx/oxml/styles.py

@@ -118,6 +118,7 @@ class CT_Style(BaseOxmlElement):
     )
     name = ZeroOrOne('w:name', successors=_tag_seq[1:])
     basedOn = ZeroOrOne('w:basedOn', successors=_tag_seq[3:])
+    next = ZeroOrOne('w:next', successors=_tag_seq[4:])
     uiPriority = ZeroOrOne('w:uiPriority', successors=_tag_seq[8:])
     semiHidden = ZeroOrOne('w:semiHidden', successors=_tag_seq[9:])
     unhideWhenUsed = ZeroOrOne('w:unhideWhenUsed', successors=_tag_seq[10:])
@@ -204,6 +205,19 @@ def name_val(self, value):
             name = self._add_name()
             name.val = value
 
+    @property
+    def next_style(self):
+        """
+        Sibling CT_Style element identified by the value of `w:name/@w:val`
+        or |None| if no value is present or no style with that style id
+        is found.
+        """
+        next = self.next
+        if next is None:
+            return None
+        styles = self.getparent()
+        return styles.get_by_id(next.val)  # None if not found
+
     @property
     def qFormat_val(self):
         """

docx/styles/style.py

@@ -229,6 +229,25 @@ class _ParagraphStyle(_CharacterStyle):
 
     __slots__ = ()
 
+    def __repr__(self):
+        return '_ParagraphStyle(\'%s\') id: %s' % (self.name, id(self))
+
+    @property
+    def next_paragraph_style(self):
+        """
+        |_ParagraphStyle| object representing the style to be applied
+        automatically to a new paragraph inserted after a paragraph of this
+        style. Returns self if no next paragraph style is defined. Assigning
+        |None| or *self* removes the setting such that new paragraphs are
+        created using this same style.
+        """
+        next_style_elm = self._element.next_style
+        if next_style_elm is None:
+            return self
+        if next_style_elm.type != WD_STYLE_TYPE.PARAGRAPH:
+            return self
+        return StyleFactory(next_style_elm)
+
     @property
     def paragraph_format(self):
         """

features/sty-style-props.feature

@@ -81,7 +81,6 @@ Feature: Get and set style properties
      Then style.name is the new name
 
 
-  @wip
   Scenario Outline: Get next paragraph style
     Given a style having next paragraph style set to <setting>
      Then style.next_paragraph_style is <value>

tests/styles/test_style.py

@@ -464,6 +464,10 @@ def StyleFactory_(self, request):
 
 class Describe_ParagraphStyle(object):
 
+    def it_knows_its_next_paragraph_style(self, next_get_fixture):
+        style, expected_value = next_get_fixture
+        assert style.next_paragraph_style == expected_value
+
     def it_provides_access_to_its_paragraph_format(self, parfmt_fixture):
         style, ParagraphFormat_, paragraph_format_ = parfmt_fixture
         paragraph_format = style.paragraph_format
@@ -472,6 +476,32 @@ def it_provides_access_to_its_paragraph_format(self, parfmt_fixture):
 
     # fixtures -------------------------------------------------------
 
+    @pytest.fixture(params=[
+        ('H1',   'Body'),
+        ('H2',   'H2'),
+        ('Body', 'Body'),
+        ('Foo',  'Foo'),
+    ])
+    def next_get_fixture(self, request):
+        style_name, next_style_name = request.param
+        styles = element(
+            'w:styles/('
+            'w:style{w:type=paragraph,w:styleId=H1}/w:next{w:val=Body},'
+            'w:style{w:type=paragraph,w:styleId=H2}/w:next{w:val=Char},'
+            'w:style{w:type=paragraph,w:styleId=Body},'
+            'w:style{w:type=paragraph,w:styleId=Foo}/w:next{w:val=Bar},'
+            'w:style{w:type=character,w:styleId=Char})'
+        )
+        style_names = ['H1', 'H2', 'Body', 'Foo', 'Char']
+        style_elm = styles[style_names.index(style_name)]
+        next_style_elm = styles[style_names.index(next_style_name)]
+        style = _ParagraphStyle(style_elm)
+        if style_name == 'H1':
+            next_style = _ParagraphStyle(next_style_elm)
+        else:
+            next_style = style
+        return style, next_style
+
     @pytest.fixture
     def parfmt_fixture(self, ParagraphFormat_, paragraph_format_):
         style = _ParagraphStyle(element('w:style'))