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! |
The
Git.executemethod docstring includes this in the description of itsoutput_streamparameter:GitPython/git/cmd.py
Lines 990 to 991 in 1e044ea
I think this is referring to the
subprocessmodule, which could be clarified by changingsubprocessto: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_streamshouldn'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
subprocessitself, then it could be changed to:But I hope something more specific can be said.
The full context is:
GitPython/git/cmd.py
Lines 987 to 994 in 1e044ea