[issue32509] doctest syntax ambiguity between continuation line and ellipsis

[Jason R. Coombs]

Jason R. Coombs <jaraco at jaraco.com> added the comment:

Thank you Steven for creating a reproduction of the issue; I should have done that in the first place. I have the +ELLIPSIS enabled elsewhere in the test suite, which is why it didn't appear in my example.

I should clarify - what I thought was a suitable workaround turns out is not, in part because the ellipsis must match _something_ and cannot be a degenerate match, leading to [this failure](https://travis-ci.org/jaraco/jaraco.financial/jobs/325955523). So the workaround I thought I'd devised was only suitable in some environments (where some content did appear before the target content).

I conclude that trying to match only a single line from a non-deterministically-ordered list of lines isn't a function for which ellipsis is well suited. I'll be adapting the test to simply test for the presence of the expected substring. Therefore, the use-case I presented is invalid (at least while ellipsis must match at least one character).

Still, I suspect I haven't been the only person to encounter the reported ambiguity, and I appreciate the progress toward addressing it. I like Steven's approach, as it's simple and directly addresses the ambiguity. It does have the one downside that for the purposes of the documentation, it's a little less elegant, as a literal "<ELLIPSIS>" appears in the docstring.

Perhaps instead of "ELLIPSIS", the indicator should be "ANYTHING" or similar, acting more as a first-class feature rather than a stand-in for an ellipsis. That would save the human reader the distraction and trouble of translating "<ELLIPSIS>" to "..." before interpreting the value (even if that's what the doctest interpreter does under the hood).

Alternatively, consider "<...>" as the syntax. I'm liking that because it almost looks like it's intention, avoiding much of the distraction. As I think about it more, I'm pretty sure such and approach is not viable, as it's a new syntax (non-alpha in the directive) and highly likely to conflict with existing doctests in the wild.

Another way to think about this problem is that the literal "..." is only non-viable when it's the first content in the expected output. Perhaps all that's needed is a signal that the output is starting, with something like "<OUTPUT>" or "<START>" or "<EXPECT>" or "<NULL>" or "<EMPTY>", a token like "<BLANKLINE>" except it's an empty match specifically designed to make the transition. Such a token would specifically address the issue at the border of the test and the output and would _also_ address the issue if the expected output begins with a _literal_ "...". Consider this case:

# --- cut %< ---
import doctest

def print_3_dot():
    """
    >>> print_3_dot()
    ...
    """
    print('...')

doctest.run_docstring_examples(print_3_dot, globals())
# --- cut %< ---

In that case, "<ELLIPSIS>" may also work, but only because a literal substitution is being made. One _might_ be surprised when "<ELLIPSIS>" does't match anything (when +ELLIPSIS is not enabled).

Overall, I'm now thinking the "<ELLIPSIS>" solution is suitable and clear enough.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue32509>
_______________________________________