Skip to content

patch to subprocess docs to better explain Popen's 'args' argument #51009

Closed

Description

@cvrebert
mannequin
BPO 6760
Nosy @birkenfeld, @terryjreedy, @ncoghlan, @pitrou, @ericvsmith, @benjaminp, @bitdancer, @briancurtin
Files
  • subprocess-doc.patch
  • subprocess-doc.patch
  • subprocess.rst.patch: tweak shell transcript
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = 'https://github.com/birkenfeld'
    closed_at = <Date 2010-02-04.16:49:42.301>
    created_at = <Date 2009-08-22.10:40:31.894>
    labels = ['type-feature', 'docs']
    title = "patch to subprocess docs to better explain Popen's 'args' argument"
    updated_at = <Date 2010-02-18.14:28:48.871>
    user = 'https://bugs.python.org/cvrebert'

    bugs.python.org fields:

    activity = <Date 2010-02-18.14:28:48.871>
    actor = 'christoph.neuroth'
    assignee = 'georg.brandl'
    closed = True
    closed_date = <Date 2010-02-04.16:49:42.301>
    closer = 'r.david.murray'
    components = ['Documentation']
    creation = <Date 2009-08-22.10:40:31.894>
    creator = 'cvrebert'
    dependencies = []
    files = ['16102', '16107', '16128']
    hgrepos = []
    issue_num = 6760
    keywords = ['patch', 'needs review']
    message_count = 33.0
    messages = ['91859', '92688', '93519', '98658', '98683', '98684', '98707', '98711', '98713', '98719', '98729', '98731', '98732', '98733', '98734', '98735', '98736', '98738', '98739', '98742', '98745', '98746', '98747', '98748', '98826', '98827', '98832', '98836', '98840', '98841', '98880', '98881', '99508']
    nosy_count = 10.0
    nosy_names = ['georg.brandl', 'terry.reedy', 'ncoghlan', 'pitrou', 'eric.smith', 'benjamin.peterson', 'r.david.murray', 'brian.curtin', 'cvrebert', 'christoph.neuroth']
    pr_nums = []
    priority = 'normal'
    resolution = 'accepted'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue6760'
    versions = ['Python 2.6', 'Python 3.1', 'Python 2.7', 'Python 3.2']

    Activity

    1. cvrebert commented on Aug 22, 2009

      cvrebertmannequin
      MannequinAuthor

      From what I've seen on several c.l.p threads, some people have a tough
      time figuring the correct 'args' argument to subprocess.Popen's
      constructor. In an effort to cut down on such discussions in the future,
      I've written the attached docs patch to better explain the subject.

      I'm not an rst/Sphinx guru and thus was unable to actually test the
      patch, so there might be some (hopefully minor) formatting errors.

    2. added
      docsDocumentation in the Doc dir
      type-featureA feature request or enhancement
      on Aug 22, 2009
    3. benjaminp commented on Sep 16, 2009

      @benjaminp
      Contributor

      We are trying to cut down on the number of "warning" directives in the
      docs; I think a "note" directive would be appropriate for yours.

    4. cvrebert commented on Oct 4, 2009

      cvrebertmannequin
      MannequinAuthor

      Ok, changed to "note" directives instead of "warning"s. Anything else
      that keeps this from being applied?

    5. pitrou commented on Feb 1, 2010

      @pitrou
      Member

      This is a particularly verbose patch for the information it is trying to convey.

    6. terryjreedy commented on Feb 1, 2010

      @terryjreedy
      Member

      The note starts out "Do not (do x) unless you're not (doing y)". This is confusing. I believe this means "If you are (doing y), you may (do x)". If so, please write it so. If not, please write what you do mean.

      After thinking about it, "Only (do x) if you are (doing y)" might be a better rewrite. Or "You may (do x) only if you are (doing y)"

      Change "be mindful of escaping" to the more direct "escape". Perhaps give a list of possible special characters.

      I agree that this seems a bit verbose for reference documentation. Perhaps there should be a separate PyWiki entry or HowTo doc. That could, for instance, list the special characters for various shells if they are not all the same.

    7. terryjreedy commented on Feb 1, 2010

      @terryjreedy
      Member

      PS. I only looked at the style of the patch. Once that is clearer, someone who knows more than me needs to review it for content correctness.

    8. cvrebert commented on Feb 2, 2010

      cvrebertmannequin
      MannequinAuthor

      Working on a more concise new draft...

    9. cvrebert commented on Feb 2, 2010

      cvrebertmannequin
      MannequinAuthor

      Okay; new, hopefully better, draft. Feedback?

    10. briancurtin commented on Feb 2, 2010

      @briancurtin
      Member

      The raw_input() doesn't provide anything. I'd just drop that and pass the string directly to shlex.split.

      "Do not put an argument-taking option together with its argument as a single item in the *args* list"
      -- Something like "Argument-taking options should not be grouped with their arguments in the *args* list." may be a cleaner read, and avoids the big scary "do not".

      "Because that is incorrect"
      -- Maybe something like "shlex.split would suggest the following" instead?

    11. cvrebert commented on Feb 2, 2010

      cvrebertmannequin
      MannequinAuthor

      Gonna have to disagree about the raw_input(), because the escaping involved would complicate the example and could be distracting/confusing.
      Rest of Brian's suggestions taken into account.

    12. pitrou commented on Feb 2, 2010

      @pitrou
      Member

      I still think this is much too verbose. The second note looks redundant with the first one and the third one.
      Remember, the notes you are adding may be useful, but they'll also make reading the whole page more tedious.

    13. cvrebert commented on Feb 2, 2010

      cvrebertmannequin
      MannequinAuthor

      Well, the same basic example is used for cohesiveness, but the issue/pitfall being highlighted in each note is distinct. But you have a point about shlex being pointed out twice, so here's a version with that redundancy excised.

    14. 8 remaining items

    15. bitdancer commented on Feb 2, 2010

      @bitdancer
      Member

      I'm happy to delete the two sentences about quoting.

      As for -c, you are so right that it is cryptic. In the new version of the patch I've changed the sentence to be as precise as possible, but I'm not at all convinced that it is less confusing. This is why I think the API should be changed.

    16. cvrebert commented on Feb 2, 2010

      cvrebertmannequin
      MannequinAuthor

      This version takes Murray's most recent draft, applies some minor tweaks from my prior patch, and has the "python -c" etc. changed to "echo '$MONEY'" so the sh -c comment is completely unambiguous (and it's a simpler example generally).

      Whether the subprocess.Popen() call should be demonstrated in the code snippet remains an open issue.

    17. bitdancer commented on Feb 2, 2010

      @bitdancer
      Member

      The change to echo is an excellent improvement. You forgot to change 'python' to 'echo' in the following paragraph, though. You are also correct about /bin/sh vs sh, my bad. And I was even looking at the source code when I wrote that...

    18. ericvsmith commented on Feb 2, 2010

      @ericvsmith
      Member

      Now you need to put the import of subprocess back in!

      Otherwise it looks good to me.

    19. cvrebert commented on Feb 4, 2010

      cvrebertmannequin
      MannequinAuthor

      Okay, now if this could just get dev review...

    20. ericvsmith commented on Feb 4, 2010

      @ericvsmith
      Member

      I think this is an improvement to the existing docs, and should be committed.

    21. ncoghlan commented on Feb 4, 2010

      @ncoghlan
      Contributor

      Committed for 2.7 as r77959.

      Still needs to be merged to the other branches.

    22. ericvsmith commented on Feb 4, 2010

      @ericvsmith
      Member

      When merging to py3k, don't forget to modify the print statement to be a function.

    23. bitdancer commented on Feb 4, 2010

      @bitdancer
      Member

      Merged as part of r77961 (2.6), r77962 (py3k), and r77963 (3.1). Print fixed for py3.

    24. cvrebert commented on Feb 4, 2010

      cvrebertmannequin
      MannequinAuthor

      Thanks to all for the copious feedback & suggestions, and R. David Murray for his superior docs writing skills!

    25. cvrebert commented on Feb 5, 2010

      cvrebertmannequin
      MannequinAuthor

      One problem with the 3.x versions: the raw_input() should be input().

    26. bitdancer commented on Feb 5, 2010

      @bitdancer
      Member

      Thanks for catching that. Fixed r77987 r77988.

    27. christophneuroth commented on Feb 18, 2010

      christophneurothmannequin
      Mannequin

      As recommended by eric.smith on bpo-7950, I'd like to suggest further extending the documentation to include a security warning about (quite easily) possible code injection bugs when using the shell=True parameter (similar to other places in the documentation).

    28. transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Labels

    docsDocumentation in the Doc dirtype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions