Eli Bendersky added the comment: I don't know if it matters much, but there's a slight mismatch in the description of test.support.verbose. The documentation says it's a boolean, while it's 0 or 1 in reality. Can it just be changed to True/False in the code of test.support and test.regrtest? It appears that all the other flags are True/False and there's no reason to keep this 0/1 (which is probably a relic from a distant past) ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Eli Bendersky added the comment: Here's a patch to Doc/library/test.rst with additional several exported functions documented. These are the ones I found most important and clear. fcmp() is currently not documented (pending discussion in pydev). ---------- stage: needs patch -> patch review Added file: http://bugs.python.org/file20567/issue11015.py3k.testdoc.1.patch _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Eli Bendersky added the comment: Nick, agreed regarding verbose. Somehow I didn't think it would be used in other modules like that, and only looked in regrtest where I didn't see anything meaningful about verbose not being binary. It's a good thing to document it, then :) ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Changes by Giampaolo Rodola' : ---------- nosy: +giampaolo.rodola _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Georg Brandl added the comment: The divmod() part of the patch is wrong: assertAlmostEqual does not support tuple arguments. The test succeeds because it first does an exact equality check, which apparently is true on your platform. But if it wasn't, you'd get TypeErrors. Also, fcmp() has a different definition of what "almost equal" means, but I assume this has been regarded in the discussion. ---------- nosy: +georg.brandl _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Georg Brandl added the comment: (2) would be my choice. (1) *should* be true, but this is a change in the test semantics. (3) would be feature creep and I don't think it's a good idea. ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Georg Brandl added the comment: Yes, that looks good now. ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Changes by Sandro Tosi : ---------- nosy: +sandro.tosi _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Terry J. Reedy added the comment: This is an improvement that I think should be committed before 3.2.1. Some comments: +.. function:: run_doctest(module, verbosity=None) + Run :mod:`doctest` on the given *module*. should be, I believe, + Run :func:`doctest.testmod` on the given *module*. as that is what the function actually does (I check the code). + If *verbosity* is :const:`None`, :meth:`doctest` is run with verbosity set + to :data:`verbose`. Otherwise, it is run with verbosity set to + :const:`None`. Should :meth:`doctest` be :func:`testmod` ? Otherwise the proposed text rewrites " If optional argument verbosity is not specified (or is None), pass support's belief about verbosity on to doctest. Else doctest's usual behavior is used (it searches sys.argv for -v)." The problem with the rewrite is that the keyword param of testmod is 'verbose', not 'verbosity'. 'Verbosity' is a dummy name used to either pass support.verbose to verbose, or not. So testmod is, in net effect, run with verbose=verbose or verbose=None. My attempt to explain a bad design (with probable markup errors): "If *verbosity* is :const:`None`, :func:`testmod` is run with verbose set to :data:`support.verbose`, which is set by :func:`regrtest`. Otherwise, it is run with verbose set to :const:`None` and subsequently replaced by :code:`'-v' in sys.argv`." +.. function:: temp_umask(umask) + + A context manager that temporarily sets the process umask to the + given value. "sets the process umask to *umask*." ? +.. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM) + Either this method or :func:`bind_port` should be used for any tests + where a server socket needs to be bound to a particular port for the + duration of the test. + Which one to use depends on whether the calling code is creating a python + socket, or if an unused port needs to be provided in a constructor + or passed to an external program (i.e. the ``-accept`` argument to + openssl's s_server mode). This is copied from the doc string but does really tell me which to use in which of the two situations. Other additions look OK to me. Some copied docstrings (or comments). Some are new. Support.py could also use a patch to add missing docstings (and turn a couple of comments into docstrings). ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Changes by Terry J. Reedy : Removed file: http://bugs.python.org/file21890/unnamed _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Eli Bendersky added the comment: Terry, I've incorporated your suggestions except the new formulation for verbosity to doctest.testmod, since it's not really clear which one is more accurate. I think it's intelligible as it is now (especially given that test.support is for use of Python contributors, and not random users). If you have strong preferences about it, feel free to commit another formulation. Ezio, I answered your comments in the code review tool. Regarding the use of assertEqual for the floating point results, I just didn't want to rely on the exact representation of these values. I'm not 100% sure Python ensures this is true on all platforms it supports. Recall that I was just replacing the fcmp code which did basically the same, also not comparing exactly. ---- I will commit a fixed patch to default. I see no reason to backport this since test.support is just a tool for core-devs and contributors and is mainly used for future developments. ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Eli Bendersky added the comment: Can this issue be closed? ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Eli Bendersky added the comment: Ezio, you're right, there are still a lot of undocumented symbols (functions, classes, globals). I compiled a list of those I could not find in the .rst docs, excluding ones that are only used in regrtest.py itself: ------------------------------------------ get_attribute record_original_stdout/get_original_stdout unload unlink rmtree make_legacy_pyc IPV6_ENABLED TESTFN_ENCODED TESTFN_UNENCODABLE sortdict check_syntax_error open_urlresource CleanImport DirsOnSysPath transient_internet captured_output captured_stderr gc_collect python_is_optimized set_memlimit bigmemtest precisionbigmemtest bigaddrspacetest requires_resource cpython_only impl_detail check_impl_detail no_tracing refcount_test modules_setup / modules_cleanup threading_setup / threading_cleanup reap_threads reap_children swap_attr swap_item strip_python_stderr TestHandler Matcher patch ------------------------------------------ ---------- _______________________________________ Python tracker http://bugs.python.org/issue11015 _______________________________________

Change by Cheryl Sabella : ---------- pull_requests: +5420 _______________________________________ Python tracker https://bugs.python.org/issue11015 _______________________________________

Nick Coghlan added the comment: New changeset 988fb28431d3a3fc5dc6eb657c8a4baacc04d9ce by Nick Coghlan (Cheryl Sabella) in branch 'master': bpo-11015: Update test.support documentation (GH-5610) https://github.com/python/cpython/commit/988fb28431d3a3fc5dc6eb657c8a4baacc0... ---------- _______________________________________ Python tracker https://bugs.python.org/issue11015 _______________________________________

Nick Coghlan added the comment: I merged Cheryl's PR to the dev branch, and triggered the backport to 3.7. If nobody beats me to it, I'll merge the latter tomorrow :) ---------- assignee: docs@python -> ncoghlan resolution: -> fixed stage: patch review -> backport needed _______________________________________ Python tracker https://bugs.python.org/issue11015 _______________________________________

Nick Coghlan added the comment: New changeset a0b998df314370f00502efe7ad84206f5bb782ff by Nick Coghlan (Miss Islington (bot)) in branch '3.7': bpo-11015: Update test.support documentation (GH-5619) https://github.com/python/cpython/commit/a0b998df314370f00502efe7ad84206f5bb... ---------- _______________________________________ Python tracker https://bugs.python.org/issue11015 _______________________________________

Terry J. Reedy added the comment: Since Nick already merged and backported, at least a new PR is needed. Since this is an old issue with a long discussion and several inactives on the nosy list, I suggest a new issue starting from the merge result as a base: "More revisions to test.support docs". Make a list of Serhiy's questions and comments. TESTFN_NONASCII - How different from TESTFN_UNICODE? PGO - value? True/False? TEST_SUPPORT_DIR - Not used. ... Add Nick, Serhiy, and me as nosy. We can discuss there how to handle the additional issues. ---------- components: +Documentation, Tests stage: backport needed -> resolved status: open -> closed versions: +Python 3.7 _______________________________________ Python tracker https://bugs.python.org/issue11015 _______________________________________