gitbolt 0.0.0.dev14__tar.gz → 0.0.0.dev16__tar.gz

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitbolt
-Version: 0.0.0.dev14
+Version: 0.0.0.dev16
 Summary: Fast, flexible and type-safe Git commands in Python.
 Author-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
 Maintainer-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
@@ -114,9 +114,8 @@ Gitbolt lets you pass subcommands around as typed objects. This enables highly f
 
 ```python
 import gitbolt
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 version_subcmd = git.version_subcmd
 add_subcmd = git.add_subcmd
 
@@ -136,11 +135,11 @@ method_which_only_adds_a_file(add_subcmd)
 git subcommands are modeled as terminal functions that return stdout.
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
-status_out = git.status_subcmd.status()
-print(status_out)
+git = gitbolt.get_git()
+version_stdout = git.version_subcmd.version().version()
+print(version_stdout)
 ```
 
 ### 🪼 Modular Architecture
@@ -206,9 +205,9 @@ Extensive use of type-hints ensures that invalid usages fail early — at *compi
 #### 🔁 Override a single Git env (e.g., `GIT_TRACE`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=True)
 ```
 
@@ -216,9 +215,9 @@ git = git.git_envs_override(GIT_TRACE=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')
 ```
 
@@ -226,9 +225,9 @@ git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDIT
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(
     GIT_TERMINAL_PROMPT=1,
     GIT_NO_REPLACE_OBJECTS=True
@@ -239,10 +238,10 @@ re_overridden_git = overridden_git.git_envs_override(GIT_TRACE=True)
 #### ❌ Unset Git envs using a special `UNSET` marker
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)
 no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 ```
@@ -250,9 +249,9 @@ no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 #### 🔄 Reset Git envs by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_TRACE=True)
 git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 ```
@@ -268,9 +267,9 @@ git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 #### 🔁 Override a single Git opt (e.g., `--no-replace-objects`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_opts_override(no_replace_objects=True)
 ```
 
@@ -278,7 +277,7 @@ git = git.git_opts_override(no_replace_objects=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+from gitbolt.subprocess.impl.simple import SimpleGitCommand
 
 git = SimpleGitCommand()
 git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)
@@ -287,10 +286,10 @@ git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=Tr
 #### 🪢 Chain multiple option overrides fluently
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(
     noglob_pathspecs=True,
     no_advice=True
@@ -303,11 +302,11 @@ re_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)
 #### ❌ Unset Git opts using a special `UNSET` marker
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp'), no_advice=True)
 no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 ```
@@ -315,9 +314,9 @@ no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 #### 🔄 Reset Git opts by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(no_advice=True)
 no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 ```
@@ -328,33 +327,59 @@ no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 
 At last, run unchecked commands in git.
 
-Introduced in `0.0.0dev4` to 
+Introduced in `0.0.0.dev4` to 
 - experiment.
 - have consistent interfaced commands run until all subcommands are provided by the library.
 
+#### 🖥️ Run one process per command
+
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git_command()
 git = git.git_opts_override(no_advice=True)
 git.subcmd_unchecked.run(['--version']) # run the version option for git.
 git.subcmd_unchecked.run(['version']) # run the version subcommand.
 ```
 
+#### 🖥️ Run one long-running process and communicate with it
+
+Introduced in `0.0.0.dev16` to:
+- Make communicable processes using `subprocess.Popen`.
+
+Get a long-running process and communicate with it for batching and faster operations.
+
+```python
+import gitbolt
+import sys
+
+git = gitbolt.get_git_command()
+with git.subcmd_unchecked.popen(["cat-file", "--batch-command"]) as cf:
+    cf.stdin.write(b"contents HEAD\n")
+    cf.stdin.flush()
+    header = cf.stdout.readline().strip()
+    print(f"HEADER: {header}", file=sys.stderr)
+    obj, typ, size = header.split()
+    print(cf.stdout.read(int(size)))
+    cf.stdout.readline()
+```
+
+Error handling and I/O management is left to the client/caller.
+
 #### 💻 Run commands received from CLI
 
