gitbolt 0.0.0.dev1__py3-none-any.whl

gitbolt/utils.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Utility functions related to processors specific to git commands.
+"""
+
+from __future__ import annotations
+
+
+from gitbolt.models import GitOpts, GitEnvVars
+
+
+def merge_git_opts(primary: GitOpts, fallback: GitOpts) -> GitOpts:
+    """
+    Merge the ``primary`` and ``fallback`` ``GitOpts`` object and return a new ``GitOpts`` object.
+
+    Construction of the new ``GitOpts`` object is done such that:
+
+    * first prioritise picking up a property from the ``primary``.
+    * if a property is ``None`` in the ``primary`` then that corresponding property is picked from the ``fallback``.
+
+    Example usage:
+
+    >>> from pathlib import Path
+    >>> from typing import cast
+    >>> _primary = cast(GitOpts, {
+    ...     "C": [Path("/repo")],
+    ...     "c": {"user.name": "Alice", "color.ui": None},
+    ...     "paginate": True,
+    ...     "no_pager": None,
+    ...     "exec_path": None,
+    ...     "git_dir": Path("/repo/.git"),
+    ...     "work_tree": None,
+    ...     "bare": None,
+    ...     "namespace": None
+    ... })
+    >>> _fallback = cast(GitOpts, {
+    ...     "C": [Path("/fallback")],
+    ...     "c": {"user.name": "Bob", "core.editor": "vim"},
+    ...     "paginate": False,
+    ...     "no_pager": True,
+    ...     "exec_path": Path("/usr/lib/git-core"),
+    ...     "git_dir": None,
+    ...     "work_tree": Path("/fallback"),
+    ...     "bare": True,
+    ...     "namespace": "fallback-ns"
+    ... })
+    >>> _merged = merge_git_opts(_primary, _fallback)
+    >>> _merged["C"] == [Path("/repo")]
+    True
+    >>> _merged["c"]
+    {'user.name': 'Alice', 'color.ui': None}
+    >>> _merged["paginate"]
+    True
+    >>> _merged["no_pager"]
+    True
+    >>> _merged["exec_path"] == Path("/usr/lib/git-core")
+    True
+    >>> _merged["git_dir"] == Path("/repo/.git")
+    True
+    >>> _merged["work_tree"] == Path("/fallback")
+    True
+    >>> _merged["bare"]
+    True
+    >>> _merged["namespace"]
+    'fallback-ns'
+
+    Empty example:
+
+    >>> merge_git_opts({}, {})
+    {}
+
+    Partial fallback behavior:
+
+    >>> merge_git_opts({"paginate": None}, {"paginate": True})["paginate"]
+    True
+    >>> 'paginate' in merge_git_opts({"paginate": None}, {"paginate": None})
+    False
+    >>> merge_git_opts({"paginate": False}, {"paginate": True})["paginate"]
+    False
+
+    :param primary: The first priority ``GitOpts`` object.
+    :param fallback: the second priority or fallback ``GitOpts`` object.
+    :return: A new ``GitOpts`` object that contains all the properties from the ``primary`` ``GitOpts`` object and
+        fallbacks on the corresponding property from the ``fallback`` ``GitOpts`` object if that corresponding property
+        is ``None`` in the ``primary`` ``GitOpts`` object.
+    """
+    return merge_typed_dicts(primary, fallback, GitOpts)
+
+
+def merge_git_envs(primary: GitEnvVars, fallback: GitEnvVars) -> GitEnvVars:
+    """
+    Merge the ``primary`` and ``fallback`` ``GitEnvVars`` objects and return a new ``GitEnvVars`` object.
+
+    Construction of the new ``GitEnvVars`` object is done such that:
+
+    * values from ``primary`` are prioritized.
+    * if a key exists in both, and the value in ``primary`` is explicitly ``None``, then the value from ``fallback`` is used.
+    * if a value in ``primary`` is ``Unset``, it is retained and does not fall back.
+    * any keys missing from ``primary`` but present in ``fallback`` are included.
+
+    Example usage:
+
+    >>> from pathlib import Path
+    >>> from datetime import datetime
+    >>> from typing import cast
+    >>> _primary = cast(GitEnvVars, {
+    ...     "GIT_AUTHOR_NAME": "Alice",
+    ...     "GIT_AUTHOR_EMAIL": "alice@example.com",
+    ...     "GIT_COMMITTER_DATE": None,
+    ...     "GIT_EDITOR": None,
+    ...     "GIT_TRACE": 2,
+    ...     "GIT_SSH": Path("/usr/bin/ssh"),
+    ... })
+    >>> _fallback = cast(GitEnvVars, {
+    ...     "GIT_AUTHOR_NAME": "Bob",
+    ...     "GIT_AUTHOR_EMAIL": "bob@example.com",
+    ...     "GIT_COMMITTER_DATE": datetime(2020, 1, 1),
+    ...     "GIT_EDITOR": "vim",
+    ...     "GIT_TRACE": Path("/tmp/trace.log"),
+    ...     "GIT_SSH": None,
+    ...     "GIT_CONFIG_GLOBAL": Path("/home/bob/.gitconfig"),
+    ...     "GIT_REDACT_COOKIES": "sessionid"
+    ... })
+    >>> _merged = merge_git_envs(_primary, _fallback)
+    >>> _merged["GIT_AUTHOR_NAME"]
+    'Alice'
+    >>> _merged["GIT_AUTHOR_EMAIL"]
+    'alice@example.com'
+    >>> _merged["GIT_COMMITTER_DATE"]
+    datetime.datetime(2020, 1, 1, 0, 0)
+    >>> _merged["GIT_EDITOR"]
+    'vim'
+    >>> _merged["GIT_TRACE"]
+    2
+    >>> _merged["GIT_SSH"]==Path('/usr/bin/ssh')
+    True
+    >>> _merged["GIT_CONFIG_GLOBAL"]==Path('/home/bob/.gitconfig')
+    True
+
+    Empty example:
+
+    >>> empty = merge_git_envs({}, {})
+    >>> isinstance(empty, dict)
+    True
+
+    Partial fallback behavior:
+
+    >>> merge_git_envs({"GIT_EDITOR": None}, {"GIT_EDITOR": "nano"})["GIT_EDITOR"]
+    'nano'
+    >>> 'GIT_EDITOR' in merge_git_envs({"GIT_EDITOR": None}, {"GIT_EDITOR": None})
+    False
+    >>> merge_git_envs({"GIT_EDITOR": "code"}, {"GIT_EDITOR": "nano"})["GIT_EDITOR"]
+    'code'
+
+    >>> from vt.utils.commons.commons.core_py import Unset, UNSET
+    >>> merge_git_envs({"GIT_EDITOR": UNSET}, {"GIT_EDITOR": "nano"})["GIT_EDITOR"] is UNSET
+    True
+
+    :param primary: The first priority ``GitEnvVars`` object.
+    :param fallback: The second priority or fallback ``GitEnvVars`` object.
+    :return: A new ``GitEnvVars`` object that contains all the properties from the ``primary`` ``GitEnvVars`` object and
+        fallbacks on the corresponding property from the ``fallback`` ``GitEnvVars`` object if that corresponding property
+        is explicitly ``None`` in the ``primary`` ``GitEnvVars`` object.
+    """
+    return merge_typed_dicts(primary, fallback, GitEnvVars)
+
+
+# TODO: check for typing this function
+def merge_typed_dicts(primary, fallback, the_typed_dict):
+    merged = {}
+    for k in the_typed_dict.__annotations__.keys():  # type: ignore
+        val = primary.get(k)  # type: ignore # required as mypy thinks k is not str
+        if val is None:
+            val = fallback.get(k)  # type: ignore # required as mypy thinks k is not str
+        if val is not None:
+            merged[k] = val  # type: ignore # required as mypy thinks k is not str
+    return merged

gitbolt-0.0.0.dev1.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: gitbolt
+Version: 0.0.0.dev1
+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>
+License-Expression: Apache-2.0
+Project-URL: homepage, https://github.com/Vaastav-Technologies/py-gitbolt
+Project-URL: source, https://github.com/Vaastav-Technologies/py-gitbolt
+Project-URL: issues, https://github.com/Vaastav-Technologies/py-gitbolt/issues
+Keywords: git,vcs,library,version control
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: vt-err-hndlr==0.0.0dev1
+Provides-Extra: pygit2
+Requires-Dist: pygit2; extra == "pygit2"
+Dynamic: license-file
+
+# 🚀 Gitbolt
+
+![PyPI - Types](https://img.shields.io/pypi/types/gitbolt)
+![GitHub License](https://img.shields.io/github/license/Vaastav-Technologies/py-gitbolt)
+[![🔧 test](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/test.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/test.yml)
+[![💡 typecheck](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/typecheck.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/typecheck.yml)
+[![🛠️ lint](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/lint.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/lint.yml)
+[![📊 coverage](https://codecov.io/gh/Vaastav-Technologies/py-gitbolt/branch/main/graph/badge.svg)](https://codecov.io/gh/Vaastav-Technologies/py-gitbolt)
+[![📤 Upload Python Package](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-gitbolt/actions/workflows/python-publish.yml)
+![PyPI - Version](https://img.shields.io/pypi/v/gitbolt)
+
+**Fast, flexible and type-safe Git command execution in Python using subprocess.**
+
+---
+
+## ✨ Features
+
+* 🧠 **Typed:** All commands and options are statically type-checked.
+* ⚡ **Fast:** Minimal abstractions over subprocess, runs directly on your system Git.
+* 🧩 **Composable:** Git commands and options can be passed around as objects.
+* 🔁 **Overridable:** Easily override environment variables and options in a chainable, readable manner.
+* 📦 **Lightweight:** No dependencies on heavy Git libraries or C extensions.
+* 🧰 **Extensible:** Future support for output transformers and other plugins.
+* 🚨 **Exception Handling:** Raises any error as a Python-recognisable exception.
+* 📤 **Debuggable:** Exceptions capture `stdout`, `stderr`, and the return code of the run command.
+* 💤 **Lazy Execution:** Inherently lazily processed.
+* 📄 **Transparent Output:** Returns a Git command's `stdout` as-is.
+* 🧪 **Terminal Functions:** Git subcommands are terminal functions.
+* 🧼 **Idiomatic Python:** Write commands in idiomatic Python at compile-time and be confident they’ll execute smoothly at runtime.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install gitbolt
+```
+
+---
+
+## 💡 Motivation
+
+Running system commands in Python can be tricky for the following reasons:
+
+1. Arguments sent to `subprocess` may not be typed correctly and result in runtime errors.
+2. Argument groups may be mutually exclusive or required conditionally — again causing runtime issues.
+3. Errors from subprocess are often unhelpful and difficult to debug.
+
+Also, using subprocess effectively means you must:
+
+* Understand and manage process setup, piping, and teardown.
+* Know your CLI command intricacies in depth.
+
+> This project exists to fix all that — with ergonomics, speed, and type-safety.
+
+---
+
+## 🎯 Project Goals
+
+### ✅ Predictable Compile-Time Behavior
+
+Type-checking ensures runtime safety.
+
+### ✅ Ergonomic APIs
+
+<details>
+<summary>Make git command interfaces as ergonomic to the user as possible.</summary>
+
+#### Provide versions of most used command combinations
+
+`git hash-object` supports taking multiple files and outputs a hash per file. But in practice, it's most often used to write a single file to the Git object database and return its hash. To match this real-world usage, Gitbolt offers a more ergonomic method that accepts one file and returns one hash — while still giving you the flexibility to access the full range of `git hash-object` capabilities when needed.
+
+#### Let subcommands be passed around as objects
+
+Gitbolt lets you pass subcommands around as typed objects. This enables highly focused, minimal APIs — you can write functions that accept only the subcommands they truly need. This leads to cleaner logic, better separation of concerns, and compile-time guarantees that help prevent misuse.
+
+```python
+import gitbolt
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+version_subcmd = git.version_subcmd
+add_subcmd = git.add_subcmd
+
+def method_which_only_adds_a_file(add_subcmd: gitbolt.base.Add):
+    """
+    This method only requires the `add` subcommand.
+    """
+    ...
+
+method_which_only_adds_a_file(add_subcmd)
+```
+
+</details>
+
+### ✅ Subcommands as Objects
+
+git subcommands are modeled as terminal functions that return stdout.
+
+```python
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+status_out = git.status_subcmd.status()
+print(status_out)
+```
+
+---
+
+## 🧠 Strong Typing Everywhere
+
+Extensive use of type-hints ensures that invalid usages fail early — at *compile-time*. Write at compile-time and be sure that commands run error-free at runtime.
+
+---
+
+<details>
+<summary>Allow users to set/unset/reset Git environment variables and main command options using typed, chainable, Pythonic methods — just before a subcommand is executed.</summary>
+
+### 🧬 Git Environment Variables
+
+#### 🔁 Override a single Git env (e.g., `GIT_TRACE`)
+
+```python
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+git = git.git_envs_override(GIT_TRACE=True)
+```
+
+#### 🌐 Override multiple Git envs (e.g., `GIT_TRACE`, `GIT_DIR`, `GIT_EDITOR`)
+
+```python
+from pathlib import Path
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+git = git.git_envs_override(GIT_TRACE=1, GIT_DIR=Path('/tmp/git-dir/'), GIT_EDITOR='vim')
+```
+
+#### 🪢 Chain multiple overrides fluently
+
+```python
+from pathlib import Path
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+overridden_git = git.git_envs_override(GIT_SSH=Path('/tmp/SSH')).git_envs_override(
+    GIT_TERMINAL_PROMPT=1,
+    GIT_NO_REPLACE_OBJECTS=True
+)
+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
+from vt.utils.commons.commons.core_py import UNSET
+
+git = SimpleGitCommand()
+overridden_git = git.git_envs_override(GIT_ADVICE=True, GIT_TRACE=True)
+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
+
+git = SimpleGitCommand()
+overridden_git = git.git_envs_override(GIT_TRACE=True)
+git_trace_reset_git = overridden_git.git_envs_override(GIT_TRACE=False)
+```
+</details>
+
+---
+
+<details>
+<summary>Allow users to set/unset/reset git main command options in typed and pythonic manner just before subcommand run to provide maximal flexibility.</summary>
+
+### ⚙️ Git Main Command Options
+
+#### 🔁 Override a single Git opt (e.g., `--no-replace-objects`)
+
+```python
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+git = git.git_opts_override(no_replace_objects=True)
+```
+
+#### 🌐 Override multiple options (e.g., `--git-dir`, `--paginate`)
+
+```python
+from pathlib import Path
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+git = git.git_opts_override(no_replace_objects=True, git_dir=Path(), paginate=True)
+```
+
+#### 🪢 Chain multiple option overrides fluently
+
+```python
+from pathlib import Path
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+overridden_git = git.git_opts_override(exec_path=Path('tmp')).git_opts_override(
+    noglob_pathspecs=True,
+    no_advice=True
+).git_opts_override(
+    config_env={'auth': 'suhas', 'comm': 'suyog'}
+)
+re_overridden_git = overridden_git.git_opts_override(glob_pathspecs=True)
+```
+
+#### ❌ Unset Git opts using a special `UNSET` marker
+
+```python
+from pathlib import Path
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+from vt.utils.commons.commons.core_py import UNSET
+
+git = SimpleGitCommand()
+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)
+```
+
+#### 🔄 Reset Git opts by setting new values
+
+```python
+from gitbolt.git_subprocess.impl.simple import SimpleGitCommand
+
+git = SimpleGitCommand()
+overridden_git = git.git_opts_override(no_advice=True)
+no_advice_reset_git = overridden_git.git_opts_override(no_advice=False)
+```
+
+</details>
+
+
+---
+
+## 🔍 Transparent by Default
+
+Output of git commands is returned as-is. No transformations unless explicitly requested.
+Transformers for formatting/parsing can be added later.
+
+---
+
+## ✅ Benefits Out-of-the-Box
+
+* 🔄 Composable Git commands.
+* 📤 Returns raw stdout.
+* 🚨 Exceptions with full context.
+* 💤 Lazy execution.
+* 🧠 Strong typing and compile-time guarantees.
+* 🧼 Idiomatic Python.
+* 🧪 Terminal subcommands.
+* 💣 Fail-fast on invalid usage.
+
+---
+
+## 📄 More Information
+
+- 📜 [License (Apache-2.0)](./LICENSE)
+- 🤝 [Contributing Guide](./CONTRIBUTING.md)
+
+---
+
+## 🚧 Future Goals
+
+* Support `pygit2` for direct, fast Git access.
+* Enable `porcelain` support using `pygit2` where required.

gitbolt-0.0.0.dev1.dist-info/RECORD

@@ -0,0 +1,27 @@
+gitbolt/__init__.py,sha256=oGR5nG5-sMwKrU0xa5wNuBYX4bfUa4KjSKS0WpwfVM0,536
+gitbolt/_internal_init.py,sha256=alSsIMgBWHmOdUo7P1ewftR12xPv8vb3ZgECuVsRMwk,485
+gitbolt/add.py,sha256=F16d0SQfLrjbpUzJIjKFwGU4KLSjqtYLOA9oZ5gdNS0,31731
+gitbolt/base.py,sha256=eUjzfu0OilCrOpxpwRyCSs7HD83OaXk6BCzxT8LKKhU,9322
+gitbolt/exceptions.py,sha256=7YvR7whZYM1hlWZk4GxHbeNgJ0KJXElg5VFA1Vi-fiA,989
+gitbolt/ls_tree.py,sha256=PrDSoh4Pnqh6g4AfX8kwgez_zHYaH4yqknULbFbisUY,6269
+gitbolt/models.py,sha256=iwIO-ugHYiKS57I_LPo3uDFEQlAtu2mnn5AjZHHQg04,18828
+gitbolt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitbolt/utils.py,sha256=XftX3LIKtfzjQaUZUF3QYaFJFM-QdFjc05ZrZSMSdeM,6315
+gitbolt/git_subprocess/__init__.py,sha256=ynnsY2IDCsjzd2LU2GbXtIamNyBcME58q1yDsCBXCX8,515
+gitbolt/git_subprocess/_internal_init.py,sha256=C6jfsbjXhIFHaDH9GE-wLPAN9WMlUU57rRLWvfpZuAs,255
+gitbolt/git_subprocess/add.py,sha256=1PA9XonqFi2O941eBwIPMobSNgEJ0tgFYxlkVXSe1K4,17277
+gitbolt/git_subprocess/base.py,sha256=3DIydF-yQ7cVmT0di5cJtBVz-w68tawxk2xpq0yfcz8,14399
+gitbolt/git_subprocess/constants.py,sha256=3qHXbNjPf_DOhTPNHi3_bcvIpvtqvgFtpGoTJLYmTWk,250
+gitbolt/git_subprocess/exceptions.py,sha256=cx4YKzxeBRSRKoF-oakZLpFUGrAHiGj1FtMIsiK5oHc,4063
+gitbolt/git_subprocess/ls_tree.py,sha256=MmM3qh-kvkD_tGQG9yliLx-reY_5TIVEArvAXJN6rP4,13200
+gitbolt/git_subprocess/utils.py,sha256=n9_kXPvDf0ACrzAm6SVVLBOFM1JyjHmXJl_99vBoPS8,4941
+gitbolt/git_subprocess/impl/__init__.py,sha256=bxYluO0B3My-10H5Z0JuEGvZe_g8i71QTpt6iM0WXoU,97
+gitbolt/git_subprocess/impl/simple.py,sha256=nMxZYp1ayX6kyigLzIfrT5kNLvTd3KjYPDUNV4iB04U,5653
+gitbolt/git_subprocess/runner/__init__.py,sha256=LPxbj3AwKLXyDxxCLwAVtl5b5SKjaNDj99lkKz6VSOU,177
+gitbolt/git_subprocess/runner/base.py,sha256=Sof2WaNyYULiObRF7WjaGs7-yGrdyeHUXchE2tg1820,1562
+gitbolt/git_subprocess/runner/simple_impl.py,sha256=ov8lXamu489twQanej0lCkkjBmEXvXxqGrWI_aK3JzQ,2484
+gitbolt-0.0.0.dev1.dist-info/licenses/LICENSE,sha256=pOzr5bMWS6mHi3vro8d5vw0qW1i14rVq2XFrDuystVY,11372
+gitbolt-0.0.0.dev1.dist-info/METADATA,sha256=405JbuYEnngAtA4a-mVwfhSNMZTmOwDzzzZjMAnk2-Y,10724
+gitbolt-0.0.0.dev1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gitbolt-0.0.0.dev1.dist-info/top_level.txt,sha256=QCXclkzSPZjgamcwB6XuKJexaJ1as_TLUUSGdIDA7VY,8
+gitbolt-0.0.0.dev1.dist-info/RECORD,,

gitbolt-0.0.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+