Flesh out examples included in docstrings #3439
Comments
|
Those are code examples utilizing the familiar ">>>", not doctests per se. Thanks, closing. |
|
@y-p I'm not really happy with closing this ticket. I think if there are examples, they should work. I think it is useful to have examples in the docstrings especially in ipython, where you can copy and paste them into the console and try some things with the objects created from pasting the examples. An example is numpy, where examples are given in the same way, but they work (they are using ">>>" to and I think this is no problem, it's even given in the documentation of the doctest module as an example, you can paste in the examples with the prompt into ipython and its ignoring the prompt). Numpy and matplotlib also use the "default" import names (numpy as np, matplotlib.pyplot as plt) which makes the users familiar with these shortcuts. sure it is right, that the testing in pandas is done by the unittests, but if there are examples in the docstrings I think they should be tested to and they should work. |
|
Not sure how this would be possible with pandas the the repr for objects cannot be used typically to reconstruct the object for comparison. |
|
Looking at the actual docstrings, these are examples of invocation/signature not full blown doctests also note that numpydoc docstrings use >>> to annotate something for syntax highlighting, Since they weren't written as doctests, |
|
@wesm I don't mean the repr but the object itself created by the example code. As an example, in the docs of the >>> df3 = DataFrame(np.random.randn(10, 5),
... columns=['a', 'b', 'c', 'd', 'e']) If I paste them into ipython I have a DataFrame with named columns, which maybe useful for a beginner as he can further inspect the dataframe (attribute access of the cols, ...) and you don't have to write this code yourself. It's not a big thing, but I did this with numpy and especially with matplotlib where you have more complicated objects with man attributes/methods. Maybe others do this too. @y-p ok, so perhaps the title of this ticket is wrong: most examples are not working as they are. It wasn't really meant to report "failing tests", but failing examples (and doctest is a method to test examples in this way). |
ghost
reopened this
|
as I said, PRs welcome. |
|
Just found an for a "failing doctest" on on SO. The asker is expecting the output of the docstring, however he gets a different result. |
|
@hayd I see, you are rigth. However in the example section of the |
jreback
added
Testing
|
I'm working on this now. :) |
|
BTW, running doctests using pytest can be done like: And example PR for the adjustments that are needed to get the doctests running: #15625 |
|
@jorisvandenbossche - that won't work if you're in the pandas folder already. Would need to be:
@TomAugspurger helped me with that (I'm on Windows) - though I may be misspeaking on my understanding of the issue I was having... |
|
Was just looking how you can run doctests for a single method, and you can do this as follows: in case you want to test |
From the Messages (not included in the code snippet above) one can see that most errors result from ImportErrors, so maybe the problem is only that the imports are not in the docstring.
The text was updated successfully, but these errors were encountered: