On Thu, Nov 20, 2008 at 11:45 AM, Robert Bradshaw <[EMAIL PROTECTED]> wrote: > > 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
It might be better I think to use the Sage-provided functions tmp_filename() and tmp_dir(): sage: tmp_filename() '/Users/was/.sage//temp/bsd.local/88943//tmp_0' sage: tmp_dir() '/Users/was/.sage/temp/bsd.local/88943/dir_0' These create either a valid tempory filename or temporary directory in the appropriate subdirectory of DOT_SAGE. This will definitely eventually be cleaned up by the "sage-cleaner" script, even if you kill -9 the sage process. > >> 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 > > > > > > -- William Stein Associate Professor of Mathematics University of Washington http://wstein.org --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
