Repository navigation
Unclear rationale for pipe usage in output_stream doc #1845
Description
Activity
Thanks for bringing this to my attention.
After reading the context, I take most offence from
Judging from the implementation, you shouldn't use this parameter!just because I don't find it particularly helpful and think it can be removed without substitute.From what I read, subprocesses cannot have an output stream which isn't an actual open file (and thus have a file-descriptor) or which isn't a pipe. Thus, if
output_streamisn't anything compatible, it will have to perform an inefficient copy from the end of a pipe to whatever stream-like object the user passed.I think most users wouldn't care about this detail, as long as output is streamed to
output_streamwhich should always work. Further, maybe by now it's possible to pass all kinds ofoutput_streamimplementations to processes directly (and Python abstracts over that by itself internally), so said 'issues' are no more.In any case, I believe that everything starting from
Processes will always…is unsubstantial and can be removed.I'm wondering if the motivation for the extra text is to prevent users from being misled by the phrase "will be output to the given stream directly," especially by its use of "directly," and if some rephrasing, or added note, should accompany the removal of that text.
(This is sort of conceptually related to #1762, but improving this docstring probably need not wait on that.)
I think this will work:
: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! + copied to the given stream instead of being returned as a string. + This feature only has any effect if `as_process` is False.- added a commit that references this issue
on Feb 26, 2024 Wonderful! Thank you.
Reacted by Eliah Kagan
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