multi-line strings lead to incorrect syntax

[yarnabrina]

Python Version

3.9.16

Package Version

1.13.0

Description

Question

If there is a multi-line string within ''' inside a docstring within """, blacken-docs changes the quote to """, leading to syntax error. Is there any way to tell blacken-docs to skip specific line(s), similar to black itself or most other tools?

Reproducible Code

Create test.py with the following snippet:

"""Module docstring."""
import sys


def function(argument: str) -> None:
    """Function docstring.

    Parameters
    ----------
    argument : str
        argument documentation

    Examples
    --------
    .. code-block:: pycon

        >>> sample = '''
        ...     this is
        ...     unnecessarily split
        ...     in milriple lines
        ...     only for demonstration
        ... '''
        >>> function(sample)  # doctest: +NORMALIZE_WHITESPACE
        3
            this is
            unnecessarily split
            in milriple lines
            only for demonstration
    """
    print(sys.version_info.major)
    print(argument)

If I execute blacken-docs test.py, the formatted code will become this:

"""Module docstring."""
import sys


def function(argument: str) -> None:
    """Function docstring.

    Parameters
    ----------
    argument : str
        argument documentation

    Examples
    --------
    .. code-block:: pycon

        >>> sample = """
        ...     this is
        ...     unnecessarily split
        ...     in milriple lines
        ...     only for demonstration
        ... """
        >>> function(sample)  # doctest: +NORMALIZE_WHITESPACE
        3
            this is
            unnecessarily split
            in milriple lines
            only for demonstration
    """
    print(sys.version_info.major)
    print(argument)

This is not valid python code, because of """ inside """.

Attempts

I tried passing # fmt: skip, #fmt: off, etc., but that does not skip the formatting of code.

Known Workaround

If I use ''' for the main docstring and """ in the example, this problem won't arise as blacken won't modify the example and black will not modify main docstring as well detecting there's a """ inside.

[adamchainz]

Given that blacken-docs doesn't have a real parser, only regexes, I think the only way forwards is to add enable/disable comments, as covered in #193.