-Introduced in `0.0.0dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
+Introduced in `0.0.0.dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
 
 While making a system it may be required to run cli commands as received from cli using gitbolt. An obvious example 
 would be to make a system that receives CLI commands and does certain modifications/additions inside `gitbolt` before
 actually running them. An example:
 
 ```python
-from gitbolt.git_subprocess.impl.simple import CLISimpleGitCommand
+import gitbolt
 
-opts = ["--no-pager", "--namespace", "n1"]   # options received from outside your program.
-envs = dict(GIT_AUTHOR_NAME="ss")   # env-vars received form outside your program.
-git = CLISimpleGitCommand(opts=opts, envs=envs)
+opts = ["--no-pager", "--namespace", "n1"]  # options received from outside your program.
+envs = dict(GIT_AUTHOR_NAME="ss")  # env-vars received form outside your program.
+git = gitbolt.get_git_command(opts=opts, envs=envs)
 
 # these can later be overridden
 git = git.git_opts_override(namespace="n2")

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/README.md

@@ -78,9 +78,8 @@ Gitbolt lets you pass subcommands around as typed objects. This enables highly f
 
 ```python
 import gitbolt
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 version_subcmd = git.version_subcmd
 add_subcmd = git.add_subcmd
 
@@ -100,11 +99,11 @@ method_which_only_adds_a_file(add_subcmd)
 git subcommands are modeled as terminal functions that return stdout.
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
-status_out = git.status_subcmd.status()
-print(status_out)
+git = gitbolt.get_git()
+version_stdout = git.version_subcmd.version().version()
+print(version_stdout)
 ```
 
 ### 🪼 Modular Architecture
@@ -170,9 +169,9 @@ Extensive use of type-hints ensures that invalid usages fail early — at *compi
 #### 🔁 Override a single Git env (e.g., `GIT_TRACE`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=True)
 ```
 
