@akulakov Thank you for your review!

If anything, I'd say maybe change the function signature back to what it originally (.. function:: wrap(text, width=70, **kwargs)), and keep the links. With that many arguments, the function signature kind of looks like spaghetti and I think that the browsing experience is much stronger with the links.

A couple of thoughts:

I haven't seen instances in Python docs where a list of the same links would be duplicated multiple times closely, so I feel like that doesn't match this pattern of avoiding too much repetition.

An option that "splits the difference" would be to have the list of links for the first function and omit lists for the other two. I think either this option or not having links at all would work well.

I saw a very similar example in current docs: https://docs.python.org/3.11/library/logging.html#logging.LoggerAdapter -- the methods are from a different class but are linked here, in one paragraph rather than separate lines. Seems like a good approach, WDYT?

@akulakov that seems like a good precedent to follow. See 1306f2d; what do you think?

@akulakov that seems like a good precedent to follow. See 1306f2d; what do you think?

Looks good, thanks!

The few lines with inline links in the logging example look better than the list of raw names in the screenshot here, though.

@merwok yep, the screenshot is outdated. We went with the list of inline links.

@jdevries3133 btw Serhiy also left a few requests for change above (not sure if you saw them).

One interesting question that I've just thought about is whether **kwargs should be included in the sigs of 3 functions. The sigs don't follow the code exactly, that's the point of this PR. The users are meant to follow the signature and use the args listed there. **kwargs is not to be used by them.

So the argument is that having **kwargs in the sig will probably only add confusion; the only utility may conceivably be that user is alerted to the idea that if they accidentally use an arg from a different function (out of these 3), it will not raise a TypeError.

So it seems **kwargs is just a remnant from the old, intentionally empty sig. Thoughts?

The users are meant to follow the signature and use the args listed there. **kwargs is not to be used by them.

I don’t really understand what you mean here, maybe because **kwargs means two different things in function definitions and function calls.
The textwrap functions are defined with varkwargs, but not any param is accepted, only ones valid for TextWrap.
As for calling, users can certainly use kwargs unpacking, if they have a dict of valid params on hand.

The users are meant to follow the signature and use the args listed there. **kwargs is not to be used by them.

I don’t really understand what you mean here, maybe because **kwargs means two different things in function definitions and function calls.
The textwrap functions are defined with varkwargs, but not any param is accepted, only ones valid for TextWrap.
As for calling, users can certainly use kwargs unpacking, if they have a dict of valid params on hand.

I meant to say that in this particular case, **kwargs would imply to a user that they can use some other kwargs in addition to ones explicitly listed. But if they did that, they would either get a TypeError from TextWrapper, or in case of one of the functions, the kwargs they might use would be a no-op, and so should not be used.

@akulakov @merwok @serhiy-storchaka @iritkatriel I went ahead and reverted any changes other than those to the documented function signature. I think that changes to the function signature are the closest to the bpo, and make the most sense to add. I think that Irit made good points about the redundant links introducing a maintainability problem and not providing a significant enough usability improvement.

Andrei, I agree that documenting **kwargs is not necessary. The kwargs are always forwarded immediately to the TextWrap constructor, which does not accept arbitrary arguments:

def __init__(self,
             width=70,
             initial_indent="",
             subsequent_indent="",
             expand_tabs=True,
             replace_whitespace=True,
             fix_sentence_endings=False,
             break_long_words=True,
             drop_whitespace=True,
             break_on_hyphens=True,
             tabsize=8,
             *,
             max_lines=None,
             placeholder=' [...]'):

So, you get what you would expect from a misspelled keyword argument:

>>> import textwrap
>>> textwrap.wrap('hi', widt=10)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/johndevries/.pyenv/versions/3.9.6/lib/python3.9/textwrap.py", line
378, in wrap
    w = TextWrapper(width=width, **kwargs)
TypeError: __init__() got an unexpected keyword argument 'widt'

I had this wrong in earlier revisions of this PR, but I (mostly) fixed it in 2927e0d; "fix: incorrect information; TextWrapper.init will raise Exc," and later removed all non-function-signature changes as I mentioned above.

Summary

• I reverted all changes other than those to documented function signatures
• Documented function signatures do not include **kwargs; rationale above.
• I agree with Éric that the repetitive phrase, `width defaults to ``70``` currently on line 31 should be removed, but it's out of the scope of this bpo. See bpo-44763: [doc] remove repetitive sentence from textwrap.wrap #27423 and bpo-44763.

Thanks @jdevries3133 for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.9.
🐍🍒⛏🤖

GH-27424 is a backport of this pull request to the 3.10 branch.

GH-27425 is a backport of this pull request to the 3.9 branch.