gitbolt 0.0.0.dev17__tar.gz → 0.0.0.dev19__tar.gz

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitbolt
-Version: 0.0.0.dev17
+Version: 0.0.0.dev19
 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>
@@ -146,7 +146,7 @@ print(version_stdout)
 
 #### 🧑‍💻 Modular at the programmatic level
 
-Commands are designed to be passed around as objects. This makes them modular and thus users can opt to use only 
+Commands are designed to be passed around as objects. This makes them modular and thus users can opt to use only
 particular commands.
 
 ```python
@@ -327,7 +327,7 @@ no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 
 At last, run unchecked commands in git.
 
-Introduced in `0.0.0.dev4` to 
+Introduced in `0.0.0.dev4` to
 - experiment.
 - have consistent interfaced commands run until all subcommands are provided by the library.
 
@@ -366,11 +366,47 @@ with git.subcmd_unchecked.popen(["cat-file", "--batch-command"]) as cf:
 
 Error handling and I/O management is left to the client/caller.
 
+#### 🏃 Communicate with long-running git sessions
+
+Introduced in `0.0.0.dev17` to:
+- Make long-running git command sessions.
+- Have reentrant sessions.
+- Communicate with long-running git command session using their `stdin` and `stdout`.
+
+Get long-running process sessions and communicate with them for batching and faster operations.
+
+```python
+import gitbolt
+from gitbolt.subprocess.utils.session import cat_file_blob_content, cat_file_tree_data, cat_file_tree_content, \
+    mktree_tree_make
+
+git = gitbolt.get_git_command()
+with git.session(
+        cat_file1=["cat-file", "--batch"],
+        cat_file2=["cat-file", "--batch"],
+        cat_file3=lambda: git.subcmd_unchecked.popen(["cat-file", "--batch"]),  # pass your own git subcmd Popen(s)
+        mktree=["mktree", "--batch", "-z"]
+) as ses:
+    tree_data: list[bytes] = []
+    for mode_, sha_, name_ in cat_file_tree_data(ses.commands.cat_file2, b"HEAD^{tree}"):
+        print(mode_, sha_, name_)
+    for tree_entry in cat_file_tree_content(ses.commands.cat_file2, b"HEAD^{tree}"):
+        tree_data.append(tree_entry)
+    print("+" * 40)
+    print(cat_file_blob_content(ses.commands.cat_file3, b"9854cb4d432a881f59d38582791cf2636e7819d9"))
+    print("~" * 40)
+    with ses:  # is reentrant, if you want
+        tree_hash = mktree_tree_make(ses.commands.mktree, b"\0".join(tree_data))    # make tree
+        print("Obtained tree: ", tree_hash)
+
+assert not ses.active  # session no long active
+```
+
 #### 💻 Run commands received from CLI
 
 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 
+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:
 

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/README.md

@@ -110,7 +110,7 @@ print(version_stdout)
 
 #### 🧑‍💻 Modular at the programmatic level
 
-Commands are designed to be passed around as objects. This makes them modular and thus users can opt to use only 
+Commands are designed to be passed around as objects. This makes them modular and thus users can opt to use only
 particular commands.
 
 ```python
@@ -291,7 +291,7 @@ no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
 
 At last, run unchecked commands in git.
 
-Introduced in `0.0.0.dev4` to 
+Introduced in `0.0.0.dev4` to
 - experiment.
 - have consistent interfaced commands run until all subcommands are provided by the library.
 
@@ -330,11 +330,47 @@ with git.subcmd_unchecked.popen(["cat-file", "--batch-command"]) as cf:
 
 Error handling and I/O management is left to the client/caller.
 