@@ -180,9 +179,9 @@ git = git.git_envs_override(GIT_TRACE=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')
 ```
 
@@ -190,9 +189,9 @@ git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDIT
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(
     GIT_TERMINAL_PROMPT=1,
     GIT_NO_REPLACE_OBJECTS=True
@@ -203,10 +202,10 @@ re_overridden_git = overridden_git.git_envs_override(GIT_TRACE=True)
 #### ❌ Unset Git envs using a special `UNSET` marker
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)
 no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 ```
@@ -214,9 +213,9 @@ no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 #### 🔄 Reset Git envs by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_TRACE=True)
 git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 ```
@@ -232,9 +231,9 @@ git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 #### 🔁 Override a single Git opt (e.g., `--no-replace-objects`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_opts_override(no_replace_objects=True)
 ```
 
@@ -242,7 +241,7 @@ git = git.git_opts_override(no_replace_objects=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+from gitbolt.subprocess.impl.simple import SimpleGitCommand
 
 git = SimpleGitCommand()
 git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)
@@ -251,10 +250,10 @@ git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=Tr
 #### 🪢 Chain multiple option overrides fluently
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(
     noglob_pathspecs=True,
     no_advice=True
@@ -267,11 +266,11 @@ re_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)
 #### ❌ Unset Git opts using a special `UNSET` marker
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp'), no_advice=True)
 no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 ```
@@ -279,9 +278,9 @@ no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 #### 🔄 Reset Git opts by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(no_advice=True)
 no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 ```
@@ -292,33 +291,59 @@ no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 
 At last, run unchecked commands in git.
 
-Introduced in `0.0.0dev4` to 
+Introduced in `0.0.0.dev4` to 
 - experiment.
 - have consistent interfaced commands run until all subcommands are provided by the library.
 
+#### 🖥️ Run one process per command
+
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git_command()
 git = git.git_opts_override(no_advice=True)
 git.subcmd_unchecked.run(['--version']) # run the version option for git.
 git.subcmd_unchecked.run(['version']) # run the version subcommand.
 ```
 
+#### 🖥️ Run one long-running process and communicate with it
+
+Introduced in `0.0.0.dev16` to:
+- Make communicable processes using `subprocess.Popen`.
+
+Get a long-running process and communicate with it for batching and faster operations.
+
+```python
+import gitbolt
+import sys
+
+git = gitbolt.get_git_command()
+with git.subcmd_unchecked.popen(["cat-file", "--batch-command"]) as cf:
+    cf.stdin.write(b"contents HEAD\n")
+    cf.stdin.flush()
+    header = cf.stdout.readline().strip()
+    print(f"HEADER: {header}", file=sys.stderr)
+    obj, typ, size = header.split()
+    print(cf.stdout.read(int(size)))
+    cf.stdout.readline()
+```
+
+Error handling and I/O management is left to the client/caller.
+
 #### 💻 Run commands received from CLI
 
-Introduced in `0.0.0dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
+Introduced in `0.0.0.dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
 
 While making a system it may be required to run cli commands as received from cli using gitbolt. An obvious example 
 would be to make a system that receives CLI commands and does certain modifications/additions inside `gitbolt` before
 actually running them. An example:
 
 ```python
-from gitbolt.git_subprocess.impl.simple import CLISimpleGitCommand
+import gitbolt
 
-opts = ["--no-pager", "--namespace", "n1"]   # options received from outside your program.
-envs = dict(GIT_AUTHOR_NAME="ss")   # env-vars received form outside your program.
-git = CLISimpleGitCommand(opts=opts, envs=envs)
+opts = ["--no-pager", "--namespace", "n1"]  # options received from outside your program.
+envs = dict(GIT_AUTHOR_NAME="ss")  # env-vars received form outside your program.
+git = gitbolt.get_git_command(opts=opts, envs=envs)
 
 # these can later be overridden
 git = git.git_opts_override(namespace="n2")

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gitbolt"
-version = "0.0.0dev14"
+version = "0.0.0.dev16"
 description = "Fast, flexible and type-safe Git commands in Python."
 requires-python = ">=3.12"
 readme = "README.md"
@@ -45,9 +45,7 @@ pygit2 = ['pygit2']
 test = ['pytest']
 
 [dependency-groups]
-# TODO: report the mypy recent version (1.16.0, 1.16.1 issue) RuntimeError: ('Not implemented', <class 'mypy.types.TypeGuardedType'>)
-#   btw, this error doesn't show in the latest developer version. So, this error will go away with 1.17.0 relase
-dev = ["mypy==1.15.0", "ruff"]
+dev = ["mypy", "ruff"]
 doc = ['sphinx', 'sphinx-argparse']
 test = ["pytest", 'pytest-cov', "pytest-xdist"]
 multitest = ['tox']

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/__init__.py

@@ -52,8 +52,8 @@ def get_git_command(
     git_root_dir: Path = Path.cwd(),
     *,
     git_prog: str | Path = GIT_CMD,
-    main_cmd_opts: list[str] | None = None,
-    main_cmd_envs: dict[str, str] | None = None,
+    opts: list[str] | None = None,
+    envs: dict[str, str] | None = None,
     prefer_cli: bool = False,
 ) -> GitCommand:
     """
@@ -75,8 +75,8 @@ def get_git_command(
     :param git_root_dir: Path to the git repo root directory. Defaults to current working directory.
     :param git_prog: git program name/location. Useful when user wants to run a separate git version/git emulator.
     :param opts: main git cli options. The main git command options like ``--no-replace-objects``, ``--no-pager``, ``-C`` etc are git main command args.
-    :param envs: main git cli env vars. Not supplying any env vars (default behavior: ``None``) simply supplies all
-        the env vars to the underlying runner.
+    :param envs: main git cli environment variables (env vars). Not supplying any env vars (default behavior: ``None``)
+        simply supplies all the env vars to the underlying runner.
     :param prefer_cli: cli opts and envs will be given priority over programmatically set opts and envs. Setting
         this param to ``True`` will make cli opts and envs appear later in the opts and envs strings which will
         make them override previously programmatically set opts and envs.
@@ -84,13 +84,13 @@ def get_git_command(
         separate runner in subprocess.
     """
     runner = _SimpleGitCR(git_prog)
-    if main_cmd_opts is None:
+    if opts is None:
         return _SimpleGitCommand(git_root_dir, runner)
     else:
         return _CLISimpleGitCommand(
             git_root_dir,
             runner,
-            opts=main_cmd_opts,
-            envs=main_cmd_envs,
+            opts=opts,
+            envs=envs,
             prefer_cli=prefer_cli,
         )

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/base.py

@@ -20,29 +20,21 @@ from gitbolt.ls_tree import LsTreeArgsValidator, UtilLsTreeArgsValidator
 from gitbolt.add import AddArgsValidator, UtilAddArgsValidator
 
 
-class ForGit(Protocol):
-    """
-    Marker interface to mark an operation for git.
-    """
-
-    pass
-
-
-class HasGitUnderneath[G: "Git"](ForGit, Protocol):
+class HasGitUnderneath[G: "Git"](Protocol):
     """
     Stores a reference to main git instance.
     """
 
     @property
     @abstractmethod
-    def underlying_git(self) -> G:
+    def git(self) -> G:
         """
-        :return: stored git instance reference.
+        :return: stored underlying git instance reference.
         """
         ...
 
 
-class CanOverrideGitOpts(ForGit, Protocol):
+class CanOverrideGitOpts(Protocol):
     """
     Can override main git command options.
 
@@ -65,7 +57,7 @@ class CanOverrideGitOpts(ForGit, Protocol):
         ...
 
 
-class CanOverrideGitEnvs(ForGit, Protocol):
+class CanOverrideGitEnvs(Protocol):
     """
     Can override main git command environment variables.
 

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/subprocess/base.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from abc import abstractmethod, ABC
 from collections.abc import Callable
 from pathlib import Path
-from subprocess import CompletedProcess
+from subprocess import CompletedProcess, Popen, PIPE
 from typing import override, Protocol, Unpack, Self, overload, Literal, Any
 
 from vt.utils.commons.commons.core_py import is_unset, not_none_not_unset
@@ -306,13 +306,13 @@ class GitSubcmdCommand(GitSubCommand, HasGitUnderneath["GitCommand"], Protocol):
 
     @override
     def git_opts_override(self, **overrides: Unpack[GitOpts]) -> Self:
-        overridden_git = self.underlying_git.git_opts_override(**overrides)
+        overridden_git = self.git.git_opts_override(**overrides)
         self._set_underlying_git(overridden_git)
         return self
 
     @override
     def git_envs_override(self, **overrides: Unpack[GitEnvVars]) -> Self:
-        overridden_git = self.underlying_git.git_envs_override(**overrides)
+        overridden_git = self.git.git_envs_override(**overrides)
         self._set_underlying_git(overridden_git)
         return self
 
@@ -403,11 +403,11 @@ class LsTreeCommand(LsTree, GitSubcmdCommand, Protocol):
     def ls_tree(self, tree_ish: str, **ls_tree_opts: Unpack[GitLsTreeOpts]) -> str:
         self.args_validator.validate(tree_ish, **ls_tree_opts)
         sub_cmd_args = self.cli_args_builder.build(tree_ish, **ls_tree_opts)
-        main_cmd_args = self.underlying_git.build_main_cmd_args()
-        env_vars = self.underlying_git.build_git_envs()
+        main_cmd_args = self.git.build_main_cmd_args()
+        env_vars = self.git.build_git_envs()
 
         # Run the git command
-        result = self.underlying_git.runner.run_git_command(
+        result = self.git.runner.run_git_command(
             main_cmd_args,
             sub_cmd_args,
             check=True,
@@ -485,11 +485,11 @@ class AddCommand(Add, GitSubcmdCommand, Protocol):
             pathspec_file_nul=pathspec_file_nul,
             **add_opts,
         )
-        main_cmd_args = self.underlying_git.build_main_cmd_args()
-        env_vars = self.underlying_git.build_git_envs()
+        main_cmd_args = self.git.build_main_cmd_args()
+        env_vars = self.git.build_git_envs()
 
         # Run the git command
-        result = self.underlying_git.runner.run_git_command(
+        result = self.git.runner.run_git_command(
             main_cmd_args,
             sub_cmd_args,
             _input=pathspec_stdin,
@@ -584,17 +584,13 @@ class UncheckedSubcmd(GitSubcmdCommand, RootDirOp, Protocol):
 
         :return: ``CompletedProcess`` capturing all the required stdout, stderr, return-code etc.
         """
-        main_cmd_args = self.underlying_git.build_main_cmd_args()
-        envs_vars = self.underlying_git.build_git_envs()
-        another_supplied_env = subprocess_run_kwargs.pop("env", None)
-        if another_supplied_env:
-            if envs_vars is not None:
-                envs_vars.update(another_supplied_env)
+        main_cmd_args = self.git_main_cmd_args()
+        envs_vars = self.git_envs(subprocess_run_kwargs.pop("env", None))
         cwd = subprocess_run_kwargs.pop("cwd", self.root_dir)
         capture_output = subprocess_run_kwargs.pop("capture_output", True)
         check = subprocess_run_kwargs.pop("check", True)
         # Run the git command
-        result = self.underlying_git.runner.run_git_command(
+        result = self.git.runner.run_git_command(
             main_cmd_args,
             subcommand_args,
             *subprocess_run_args,
@@ -607,3 +603,103 @@ class UncheckedSubcmd(GitSubcmdCommand, RootDirOp, Protocol):
             **subprocess_run_kwargs,
         )
         return result
+
+    @overload
+    def popen(
+        self,
+        subcommand_args: list[str],
+        *popen_args: Any,
+        text: Literal[True] = True,
+        **popen_kwargs: Any,
+    ) -> Popen[str]: ...
+
+    @overload
+    def popen(
+        self,
+        subcommand_args: list[str],
+        *popen_args: Any,
+        text: Literal[False] = False,
+        **popen_kwargs: Any,
+    ) -> Popen[bytes]: ...
+
+    def popen(
+        self,
+        subcommand_args: list[str],
+        *popen_args: Any,
+        text: Literal[True, False] = False,
+        **popen_kwargs: Any,
+    ) -> Popen[str] | Popen[bytes]:
+        """
+        Open unchecked git subcommand communicable process, using ``subprocess.Popen``.
+
+        All the arguments are congruent to ``subprocess.Popen`` and mostly passes as-is.
+
+        :param subcommand_args: the full subcommand argument list.
+        :param popen_args: additional subprocess positionals.
+        :param text: ``_input`` and returns both are str if this value is ``True``. Else, bytes are considered.
+        :param popen_kwargs: additional subprocess keyword arguments.
+
+        :return: ``Popen`` capturing all the required stdout, stderr etc and streaming stdin.
+        """
+        main_cmd_args = self.git_main_cmd_args()
+        envs_vars = self.git_envs(popen_kwargs.pop("env", None))
+        cwd = popen_kwargs.pop("cwd", self.root_dir)
+        stdin = popen_kwargs.pop("stdin", PIPE)
+        stdout = popen_kwargs.pop("stdout", PIPE)
+        stderr = popen_kwargs.pop("stderr", PIPE)
+        bufsize = popen_kwargs.pop("bufsize", 0)
+        # Popen the git command
+        result = self.git.runner.popen_git_command(
+            main_cmd_args,
+            subcommand_args,
+            *popen_args,
+            text=text,
+            env=envs_vars,
+            cwd=cwd,
+            stdin=stdin,
+            stdout=stdout,
+            stderr=stderr,
+            bufsize=bufsize,
+            **popen_kwargs,
+        )
+        return result
+
+    def make_cmd(self, subcommand_args: list[str]) -> list[str]:
+        """
+        Make full runnable command for execution from the supplied ``subcommand_args``.
+
+        As knowledge of the git program and the main command is encapsulated within this ``UncheckedSubcmd`` thus,
+        this is a convenience method for any external entities that want to run commands in their own subprocess.
+
+        :param subcommand_args: arguments for subcommand.
+        :returns: a fully made and runnable command for some external ``subprocess`` call.
+        """
+        return self.git.runner.make_cmd(self.git.build_main_cmd_args(), subcommand_args)
+
+    def git_main_cmd_args(self) -> list[str]:
+        """
+        Get CLI args for git main cli command.
+
+        For example, ``--no-pager --no-advice`` is the git main command in ``git --no-pager --no-advice log master -1``.
+
+        :return: CLI args for git main cli command.
+        """
+        return self.git.build_main_cmd_args()
+
+    def git_envs(
+        self, extra_git_envs: dict[str, str] | None = None
+    ) -> dict[str, str] | None:
+        """
+        Get Git environment variables from the merged ``GitEnvVars`` object.
+
+        Skips values that are ``Unset`` or ``None``-like using ``not_none_not_unset()``.
+        Converts ``Path`` and ``datetime`` instances to ``str``.
+
+        :param extra_git_envs: extraneous git envs supplied by the caller. These will be merged into the resultant
+            git envs and then returned.
+        :return: A cleaned and normalized GitEnvVars dict suitable for use in subprocesses.
+        """
+        env_vars = self.git.build_git_envs()
+        if extra_git_envs and env_vars is not None:
+            env_vars.update(extra_git_envs)
+        return env_vars

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/subprocess/impl/simple.py

@@ -36,7 +36,7 @@ class GitSubcmdCommandImpl(GitSubcmdCommand, ABC):
         self._underlying_git = git
 
     @property
-    def underlying_git(self) -> GitCommand:
+    def git(self) -> GitCommand:
         return self._underlying_git
 
     def _set_underlying_git(self, git: "GitCommand") -> None:
@@ -55,14 +55,14 @@ class VersionCommandImpl(VersionCommand, GitSubcmdCommandImpl):
         self, build_options: Literal[True, False] = False
     ) -> Version.VersionInfo | Version.VersionWithBuildInfo:
         self._require_valid_args(build_options)
-        main_cmd_args = self.underlying_git.build_main_cmd_args()
+        main_cmd_args = self.git.build_main_cmd_args()
         sub_cmd_args = [VERSION_CMD]
-        env_vars = self.underlying_git.build_git_envs()
+        env_vars = self.git.build_git_envs()
         if build_options:
             sub_cmd_args.append("--build-options")
 
         def rosetta_supplier():
-            return self.underlying_git.runner.run_git_command(
+            return self.git.runner.run_git_command(
                 main_cmd_args,
                 sub_cmd_args,
                 check=True,
@@ -76,7 +76,7 @@ class VersionCommandImpl(VersionCommand, GitSubcmdCommandImpl):
         return VersionCommand.VersionInfoForCmd(rosetta_supplier)
 
     def clone(self) -> "VersionCommandImpl":
-        return VersionCommandImpl(self.underlying_git)
+        return VersionCommandImpl(self.git)
 
 
 class LsTreeCommandImpl(LsTreeCommand, GitSubcmdCommandImpl):
@@ -117,7 +117,7 @@ class LsTreeCommandImpl(LsTreeCommand, GitSubcmdCommandImpl):
         return self._cli_args_builder
 
     def clone(self) -> "LsTreeCommandImpl":
-        return LsTreeCommandImpl(self.root_dir, self.underlying_git)
+        return LsTreeCommandImpl(self.root_dir, self.git)
 
 
 class AddCommandImpl(AddCommand, GitSubcmdCommandImpl):
@@ -150,7 +150,7 @@ class AddCommandImpl(AddCommand, GitSubcmdCommandImpl):
         return self._cli_args_builder
 
     def clone(self) -> "AddCommandImpl":
-        return AddCommandImpl(self.root_dir, self.underlying_git)
+        return AddCommandImpl(self.root_dir, self.git)
 
 
 class UncheckedSubcmdImpl(UncheckedSubcmd, GitSubcmdCommandImpl):
@@ -164,7 +164,7 @@ class UncheckedSubcmdImpl(UncheckedSubcmd, GitSubcmdCommandImpl):
         return self._root_dir
 
     def clone(self) -> "UncheckedSubcmdImpl":
-        return UncheckedSubcmdImpl(self.root_dir, self.underlying_git)
+        return UncheckedSubcmdImpl(self.root_dir, self.git)
 
 
 class SimpleGitCommand(GitCommand, RootDirOp):
@@ -266,8 +266,8 @@ class CLISimpleGitCommand(SimpleGitCommand):
     ):
         """
         :param opts: main git cli options.
-        :param envs: main git cli env vars. Not supplying any env vars (default behavior: ``None``) simply supplies all
-            the env vars to the underlying runner.
+        :param envs: main git cli environment variables (env vars). Not supplying any env
+            vars (default behavior: ``None``) simply supplies all the env vars to the underlying runner.
         :param prefer_cli: cli opts and envs will be given priority over programmatically set opts and envs. Setting
             this param to ``True`` will make cli opts and envs appear later in the opts and envs strings which will
             make them override previously programmatically set opts and envs.

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/subprocess/runner/base.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import pathlib
 from abc import abstractmethod
-from subprocess import CompletedProcess
+from subprocess import CompletedProcess, Popen
 from typing import Protocol, overload, Any, Literal
 
 
@@ -64,6 +64,39 @@ class GitCommandRunner(Protocol):
         **subprocess_run_kwargs: Any,
     ) -> CompletedProcess[bytes]: ...
 
+    @overload
+    @abstractmethod
+    def popen_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *popen_run_args: Any,
+        text: Literal[False],
+        **popen_run_kwargs: Any,
+    ) -> Popen[bytes]: ...
+
+    @overload
+    @abstractmethod
+    def popen_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *popen_run_args: Any,
+        text: Literal[True],
+        **popen_run_kwargs: Any,
+    ) -> Popen[str]: ...
+
+    @abstractmethod
+    def make_cmd(self, main_cmd_args: list[str], sub_cmd_args: list[str]) -> list[str]:
+        """
+        Make command for execution for use in an external subprocess.
+
+        :param main_cmd_args: arguments for the main command.
+        :param sub_cmd_args: arguments for subcommand.
+        :returns: a fully made and runnable command for some external ``subprocess`` call.
+        """
+        ...
+
     @property
     @abstractmethod
     def git_prog(self) -> str | pathlib.Path:

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt/subprocess/runner/simple.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import pathlib
 import subprocess
-from subprocess import CompletedProcess
+from subprocess import CompletedProcess, Popen
 from typing import overload, override, Any, Literal
 
 from gitbolt.subprocess.constants import GIT_CMD
@@ -86,7 +86,7 @@ class SimpleGitCR(GitCommandRunner):
     ) -> CompletedProcess[str] | CompletedProcess[bytes]:
         try:
             return subprocess.run(
-                [str(self.git_prog), *main_cmd_args, *subcommand_args],
+                self.make_cmd(main_cmd_args, subcommand_args),
                 *subprocess_run_args,
                 input=_input,
                 text=text,
@@ -97,6 +97,53 @@ class SimpleGitCR(GitCommandRunner):
                 e.stderr, called_process_error=e, exit_code=e.returncode
             ) from e
 
