◐ Shell
clean mode source ↗

Unclear rationale for pipe usage in `output_stream` doc

The Git.execute method docstring includes this in the description of its output_stream parameter:

This feature only has any effect if `as_process` is False. Processes will
always be created with a pipe due to issues with subprocess.

I think this is referring to the subprocess module, which could be clarified by changing subprocess to :mod:`subprocess`. But I'm not sure what issues this is referring to, or what information it seeks to impart to the reader.

To be clear, I'm not arguing that output_stream shouldn't use a pipe. Instead, I think this part of the docstring should be clarified (and I am unsure how to do so).

If this intends to be general, and vagueness is acceptable, yet it is considered better to have this "due to" clause than simply remove it, and the issue really is in subprocess itself, then it could be changed to:

due to limitations of :mod:`subprocess`

But I hope something more specific can be said.

The full context is:

:param output_stream:
If set to a file-like object, data produced by the git command will be
output to the given stream directly.
This feature only has any effect if `as_process` is False. Processes will
always be created with a pipe due to issues with subprocess.
This merely is a workaround as data will be copied from the
output pipe to the given output stream directly.
Judging from the implementation, you shouldn't use this parameter!