classification
Title: subprocess docs should mention pipes.quote/shlex.quote
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, cvrebert, docs@python, eric.araujo, ezio.melotti, python-dev, sandro.tosi, tshepang
Priority: normal Keywords: patch

Created on 2012-04-18 17:12 by eric.araujo, last changed 2013-05-28 18:28 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
subprocess.rst-2.7.patch cvrebert, 2012-09-15 19:53 patch against 2.7; mentions pipes.quote review
subprocess.rst-default.diff cvrebert, 2012-10-28 08:33 patch against default branch; only mention shlex.quote() review
pipes.rst.diff cvrebert, 2012-10-28 09:10 document pipes.quote() in 2.7 review
Messages (15)
msg158641 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-04-18 17:12
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).
msg160586 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-05-14 00:14
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.
msg162570 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-06-10 01:23
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!
msg162571 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-06-10 01:23
Please also take my note about pipes.quote in my OP into account.
msg170528 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-09-15 19:54
Updated patches to mention pipes.quote().
msg170611 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-09-17 14:20
You thought it was better not to mention that pipes.quote is semi-official and becomes public as shlex.quote in 3.3?
msg173740 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-10-25 07:28
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?
msg173759 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-10-25 13:51
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.
msg173777 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-25 17:44
> 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+.
msg174011 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-10-28 08:33
Here's a revised patch against the default branch (3.4 I presume?).
msg174014 - (view) Author: Chris Rebert (cvrebert) * Date: 2012-10-28 09:10
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)
msg174018 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-10-28 09:43
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
msg174019 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-10-28 09:48
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
msg174020 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-10-28 09:49
I have applied all patches. Thanks, Chris.
msg190234 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-05-28 18:28
> .. deprecated:: 1.6

This looks weird to me.
History
Date User Action Args
2013-05-28 18:28:56eric.araujosetmessages: + msg190234
2012-10-28 09:49:29asvetlovsetstatus: open -> closed
type: enhancement
messages: + msg174020

resolution: fixed
stage: resolved
2012-10-28 09:48:14python-devsetmessages: + msg174019
2012-10-28 09:43:14python-devsetnosy: + python-dev
messages: + msg174018
2012-10-28 09:10:30cvrebertsetfiles: + pipes.rst.diff

messages: + msg174014
versions: + Python 3.4, Python 3.5
2012-10-28 09:04:15cvrebertsetfiles: - subprocess.rst-3.3.patch
2012-10-28 08:33:24cvrebertsetfiles: + subprocess.rst-default.diff

messages: + msg174011
2012-10-25 17:44:08ezio.melottisetnosy: + ezio.melotti
messages: + msg173777
2012-10-25 13:51:29asvetlovsetnosy: + asvetlov
messages: + msg173759
2012-10-25 07:28:10cvrebertsetmessages: + msg173740
2012-09-17 14:20:18eric.araujosetmessages: + msg170611
2012-09-15 19:54:51cvrebertsetfiles: - subprocess_shlex_quote.patch
2012-09-15 19:54:42cvrebertsetfiles: + subprocess.rst-3.3.patch

messages: + msg170528
2012-09-15 19:53:41cvrebertsetfiles: + subprocess.rst-2.7.patch
2012-06-10 01:23:46eric.araujosetmessages: + msg162571
2012-06-10 01:23:02eric.araujosetnosy: + sandro.tosi
messages: + msg162570
2012-05-14 00:14:12cvrebertsetfiles: + subprocess_shlex_quote.patch
keywords: + patch
messages: + msg160586
2012-04-23 12:30:42cvrebertsetnosy: + cvrebert
2012-04-23 08:41:24tshepangsetnosy: + tshepang
2012-04-18 17:12:37eric.araujocreate