test_format_docstring.py

# pylint: skip-file
# type: ignore
#
#       tests.test_format_docstring.py is part of the docformatter project
#
# Copyright (C) 2012-2019 Steven Myint
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Module for testing the format_docstring() function."""


# Standard Library Imports
import itertools
import random
import sys

# Third Party Imports
import pytest

# docformatter Package Imports
import docformatter
from docformatter import Formator

# docformatter Local Imports
from . import generate_random_docstring

INDENTATION = "    "


class TestFormatDocstring:
    """Class for testing _do_format_docstring() with no arguments."""

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring(self, test_args, args):
        """Return one-line docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '"""Hello."""' == uut._do_format_docstring(
            INDENTATION,
            '''
"""

Hello.
"""
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_summary_that_ends_in_quote(
        self, test_args, args
    ):
        """Return one-line docstring with period after quote."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''""""Hello"."""''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""

"Hello"
"""
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "44", ""]])
    def test_format_docstring_with_bad_indentation(self, test_args, args):
        """Add spaces to indentation when too few."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Hello.

    This should be indented but it is not.
    The next line should be indented too.
    And this too.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""Hello.

 This should be indented but it is not. The
 next line should be indented too. And
 this too.
    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_too_much_indentation(self, test_args, args):
        """Remove spaces from indentation when too many."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Hello.

    This should be dedented.

    1. This too.
    2. And this.
    3. And this.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""Hello.

        This should be dedented.

        1. This too.
        2. And this.
        3. And this.

    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "52", ""]])
    def test_format_docstring_with_trailing_whitespace(self, test_args, args):
        """Remove trailing white space."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Hello.

    This should be not have trailing whitespace. The
    next line should not have trailing whitespace
    either.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""Hello.\t
\t
    This should be not have trailing whitespace. The\t\t\t
    next line should not have trailing whitespace either.\t
\t
    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_empty_docstring(self, test_args, args):
        """Do nothing with empty docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '""""""' == uut._do_format_docstring(INDENTATION, '""""""')

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_no_period(self, test_args, args):
        """Add period to end of one-line and summary line."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '"""Hello."""' == uut._do_format_docstring(
            INDENTATION,
            '''
"""

Hello
"""
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_single_quotes(self, test_args, args):
        """Replace single triple quotes with triple double quotes."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '"""Hello."""' == uut._do_format_docstring(
            INDENTATION,
            """
'''

Hello.
'''
""".strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_single_quotes_multi_line(
        self, test_args, args
    ):
        """Replace single triple quotes with triple double quotes."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''
    """Return x factorial.

    This uses math.factorial.
    """
'''.strip() == uut._do_format_docstring(
            INDENTATION,
            """
    '''
    Return x factorial.

    This uses math.factorial.
    '''
""".strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_leave_underlined_summaries_alone(
        self, test_args, args
    ):
        """Leave underlined summary lines as is."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""
    Foo bar
    -------

    This is more.

    """'''
        assert docstring == uut._do_format_docstring(INDENTATION, docstring)


class TestFormatLists:
    """Class for testing format_docstring() with lists in the docstring."""

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_numbered_lists(
        self, test_args, args
    ):
        """Ignore lists beginning with numbers."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""Hello.

    1. This should be indented but it is not. The
    next line should be indented too. But
    this is okay.
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_parameter_lists(
        self, test_args, args
    ):
        """Ignore lists beginning with <word> -."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""Hello.

    foo - This is a foo. This is a foo. This is a foo. This is a foo. This is.
    bar - This is a bar. This is a bar. This is a bar. This is a bar. This is.
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_colon_parameter_lists(
        self, test_args, args
    ):
        """Ignore lists beginning with <word>:"""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""Hello.

    foo: This is a foo. This is a foo. This is a foo. This is a foo. This is.
    bar: This is a bar. This is a bar. This is a bar. This is a bar. This is.
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_should_leave_list_alone(self, test_args, args):
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""
    one
    two
    three
    four
    five
    six
    seven
    eight
    nine
    ten
    eleven
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )


