[issue11015] Bring test.support docs up to date

[Terry J. Reedy]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Cheryl Sabella]

Cheryl Sabella  added the comment:

Thanks Nick for merging.  Should I open a new PR to address Serhiy's review or 
fix them on the original PR?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Nick Coghlan]

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/a0b998df314370f00502efe7ad84206f5bb782ff


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

I have left comments to PR.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Nick Coghlan]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[miss-islington]

Change by miss-islington :


--
pull_requests: +5428

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Nick Coghlan]

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/988fb28431d3a3fc5dc6eb657c8a4baacc04d9ce


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Cheryl Sabella]

Cheryl Sabella  added the comment:

I have created a pull request adding documentation for all of test.support, 
including script_helper.py.  I hope this will be helpful.

--
nosy: +csabella
versions: +Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Cheryl Sabella]

Change by Cheryl Sabella :


--
pull_requests: +5420

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Ezio Melotti]

Ezio Melotti added the comment:

 There are some other helper modules (such as test.script_helper)
 that could also stand to be made easier to find.

Documenting script_helper.py would be good too.  I seem to remember some 
discussion about merging it with support.py -- if that happens it can be 
documented there, otherwise a separate section/file should be created.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

Can this issue be closed?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Ezio Melotti]

Ezio Melotti ezio.melo...@gmail.com added the comment:

There are still functions that are not documented, so I think this should stay 
open until we documented them (unless they shouldn't be documented -- in that 
case it can be closed).

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Roundup Robot]

Roundup Robot devnull@devnull added the comment:

New changeset 2fd435ac3551 by Eli Bendersky in branch 'default':
Issue #11015: bring test.support docs up to date
http://hg.python.org/cpython/rev/2fd435ac3551

--
nosy: +python-dev

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Ezio Melotti]

Ezio Melotti ezio.melo...@gmail.com added the comment:

I left a few comments on rietveld for the testdoc and remove_fcmp patches.
Unless I'm missing something, assertEqual works just fine in all the places 
where fcmp was used, so there's no need to use assertAlmostEqual.

--
nosy: +ezio.melotti

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Sandro Tosi]

Changes by Sandro Tosi sandro.t...@gmail.com:


--
nosy: +sandro.tosi

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Sandro Tosi]

Sandro Tosi sandro.t...@gmail.com added the comment:

Hi all,
IIUIC we are left with issue11015.py3k.testdoc.1.patch) since 
issue11015.py3k.remove_fcmp.{1,2}.patch has been already applied on default.

I just gave a look to the doc patch and it seems fine (it also applies without 
any warning on default).

Eli, do you want to expand this patch further (and how :) or do you think it's 
still the version you want to commit? Can a core devel, then, give this patch a 
deeper look?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Terry J. Reedy]

Terry J. Reedy tjre...@udel.edu 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

 Eli, do you want to expand this patch further (and how :) or do you think
 it's still the version you want to commit? Can a core devel, then, give this
 patch a deeper look?


I will review this again in a couple of days and will commit.

--
Added file: http://bugs.python.org/file21890/unnamed

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___div dir=ltrbrdiv class=gmail_quoteblockquote class=gmail_quote 
style=margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;
Eli, do you want to expand this patch further (and how :) or do you think 
it#39;s still the version you want to commit? Can a core devel, then, give 
this patch a deeper look?br/blockquote/divbrI will review this again in 
a couple of days and will commit.br

br/div
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Terry J. Reedy]

Changes by Terry J. Reedy tjre...@udel.edu:


Removed file: http://bugs.python.org/file21890/unnamed

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Georg Brandl]

Georg Brandl ge...@python.org 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

Georg,

Good catch on the tuples in assertAlmostEqual, thanks! I see three methods of 
resolution:

1. Since the floats in this case are powers of 1/2, they could be tested for 
exact equality, or do you figure there are platforms where this is not 
guaranteed?
2. I can make a local change in the test to assertAlmostEqual on each member of 
the tuple
3. assertAlmostEqual on tuples can be added to the unittest module

Any ideas?

I can also commit (2) for the time being since it's the least dubious, and 
leave the resolution on 1  3 for later (and/or in separate issues).

Regarding fcmp being not exactly assertAlmostEqual - it was discussed.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Georg Brandl]

Georg Brandl ge...@python.org 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

Attaching a revised patch with (2) implemented.

--
Added file: http://bugs.python.org/file20885/issue11015.py3k.remove_fcmp.2.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Georg Brandl]

Georg Brandl ge...@python.org added the comment:

Yes, that looks good now.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

 Georg Brandl ge...@python.org added the comment:

 Yes, that looks good now.


Thanks. fcmp  FUZZ removal committed in revision 88558

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

Following the python-dev discussion, attaching a patch for removing fcmp and 
replacing its uses with assertAlmostEqual when needed.

All tests pass and patchcheck is clean.

Please review before I commit.

--
nosy: +terry.reedy
Added file: http://bugs.python.org/file20884/issue11015.py3k.remove_fcmp.1.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Giampaolo Rodola']

Changes by Giampaolo Rodola' g.rod...@gmail.com:


--
nosy: +giampaolo.rodola

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Nick Coghlan]

Nick Coghlan ncogh...@gmail.com added the comment:

verbose isn't a boolean at all - it's an integer. You can supply it multiple 
times to bump the logging level up even higher than normal.

~/devel/py3k/Lib/test$ grep verbose  *.py
regrtest.py:if self.verbose  1:
test_cmd_line_script.py:if verbose  1:
test_cmd_line_script.py:if verbose  1:
test_cmd_line_script.py:if verbose  1:
test_cmd_line_script.py:if verbose  1:
test_cmd_line_script.py:if verbose  1:
test_fork1.py:if verbose  1:
test_fork1.py:if verbose  1:

(I didn't check explicitly, but I believe those verbose values are shorthand 
references to test.support.verbose)

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Changes by Eli Bendersky eli...@gmail.com:


Removed file: http://bugs.python.org/file20564/issue11015.py3k.1.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Changes by Eli Bendersky eli...@gmail.com:


--
nosy: +eli.bendersky

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com added the comment:

Here's a patch fixing the 0/1 to True/False in a couple of places in 
test.support and test.regrtest

I ran the test suite and it passes.

A review is needed to commit. I'll keep working on the documentation itself in 
the meantime.

--
keywords: +patch
Added file: http://bugs.python.org/file20564/issue11015.py3k.1.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Eli Bendersky]

Eli Bendersky eli...@gmail.com 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 rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11015] Bring test.support docs up to date

[Nick Coghlan]

New submission from Nick Coghlan ncogh...@gmail.com:

The test.support docs are there to help CPython devs with writing good unit 
tests more easily. There are a few additions we've made in recent years that 
haven't made it into the .rst file, so it is easy to miss useful tools if you 
don't go looking through the module source code.

There are some other helper modules (such as test.script_helper) that could 
also stand to be made easier to find.

Fixing this is just a matter of doing a pass through test.support and the test 
directory looking for things that might be worth mentioning in the test package 
docs.

--
assignee: docs@python
keywords: easy
messages: 127086
nosy: docs@python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: Bring test.support docs up to date
type: behavior

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11015
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com