+#### 🏃 Communicate with long-running git sessions
+
+Introduced in `0.0.0.dev17` to:
+- Make long-running git command sessions.
+- Have reentrant sessions.
+- Communicate with long-running git command session using their `stdin` and `stdout`.
+
+Get long-running process sessions and communicate with them for batching and faster operations.
+
+```python
+import gitbolt
+from gitbolt.subprocess.utils.session import cat_file_blob_content, cat_file_tree_data, cat_file_tree_content, \
+    mktree_tree_make
+
+git = gitbolt.get_git_command()
+with git.session(
+        cat_file1=["cat-file", "--batch"],
+        cat_file2=["cat-file", "--batch"],
+        cat_file3=lambda: git.subcmd_unchecked.popen(["cat-file", "--batch"]),  # pass your own git subcmd Popen(s)
+        mktree=["mktree", "--batch", "-z"]
+) as ses:
+    tree_data: list[bytes] = []
+    for mode_, sha_, name_ in cat_file_tree_data(ses.commands.cat_file2, b"HEAD^{tree}"):
+        print(mode_, sha_, name_)
+    for tree_entry in cat_file_tree_content(ses.commands.cat_file2, b"HEAD^{tree}"):
+        tree_data.append(tree_entry)
+    print("+" * 40)
+    print(cat_file_blob_content(ses.commands.cat_file3, b"9854cb4d432a881f59d38582791cf2636e7819d9"))
+    print("~" * 40)
+    with ses:  # is reentrant, if you want
+        tree_hash = mktree_tree_make(ses.commands.mktree, b"\0".join(tree_data))    # make tree
+        print("Obtained tree: ", tree_hash)
+
+assert not ses.active  # session no long active
+```
+
 #### 💻 Run commands received from CLI
 
 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 
+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:
 

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gitbolt"
-version = "0.0.0.dev17"
+version = "0.0.0.dev19"
 description = "Fast, flexible and type-safe Git commands in Python."
 requires-python = ">=3.12"
 readme = "README.md"

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/src/gitbolt/__init__.py

@@ -17,6 +17,7 @@ from gitbolt.base import LsTree as LsTree
 from gitbolt.base import Version as Version
 from gitbolt.base import Add as Add
 from gitbolt.subprocess.base import GitCommand
+from gitbolt.subprocess.base import GitSession as GitSession
 # endregion
 
 

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/src/gitbolt/subprocess/base.py

@@ -7,6 +7,7 @@ Git command interfaces with default implementation using subprocess calls.
 
 from __future__ import annotations
 
+import sys
 from abc import abstractmethod, ABC
 from collections.abc import Callable
 from contextlib import AbstractContextManager
@@ -306,8 +307,7 @@ class GitCommand(Git, ABC):
     @abstractmethod
     def session(self, **commands: list[str] | Callable[[], Popen[bytes]]) -> GitSession:
         """
-        Run long-running git session with multiple unchecked subcommands using ``subprocess.Popen`` and
-        communicate with them.
+        Run long-running git session with multiple unchecked subcommands using ``subprocess.Popen`` and communicate with them.
 
         Client/Caller can communicate with ``GitSession``'s processes with their stdin and stdout.
 
@@ -326,65 +326,155 @@ class GitCommand(Git, ABC):
         >>> with _git.session(cat_file=["cat-file", "--batch"]) as ses: # obtain, start and ctx manage the session.
         ...     pass    # any communication can be done by Popen semantics.
 
+        Run special Popen:
+
+        >>> import gitbolt
+        >>> _git = gitbolt.get_git_command()
+        >>> ses = _git.session(ls_tree=["ls-tree", "HEAD"],
+        ...                     cat_file=lambda : _git.subcmd_unchecked.popen(["cat-file", "--batch"], env=None))
+        >>> with ses:   # start the session by ctx mgr
+        ...     pass    # any communication can be done by Popen semantics.
+
+        Is reentrant:
+
+        >>> import gitbolt
+        >>> _git = gitbolt.get_git_command()
+        >>> ses = _git.session(cat_file=["cat-file", "--batch-check"])
+        >>> with ses:   # start the session by ctx mgr
+        ...     with ses:   # reentrant
+        ...         pass
+        ...     pass    # any communication can be done by Popen semantics.
+
+
+       Note: All commands/processes are assumed:
+
+       - in bytes mode.
+       - pipe their stdin and stdout.
+
         :param commands: list of string git commands suppliable to ``subprocess.Popen`` or ``subprocess.Popen`` lambdas.
         :returns: A (not yet started) long-running ``GitSession`` context manager.
         """
         ...
 
 
