Skip to content

Unclear rationale for pipe usage in output_stream doc #1845

Closed
@EliahKagan

Description

@EliahKagan

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

GitPython/git/cmd.py

Lines 990 to 991 in 1e044ea

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:

GitPython/git/cmd.py

Lines 987 to 994 in 1e044ea

: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!

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions