[issue14616] subprocess docs should mention pipes.quote/shlex.quote
New submission from Éric Araujo <merwok@netwok.org>: 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). ---------- assignee: docs@python components: Documentation messages: 158641 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: subprocess docs should mention pipes.quote/shlex.quote versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: ---------- nosy: +cvrebert _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Chris Rebert <pybugs@rebertia.com> added the comment: 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. ---------- keywords: +patch Added file: http://bugs.python.org/file25570/subprocess_shlex_quote.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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! ---------- nosy: +sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Please also take my note about pipes.quote in my OP into account. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Added file: http://bugs.python.org/file27196/subprocess.rst-2.7.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Chris Rebert added the comment: Updated patches to mention pipes.quote(). ---------- Added file: http://bugs.python.org/file27197/subprocess.rst-3.3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file25570/subprocess_shlex_quote.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Éric Araujo added the comment: You thought it was better not to mention that pipes.quote is semi-official and becomes public as shlex.quote in 3.3? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Chris Rebert added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Andrew Svetlov added the comment: 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. ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Ezio Melotti added the comment:
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+. ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Chris Rebert added the comment: Here's a revised patch against the default branch (3.4 I presume?). ---------- Added file: http://bugs.python.org/file27760/subprocess.rst-default.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: Removed file: http://bugs.python.org/file27197/subprocess.rst-3.3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Chris Rebert added the comment: 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) ---------- versions: +Python 3.4, Python 3.5 Added file: http://bugs.python.org/file27761/pipes.rst.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Andrew Svetlov added the comment: I have applied all patches. Thanks, Chris. ---------- resolution: -> fixed stage: -> committed/rejected status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
Éric Araujo added the comment:
.. deprecated:: 1.6
This looks weird to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14616> _______________________________________
participants (6)
-
Andrew Svetlov -
Chris Rebert
-
Ezio Melotti
-
Roundup Robot
-
Tshepang Lekhonkhobe
-
Éric Araujo