Repository navigation
Missing references to cli flags for pickletools #130973
Description
Documentation
While looking for more examples for issue #130160 i found that the pickletools CLI documentation doesn't cover all the flags. I know many CLI docs don't mention the -h flag but this one also doesn't mention the -t and -v flags
./python -m pickletools -h output:
usage: python -m pickletools [-h] [-o OUTPUT] [-m] [-l INDENTLEVEL] [-a] [-p PREAMBLE] [-t] [-v] [pickle_file ...]
disassemble one or more pickle files
positional arguments:
pickle_file the pickle file
options:
-h, --help show this help message and exit
-o, --output OUTPUT the file where the output should be written
-m, --memo preserve memo between disassemblies
-l, --indentlevel INDENTLEVEL
the number of blanks by which to indent a new MARK level
-a, --annotate annotate each line with a short opcode description
-p, --preamble PREAMBLE
if more than one pickle file is specified, print this before each disassembly
-t, --test run self-test suite
-v run verbosely; only affects self-test run
Link to current documentation: https://docs.python.org/dev/library/pickletools.html
Activity
pythongh-130973: Add missing options at doc for pickletools
picnixz commentedon Mar 8, 2025
The t flag is probably something internal that we don't want to expose and the v flag then becomes also internal as it only affects self-tests.
picnixz commentedon Mar 8, 2025
Note: even if they are available through -h/--help I don't think we want to document them explicitly
picnixz commentedon Mar 8, 2025
cc @serhiy-storchaka wdyt?
alex-semenyuk commentedon Mar 8, 2025
imho don't see something bad to have consistency between -help and doc. any reason against this?
picnixz commentedon Mar 8, 2025
Yes, because it's something not meant for the enduser. It's only used for running self-tests so it's not really the purpose of the tool.
Ideally, I would rather move the self-testing into the regular test directory instead but self-testing is sometimes used by the module's maintainer if they don't want to run the entire test suite.
picnixz commentedon Mar 8, 2025
For instance, the only output that the enduser should expect from using -t is "SUCCESS" because otherwise something really went wrong when we released Python. So I don't think we need to document those two commands (IIRC there are other modules with this kind of self-testing and I don't think we actually documented them)
donbarbos commentedon Mar 10, 2025
@picnixz sorry, my bad. i was in a hurry to open this issue :(
as far as i understand i can send a PR for issue #93096 to get rid of such flags (
-tand-v), right?P.S.: I also want to remove similar flags for
picklebut running teststest_pickle.pygives a lot of errors (i run it like./python ./Lib/test/test_pickle.pyand get 24 failures tests).I would appreciate if you confirmed that the problem is not with me and I need to open an issue about crashing tests in
test_pickle. Judging by the output, the problem is in the mismatch error messages inpicklemodulepicnixz commentedon Mar 10, 2025
No, because as I'm not the maintainer of such module, I don't want to endorse such change without consulting with @serhiy-storchaka. Keeping the status quo is also fine (and we do not need to document the options).
serhiy-storchaka commentedon Mar 10, 2025
I can't remember using this option even once. Maybe other core developers used it, but it only runs corresponding doctests.
./python -m pickletools -t -vis equivalent to./python -m doctest Lib/pickletools.py -v. It only has advantage of not specifying the path to the module, that's all. Doctests should be included in unit tests run, and unit tests cover much more, so I do not see the need in keeping this feature.To make the change lossless, we can add the doctest CLI option to specify the module instead of the file path. I think there may already be an open issue for this.