+# TODO: extract a base session class from this
 class GitSession(HasGitUnderneath[GitCommand], AbstractContextManager):
-
     def __init__(self, git: GitCommand, **commands: Callable[[], Popen[bytes]]):
         """
-        Context Manager to start a git long-running session. Useful when a command is to be held in open state and be
-        communicated with its stdin and stdout. This is way faster that spawning multiple processes each time.
+        Reusable and reentrant context Manager to start a git long-running session. Useful when a command is to be
+        held in open state and be communicated with its stdin and stdout. This is way faster that spawning multiple
+        processes each time.
 
         Examples:
 
         Obtain a session:
 
         >>> import gitbolt
+        >>> from gitbolt.subprocess.base import GitSession
         >>> _git = gitbolt.get_git_command()
-        >>> ses = _git.session(ls_tree=["ls-tree", "HEAD"], cat_file=["cat-file", "--batch"])
+        >>> ses = GitSession(_git, ls_tree= lambda : _git.subcmd_unchecked.popen(["ls-tree", "HEAD"], text=False),
+        ...                 cat_file= lambda : _git.subcmd_unchecked.popen(["cat-file", "--batch"], text=False))
         >>> with ses:   # start the session by ctx mgr
         ...     pass    # any communication can be done by Popen semantics.
 
         Start the session in one go:
 
-        >>> with _git.session(cat_file=["cat-file", "--batch"]) as ses: # obtain, start and ctx manage the session.
+        >>> with GitSession(_git, cat_file= lambda : _git.subcmd_unchecked.popen(["cat-file", "--batch"], text=False)) as ses: # obtain, start and ctx manage the session.
         ...     pass    # any communication can be done by Popen semantics.
 
+
+       Note: All processes are assumed:
+
+       - in bytes mode.
+       - pipe their stdin and stdout.
+
         :param git: ``gitbolt.subprocess.GitCommand`` instance.
         :param commands: commands in kwargs fashion.
         """
         self._git = git
         self.unstarted_commands: dict[str, Callable[[], Popen[bytes]]] = commands
         self.started_commands: dict[str, Popen[bytes]] = dict()
-        self.commands: SimpleNamespace | None = None
+        self._commands: SimpleNamespace | None = None
+        self.__started = False
+        self.__done = False
+        self.__depth = 0
 
+    @override
     def __enter__(self) -> Self:
-        processes_started_keys: list[str] = []
-        for unstarted_command_key, unstarted_command in self.unstarted_commands.items():
-            self.started_commands[unstarted_command_key] = unstarted_command().__enter__()
-            processes_started_keys.append(unstarted_command_key)
-        self.commands = SimpleNamespace(**self.started_commands)
-        for pk in processes_started_keys:
-            del self.unstarted_commands[pk]
+        if self.depth == 0:
+            processes_started_keys: list[str] = []
+            for unstarted_command_key, unstarted_command in self.unstarted_commands.items():
+                try:
+                    self.started_commands[unstarted_command_key] = unstarted_command().__enter__()
+                except Exception:
+                    for k in reversed(processes_started_keys):
+                        self.started_commands[k].__exit__(*sys.exc_info())
+                    raise
+                processes_started_keys.append(unstarted_command_key)
+            self._commands = SimpleNamespace(**self.started_commands)
+            for pk in processes_started_keys:
+                del self.unstarted_commands[pk]
+            self.__started = True
+        self.__depth += 1
+        return self
 
+    @override
     @property
     def git(self) -> GitCommand:
         return self._git
 
-    def __exit__(self, exc_type, exc_value, traceback, /):
-        process_done_keys: list[str] = []
-        for started_popen_key, started_popen in self.started_commands.items():
-            started_popen.__exit__(exc_type, exc_value, traceback)
-            process_done_keys.append(started_popen_key)
-        self.commands = None
-        for pk in process_done_keys:
-            del self.started_commands[pk]
+    @override
+    def __exit__(self, exc_type, exc_value, traceback, /) -> Literal[False]:
+        self.__depth -= 1
+        if self.__depth == 0:
+            process_done_keys: list[str] = []
+            for started_popen_key, started_popen in self.started_commands.items():
+                started_popen.__exit__(exc_type, exc_value, traceback)
+                process_done_keys.append(started_popen_key)
+            self._commands = None
+            for pk in process_done_keys:
+                del self.started_commands[pk]
+            self.__done = True
         return False
 
