[Numpy-discussion] Code samples in docstrings mistaken as doctests

Alan McIntyre alan.mcintyre@gmail....
Mon Jun 23 16:31:19 CDT 2008


On Mon, Jun 23, 2008 at 4:51 PM, Robert Kern <robert.kern@gmail.com> wrote:
>> I agree that this can be awkward sometimes, and should certainly not
>> be policy, but one can usually get around this.  Instead of printing
>> the result, you can use it, or demonstrate porperties:
>>
>>  >>> random_array = np.random.rand(3,4)
>>  >>> random_array.shape
>> (3,4)
>>  >>> random_array.max() < 1
>> True
>>  >>> random_array.min() > 0
>> True
>
> Yes, this makes it doctestable, but you've destroyed the exampleness.
> It should be policy *not* to do this.

So it seems we have:
 1. Example code that is doctestable
 2. Example code that probably can't ever be doctestable (random
number stuff, etc.), but is still executable
 3. Schematic examples that aren't executable

Personally, I'm in favor of filling out examples of type #3 to make
them at least #2, but maybe that's not always practical.  I don't
think #3 should ever have ">>>" prompts, so it shouldn't ever be
picked up by doctest.

I suppose I could go for a decorator option to flag #2. If we execute
them, but not look at the results, then at least we find out about
examples that are broken enough to raise exceptions.


More information about the Numpy-discussion mailing list