New submission from Cheryl Sabella <>:

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.

PGO -  value? True/False?
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 

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 

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

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 

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

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 rather of test_logging.

assert_python_ok(*args, **env_vars) - Since this is a keyword argument name, it 
should be formatter as *__cleanenv*.

assignee: docs@python
components: Documentation
messages: 312170
nosy: csabella, docs@python, ncoghlan, serhiy.storchaka, terry.reedy
priority: normal
severity: normal
status: open
title: More revisions to docs
type: enhancement
versions: Python 3.8

Python tracker <>
Python-bugs-list mailing list

Reply via email to