rusty-git 0.3.0__cp312-abi3-pyemscripten_2024_0_wasm32.whl

rusty_git/__init__.py

@@ -0,0 +1,76 @@
+"""High-speed pure Rust Git engine for the ``dev-m`` suite.
+
+This package is a thin Python shell around the compiled PyO3 extension
+``rusty_git._rusty_git``. Everything public is re-exported here so callers
+never need to know about the private module name::
+
+    import rusty_git
+
+    info = await rusty_git.get_commit("/srv/repos/app.git", "HEAD")
+
+Layering
+--------
+* ``inspect``  — read paths (commits, refs, blobs, diffs) via ``gix``.
+* ``merge``    — 3-way merge / conflict detection via ``git2`` (libgit2).
+* ``protocol`` — in-process Smart-HTTP packet-line framing.
+* ``upload``   — ``git-upload-pack``: advertisement, negotiation, pack stream.
+* ``receive``  — ``git-receive-pack``: pack ingest and ref updates.
+
+The ``CommitInfo``, ``DiffHunk``, ``MergeResult``, ``UploadResult`` and
+``PushResult`` names are ``TypedDict`` declarations in ``_rusty_git.pyi`` only —
+they describe the shape of the dicts the engine returns, and have no runtime
+presence, so they are not re-exported here. Use them under ``TYPE_CHECKING``
+for annotations.
+
+Concurrency
+-----------
+Every callable is ``async``. The blocking Git work runs on a Tokio worker
+thread with the GIL released, so the event loop (Granian/Tokio or
+Uvicorn/uvloop) is never stalled.
+"""
+
+from ._rusty_git import (
+    GitError,
+    GitObjectError,
+    GitProtocolError,
+    GitRepositoryError,
+    __runtime__,
+    __rust_version__,
+    __version__,
+    advertise,
+    capabilities,
+    compare_refs,
+    create_commit,
+    encode_pkt_line,
+    execute_merge,
+    get_commit,
+    get_tree_blob,
+    init_bare_repository,
+    list_branches,
+    receive_pack,
+    sync,
+    upload_pack,
+)
+
+__all__ = [
+    "GitError",
+    "GitObjectError",
+    "GitProtocolError",
+    "GitRepositoryError",
+    "__runtime__",
+    "__rust_version__",
+    "__version__",
+    "advertise",
+    "capabilities",
+    "compare_refs",
+    "create_commit",
+    "encode_pkt_line",
+    "execute_merge",
+    "get_commit",
+    "get_tree_blob",
+    "init_bare_repository",
+    "list_branches",
+    "receive_pack",
+    "sync",
+    "upload_pack",
+]

rusty_git/_rusty_git.pyi

