Undocumented Cmd method print_topics

[ivansantiagojr]

Documentation

When exploring the Cmd Python library, I realized that there is no documentation for print_topics method.

I only realized the missing documentation because I noticed that print_topics method has an unused parameter called cmdlen, and I couldn't figure out if it is actually useful for something.
I could also notice that on typeshed it is typed as Any, even though it seems to be only used as an int.

Extra doubts:

Maybe print_topics should be renamed to _print_topics or we should document how to use it properly?
Also, is that cmdlen parameter really needed?

I am willing to contribute with that, but I don't know which type of issue I should open to report an unused param.

Links:

• Cmd documentation: https://docs.python.org/3.13/library/cmd.html
• Cdm.print_topics definition: https://github.com/python/cpython/blob/main/Lib/cmd.py#L346
• typeshed: https://github.com/python/typeshed/blob/main/stdlib/cmd.pyi#L45

Linked PRs

• gh-128430: Add docstring for cmd.Cmd.do_topics #134539

[catherinedevlin]

Thank you. Agreed that, in hindsight, .print_topics should be ._print_topics, and the unused argument cmdlen should be omitted.

But it's difficult to be confident that nobody, anywhere, has made use of .print_topics in their cmd-based applications; and, for that matter, that nobody, anywhere, has relied on maxcol being the 4th argument to .print_topics, such that we would break it if we removed cmdlen.

Any potential break of dependent code, even if unlikely, calls out for discussion... so for now, a simple documentation-only PR would resolve this ticket. Perhaps create a second ticket for the (slightly) breaking suggestion of renaming .print_topics and dropping .cmdlen?

FWIW cmd2 re-implements .print_topics in its current form. https://github.com/python-cmd2/cmd2/blob/4788e2db86ff77123968ff2b4dbfdf5ca1e2859b/cmd2/cmd2.py#L3862