This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author jaraco
Recipients jaraco, r.david.murray, steven.daprano, tim.peters
Date 2018-01-07.15:27:08
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1515338829.25.0.467229070634.issue32509@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2018-01-07 15:27:09jaracosetrecipients: + jaraco, tim.peters, steven.daprano, r.david.murray
2018-01-07 15:27:09jaracosetmessageid: <1515338829.25.0.467229070634.issue32509@psf.upfronthosting.co.za>
2018-01-07 15:27:09jaracolinkissue32509 messages
2018-01-07 15:27:08jaracocreate