@@ -0,0 +1,195 @@
+"""Type stubs for the compiled ``rusty_git._rusty_git`` extension module.
+
+These are the source of truth for the async surface. Every callable is a
+coroutine: the underlying blocking Git work happens on a Tokio worker thread
+with the GIL released. The public package ``rusty_git`` re-exports all of this,
+so application code can import from ``rusty_git`` directly.
+"""
+
+from typing import TypedDict
+
+__version__: str
+__rust_version__: str
+__runtime__: str
+
+class GitError(Exception):
+    """Base class for every rusty-git failure."""
+
+class GitRepositoryError(GitError):
+    """Repository could not be opened, created, or mutated."""
+
+class GitObjectError(GitError):
+    """A commit, tree, blob, or diff could not be resolved."""
+
+class GitProtocolError(GitError):
+    """Smart-HTTP packet-line negotiation failed."""
+
+class CommitInfo(TypedDict):
+    sha: str
+    author_name: str
+    author_email: str
+    committer_name: str
+    committer_email: str
+    message: str
+    timestamp: str
+    timestamp_epoch: int
+    timezone_offset: int
+    committer_timestamp: str
+    committer_timestamp_epoch: int
+    committer_timezone_offset: int
+    parent_shas: list[str]
+
+class DiffHunk(TypedDict):
+    old_path: str
+    new_path: str
+    old_mode: int
+    new_mode: int
+    old_start: int
+    old_lines: int
+    new_start: int
+    new_lines: int
+    content: str
+    is_binary: bool
+
+class MergeResult(TypedDict):
+    status: str
+    commit_sha: str | None
+    conflicts: list[str] | None
+
+class UploadResult(TypedDict):
+    body: bytes
+    object_count: int
+    used_have: str | None
+    side_band: bool
+
+class PushResult(TypedDict):
+    indexed_objects: int
+    updated_refs: list[str]
+
+class CommitCreateResult(TypedDict):
+    commit_sha: str
+    tree_sha: str
+    parent_shas: list[str]
+    branch: str
+
+async def init_bare_repository(path: str) -> str:
+    """Create a bare repository at *path*; returns the normalised path."""
+
+async def get_commit(repo_path: str, sha: str) -> CommitInfo:
+    """Resolve *sha* (or any revision) to full commit metadata."""
+
+async def list_branches(repo_path: str) -> list[str]:
+    """Return the sorted local branch names."""
+
+async def get_tree_blob(repo_path: str, ref_name: str, file_path: str) -> bytes | None:
+    """Return raw file bytes, or ``None`` when the path does not exist."""
+
+async def compare_refs(repo_path: str, base_ref: str, head_ref: str) -> list[DiffHunk]:
+    """Return unified-diff hunks between two refs."""
+
+async def create_commit(
+    repo_path: str,
+    branch: str,
+    files: dict[str, bytes | None],
+    message: str,
+    author_name: str | None = None,
+    author_email: str | None = None,
+    expected_sha: str | None = None,
+    force: bool = False,
+) -> CommitCreateResult:
+    """Create a commit atomically on *branch* with the provided *files* mapping.
+
+    *files* maps relative paths to `bytes` (create/update) or `None` (delete).
+    Supports initial root commits, consequent commits, and optimistic concurrency
+    control (`expected_sha` / force-with-lease).
+    """
+
+async def execute_merge(
+    repo_path: str,
+    base_ref: str,
+    head_ref: str,
+    author_name: str | None = None,
+    author_email: str | None = None,
+    commit_message: str | None = None,
+) -> MergeResult:
+    """3-way merge *head_ref* into *base_ref*."""
+
+def capabilities() -> list[str]:
+    """Return the Git protocols this engine can serve in-process."""
+
+async def advertise(repo_path: str, service: str) -> bytes:
+    """Return the smart-HTTP ref advertisement for *service*.
+
+    *service* must be ``"git-upload-pack"`` or ``"git-receive-pack"``. The
+    result is the complete HTTP response body, including the
+    ``# service=...`` prefix line.
+    """
+
+async def upload_pack(repo_path: str, body: bytes) -> UploadResult:
+    """Serve a ``git-upload-pack`` request body.
+
+    Returns the response body (``NAK``/``ACK`` plus the pkt-line-framed pack),
+    ready to send verbatim as an HTTP response.
+    """
+
+async def receive_pack(
+    repo_path: str,
+    body: bytes,
+    author_name: str | None = None,
+    author_email: str | None = None,
+) -> PushResult:
+    """Serve a ``git-receive-pack`` request body.
+
+    Ingests the inbound pack, then moves refs. Objects are made durable before
+    any ref names them, so a failure never leaves a repository that ``git fsck``
+    rejects.
+    """
+
+def encode_pkt_line(payload: bytes) -> bytes:
+    """Frame *payload* as a Git pkt-line.
+
+    Raises :class:`GitProtocolError` when the payload exceeds
+    :data:`MAX_PKT_PAYLOAD` and cannot fit in a single frame.
+    """
+
+class _SyncModule:
+    """Synchronous interface releasing the Python GIL directly on calling thread."""
+
+    def init_bare_repository(self, path: str) -> str: ...
+    def get_commit(self, repo_path: str, sha: str) -> CommitInfo: ...
+    def list_branches(self, repo_path: str) -> list[str]: ...
+    def get_tree_blob(self, repo_path: str, ref_name: str, file_path: str) -> bytes | None: ...
+    def compare_refs(self, repo_path: str, base_ref: str, head_ref: str) -> list[DiffHunk]: ...
+    def create_commit(
+        self,
+        repo_path: str,
+        branch: str,
+        files: dict[str, bytes | None],
+        message: str,
+        author_name: str | None = None,
+        author_email: str | None = None,
+        expected_sha: str | None = None,
+        force: bool = False,
+    ) -> CommitCreateResult: ...
+    def execute_merge(
+        self,
+        repo_path: str,
+        base_ref: str,
+        head_ref: str,
+        author_name: str | None = None,
+        author_email: str | None = None,
+        commit_message: str | None = None,
+    ) -> MergeResult: ...
+    def capabilities(self) -> list[str]: ...
+    def encode_pkt_line(self, payload: bytes) -> bytes: ...
+    def advertise(self, repo_path: str, service: str) -> bytes: ...
+    def upload_pack(self, repo_path: str, body: bytes) -> UploadResult: ...
+    def receive_pack(
+        self,
+        repo_path: str,
+        body: bytes,
+        author_name: str | None = None,
+        author_email: str | None = None,
+    ) -> PushResult: ...
+
+sync: _SyncModule

