CODEWITHSUNDEEP
pythondocumentationintegration-testing
MERose
MERose

Reputation: 4421

How to write examples in docstrings that pass Travis CI?

I'm a friend of examples in docstrings and good examples (in my view) include a statement of what the user will see if she executes some lines of code. Sometimes the output are dictionaries, which as well all know are inherently unordered.

"""This method prints a dictionary.

Examples
--------
>>> a = dict(x=1, y=2)
>>> a
{'y': 2, 'x': 1}
""""

I can of course also be {'x': 1, 'y': 2}. And because of that, the Travis CI would complain about a "Failed doctest test" with words similar to these:

Expected:
    {'y': 2, 'x': 1}
Got:
    {'x': 1, 'y': 2}

I can't tell Travis CI that a dictionary is unordered. How can I write a docstring with examples that include dictionary output such that the docstring test is passed?

Upvotes: 1

Views: 258

Answers (2)

MERose
MERose

Reputation: 4421

My question is essentially about dictionaries in docstrings. My favorite workaround is 

"""
>>> a = dict(x=1, y=2)
>>> sorted(a.items())
[('x', 1), ('y', 2)]
"""

Upvotes: 3

Lightness Races in Orbit
Lightness Races in Orbit

Reputation: 385194

That does sound kind of annoying.

I don't think you can do anything about it beyond raising an issue against Travis CI (because this is a Travis bug) and hoping it'll get fixed.

In the meantime, you could configure Travis CI not to run this particular test, or you could adjust the order and pray that the result is at least partially deterministic on your particular installation, given a particular input.

For what it's worth, you're not alone:

It looks like various projects are having to write workarounds for this problem.

Upvotes: 3

Related Questions