+    @property
+    def started(self) -> bool:
+        """
+        :returns: Whether the session has started.
+        """
+        return self.__started
+
+    @property
+    def done(self) -> bool:
+        """
+        :returns: Whether the session has completed and thus exited/closed.
+        """
+        return self.__done
+
+    @property
+    def active(self) -> bool:
+        """
+        :returns: Whether the session is currently actively running.
+        """
+        return self.started and not self.done
+
+    @property
+    def commands(self) -> SimpleNamespace:
+        """
+        :returns: All the registered commands and these can be accessed by member notations.
+        :raises RuntimeError: if commands are queried when the session is inactive.
+        """
+        if self._commands is None or not self.active:
+            raise RuntimeError("GitSession not active")
+        return self._commands
+
+    @property
+    def depth(self) -> int:
+        """
+        :returns: The current session depth. Multilevel context managers increment the depth each y one.
+        """
+        return self.__depth
+
 
 class GitSubcmdCommand(GitSubCommand, HasGitUnderneath["GitCommand"], Protocol):
     """
@@ -696,30 +786,30 @@ class UncheckedSubcmd(GitSubcmdCommand, RootDirOp, Protocol):
         self,
         subcommand_args: list[str],
         *popen_args: Any,
-        text: Literal[True] = True,
+        text: Literal[False] = False,
         **popen_kwargs: Any,
-    ) -> Popen[str]: ...
+    ) -> Popen[bytes]: ...
 
     @overload
     def popen(
         self,
         subcommand_args: list[str],
         *popen_args: Any,
-        text: Literal[False] = False,
+        text: Literal[True] = True,
         **popen_kwargs: Any,
-    ) -> Popen[bytes]: ...
+    ) -> Popen[str]: ...
 
     def popen(
         self,
         subcommand_args: list[str],
         *popen_args: Any,
-        text: Literal[True, False] = False,
+        text: Literal[False, True] = 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.
+        All the arguments are congruent to ``subprocess.Popen`` and mostly pass as-is.
 
         :param subcommand_args: the full subcommand argument list.
         :param popen_args: additional subprocess positionals.
@@ -734,7 +824,6 @@ class UncheckedSubcmd(GitSubcmdCommand, RootDirOp, Protocol):
         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,
@@ -746,7 +835,6 @@ class UncheckedSubcmd(GitSubcmdCommand, RootDirOp, Protocol):
             stdin=stdin,
             stdout=stdout,
             stderr=stderr,
-            bufsize=bufsize,
             **popen_kwargs,
         )
         return result

{gitbolt-0.0.0.dev17 → gitbolt-0.0.0.dev19}/src/gitbolt/subprocess/impl/simple.py

@@ -170,7 +170,6 @@ class UncheckedSubcmdImpl(UncheckedSubcmd, GitSubcmdCommandImpl):
 
 
 class SimpleGitCommand(GitCommand, RootDirOp):
-
     def __init__(
         self,
         git_root_dir: Path = Path.cwd(),
@@ -250,11 +249,17 @@ class SimpleGitCommand(GitCommand, RootDirOp):
 
     def session(self, **commands: list[str] | Callable[[], Popen[bytes]]) -> GitSession:
         cmds: dict[str, Callable[[], Popen[bytes]]] = {}
+
+        # curb the lambda-late-binding-trap
+        # resource: https://medium.com/skiller-whale/late-binding-variables-its-a-trap-c17af980164f
+        def lambda_for_subcmd_popen(_runnable_cmd: list[str]):
+            return lambda: self.subcmd_unchecked.popen(_runnable_cmd)
+
         for cmd_name, runnable_cmd in commands.items():
             if callable(runnable_cmd):
                 cmds[cmd_name] = runnable_cmd
             else:
-                cmds[cmd_name] = lambda : self.subcmd_unchecked.popen(runnable_cmd, text=False)
+                cmds[cmd_name] = lambda_for_subcmd_popen(runnable_cmd)
         return GitSession(self, **cmds)
 
 

gitbolt-0.0.0.dev19/src/gitbolt/subprocess/utils/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Utilities related to processors specific to git commands using subprocess.
+"""