+    @overload
+    @override
+    def popen_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *popen_run_args: Any,
+        text: Literal[False],
+        **popen_run_kwargs: Any,
+    ) -> Popen[bytes]: ...
+
+    @overload
+    @override
+    def popen_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *popen_run_args: Any,
+        text: Literal[True],
+        **popen_run_kwargs: Any,
+    ) -> Popen[str]: ...
+
+    @override
+    def popen_git_command(
+        self,
+        main_cmd_args: list[str],
+        subcommand_args: list[str],
+        *popen_run_args: Any,
+        text: Literal[True, False],
+        **popen_run_kwargs: Any,
+    ) -> Popen[str] | Popen[bytes]:
+        try:
+            return subprocess.Popen(
+                self.make_cmd(main_cmd_args, subcommand_args),
+                *popen_run_args,
+                text=text,
+                **popen_run_kwargs,
+            )
+        except subprocess.CalledProcessError as e:
+            raise GitCmdException(
+                e.stderr, called_process_error=e, exit_code=e.returncode
+            ) from e
+
+    @override
+    def make_cmd(self, main_cmd_args: list[str], sub_cmd_args: list[str]) -> list[str]:
+        return [str(self.git_prog), *main_cmd_args, *sub_cmd_args]
+
     @override
     @property
     def git_prog(self) -> str | pathlib.Path:

