classification
Title: More revisions to test.support docs
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, ncoghlan, serhiy.storchaka, terry.reedy
Priority: normal Keywords: patch

Created on 2018-02-14 11:18 by cheryl.sabella, last changed 2018-02-21 01:22 by ncoghlan.

Pull Requests
URL Status Linked Edit
PR 5774 open cheryl.sabella, 2018-02-20 16:19
Messages (3)
msg312170 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-14 11:18
Serhiy had made the following comments on the pull request for issue11015, but that PR was merged before applying his requested changes.  This issue is to address his concerns.


TESTFN_NONASCII - How different from TESTFN_UNICODE?
PGO -  value? True/False?
TEST_SUPPORT_DIR - Not used.
max_memuse - Not used.
MISSING_C_DOCSTRINGS - Remove `Return` since it's a constant.
HAVE_DOCSTRINGS - Remove `Check` since it's a constant.

Possibly group the next 3 to avoid repetition:
unlink(filename) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).
rmdir(filename) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).
rmtree(path) - Add an explanation why this is needed (due to antiviruses that can hold files open and prevent thy deletion).

make_legacy_pyc(source) - Add markup references to PEPs.
system_must_validate_cert(f) - This is a decorator and change text to "Skip the test on TLS certificate validation failures.".

match_test(test) and set_match_tests(patterns) - Used internally to regrtest.  Remove or ask Victor to document as the current documentation is useless.

check_impl_detail(**guards) - Document that a boolean is returned and check the docstring to include more information.

get_original_stdout - Add ().

strip_python_strerr(stderr) - Typo `strip_python_stderr` and make it clear that *stderr* is a byte string.

disable_faulthandler() - Wrong description.

disable_gc() - Add that it works only if it was enabled.

start_threads(threads, unlock=None) - Document that *threads* is a sequence of threads and document what unlock is.

calcobjsize(fmt) - Add the purpose of this - calcobjsize() returns the size of Python object (PyObject) whose structure is defined by fmt with account of Python object header.
calcvobjsize(fmt) - Same as above for PyVarObject.

requires_freebsd_version(*min_version) - Change to skip the test instead of Raise.

cpython_only(test) - Remove argument.
no_tracing(func) - Remove argument.
refcount_test(test) - Remove argument.
reap_threads(func) - Remove argument.
bigaddrspacetest(f) - Remove argument.

import_module(name, deprecated=False, *, required_on()) - Missed =

check_free_after_iterating(test, iter, cls, args=()) - This description is misleading. This function doesn't test iter. iter is either iter or reversed, cls is a base iterable class, args are arguments for its constructor. The true description is too complex, I suggest to remove this function from the documentation.

missing_compiler_executable(cmd_names=[]) - It is used only in distutils tests and should be in distutils.tests.support.

CleanImport(*module_names) - Format DeprecationWarning as a link.

DirsOnSysPath(*paths) - Format first sys.path as a link, Keeps the first one (in the above sentence) and format other mentions as ``sys.path`` or :data:`!sys.path`.

SaveSignals() - How to use it?

Matcher() - This class is used only in test_logging, and only with TestHandler. These classes should be documented together and with references to logging. I'm not sure they should be in test.support.

BasicTestRunner() - This is an internal class used for implementing run_unittest(). No need to expose it.

TestHandler(logging.handlers.BufferingHandler) - I'm not sure it should be in test.support rather of test_logging.

assert_python_ok(*args, **env_vars) - Since this is a keyword argument name, it should be formatter as *__cleanenv*.
msg312420 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-02-20 16:22
I've made the changes requested.  I wasn't sure about:

TESTFN_NONASCII - How different from TESTFN_UNICODE?


Should I move these out of test.support?:
missing_compiler_executable(cmd_names=[]) - It is used only in distutils tests and should be in distutils.tests.support.
Matcher() - This class is used only in test_logging, and only with TestHandler. These classes should be documented together and with references to logging. I'm not sure they should be in test.support.
TestHandler(logging.handlers.BufferingHandler) - I'm not sure it should be in test.support rather of test_logging.

Thanks!
msg312450 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-02-21 01:22
For TESTFN_NONASCII vs TESTFN_UNICODE (inferred from reading the current code & https://github.com/python/cpython/commit/8b219b2936d767bf6c6c17618db3a7b22fc2e865):

* TESTFN_NONASCII guarantees that it can be encoded and decoded with the default filesystem encoding, but may be None if it can't find a suitable non-ASCII character that meets that constraint. This allows affected tests to be easily skipped on platforms where they can't work.
* TESTFN_UNICODE is always set, but may *not* be encodable with os.fsencode()

(The two could potentially be consolidated by converting the tests that use TESTFN_UNICODE over to TESTFN_NONASCII, but for now it makes sense to just document the above differences)

For the logging helpers, I'd check how they're used in test_logging: if they're used in logging configuration tests, they may be in test.support to avoid reimporting the module that defines the logging tests. If so, then they can be filed away in their own subsection at the end of the test.support documentation. If not, then yeah, moving them into test_logging would make sense.

Similarly, moving the distutils helper makes sense to me, *unless* there's a specific reason that importing it from "distutils.tests.support" instead would be problematic.
History
Date User Action Args
2018-02-22 23:06:31cheryl.sabellalinkissue19412 superseder
2018-02-21 01:22:34ncoghlansetmessages: + msg312450
2018-02-20 16:22:30cheryl.sabellasetstage: patch review
2018-02-20 16:22:12cheryl.sabellasetmessages: + msg312420
stage: patch review -> (no value)
2018-02-20 16:19:30cheryl.sabellasetkeywords: + patch
stage: patch review
pull_requests: + pull_request5553
2018-02-14 11:18:06cheryl.sabellacreate