66
66
"with_extended_output" ,
67
67
"with_exceptions" ,
68
68
"as_process" ,
69
- "stdout_as_string" ,
70
69
"output_stream" ,
71
- "with_stdout " ,
70
+ "stdout_as_string " ,
72
71
"kill_after_timeout" ,
72
+ "with_stdout" ,
73
73
"universal_newlines" ,
74
74
"shell" ,
75
75
"env" ,
@@ -105,7 +105,7 @@ def handle_process_output(
105
105
) -> None :
106
106
"""Registers for notifications to learn that process output is ready to read, and dispatches lines to
107
107
the respective line handlers.
108
- This function returns once the finalizer returns
108
+ This function returns once the finalizer returns.
109
109
110
110
:return: result of finalizer
111
111
:param process: subprocess.Popen instance
@@ -294,9 +294,7 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
294
294
295
295
@classmethod
296
296
def refresh (cls , path : Union [None , PathLike ] = None ) -> bool :
297
- """This gets called by the refresh function (see the top level
298
- __init__).
299
- """
297
+ """This gets called by the refresh function (see the top level __init__)."""
300
298
# discern which path to refresh with
301
299
if path is not None :
302
300
new_git = os .path .expanduser (path )
@@ -446,9 +444,9 @@ def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None) -> PathLike:
446
444
if is_cygwin :
447
445
url = cygpath (url )
448
446
else :
449
- """Remove any backslahes from urls to be written in config files.
447
+ """Remove any backslashes from urls to be written in config files.
450
448
451
- Windows might create config- files containing paths with backslashed ,
449
+ Windows might create config files containing paths with backslashes ,
452
450
but git stops liking them as it will escape the backslashes.
453
451
Hence we undo the escaping just to be sure.
454
452
"""
@@ -464,8 +462,8 @@ def check_unsafe_protocols(cls, url: str) -> None:
464
462
Check for unsafe protocols.
465
463
466
464
Apart from the usual protocols (http, git, ssh),
467
- Git allows "remote helpers" that have the form `<transport>::<address>`,
468
- one of these helpers (`ext::`) can be used to invoke any arbitrary command.
465
+ Git allows "remote helpers" that have the form `` <transport>::<address>` `,
466
+ one of these helpers (`` ext::` `) can be used to invoke any arbitrary command.
469
467
470
468
See:
471
469
@@ -517,7 +515,7 @@ def __init__(self, proc: Union[None, subprocess.Popen], args: Any) -> None:
517
515
self .status : Union [int , None ] = None
518
516
519
517
def _terminate (self ) -> None :
520
- """Terminate the underlying process"""
518
+ """Terminate the underlying process. """
521
519
if self .proc is None :
522
520
return
523
521
@@ -572,7 +570,7 @@ def wait(self, stderr: Union[None, str, bytes] = b"") -> int:
572
570
"""Wait for the process and return its status code.
573
571
574
572
:param stderr: Previously read value of stderr, in case stderr is already closed.
575
- :warn: may deadlock if output or error pipes are used and not handled separately.
573
+ :warn: May deadlock if output or error pipes are used and not handled separately.
576
574
:raise GitCommandError: if the return status is not 0"""
577
575
if stderr is None :
578
576
stderr_b = b""
@@ -605,13 +603,12 @@ def read_all_from_possibly_closed_stream(stream: Union[IO[bytes], None]) -> byte
605
603
# END auto interrupt
606
604
607
605
class CatFileContentStream (object ):
608
-
609
606
"""Object representing a sized read-only stream returning the contents of
610
607
an object.
611
608
It behaves like a stream, but counts the data read and simulates an empty
612
609
stream once our sized content region is empty.
613
- If not all data is read to the end of the objects 's lifetime, we read the
614
- rest to assure the underlying stream continues to work"""
610
+ If not all data is read to the end of the object 's lifetime, we read the
611
+ rest to assure the underlying stream continues to work. """
615
612
616
613
__slots__ : Tuple [str , ...] = ("_stream" , "_nbr" , "_size" )
617
614
@@ -740,11 +737,11 @@ def __getattr__(self, name: str) -> Any:
740
737
741
738
def set_persistent_git_options (self , ** kwargs : Any ) -> None :
742
739
"""Specify command line options to the git executable
743
- for subsequent subcommand calls
740
+ for subsequent subcommand calls.
744
741
745
742
:param kwargs:
746
743
is a dict of keyword arguments.
747
- these arguments are passed as in _call_process
744
+ These arguments are passed as in _call_process
748
745
but will be passed to the git command rather than
749
746
the subcommand.
750
747
"""
@@ -775,7 +772,7 @@ def version_info(self) -> Tuple[int, int, int, int]:
775
772
"""
776
773
:return: tuple(int, int, int, int) tuple with integers representing the major, minor
777
774
and additional version numbers as parsed from git version.
778
- This value is generated on demand and is cached"""
775
+ This value is generated on demand and is cached. """
779
776
return self ._version_info
780
777
781
778
@overload
@@ -842,16 +839,16 @@ def execute(
842
839
strip_newline_in_stdout : bool = True ,
843
840
** subprocess_kwargs : Any ,
844
841
) -> Union [str , bytes , Tuple [int , Union [str , bytes ], str ], AutoInterrupt ]:
845
- """Handles executing the command on the shell and consumes and returns
846
- the returned information (stdout)
842
+ """Handles executing the command and consumes and returns the returned
843
+ information (stdout).
847
844
848
845
:param command:
849
846
The command argument list to execute.
850
- It should be a string, or a sequence of program arguments. The
847
+ It should be a sequence of program arguments, or a string . The
851
848
program to execute is the first item in the args sequence or string.
852
849
853
850
:param istream:
854
- Standard input filehandle passed to subprocess.Popen.
851
+ Standard input filehandle passed to ` subprocess.Popen` .
855
852
856
853
:param with_extended_output:
857
854
Whether to return a (status, stdout, stderr) tuple.
@@ -862,8 +859,7 @@ def execute(
862
859
:param as_process:
863
860
Whether to return the created process instance directly from which
864
861
streams can be read on demand. This will render with_extended_output and
865
- with_exceptions ineffective - the caller will have
866
- to deal with the details himself.
862
+ with_exceptions ineffective - the caller will have to deal with the details.
867
863
It is important to note that the process will be placed into an AutoInterrupt
868
864
wrapper that will interrupt the process once it goes out of scope. If you
869
865
use the command in iterators, you should pass the whole process instance
@@ -876,13 +872,34 @@ def execute(
876
872
always be created with a pipe due to issues with subprocess.
877
873
This merely is a workaround as data will be copied from the
878
874
output pipe to the given output stream directly.
879
- Judging from the implementation, you shouldn't use this flag !
875
+ Judging from the implementation, you shouldn't use this parameter !
880
876
881
877
:param stdout_as_string:
882
- if False, the commands standard output will be bytes. Otherwise, it will be
883
- decoded into a string using the default encoding (usually utf -8).
878
+ If False, the command's standard output will be bytes. Otherwise, it will be
879
+ decoded into a string using the default encoding (usually UTF -8).
884
880
The latter can fail, if the output contains binary data.
885
881
882
+ :param kill_after_timeout:
883
+ Specifies a timeout in seconds for the git command, after which the process
884
+ should be killed. This will have no effect if as_process is set to True. It is
885
+ set to None by default and will let the process run until the timeout is
886
+ explicitly specified. This feature is not supported on Windows. It's also worth
887
+ noting that kill_after_timeout uses SIGKILL, which can have negative side
888
+ effects on a repository. For example, stale locks in case of ``git gc`` could
889
+ render the repository incapable of accepting changes until the lock is manually
890
+ removed.
891
+
892
+ :param with_stdout:
893
+ If True, default True, we open stdout on the created process.
894
+
895
+ :param universal_newlines:
896
+ if True, pipes will be opened as text, and lines are split at
897
+ all known line endings.
898
+
899
+ :param shell:
900
+ Whether to invoke commands through a shell (see `Popen(..., shell=True)`).
901
+ It overrides :attr:`USE_SHELL` if it is not `None`.
902
+
886
903
:param env:
887
904
A dictionary of environment variables to be passed to `subprocess.Popen`.
888
905
@@ -891,38 +908,23 @@ def execute(
891
908
one invocation of write() method. If the given number is not positive then
892
909
the default value is used.
893
910
911
+ :param strip_newline_in_stdout:
912
+ Whether to strip the trailing ``\\ n`` of the command stdout.
913
+
894
914
:param subprocess_kwargs:
895
- Keyword arguments to be passed to subprocess.Popen. Please note that
896
- some of the valid kwargs are already set by this method, the ones you
915
+ Keyword arguments to be passed to ` subprocess.Popen` . Please note that
916
+ some of the valid kwargs are already set by this method; the ones you
897
917
specify may not be the same ones.
898
918
899
- :param with_stdout: If True, default True, we open stdout on the created process
900
- :param universal_newlines:
901
- if True, pipes will be opened as text, and lines are split at
902
- all known line endings.
903
- :param shell:
904
- Whether to invoke commands through a shell (see `Popen(..., shell=True)`).
905
- It overrides :attr:`USE_SHELL` if it is not `None`.
906
- :param kill_after_timeout:
907
- To specify a timeout in seconds for the git command, after which the process
908
- should be killed. This will have no effect if as_process is set to True. It is
909
- set to None by default and will let the process run until the timeout is
910
- explicitly specified. This feature is not supported on Windows. It's also worth
911
- noting that kill_after_timeout uses SIGKILL, which can have negative side
912
- effects on a repository. For example, stale locks in case of git gc could
913
- render the repository incapable of accepting changes until the lock is manually
914
- removed.
915
- :param strip_newline_in_stdout:
916
- Whether to strip the trailing ``\\ n`` of the command stdout.
917
919
:return:
918
920
* str(output) if extended_output = False (Default)
919
921
* tuple(int(status), str(stdout), str(stderr)) if extended_output = True
920
922
921
- if output_stream is True, the stdout value will be your output stream:
923
+ If output_stream is True, the stdout value will be your output stream:
922
924
* output_stream if extended_output = False
923
925
* tuple(int(status), output_stream, str(stderr)) if extended_output = True
924
926
925
- Note git is executed with LC_MESSAGES="C" to ensure consistent
927
+ Note that git is executed with `` LC_MESSAGES="C"`` to ensure consistent
926
928
output regardless of system language.
927
929
928
930
:raise GitCommandError:
@@ -971,18 +973,15 @@ def execute(
971
973
# end handle
972
974
973
975
stdout_sink = PIPE if with_stdout else getattr (subprocess , "DEVNULL" , None ) or open (os .devnull , "wb" )
974
- istream_ok = "None"
975
- if istream :
976
- istream_ok = "<valid stream>"
977
976
if shell is None :
978
977
shell = self .USE_SHELL
979
978
log .debug (
980
- "Popen(%s, cwd=%s, universal_newlines =%s, shell=%s, istream =%s)" ,
979
+ "Popen(%s, cwd=%s, stdin =%s, shell=%s, universal_newlines =%s)" ,
981
980
redacted_command ,
982
981
cwd ,
983
- universal_newlines ,
982
+ "<valid stream>" if istream else "None" ,
984
983
shell ,
985
- istream_ok ,
984
+ universal_newlines ,
986
985
)
987
986
try :
988
987
with maybe_patch_caller_env :
@@ -1010,8 +1009,8 @@ def execute(
1010
1009
if as_process :
1011
1010
return self .AutoInterrupt (proc , command )
1012
1011
1013
- def _kill_process (pid : int ) -> None :
1014
- """Callback method to kill a process."""
1012
+ def kill_process (pid : int ) -> None :
1013
+ """Callback to kill a process."""
1015
1014
p = Popen (
1016
1015
["ps" , "--ppid" , str (pid )],
1017
1016
stdout = PIPE ,
@@ -1044,7 +1043,7 @@ def _kill_process(pid: int) -> None:
1044
1043
1045
1044
if kill_after_timeout is not None :
1046
1045
kill_check = threading .Event ()
1047
- watchdog = threading .Timer (kill_after_timeout , _kill_process , args = (proc .pid ,))
1046
+ watchdog = threading .Timer (kill_after_timeout , kill_process , args = (proc .pid ,))
1048
1047
1049
1048
# Wait for the process to return
1050
1049
status = 0
@@ -1208,7 +1207,7 @@ def _unpack_args(cls, arg_list: Sequence[str]) -> List[str]:
1208
1207
1209
1208
def __call__ (self , ** kwargs : Any ) -> "Git" :
1210
1209
"""Specify command line options to the git executable
1211
- for a subcommand call
1210
+ for a subcommand call.
1212
1211
1213
1212
:param kwargs:
1214
1213
is a dict of keyword arguments.
@@ -1246,7 +1245,7 @@ def _call_process(
1246
1245
self , method : str , * args : Any , ** kwargs : Any
1247
1246
) -> Union [str , bytes , Tuple [int , Union [str , bytes ], str ], "Git.AutoInterrupt" ]:
1248
1247
"""Run the given git command with the specified arguments and return
1249
- the result as a String
1248
+ the result as a string.
1250
1249
1251
1250
:param method:
1252
1251
is the command. Contained "_" characters will be converted to dashes,
@@ -1255,7 +1254,7 @@ def _call_process(
1255
1254
:param args:
1256
1255
is the list of arguments. If None is included, it will be pruned.
1257
1256
This allows your commands to call git more conveniently as None
1258
- is realized as non-existent
1257
+ is realized as non-existent.
1259
1258
1260
1259
:param kwargs:
1261
1260
It contains key-values for the following:
@@ -1385,7 +1384,7 @@ def get_object_header(self, ref: str) -> Tuple[str, str, int]:
1385
1384
return self .__get_object_header (cmd , ref )
1386
1385
1387
1386
def get_object_data (self , ref : str ) -> Tuple [str , str , int , bytes ]:
1388
- """As get_object_header, but returns object data as well
1387
+ """As get_object_header, but returns object data as well.
1389
1388
1390
1389
:return: (hexsha, type_string, size_as_int, data_string)
1391
1390
:note: not threadsafe"""
@@ -1395,10 +1394,10 @@ def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]:
1395
1394
return (hexsha , typename , size , data )
1396
1395
1397
1396
def stream_object_data (self , ref : str ) -> Tuple [str , str , int , "Git.CatFileContentStream" ]:
1398
- """As get_object_header, but returns the data as a stream
1397
+ """As get_object_header, but returns the data as a stream.
1399
1398
1400
1399
:return: (hexsha, type_string, size_as_int, stream)
1401
- :note: This method is not threadsafe, you need one independent Command instance per thread to be safe !"""
1400
+ :note: This method is not threadsafe, you need one independent Command instance per thread to be safe!"""
1402
1401
cmd = self ._get_persistent_cmd ("cat_file_all" , "cat_file" , batch = True )
1403
1402
hexsha , typename , size = self .__get_object_header (cmd , ref )
1404
1403
cmd_stdout = cmd .stdout if cmd .stdout is not None else io .BytesIO ()
0 commit comments