This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: cmd module should sort misc help topics
Type: enhancement Stage: test needed
Components: Library (Lib) Versions: Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: samwyse, terry.reedy
Priority: normal Keywords:

Created on 2014-12-15 21:02 by samwyse, last changed 2022-04-11 14:58 by admin.

Messages (2)
msg232680 - (view) Author: Samwyse (samwyse) * Date: 2014-12-15 21:02
I've discovered that do_help method of cmd.Cmd prints the documented and undocumented commands in sorted order, but does not sort the miscellaneous topics.  This would be an easy fix, just change "self.print_topics(self.misc_header, help.keys(),15,80)" to use "sorted(help.keys())".
msg232948 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-12-19 21:45
cmd.Cmd has a documented do_help(self, arg) method (written in 2000).  If arg is '', it prints
1. Documented commands (do_x with help_x or do_x.__doc__ != ''), sorted
2. Other help topics (help_y with no do_y), unsorted
3. Undocumented commands (do_ without no help_x and no do_x.__doc__), sorted

The dict called 'help' (which should be a set, and might better be called 'topics') ends up with a member for each help_y topic without a do_y command.  Not sorting the keys is at least a design bug.  Leaving users aside, it makes do_help unpredictable and hard to test.  Our test.test_cmd omits misc help topics.  In verbose mode, it prints

Trying:
    mycmd.do_help("")
Expecting:
    <BLANKLINE>
    Documented commands (type help <topic>):
    ========================================
    add  help
    <BLANKLINE>
    Undocumented commands:
    ======================
    exit  shell
    <BLANKLINE>
ok

As near as I can tell, text_cmd would still pass if Misc topics were removed and never printed.  Topics can only be added to the test above is they are dependably ordered (ie, sorted).

---
This '?' or 'help' case is also not properly documented, but should be.  3.4 cmd.__doc__ has this mishmash:

"With no arguments, it lists all topics with defined help_ functions, broken into up to three topics; documented commands, miscellaneous help topics, and undocumented commands."

3.4 doc says "With no argument, do_help() lists all available help topics (that is, all commands with corresponding help_*() methods or commands that have docstrings), and also lists any undocumented commands."
History
Date User Action Args
2022-04-11 14:58:11adminsetgithub: 67248
2014-12-19 21:45:41terry.reedysetnosy: + terry.reedy
messages: + msg232948

type: enhancement
stage: test needed
2014-12-16 02:36:52samwysesettitle: sort misc help topics in cmd -> cmd module should sort misc help topics
2014-12-15 21:02:49samwysecreate