gh-131524: Update platform CLI to use argparse

[Harry-Lees]

Closes: #131524
Related To: #131178

This PR updates the platform CLI to use argparse which adds --help flags and a usage section which was previously unavailable.

• Issue: Improve platform CLI #131524

[sobolevn]

And don't forget about a NEWS entry :)

[hugovk]

We now have help which shows the arguments:

❯ ./python.exe -m platform -h
usage: python.exe -m platform [-h] [--terse] [--nonaliased] [{nonaliased,terse} ...]

positional arguments:
  {nonaliased,terse}

options:
  -h, --help          show this help message and exit
  --terse
  --nonaliased

But doesn't say what they do. Please can you add short descriptions?

[Harry-Lees]

But doesn't say what they do. Please can you add short descriptions?

The help message now gives a short description of each flag

usage: python.exe -m platform [-h] [--terse] [--nonaliased] [{nonaliased,terse} ...]

positional arguments:
  {nonaliased,terse}

options:
  -h, --help          show this help message and exit
  --terse             return only the absolute minimum information needed to identify the platform
  --nonaliased        disable system/ OS name aliasing. If aliasing is enabled, some platforms will report system names which differ from their common names, e.g. SunOS will be reported
                      as Solaris

[picnixz]

Suggested change

	def _parse_args(args: list[str] | None):
	import argparse
	parser = argparse.ArgumentParser()
	parser.add_argument("args", nargs="*", choices=["nonaliased", "terse"])
	parser.add_argument(
	"--terse",
	action="store_true",
	help=("return only the absolute minimum information needed to identify the "
	"platform"),
	)
	parser.add_argument(
	"--nonaliased",
	dest="aliased",
	action="store_false",
	help=("disable system/ OS name aliasing. If aliasing is enabled, some "
	"platforms will report system names which differ from their common "
	"names, e.g. SunOS will be reported as Solaris"),
	)
	return parser.parse_args(args)
	def _main(args: list[str] | None = None):
	args = _parse_args(args)
	def _make_parser():
	import argparse
	parser = argparse.ArgumentParser()
	parser.add_argument("args", nargs="*", choices=["nonaliased", "terse"])
	parser.add_argument(
	"--terse",
	action="store_true",
	help=("return only the absolute minimum information needed "
	"to identify platform"),
	)
	parser.add_argument(
	"--nonaliased",
	dest="aliased",
	action="store_false",
	help=("disable system/OS name aliasing. If aliasing is enabled, "
	"some platforms will report system names which differ from "
	"their common names, e.g., SunOS is reported as Solaris"),
	)
	return parser
	def _main(args=None):
	parser = _make_parser()
	args = parser.parse(args)

[hugovk]

Delete the space after the slash "system/ OS" -> "system/OS".

And this help is very long, can we make it shorter?

[picnixz]

I think so, but I just suggested to actually decouple the parsing from the creation of the argument parser (and reflowed the strings).

[Harry-Lees]

And this help is very long, can we make it shorter?

I did think this while I was writing it, the second part is an excerpt from the platform.platform docs.

Just "disable system/OS name aliasing" was confusing to me, so I wanted to add some more information. The CLI itself is obviously just an interface for platform.platform(), I'm not sure if its appropriate to have the CLI say something like "See platform.platform docs for more information" or if theres any precedent for that in other modules.

I looked around some of the other CLI tools for similar help commands. Several other tools such as compileall, doctest, random, and trace have quite long help commands for arguments. In my opinion, I'd prefer a more descriptive than terse help message.

[Harry-Lees]

I just suggested to actually decouple the parsing from the creation of the argument parser

Do you mind if I ask what the reasoning behind this suggestion is? I'm happy to many any suggested refactors to the PR, this is not my codebase :D, but I haven't seen this pattern used anywhere, and quite a few of the other cPython CLI modules use the _main() and _parse_args() pattern. Are there any benefits to separating the stages like this?

I'll update the help message formatting though, I do think it reads nicer in your example :).

[hugovk]

I also prefer to use separate _main() and _parse_args(), it makes it easier to test separate parts of the CLI, following the example of https://pythontest.com/testing-argparse-apps/

And it will ease maintenance to use a similar pattern in different modules in this codebase.