On Nov 20, 2008, at 11:00 AM, Simon King wrote: > > Hi folks, > > assume that some function/method produces files on the disk. What > should a doc test look like for such functions/methods? Is there a > standard? My fear is to have doc tests that destroy user data. I'd > like to know your opinion on my concerns. > > 1. The doc test would produce a file, even though the user didn't ask > for having nonsense data written onto his/her disk. > a) In what directory should the files be created? [Subdirectories > of] SAGE_TMP perhaps?
Yes. > b) How can one avoid name conflicts with user data? E.g., in the doc > test for save_session, this point is not taken care of. See http://www.python.org/doc/2.5.2/lib/module-tempfile.html > c) Should the doc test always end with removing the files (see doc > test for save_session)? Even if the test data are written into a > default location and are not nonsense but actually meaningful and > reasonable to keep? That depends on what exactly they are, but usually they should. > d) Would an explicit removal of the files also be needed in > SAGE_TMP? I'm not sure exactly how SAGE_TMP is cleaned up (except not as well as I would like). > 2. In view of 1.: Should such functions/methods have no doc test, > making an exception to the "100% doc test coverage" policy? > a) There is some evidence that the answer should be yes. For > example, there is no doc-test for 'file' or for 'os.mkdir'. However > these are not Sage but Python, and 'save_session' is a counter- > example. > b) In my case, 2.a) would mean to have *no* doc test *at all* in the > whole package. Not good. There should absolutely be doctests. - Robert --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-support@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-support URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