rusty_git-0.3.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: rusty-git
+Version: 0.3.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Summary: High-speed pure Rust Git engine (gix + git2) for Python
+Keywords: git,gix,pyo3,gitoxide,forge,libgit2
+Author-email: Framework M <dev@frameworkm.dev>
+License: Apache-2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://gitlab.com/framework-m/rusty-git
+Project-URL: Issues, https://gitlab.com/framework-m/rusty-git/-/issues
+Project-URL: Repository, https://gitlab.com/framework-m/rusty-git
+
+# rusty-git
+
+[![GitLab CI](https://gitlab.com/framework-m/rusty-git/badges/main/pipeline.svg)](https://gitlab.com/framework-m/rusty-git/-/pipelines)
+[![PyPI version](https://img.shields.io/pypi/v/rusty-git.svg)](https://pypi.org/project/rusty-git/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**High-speed pure Rust Git engine (`gix` + `git2`) compiled via PyO3 with both native `async` (Tokio) and GIL-released `sync` APIs.**
+
+`rusty-git` provides in-process Git operations with **zero OS subprocess forks** and **statically-compiled native wheels** (no dynamic `libgit2.so` dependencies required).
+
+---
+
+## Installation
+
+```bash
+pip install rusty-git
+# or with uv:
+uv add rusty-git
+```
+
+---
+
+## Quickstart: 100% In-Process Demo (Zero Subprocesses)
+
+Copy-paste this into `example.py` to test immediately in any environment:
+
+```python
+import asyncio
+import os
+import tempfile
+import rusty_git
+
+
+async def main():
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        repo_path = os.path.join(tmp_dir, "demo.git")
+
+        # 1. Initialize a bare repository in-process (ZERO subprocesses)
+        await rusty_git.init_bare_repository(repo_path)
+
+        # 2. Create the initial root commit in-process
+        res = await rusty_git.create_commit(
+            repo_path,
+            branch="main",
+            files={
+                "README.md": b"# Hello from rusty-git!\n",
+                "src/main.py": b"print('Hello World')\n",
+            },
+            message="Initial commit",
+            author_name="Alice",
+            author_email="alice@example.com",
+        )
+        print("Root Commit SHA:", res["commit_sha"])
+
+        # 3. Inspect commit in-process
+        commit = await rusty_git.get_commit(repo_path, "HEAD")
+        print(f"Author:  {commit['author_name']} <{commit['author_email']}>")
+        print(f"Message: {commit['message']}")
+
+        # 4. Read tree blob without disk checkout
+        blob = await rusty_git.get_tree_blob(repo_path, "HEAD", "README.md")
+        print("Blob Content:", blob.decode("utf-8").strip())
+
+        # 5. List branches
+        branches = await rusty_git.list_branches(repo_path)
+        print("Branches:", branches)
+
+
+asyncio.run(main())
+```
+
+---
+
+## Dual-Color Usage: Async & Sync
+
+### 1. Asynchronous API (Default - for Litestar, FastAPI, Granian, Uvicorn)
+
+All blocking Git I/O is offloaded to a Tokio multi-threaded worker pool, releasing the Python GIL:
+
+```python
+import asyncio
+import rusty_git
+
+
+async def main():
+    repo_path = "/path/to/your/repo"
+
+    # 1. Inspect commits
+    commit = await rusty_git.get_commit(repo_path, "HEAD")
+    print(commit["sha"], commit["message"], commit["author_name"])
+
+    # 2. Read tree blobs without disk checkout
+    readme = await rusty_git.get_tree_blob(repo_path, "main", "README.md")
+    print(readme.decode("utf-8"))
+
+    # 3. Fast unified diffs
+    hunks = await rusty_git.compare_refs(repo_path, "main~1", "main")
+    for hunk in hunks:
+        print(hunk["new_path"], hunk["content"])
+
+    # 4. 3-Way Merge
+    result = await rusty_git.execute_merge(
+        repo_path,
+        base_ref="main",
+        head_ref="feature",
+        author_name="Automated Merge",
+        author_email="bot@example.com",
+    )
+    if result["status"] == "merged":
+        print("Merged Commit SHA:", result["commit_sha"])
+
+
+asyncio.run(main())
+```
+
+---
+
+### 2. Synchronous API (`rusty_git.sync` - for CLI tools, Celery, scripts)
+
+Direct execution on the calling thread with the Python GIL cleanly released (`py.detach`):
+
+```python
+import rusty_git
+
+# Read commit synchronously
+commit = rusty_git.sync.get_commit("/path/to/repo.git", "HEAD")
+print(commit["sha"], commit["author_name"])
+
+# List branches synchronously
+branches = rusty_git.sync.list_branches("/path/to/repo.git")
+print("Branches:", branches)
+
+# Read file directly from commit tree
+blob = rusty_git.sync.get_tree_blob("/path/to/repo.git", "HEAD", "pyproject.toml")
+
+# Create a commit directly on any branch (new or existing)
+res = rusty_git.sync.create_commit(
+    "/path/to/repo.git",
+    branch="feature-x",
+    files={"hello.txt": b"Hello world!\n"},
+    message="feat: add hello.txt",
+)
+
+# 3-Way Merge synchronously
+result = rusty_git.sync.execute_merge(
+    "/path/to/repo.git",
+    "main",
+    "feature",
+    author_name="Merge Bot",
+    author_email="bot@example.com",
+)
+```
+
+---
+
+## Architectural Note: Forges & Branch Management
+
+`rusty-git` is designed for high-performance server-side forges and tools operating on **bare repositories**:
+
+* **Creating branches with commits**: Passing any branch name to `create_commit(...)` will create or advance that branch atomically.
+* **Creating a branch without a commit**: Git branches are simply ref pointers. To create a branch pointing to an existing commit without a new commit, your application or CLI can write the commit SHA directly to `refs/heads/<branch_name>`.
+* **Switching active branch (`HEAD`)**: In a bare repo or CLI, switching the symbolic reference is done by writing `ref: refs/heads/<branch_name>\n` to the `HEAD` file.
+
+### Engine Architecture: Pure `gix` vs. `git2` Wire Streaming
+
+`rusty-git` intentionally separates user-facing operations from network pack streaming:
+
+* **100% Pure `gix` Core (WebAssembly / Pyodide Ready)**: `commit` (atomic in-memory trees & commits), `inspect` (refs, tree blobs, histogram unified diffs), and `merge` (3-way ORT tree merge) run entirely on pure-Rust `gix`. They require zero C headers and run in browsers and Pyodide.
+* **Wire Protocol Pack Streaming (`git2`)**: Ingesting thin packs (`git push`) and streaming sliding-window delta packs (`git clone`/`git fetch`) use `libgit2`'s battle-tested pack engine. Once `gix-pack` high-level streaming pack generation reaches full maturity, these remaining wire endpoints will transition to `gix`, completing the journey to 100% pure Rust.
+
+This keeps `rusty-git` focused entirely on performance-critical operations without unnecessary file-I/O wrapper overhead.
+
+---
+
+## Smart-HTTP Protocol Wire Support
+
+`rusty-git` can drive Git HTTP and SSH protocol negotiation completely in-process:
+
+> **Note on Transport & Auth (SSH / TLS):** `rusty-git` operates directly on request/response byte streams rather than managing sockets. Transport encryption and authentication (SSH keys via `asyncssh`/OpenSSH, or TLS/mTLS client certs via Nginx/Caddy/HTTPX) happen cleanly at the transport layer before passing payloads to `rusty-git`.
+
+```python
+import rusty_git
+
+# Ref advertisement for git-upload-pack (git clone / fetch)
+advert = await rusty_git.advertise("/srv/repos/myorg/backend.git", "git-upload-pack")
+
+# Handle pack negotiation and streaming
+upload_res = await rusty_git.upload_pack("/srv/repos/myorg/backend.git", request_body)
+
+# Ingest inbound git push packfile atomically
+push_res = await rusty_git.receive_pack("/srv/repos/myorg/backend.git", push_body)
+print("Updated Refs:", push_res["updated_refs"])
+```
+
+---
+
+## Development & Testing
+
+### Rust Tests
+```bash
+cargo test
+```
+
+### Python Integration Tests
+```bash
+uv run pytest
+```
+
+---
+
+## License
+
+Apache-2.0 © Framework M Contributors
+

rusty_git-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+rusty_git/__init__.py,sha256=pozmSzjh30xmhYQSkNU-Sik9y9QMeMK5Sv5ReavFeb4,2086
+rusty_git/_rusty_git.abi3.so,sha256=j1ppObruPwc3zAUGsedFCbcAyzvQQKkgikzb8bjdQ6c,4520875
+rusty_git/_rusty_git.pyi,sha256=XOXipEiRsQhoRJ1-TTCIB_xzAzaqmIHwIw0QcrlKh4Y,6103
+rusty_git-0.3.0.dist-info/sboms/rusty-git.cyclonedx.json,sha256=gkQkSR54NMRooGbpfiOkW5J_NItzbDVM-H9maDl1iSw,206837
+rusty_git-0.3.0.dist-info/METADATA,sha256=ogkqfE3Y6vMr8tV361_MF5LFHKYvGhmBTBBq15FUSf4,8104
+rusty_git-0.3.0.dist-info/WHEEL,sha256=xoVwukNZX5x0STCtBOeW-Whs4wuCh7O9bG4M5ei4aFI,114
+rusty_git-0.3.0.dist-info/RECORD,,

rusty_git-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.16.0)
+Root-Is-Purelib: false
+Tag: cp312-abi3-pyemscripten_2024_0_wasm32
+