{gitbolt-0.0.0.dev14 → gitbolt-0.0.0.dev16}/src/gitbolt.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitbolt
-Version: 0.0.0.dev14
+Version: 0.0.0.dev16
 Summary: Fast, flexible and type-safe Git commands in Python.
 Author-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
 Maintainer-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
@@ -114,9 +114,8 @@ Gitbolt lets you pass subcommands around as typed objects. This enables highly f
 
 ```python
 import gitbolt
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 version_subcmd = git.version_subcmd
 add_subcmd = git.add_subcmd
 
@@ -136,11 +135,11 @@ method_which_only_adds_a_file(add_subcmd)
 git subcommands are modeled as terminal functions that return stdout.
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
-status_out = git.status_subcmd.status()
-print(status_out)
+git = gitbolt.get_git()
+version_stdout = git.version_subcmd.version().version()
+print(version_stdout)
 ```
 
 ### 🪼 Modular Architecture
@@ -206,9 +205,9 @@ Extensive use of type-hints ensures that invalid usages fail early — at *compi
 #### 🔁 Override a single Git env (e.g., `GIT_TRACE`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=True)
 ```
 
@@ -216,9 +215,9 @@ git = git.git_envs_override(GIT_TRACE=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')
 ```
 
@@ -226,9 +225,9 @@ git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDIT
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(
     GIT_TERMINAL_PROMPT=1,
     GIT_NO_REPLACE_OBJECTS=True
@@ -239,10 +238,10 @@ re_overridden_git = overridden_git.git_envs_override(GIT_TRACE=True)
 #### ❌ Unset Git envs using a special `UNSET` marker
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)
 no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 ```
@@ -250,9 +249,9 @@ no_advice_unset_git = overridden_git.git_envs_override(GIT_TRACE=UNSET)
 #### 🔄 Reset Git envs by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_envs_override(GIT_TRACE=True)
 git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 ```
