Repository navigation
Argument Clinic: Enforce summary line length #137623
Description
Feature or enhancement
Proposal:
Argument Clinic currently requires that a summary line exists, but places no further restrictions on the content.
There are 32 instances of a docstring over 100 characters long, with the longest at 148 characters (_sre.SRE_Pattern.subn / re.Pattern.subn). Long lines like this become hard to read, for example in help or pydoc output.
I propose that we start enforcing a maximum length of 80 characters for new docstrings, but use a whitelist so that we don't need to change existing overly long docstrings (for now).
A
cc @erlend-aasland @serhiy-storchaka
Has this already been discussed elsewhere?
This is a minor feature, which does not need previous discussion elsewhere
Links to previous discussion of this feature:
No response
Activity
serhiy-storchaka commentedon Aug 11, 2025
PEP 8 requires limiting docstring lines to 72 characters.
pydocadds 8 characters for functions and classes, so the total length is 80. It adds 12 characters for methods, so the limit may be 68 for them.terryjreedy commentedon Aug 11, 2025
I believe that there are docstrings with a 2-line summary, perhaps in idlelib, but at least they display correctly.
I would be willing to help revise existing long lines in a followup.
AA-Turner commentedon Aug 11, 2025
I've updated the PR to make the maximum lenth 72 characters, per PEP 8. Going to 68 characters is a further ~6% reduction, and goes beyond the strictures of PEP 8, so I haven't implemented this suggestion. It might be worth considering using a two- or three- space indentation in
pydoc, but that would be a separate issue/discussion.A
serhiy-storchaka commentedon Aug 12, 2025
If follow PEP 8 literally, the limits should even be smaller.
PEP 8 limits the length of the source lines. In global functions, docstrings have a 4-spaces indentation, so the length of the docstring line is limited to 68 characters. In methods, docstrings have an 8-spaces indentation, so the length of the docstring line is limited to 64 characters. So all docstrings in Python code following PEP 8 should be more limited.
But this is for readability of Python code. We must ensure readability of the
pydocoutput -- so the limits are higher, 72 and 68 correspondingly.AA-Turner commentedon Aug 12, 2025
Good points, I've updated to use 68 for methods.
A
serhiy-storchaka commentedon Aug 12, 2025
Sorry, I somehow miscalculated (it was 6 am here).
pydocadds only 4 characters for global functions and classes and 8 characters for methods, so the limits should be 76 and 72.PEP 8 limits docstring line length in Python code, but this is not Python code.
GH-137623: Begin enforcing docstring length in Argument Clinic (#137624)
GH-137623: Use an AC decorator for docstring line length enforcement (#…
pythonGH-137623: Begin enforcing docstring length in Argument Clinic (p…
pythonGH-137623: Use an AC decorator for docstring line length enforc…
erlend-aasland commentedon Sep 18, 2025
Is there anything more left to do here?