[docs] [issue13237] subprocess docs should use emphasise convenience functions

Nick Coghlan report at bugs.python.org
Fri Oct 21 07:25:02 CEST 2011


New submission from Nick Coghlan <ncoghlan at gmail.com>:

Many typical subprocess use cases can now be handled simply via the convenience functions:

  subprocess.call()
  subprocess.check_call()
  subprocess.check_output()

However, readers of the documentation could be forgiven for not realising that, since the docs dive right in with Popen() and will scare most readers away in search of more user friendly APIs (or even other languages).

The module documentation should be reordered to introduce the helper function first, then Popen afterwards.

The "subprocess replacements" [1] section would ideally help address this, but it hasn't been updated to use the convenience function, instead using confusing direct calls to Popen.

[1] http://docs.python.org/library/subprocess.html#subprocess-replacements

----------
assignee: docs at python
components: Documentation
messages: 146059
nosy: docs at python, ncoghlan
priority: normal
severity: normal
stage: needs patch
status: open
title: subprocess docs should use emphasise convenience functions
versions: Python 2.7, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13237>
_______________________________________


More information about the docs mailing list