`shlex.join`'s docstring isn't sufficiently clear

[BenFrantzDale]

Documentation

I had been using " ".join(shlex.escape(x) for x in args), not realizing that shlex.join(args) is exactly that.

The docstring is just """Return a shell-escaped string from *split_command*.""". I'd like to see something like

    """
    Return a shell-escaped string from *split_command*.
    That is, given a list of strings, return a string that, when printed,
    can be copy-pasted into a shell and provide an argc of len(split_command).
    
    For example:
    >>> print(shlex.join(['echo', 'foo \"bar\" baz']))
    echo 'foo "bar" baz'
    >>>
    $ echo 'foo "bar" baz'
    foo "bar" baz
    $
    """

Linked PRs

• gh-142895: Improve shlex.join documentation #142914
• gh-142895: Improve shlex.join docstring #144441

[picnixz]

Are the online docs inaccurate? I prefer updating the online docs rather than the docstring. Docstrings are usually shorter and less complete than online docs.

[BenFrantzDale]

As a user, I go to the docstrings. I didn't know there was separate documentation. (I feel like numpy has most of its docs in docstrings...)

[picnixz]

NumPy does have many of its docs at the code level, and while we do also have some at the code level, we try to reduce the size of docstrings for the sake of maintenance purposes. Examples are usually included online as well. I am going to close this one (I totally forgot about it), sorry.