Misaligned columns in help('topics') due to the length of "ASSIGNMENTEXPRESSIONS"

[EtiennePelletier]

Documentation

Description

The pydoc.Helper.list function currently uses default values of 80 characters per line and 4 columns. This provides an implicit maximum length of 19 characters per item to ensure columns are aligned properly (the item length is not verified within the function).

Historically, the longest values were _testimportmultiple from help('module') and AUGMENTEDASSIGNMENT from help('topics'), both with a length of 19 characters.

The recent addition of "ASSIGNMENTEXPRESSIONS" (21 characters) in PR 124641 causes misaligned columns with these default values. As seen in Python 3.13.0:

>>> help('topics')

Here is a list of available topics.  Enter any topic name to get more help.

ASSERTION           DEBUGGING           LITERALS            SEQUENCES
ASSIGNMENT          DELETION            LOOPING             SHIFTING
ASSIGNMENTEXPRESSIONS DICTIONARIES        MAPPINGMETHODS      SLICINGS
ATTRIBUTEMETHODS    DICTIONARYLITERALS  MAPPINGS            SPECIALATTRIBUTES
ATTRIBUTES          DYNAMICFEATURES     METHODS             SPECIALIDENTIFIERS
...

Impact

This misalignment affects the readability of the output, making it a bit more difficult to quickly scan through it.

Proposed Solutions

I see two simple options to address this issue, but I’m open to any other suggestions as well:

1. Increase the line width to 88 characters:
   To preserve the default four columns, a minimum width of 88 characters would be required to ensure each item, including "ASSIGNMENTEXPRESSIONS", fits within its column:

   ASSERTION             DEBUGGING             LITERALS              SEQUENCES
   ASSIGNMENT            DELETION              LOOPING               SHIFTING
   ASSIGNMENTEXPRESSIONS DICTIONARIES          MAPPINGMETHODS        SLICINGS
   ATTRIBUTEMETHODS      DICTIONARYLITERALS    MAPPINGS              SPECIALATTRIBUTES
   ATTRIBUTES            DYNAMICFEATURES       METHODS               SPECIALIDENTIFIERS
   ...
   

2. Reduce the number of columns to 3 (Recommendation):
   Reducing the column count to 3 when listing topics would provide enough space for longer topic names (up to 25 characters). This solution is preferred for compatibility with many terminals that default to 80 characters per line:

   ASSERTION                 EXCEPTIONS                PACKAGES
   ASSIGNMENT                EXECUTION                 POWER
   ASSIGNMENTEXPRESSIONS     EXPRESSIONS               PRECEDENCE
   ATTRIBUTEMETHODS          FLOAT                     PRIVATENAMES
   ATTRIBUTES                FORMATTING                RETURNING
   ...
   

🙂

Linked PRs

• gh-125225 Fix column misalignment in help('topics') output #125226
• [3.14] gh-125225: Fix column misalignment in help('topics') output (gh-125226) #134225
• [3.13] gh-125225: Fix column misalignment in help('topics') output (gh-125226) #134226

[zware]

I'm in favor of your option 2. Are you interested in submitting a pull request?