class TestFormatWrap:
    """Class for testing _do_format_docstring() with line wrapping."""

    @pytest.mark.unit
    def test_unwrap_summary(self):
        """Remove newline and tab characters."""
        assert "This is a sentence." == docformatter.unwrap_summary(
            "This \n\tis\na sentence."
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_wrap(
        self,
        test_args,
        args,
    ):
        """Wrap the docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        # This function uses `random` so make sure each run of this test is
        # repeatable.
        random.seed(0)

        min_line_length = 50
        for max_length, num_indents in itertools.product(
            range(min_line_length, 100), range(20)
        ):
            indentation = " " * num_indents
            uut.args.wrap_summaries = max_length
            formatted_text = indentation + uut._do_format_docstring(
                indentation=indentation,
                docstring=generate_random_docstring(
                    max_word_length=min_line_length // 2
                ),
            )
            for line in formatted_text.split("\n"):
                # It is not the formatter's fault if a word is too long to
                # wrap.
                if len(line.split()) > 1:
                    assert len(line) <= max_length

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-summaries", "79", ""]])
    def test_format_docstring_with_weird_indentation_and_punctuation(
        self,
        test_args,
        args,
    ):
        """Wrap and dedent docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''
    """Creates and returns four was awakens to was created tracked ammonites
    was the fifty, arithmetical four was pyrotechnic to pyrotechnic physicists.

    `four' falsified x falsified ammonites to awakens to. `created' to
    ancestor was four to x dynamo to was four ancestor to physicists().
    """
        '''.strip() == uut._do_format_docstring(
            INDENTATION,
            '''
            """Creates and returns four was awakens to was created tracked
               ammonites was the fifty, arithmetical four was pyrotechnic to
               pyrotechnic physicists. `four' falsified x falsified ammonites
               to awakens to. `created' to ancestor was four to x dynamo to was
               four ancestor to physicists().
            """
        '''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_with_description_wrapping(
        self,
        test_args,
        args,
    ):
        """Wrap description at 72 characters."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Hello.

    This should be indented but it is not. The next line should be
    indented too. But this is okay.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""Hello.

    This should be indented but it is not. The
    next line should be indented too. But
    this is okay.

    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_multi_paragraph(
        self,
        test_args,
        args,
    ):
        """Ignore multiple paragraphs in elaborate description."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""Hello.

    This should be indented but it is not. The
    next line should be indented too. But
    this is okay.

    This should be indented but it is not. The
    next line should be indented too. But
    this is okay.
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_doctests(
        self,
        test_args,
        args,
    ):
        """Leave doctests alone."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""Hello.

    >>> 4
    4
    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_ignore_doctests_in_summary(
        self,
        test_args,
        args,
    ):
        """Leave doctests alone if they're in the summary."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''"""
    >>> 4
    4

    """'''
        assert docstring == uut._do_format_docstring(
            INDENTATION,
            docstring,
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--wrap-descriptions", "72", ""]])
    def test_format_docstring_should_maintain_indentation_of_doctest(
        self,
        test_args,
        args,
    ):
        """Don't change indentation of doctest lines."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Foo bar bing bang.

        >>> tests = DocTestFinder().find(_TestClass)
        >>> runner = DocTestRunner(verbose=False)
        >>> tests.sort(key = lambda test: test.name)
    """''' == uut._do_format_docstring(
            INDENTATION,
            docstring='''"""Foo bar bing bang.

        >>> tests = DocTestFinder().find(_TestClass)
        >>> runner = DocTestRunner(verbose=False)
        >>> tests.sort(key = lambda test: test.name)

    """''',
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [
            [
                "--wrap-descriptions",
                "72",
                "--wrap-summaries",
                "50",
                "--force-wrap",
                "",
            ]
        ],
    )
    def test_force_wrap(
        self,
        test_args,
        args,
    ):
        """Force even lists to be wrapped."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert (
            (
                '''\
"""num_iterations is the number of updates -
    instead of a better definition of
    convergence."""\
'''
            )
            == uut._do_format_docstring(
                INDENTATION,
                '''\
"""
num_iterations is the number of updates - instead of a better definition of convergence.
"""\
''',
            )
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-summaries", "30", "--tab-width", "4", ""]],
    )
    def test_format_docstring_with_summary_only_and_wrap_and_tab_indentation(
        self,
        test_args,
        args,
    ):
        """Should account for length of tab when wrapping.

        See PR #69.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''
\t\t"""Some summary x x x
\t\tx."""
'''.strip() == uut._do_format_docstring(
            "\t\t",
            '''
\t\t"""Some summary x x x x."""
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-summaries", "69", "--close-quotes-on-newline", ""]],
    )
    def test_format_docstring_for_multi_line_summary_alone(
        self,
        test_args,
        args,
    ):
        """Place closing quotes on newline when wrapping one-liner."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert (
            (
                '''\
"""This one-line docstring will be multi-line because it's quite
    long.
    """\
'''
            )
            == uut._do_format_docstring(
                INDENTATION,
                '''\
"""This one-line docstring will be multi-line because it's quite long."""\
''',
            )
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-summaries", "88", "--close-quotes-on-newline", ""]],
    )
    def test_format_docstring_for_one_line_summary_alone_but_too_long(
        self,
        test_args,
        args,
    ):
        """"""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert (
            (
                '''\
"""This one-line docstring will not be wrapped and quotes will be in-line."""\
'''
            )
            == uut._do_format_docstring(
                INDENTATION,
                '''\
"""This one-line docstring will not be wrapped and quotes will be in-line."""\
''',
            )
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-descriptions", "72", ""]],
    )
    def test_format_docstring_with_inline_links(
        self,
        test_args,
        args,
    ):
        """Preserve links instead of wrapping them.

        See issue #75. See requirement docformatter_10.1.3.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''\
"""This is a docstring with a link.

    Here is an elaborate description containing a link.
    `Area Under the Receiver Operating Characteristic Curve (ROC AUC)
        <https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Further_interpretations>`_.
    """\
'''

        assert '''\
"""This is a docstring with a link.

    Here is an elaborate description containing a link. `Area Under the
    Receiver Operating Characteristic Curve (ROC AUC)
    <https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Further_interpretations>`_.
    """\
''' == uut._do_format_docstring(
            INDENTATION, docstring.strip()
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-descriptions", "72", ""]],
    )
    def test_format_docstring_with_target_links(
        self,
        test_args,
        args,
    ):
        """Preserve links instead of wrapping them.

        See issue #75. See requirement docformatter_10.1.3.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''\
"""This is another docstring with `a link`_.

    .. a link: http://www.reliqual.com/wiki/how_to_use_ramstk/verification_and_validation_module/index.html.
    """\
'''

        assert '''\
"""This is another docstring with `a link`_.

    .. a link: http://www.reliqual.com/wiki/how_to_use_ramstk/verification_and_validation_module/index.html.
    """\
''' == uut._do_format_docstring(
            INDENTATION, docstring.strip()
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-descriptions", "72", ""]],
    )
    def test_format_docstring_with_simple_link(
        self,
        test_args,
        args,
    ):
        """Preserve links instead of wrapping them.

        See issue #75. See requirement docformatter_10.1.3.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''\
"""This is another docstring with a link.

    See http://www.reliqual.com/wiki/how_to_use_ramstk/verification_and_validation_module/index.html for additional information.
    """\
'''

        assert '''\
"""This is another docstring with a link.

    See
    http://www.reliqual.com/wiki/how_to_use_ramstk/verification_and_validation_module/index.html
    for additional information.
    """\
''' == uut._do_format_docstring(
            INDENTATION, docstring.strip()
        )

    @pytest.mark.unit
    @pytest.mark.parametrize(
        "args",
        [["--wrap-descriptions", "72", ""]],
    )
    def test_format_docstring_with_short_link(
        self,
        test_args,
        args,
    ):
        """Short links will remain untouched.

        See issue #75. See requirement docformatter_10.1.3.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''\
"""This is yanf with a short link.

    See http://www.reliaqual.com for examples.
    """\
'''

        assert '''\
"""This is yanf with a short link.

    See http://www.reliaqual.com for examples.
    """\
''' == uut._do_format_docstring(
            INDENTATION, docstring.strip()
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_class_attributes(self, test_args, args):
        """Wrap long class attribute docstrings."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring = '''\
class TestClass:
    """This is a class docstring."""

    test_int = 1
    """This is a very, very, very long docstring that should really be
    reformatted nicely by docformatter."""
'''
        assert docstring == uut._do_format_code(
            '''\
class TestClass:
    """This is a class docstring."""

    test_int = 1
    """This is a very, very, very long docstring that should really be reformatted nicely by docformatter."""
'''
        )


class TestFormatStyleOptions:
    """Class for testing format_docstring() when requesting style options."""

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_format_docstring_with_no_post_description_blank(
        self,
        test_args,
        args,
    ):
        """Remove blank lines before closing triple quotes."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""Hello.

    Description.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""

Hello.

    Description.


    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--pre-summary-newline", ""]])
    def test_format_docstring_with_pre_summary_newline(
        self,
        test_args,
        args,
    ):
        """Remove blank line before summary."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert '''"""
    Hello.

    Description.
    """''' == uut._do_format_docstring(
            INDENTATION,
            '''
"""

Hello.

    Description.


    """
'''.strip(),
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--make-summary-multi-line", ""]])
    def test_format_docstring_make_summary_multi_line(
        self,
        test_args,
        args,
    ):
        """Place the one-line docstring between triple quotes."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert (
            (
                '''\
"""
    This one-line docstring will be multi-line.
    """\
'''
            )
            == uut._do_format_docstring(
                INDENTATION,
                '''\
"""This one-line docstring will be multi-line"""\
''',
            )
        )

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [["--pre-summary-space", ""]])
    def test_format_docstring_pre_summary_space(
        self,
        test_args,
        args,
    ):
        """Place a space between the opening quotes and the summary."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        assert (
            '''""" This one-line docstring will have a leading space."""'''
        ) == uut._do_format_docstring(
            INDENTATION,
            '''\
"""This one-line docstring will have a leading space."""\
''',
        )


class TestStripDocstring:
    """Class for testing _do_strip_docstring()."""

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring(
        self,
        test_args,
        args,
    ):
        """Strip triple double quotes from docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring, open_quote = uut._do_strip_docstring(
            '''
    """Hello.

    """

    '''
        )
        assert docstring == "Hello."
        assert open_quote == '"""'

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_single_quotes(
        self,
        test_args,
        args,
    ):
        """Strip triple single quotes from docstring."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring, open_quote = uut._do_strip_docstring(
            """
    '''Hello.

    '''

    """
        )
        assert docstring == "Hello."
        assert open_quote == '"""'

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_empty_string(
        self,
        test_args,
        args,
    ):
        """Return series of six double quotes when passed empty string."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring, open_quote = uut._do_strip_docstring('""""""')
        assert docstring == ""
        assert open_quote == '"""'

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_raw_string(
        self,
        test_args,
        args,
    ):
        """Return docstring and raw open quote."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring, open_quote = uut._do_strip_docstring('r"""foo"""')
        assert docstring == "foo"
        assert open_quote == 'r"""'

        docstring, open_quote = uut._do_strip_docstring("R'''foo'''")
        assert docstring == "foo"
        assert open_quote == 'R"""'

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_unicode_string(
        self,
        test_args,
        args,
    ):
        """Return docstring and unicode open quote."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        docstring, open_quote = uut._do_strip_docstring("u'''foo'''")
        assert docstring == "foo"
        assert open_quote == 'u"""'

        docstring, open_quote = uut._do_strip_docstring('U"""foo"""')
        assert docstring == "foo"
        assert open_quote == 'U"""'

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_unknown(
        self,
        test_args,
        args,
    ):
        """Raise ValueError with single quotes."""
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        with pytest.raises(ValueError):
            uut._do_strip_docstring("foo")

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_single_quotes(
        self,
        test_args,
        args,
    ):
        """Raise ValueError when strings begin with single single quotes.

        See requirement PEP_257_1.  See issue #66 for example of
        docformatter breaking code when encountering single quote.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        with pytest.raises(ValueError):
            uut._do_strip_docstring("'hello\\''")

    @pytest.mark.unit
    @pytest.mark.parametrize("args", [[""]])
    def test_strip_docstring_with_double_quotes(
        self,
        test_args,
        args,
    ):
        """Raise ValueError when strings begin with single double quotes.

        See requirement PEP_257_1.  See issue #66 for example of
        docformatter breaking code when encountering single quote.
        """
        uut = Formator(
            test_args,
            sys.stderr,
            sys.stdin,
            sys.stdout,
        )

        with pytest.raises(ValueError):
            uut._do_strip_docstring('"hello\\""')