Missing references to cli flags for `pickletools`

[donbarbos]

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

Linked PRs

• gh-130973: Add missing options at doc for pickletools #130974

[picnixz]

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]

Note: even if they are available through -h/--help I don't think we want to document them explicitly

[picnixz]

cc @serhiy-storchaka wdyt?

[alex-semenyuk]

imho don't see something bad to have consistency between -help and doc. any reason against this?

[picnixz]

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]

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]

@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 (-t and -v), right?

P.S.: I also want to remove similar flags for pickle but running tests test_pickle.py gives a lot of errors (i run it like ./python ./Lib/test/test_pickle.py and 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 in pickle module

[picnixz]

as far as i understand i can send a PR for issue #93096 to get rid of such flags (-t and -v), right?

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