The warning at http://docs.python.org/library/subprocess#frequently-used-arguments should IMO recommend using shlex.quote.  Even if it strongly advises against using shell=True, there are people who need or want to use it, so let’s give them a pointer to the quote function.

For older versions, I think we should talk about pipes.quote; even if it’s not documented in library/pipes, it is there, it is known and it is used, so I see no harm in mentioning it (with due mention that it’s only semi-official and that it becomes public in 3.3).

Patch to mention shlex.quote() in the `subprocess` module's "Frequently Used Arguments" Warning box. Could perhaps be a separate Note, but that could be clutter-y.

Text LGTM; I haven’t looked at the position in the doc file though.  Sandro, once again I’m adding you to nosy in the hope that you’ll have time to make a review and maybe a commit, with my thanks!

Please also take my note about pipes.quote in my OP into account.

Updated patches to mention pipes.quote().

You thought it was better not to mention that pipes.quote is semi-official and becomes public as shlex.quote in 3.3?

No, the thought merely did not occur to me. I don't recall having seen such forward-looking notes in Python's documentation before.

Should the pipes.quote() mention be axed from the 3.x patch?

I think patch for 3.3 should mention only shlex.quote.
I don't care about 2.7 patch but it looks good to me.

> I think patch for 3.3 should mention only shlex.quote.

+1

I'm not sure what's the best thing to do about pipes.quote.  Pointing to an undocumented function that is available in 3.3 in a different module doesn't sound like a really good idea.
Maybe we could document pipes.quote as an internal/deprecated function so that people that follow the link from the subprocess docs will be aware that the function is available under a different name in 3.3+.
Otherwise we could just document shlex.quote() in 3.3+.

Here's a revised patch against the default branch (3.4 I presume?).

Just to keep the ball rolling, in case it ends up being the solution ultimately chosen, here is a patch against 2.7 to document pipes.quote(). The text is yanked straight from shlex.quote(), the differences being:
- qualify shlex.split() references
- print function -> print statement
- add deprecation note (currently backdated to when `pipes` was added to the std lib; mentions what happens in 3.3)

New changeset f9d11ca3ccd1 by Andrew Svetlov in branch '3.3':
Issue #14616: Mention shlex.quote in subprocess docs.
http://hg.python.org/cpython/rev/f9d11ca3ccd1

New changeset 72672cf5d850 by Andrew Svetlov in branch 'default':
Merge issue #14616: Mention shlex.quote in subprocess docs.
http://hg.python.org/cpython/rev/72672cf5d850

New changeset d9ca966cd116 by Andrew Svetlov in branch '2.7':
Issue #14616: Document pipes.quote and mention this one in subprocess docs.
http://hg.python.org/cpython/rev/d9ca966cd116

I have applied all patches. Thanks, Chris.

> .. deprecated:: 1.6

This looks weird to me.