@@ -268,9 +267,9 @@ git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
 #### 🔁 Override a single Git opt (e.g., `--no-replace-objects`)
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 git = git.git_opts_override(no_replace_objects=True)
 ```
 
@@ -278,7 +277,7 @@ git = git.git_opts_override(no_replace_objects=True)
 
 ```python
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+from gitbolt.subprocess.impl.simple import SimpleGitCommand
 
 git = SimpleGitCommand()
 git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)
@@ -287,10 +286,10 @@ git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=Tr
 #### 🪢 Chain multiple option overrides fluently
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(
     noglob_pathspecs=True,
     no_advice=True
@@ -303,11 +302,11 @@ re_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)
 #### ❌ Unset Git opts using a special `UNSET` marker
 
 ```python
+import gitbolt
 from pathlib import Path
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
 from vt.utils.commons.commons.core_py import UNSET
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(exec_path=Path('tmp'), no_advice=True)
 no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 ```
@@ -315,9 +314,9 @@ no_advice_unset_git = overridden_git.git_opts_override(no_advice=UNSET)
 #### 🔄 Reset Git opts by setting new values
 
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git()
 overridden_git = git.git_opts_override(no_advice=True)
 no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 ```
@@ -328,33 +327,59 @@ no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 
 At last, run unchecked commands in git.
 
-Introduced in `0.0.0dev4` to 
+Introduced in `0.0.0.dev4` to 
 - experiment.
 - have consistent interfaced commands run until all subcommands are provided by the library.
 
+#### 🖥️ Run one process per command
+
 ```python
