More revisions to test.support docs

[csabella]

BPO	32843
Nosy	@terryjreedy, @ncoghlan, @serhiy-storchaka, @csabella
PRs	bpo-32843: Additional changes to test.support docs #5774

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-02-14.11:18:06.527>
labels = ['type-feature', '3.8', 'docs']
title = 'More revisions to test.support docs'
updated_at = <Date 2018-02-21.01:22:34.638>
user = 'https://github.com/csabella'

bugs.python.org fields:

activity = <Date 2018-02-21.01:22:34.638>
actor = 'ncoghlan'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-02-14.11:18:06.527>
creator = 'cheryl.sabella'
dependencies = []
files = []
hgrepos = []
issue_num = 32843
keywords = ['patch']
message_count = 3.0
messages = ['312170', '312420', '312450']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'ncoghlan', 'docs@python', 'serhiy.storchaka', 'cheryl.sabella']
pr_nums = ['5774']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32843'
versions = ['Python 3.8']

[csabella]

Serhiy had made the following comments on the pull request for bpo-11015, 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.

[csabella]

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!

[ncoghlan]

For TESTFN_NONASCII vs TESTFN_UNICODE (inferred from reading the current code & 8b219b2):

• 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.