gitbolt-0.0.0.dev19/src/gitbolt/subprocess/utils/models.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Models useful for session utilities.
+"""
+import dataclasses
+import datetime
+
+
+@dataclasses.dataclass
+class GitRawActor:
+    name: bytes
+    email: bytes
+    time: datetime.datetime
+
+    @classmethod
+    def from_commit_bytes(cls, commit_bytes: bytes, email_start_pattern: bytes = b" <",
+                          email_end_pattern: bytes = b"> ") -> "GitRawActor":
+        """
+        Obtain ``Actor`` object from the author/committer bytes.
+
+        Examples:
+
+        Simple timestamp without timezone:
+
+        >>> _ss_actor1 = GitRawActor.from_commit_bytes(b"Suhas <sss@ss.ss> 1780211249")
+        >>> assert _ss_actor1.name == b"Suhas"
+        >>> assert _ss_actor1.email == b"sss@ss.ss"
+        >>> assert _ss_actor1.time.timestamp() == 1780211249.0
+
+        Simple timestamp with timezone:
+
+        >>> _ss_actor2 = GitRawActor.from_commit_bytes(b"Suhas Srivastava <sss@vaastav.tech> 1780211249 +0530")
+        >>> assert _ss_actor2.name == b"Suhas Srivastava"
+        >>> assert _ss_actor2.email == b"sss@vaastav.tech"
+        >>> assert _ss_actor2.time.timestamp() == 1780211249.0
+
+        :param commit_bytes: author/committer information in bytes form.
+        :param email_start_pattern: email spearates name and timestamp. Thus is required as a separator.
+            Marks email beginning.
+        :param email_end_pattern: email spearates name and timestamp. Thus is required as a separator.
+            Marks email ending.
+        :returns: ``Actor`` object with all the parsed and set values.
+        """
+        email_pattern_start_index = commit_bytes.find(email_start_pattern)
+        email_pattern_end_index = commit_bytes.rfind(email_end_pattern)
+        email_start_index = email_pattern_start_index+len(email_start_pattern)
+        email_end_index = email_pattern_end_index
+        name = commit_bytes[:email_pattern_start_index]
+        email = commit_bytes[email_start_index:email_end_index]
+        time_bytes = commit_bytes[email_end_index+len(email_end_pattern):]
+        time_main, time_zone = time_bytes.split() if b" " in time_bytes else (time_bytes, b"")
+        date_time_for_iso_str = datetime.datetime.fromtimestamp(int(time_main))
+        date_time = datetime.datetime.fromisoformat(f"{date_time_for_iso_str.date()}T{date_time_for_iso_str.time()}{time_zone.decode()}")
+        return GitRawActor(name, email, date_time)
+
+
+@dataclasses.dataclass
+class GitRawSignature:
+    signature: bytes
+
+
+@dataclasses.dataclass
+class GPGGitRawSignature(GitRawSignature):
+    pass
+
+
+@dataclasses.dataclass
+class SSHGitRawSignature(GitRawSignature):
+    pass
+
+
+@dataclasses.dataclass
+class RawCommitBytesObj:
+    """
+    Commit info all in bytes as read from ``git cat-file --batch``.
+    """
+    commit_hash: bytes
+    tree_hash: bytes
+    parents: list[bytes]
+    author: GitRawActor
+    committer: GitRawActor
+    signature: GitRawSignature | None
+    message: bytes
+
+
+@dataclasses.dataclass
+class RawBytesValsOfCommit:
+    tree_val: bytes
+    commit_parents_vals: list[bytes]
+    author_val: bytes
+    committer_val: bytes
+    signature_val: bytes | None
+    commit_message: bytes