Skip to content

DOC: file IO in doctest examples #20302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jorisvandenbossche opened this issue Mar 12, 2018 · 5 comments
Closed

DOC: file IO in doctest examples #20302

jorisvandenbossche opened this issue Mar 12, 2018 · 5 comments
Labels
Docs IO Data IO issues that don't fit into a more specific label

Comments

@jorisvandenbossche
Copy link
Member

In several docstrings we write some data to a temporary file to illustrate reading / writing functionality.

However, this leaves behind those files when running the docstest, which is not ideal.

@TomAugspurger from #20208 (review)

We can

  • convert this to a regular code-block
  • Use io.StringIO, which is uglier but doesn't leave behind a file
  • Add a bit to os.remove('test.csv')
@jorisvandenbossche
Copy link
Member Author

@TomAugspurger what do you mean with "convert this to a regular code-block" -> I suppose not using >>> but .. code-block:: or simply :: ?

I would prefer not doing io.StringIO, as it distracts from what we want to show in the example (unless eg for read_csv, there it could be useful to create some text data to read)

Maybe we could somehow use a pytest fixture for temporary directory, but of course, that is also not transparent to the user ..

@TomAugspurger
Copy link
Contributor

what do you mean with "convert this to a regular code-block

Yep. That "avoids" the problem by not actually running the doctest :)

I think the best is to just os.remove('test.csv') at the end. It's just one extra line to import and one to cleanup.

@TomAugspurger TomAugspurger added Testing pandas testing functions or related to the test suite 2/3 Compat labels Mar 12, 2018
@jorisvandenbossche
Copy link
Member Author

I think the best is to just os.remove('test.csv') at the end. It's just one extra line to import and one to cleanup.

Yes, that is probably the easiest

@jreback
Copy link
Contributor

jreback commented Mar 13, 2018

yep agreed using the remove is pretty idiomatic (and its not in that many places anyhow)

@mroeschke mroeschke added Docs IO Data IO issues that don't fit into a more specific label and removed 2/3 Compat Testing pandas testing functions or related to the test suite labels Apr 4, 2020
@mroeschke
Copy link
Member

The approach in #44711 was to skip the lines that will actually write a file and validate that docstrings don't leave leftover files.

This was done due to a flaky segfault in the CI in during docstring validation which was suspected to be because of leftover files: #44590

Since this has a consistent behavior now, closing, but happy to reopen if there are other considerations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Docs IO Data IO issues that don't fit into a more specific label
Projects
None yet
Development

No branches or pull requests

4 participants