-from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+import gitbolt
 
-git = SimpleGitCommand()
+git = gitbolt.get_git_command()
 git = git.git_opts_override(no_advice=True)
 git.subcmd_unchecked.run(['--version']) # run the version option for git.
 git.subcmd_unchecked.run(['version']) # run the version subcommand.
 ```
 
+#### 🖥️ Run one long-running process and communicate with it
+
+Introduced in `0.0.0.dev16` to:
+- Make communicable processes using `subprocess.Popen`.
+
+Get a long-running process and communicate with it for batching and faster operations.
+
+```python
+import gitbolt
+import sys
+
+git = gitbolt.get_git_command()
+with git.subcmd_unchecked.popen(["cat-file", "--batch-command"]) as cf:
+    cf.stdin.write(b"contents HEAD\n")
+    cf.stdin.flush()
+    header = cf.stdout.readline().strip()
+    print(f"HEADER: {header}", file=sys.stderr)
+    obj, typ, size = header.split()
+    print(cf.stdout.read(int(size)))
+    cf.stdout.readline()
+```
+
+Error handling and I/O management is left to the client/caller.
+
 #### 💻 Run commands received from CLI
 
-Introduced in `0.0.0dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
+Introduced in `0.0.0.dev11` is the ability to take commands from CLI and run it inside `gitbolt`.
 
 While making a system it may be required to run cli commands as received from cli using gitbolt. An obvious example 
 would be to make a system that receives CLI commands and does certain modifications/additions inside `gitbolt` before
 actually running them. An example:
 
 ```python
-from gitbolt.git_subprocess.impl.simple import CLISimpleGitCommand
+import gitbolt
 
-opts = ["--no-pager", "--namespace", "n1"]   # options received from outside your program.
-envs = dict(GIT_AUTHOR_NAME="ss")   # env-vars received form outside your program.
-git = CLISimpleGitCommand(opts=opts, envs=envs)
+opts = ["--no-pager", "--namespace", "n1"]  # options received from outside your program.
+envs = dict(GIT_AUTHOR_NAME="ss")  # env-vars received form outside your program.
+git = gitbolt.get_git_command(opts=opts, envs=envs)
 
 # these can later be overridden
 git = git.git_opts_override(namespace="n2")