gitoxide-py 0.87.0__cp39-abi3-win_amd64.whl

gitoxide_py/__init__.py

@@ -0,0 +1,5 @@
+from .gitoxide_py import *
+
+__doc__ = gitoxide_py.__doc__
+if hasattr(gitoxide_py, "__all__"):
+    __all__ = gitoxide_py.__all__

gitoxide_py/__init__.pyi

@@ -0,0 +1,664 @@
+"""
+PyO3 bindings to gitoxide (`gix`), aiming for close naming parity with
+`gix`'s own Rust API (`open`/`discover`/`init`, `git_dir`/`workdir`,
+`head_id`/`head_commit`, `rev_parse_single`, `rev_walk`, ...).
+
+## GIL handling
+
+Every method releases the GIL for the duration of its gix work via
+`Python::detach`. `detach`'s bound requires the closure (and everything
+it captures) to be `Send`. `gix::Repository` (the thread-local handle)
+is *not* `Sync` — it carries a `RefCell`-backed object/pack cache — so a
+`&gix::Repository` capture can never satisfy that bound, `unsendable`
+pyclass or not.
+
+`gix::ThreadSafeRepository` is gix's own answer to this: a cheap,
+`Send + Sync` handle with no local cache, meant to be shared across
+threads and turned into a `gix::Repository` per unit of work via
+`to_thread_local()`. `Repository` here stores a `ThreadSafeRepository`
+and calls `to_thread_local()` *inside* each `detach` closure, so the
+closure only ever captures `Send` data and the actual gix work runs
+GIL-free.
+
+## Layout
+
+The Python-visible surface is assembled here out of items defined in
+sibling Rust modules: `repository` holds the `Repository` handle and the
+functions that open one, `types` the value objects its methods return,
+and `util` the conversions both share.
+"""
+
+from collections.abc import Sequence
+from os import PathLike
+from pathlib import Path
+from typing import final
+
+@final
+class Branch:
+    def __repr__(self, /) -> str: ...
+    @property
+    def full_name(self, /) -> str:
+        """
+        The full ref name, e.g. `refs/heads/main`.
+        """
+    @property
+    def is_remote(self, /) -> bool: ...
+    @property
+    def name(self, /) -> str:
+        """
+        The branch name without its category prefix, e.g. `main` or
+        `origin/main`.
+        """
+    @property
+    def target(self, /) -> str |None: ...
+    @property
+    def upstream(self, /) -> str |None:
+        """
+        The shorthand of the remote-tracking branch this one is configured to
+        fetch from, e.g. `origin/main`, or `None` when unconfigured.
+        """
+
+@final
+class Commit:
+    def __eq__(self, other: object, /) -> bool: ...
+    def __hash__(self, /) -> int: ...
+    def __repr__(self, /) -> str: ...
+    @property
+    def author(self, /) -> Signature: ...
+    @property
+    def committer(self, /) -> Signature: ...
+    @property
+    def id(self, /) -> str: ...
+    @property
+    def message(self, /) -> str:
+        """
+        The commit message in full, including the summary line.
+        """
+    @property
+    def parent_ids(self, /) -> list[str]: ...
+    @property
+    def short_id(self, /) -> str:
+        """
+        The first seven characters of `id`.
+        
+        Not checked for uniqueness: that costs an object-database lookup per
+        commit, which a walk pays for thousands of commits to display a
+        handful. `Repository.abbreviate()` gives the shortest prefix that is
+        unambiguous, the one `git log --format=%h` prints.
+        """
+    @property
+    def summary(self, /) -> str: ...
+    @property
+    def tree_id(self, /) -> str: ...
+
+@final
+class FileChange:
+    def __repr__(self, /) -> str: ...
+    @property
+    def deletions(self, /) -> int |None:
+        """
+        Lines removed, under the same conditions as `insertions`.
+        """
+    @property
+    def id(self, /) -> str |None:
+        """
+        The object id after the change, `None` for a deletion.
+        """
+    @property
+    def insertions(self, /) -> int |None:
+        """
+        Lines added, counted only when the diff was asked for statistics.
+        `None` for a binary side, where lines are not a meaningful unit.
+        """
+    @property
+    def path(self, /) -> str: ...
+    @property
+    def previous_id(self, /) -> str |None:
+        """
+        The object id before the change, `None` for an addition.
+        """
+    @property
+    def previous_path(self, /) -> str |None:
+        """
+        Where a renamed or copied entry came from, `None` otherwise.
+        """
+    @property
+    def status(self, /) -> str:
+        """
+        `"added"`, `"deleted"`, `"modified"`, `"renamed"` or `"copied"`.
+        """
+
+@final
+class IndexConflict:
+    def __repr__(self, /) -> str: ...
+    @property
+    def ancestor(self, /) -> IndexEntry |None:
+        """
+        The merge base's side, absent for an add/add conflict.
+        """
+    @property
+    def ours(self, /) -> IndexEntry |None:
+        """
+        Our side, absent when we deleted the path.
+        """
+    @property
+    def path(self, /) -> str: ...
+    @property
+    def theirs(self, /) -> IndexEntry |None:
+        """
+        Their side, absent when they deleted the path.
+        """
+
+@final
+class IndexEntry:
+    def __repr__(self, /) -> str: ...
+    @property
+    def id(self, /) -> str: ...
+    @property
+    def mode(self, /) -> str:
+        """
+        The entry mode in octal, e.g. `"100644"`.
+        """
+    @property
+    def path(self, /) -> str: ...
+    @property
+    def stage(self, /) -> int:
+        """
+        0 for an ordinary entry; 1, 2 or 3 for the ancestor, "ours" and
+        "theirs" sides of a conflict.
+        """
+
+@final
+class Reference:
+    def __repr__(self, /) -> str: ...
+    @property
+    def name(self, /) -> str:
+        """
+        The full ref name, e.g. `refs/heads/main`.
+        """
+    @property
+    def shorthand(self, /) -> str:
+        """
+        The ref name without its category prefix, e.g. `main`.
+        """
+    @property
+    def target(self, /) -> str |None: ...
+
+@final
+class ReflogEntry:
+    def __repr__(self, /) -> str: ...
+    @property
+    def committer(self, /) -> Signature:
+        """
+        Who moved it, and when.
+        """
+    @property
+    def message(self, /) -> str:
+        """
+        What moved the ref, e.g. `checkout: moving from main to feature` or
+        `branch: Created from HEAD` — the `%gs` of `git reflog show`.
+        """
+    @property
+    def new_id(self, /) -> str:
+        """
+        The commit the ref pointed at after this entry.
+        """
+    @property
+    def old_id(self, /) -> str:
+        """
+        The commit the ref pointed at before this entry, all zeroes when the
+        entry is the one that created the ref.
+        """
+
+@final
+class Remote:
+    def __repr__(self, /) -> str: ...
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def push_url(self, /) -> str |None:
+        """
+        The push URL, which falls back to `url` when `remote.<name>.pushurl` is
+        unset — the same value git would push to.
+        """
+    @property
+    def url(self, /) -> str |None:
+        """
+        The fetch URL, absent for a remote configured with a push URL only.
+        """
+
+@final
+class Repository:
+    """
+    A git repository, opened once and queried many times.
+    
+    Backed by a `gix::ThreadSafeRepository` so that every method can do its
+    work inside `Python::detach` — see the module doc comment in `src/lib.rs`.
+    
+    The handle sits behind an `RwLock` because a `gix` repository resolves its
+    configuration once, when it is opened. Writing configuration therefore has
+    to swap in a freshly opened handle, or a value written through this object
+    would stay invisible to every later read through it.
+    """
+    def __repr__(self, /) -> str: ...
+    def abbreviate(self, /, rev: str) -> str:
+        """
+        The shortest unambiguous prefix of the object id `rev` names.
+        
+        Mirrors `gix::Id::shorten`. What `git log --format=%h` prints: long
+        enough that no other object in this repository shares it. Finding that
+        out costs a lookup in the object database, which is why
+        `Commit.short_id` does not do it.
+        """
+    def ahead_behind(self, /, local: str, upstream: str) -> tuple[int, int]:
+        """
+        How many commits `local` is ahead of and behind `upstream`, the two
+        numbers `git rev-list --left-right --count` reports.
+        """
+    def branch(self, /, name: str) -> Branch |None:
+        """
+        A single branch by name, with its target and configured upstream.
+        
+        `name` is a shorthand: `main` finds a local branch, `origin/main` a
+        remote-tracking one. Returns `None` if neither exists.
+        """
+    def branches(self, /) -> list[str]:
+        """
+        Mirrors `gix::Repository::references().local_branches()`, flattened to
+        names.
+        """
+    def commit(self, /, rev: str) -> Commit:
+        """
+        Convenience: `rev_parse_single(rev)` followed by resolving to a commit.
+        
+        An annotated tag peels to the commit it points at, the way
+        `<rev>^{commit}` would, so a tag name resolves like a branch name does.
+        """
+    def commits(self, /, rev: str |None = None, max_count: int |None = None, hide: Sequence[str] |None = None, sort: str |None = None, since: int |None = None, first_parent_only: bool = False, reverse: bool = False) -> list[Commit]:
+        """
+        Mirrors `gix::Repository::rev_walk` starting from `rev` (default `HEAD`).
+        
+        `hide` excludes the commits reachable from the given revisions, the way
+        `git log <rev> --not <hidden>` does.
+        
+        `sort` picks the order in which queued commits are visited, not an
+        order imposed on the result: a walk always starts at `rev` and moves
+        towards its ancestors, so it only shows where history branches.
+        `"breadth-first"` (the default) follows the commit graph,
+        `"newest-first"` and `"oldest-first"` prefer the commit date, and
+        `"topological"` never shows a commit before one of its descendants,
+        the order `git log --topo-order` guarantees. Pass `reverse=True` to
+        get the collected commits oldest-first, as `git log --reverse` prints
+        them — a topological walk reversed is an order the commits can be
+        replayed in.
+        
+        `since` stops the walk at a unix timestamp and requires a date-ordered
+        sort, which it selects on its own when `sort` is left unset.
+        """
+    def config_get(self, /, key: str) -> str |None:
+        """
+        The value of a configuration key as git would resolve it, taking
+        system, global and local files into account.
+        """
+    def config_set(self, /, key: str, value: str) -> None:
+        """
+        Write a configuration key to the repository's own config file, creating
+        its section when needed — `git config --local <key> <value>`.
+        
+        The repository is reopened afterwards, so the value is visible to later
+        reads through this same object.
+        """
+    def create_branch(self, /, name: str, start_point: str, force: bool = False) -> str:
+        """
+        Point a branch at a revision, creating it or moving it.
+        
+        Mirrors `git branch <name> <start_point>`, and `git branch -f` when
+        `force=True`: without it, an existing branch is an error rather than
+        silently moved. The branch is not checked out, and `HEAD` is untouched.
+        """
+    def create_tag(self, /, name: str, target: str = "HEAD", message: str |None = None, force: bool = False) -> str:
+        """
+        Create a tag at a revision.
+        
+        With `message`, an annotated tag object is written and the tag points
+        at it, as `git tag -a -m` does; without one the tag points straight at
+        the target, as `git tag` does. `force=True` replaces an existing tag.
+        """
+    def delete_branch(self, /, name: str) -> bool:
+        """
+        Delete a branch, whether or not it is merged.
+        
+        Mirrors `git branch -D`. Returns `False` when there was no such branch,
+        so deleting twice is not an error.
+        """
+    def delete_tag(self, /, name: str) -> bool:
+        """
+        Delete a tag, reporting whether there was one.
+        
+        Mirrors `git tag -d`. The tag object an annotated tag points at is left
+        in the object database, as git leaves it.
+        """
+    def diff_tree_to_tree(self, /, old_rev: str, new_rev: str, stats: bool = False) -> list[FileChange]:
+        """
+        The changes that turn the tree at `old_rev` into the one at `new_rev`.
+        
+        Rename tracking follows the repository's own `diff.renames`
+        configuration, as it does for `git diff`.
+        
+        `stats=True` also counts the lines each change adds and removes, the
+        numbers behind `git diff --numstat`. They cost a blob diff per changed
+        file, so they are off by default, and stay `None` for a binary file.
+        """
+    def find_reference(self, /, name: str) -> Reference |None:
+        """
+        The reference `name` names, or `None` if there is no such ref.
+        
+        `name` may be full (`refs/heads/main`) or partial (`main`), the same
+        spellings `git rev-parse --symbolic-full-name` accepts.
+        """
+    @property
+    def git_dir(self, /) -> Path: ...
+    def head_commit(self, /) -> Commit: ...
+    @property
+    def head_id(self, /) -> str |None: ...
+    @property
+    def head_is_detached(self, /) -> bool: ...
+    @property
+    def head_is_unborn(self, /) -> bool:
+        """
+        `True` when `HEAD` points at a branch that has no commit yet, as in a
+        freshly initialized repository.
+        """
+    @property
+    def head_name(self, /) -> str |None: ...
+    def index_conflicts(self, /) -> list[IndexConflict]:
+        """
+        The conflicted paths in the index, each with its three stages.
+        """
+    def index_entries(self, /) -> list[IndexEntry]:
+        """
+        Every entry of the index, conflicted ones included.
+        """
+    @property
+    def is_bare(self, /) -> bool: ...
+    def is_descendant_of(self, /, commit: str, ancestor: str) -> bool:
+        """
+        Whether `commit` has `ancestor` in its history.
+        
+        A commit is not considered a descendant of itself, and revisions with
+        no common ancestor at all report `False`.
+        """
+    def is_dirty(self, /) -> bool:
+        """
+        Whether the index or the worktree differ from `HEAD`.
+        
+        Untracked files do not count as dirty, matching `gix`'s own definition;
+        use `status()` to see them.
+        """
+    @property
+    def is_shallow(self, /) -> bool: ...
+    def merge_base(self, /, one: str, two: str) -> str:
+        """
+        The best common ancestor of two revisions, as `git merge-base` finds it.
+        """
+    def object_kind(self, /, rev: str) -> str:
+        """
+        The kind of object `rev` names: `"commit"`, `"tree"`, `"blob"` or
+        `"tag"`.
+        
+        An annotated tag reports `"tag"`; peel it with a `^{}` suffix in the
+        revspec to see what it points at.
+        """
+    def read_blob(self, /, rev: str) -> bytes:
+        """
+        Read a blob's raw bytes at a revspec, e.g. `"HEAD:README.md"`.
+        """
+    def references(self, /) -> list[Reference]:
+        """
+        Mirrors `gix::Repository::references().all()`, flattened to a `Vec`.
+        """
+    def reflog(self, /, name: str) -> list[ReflogEntry]:
+        """
+        The reflog of `name`, oldest entry first.
+        
+        That is the order the reflog file records them, and the reverse of what
+        `git reflog show` prints — so the entry that created a ref is the first
+        one here, not the last. An empty list means the ref has no reflog, which
+        is also what a missing ref reports.
+        """
+    def remote(self, /, name: str) -> Remote |None:
+        """
+        A single remote by name, or `None` if it isn't configured.
+        """
+    def remote_branches(self, /) -> list[str]:
+        """
+        Mirrors `gix::Repository::references().remote_branches()`, flattened to
+        names like `origin/main`.
+        """
+    def remotes(self, /) -> list[Remote]:
+        """
+        The configured remotes, in the order git lists them.
+        """
+    def rev_parse_single(self, /, spec: str) -> str:
+        """
+        Mirrors `gix::Repository::rev_parse_single`.
+        """
+    def status(self, /, untracked: str = "normal") -> list[StatusEntry]:
+        """
+        The working tree's status, the data behind `git status --porcelain`.
+        
+        `untracked` selects how much of the directory walk is reported:
+        `"normal"` (the default) collapses an untracked directory into a single
+        entry, `"all"` lists every file inside it, and `"none"` skips the walk
+        entirely — much cheaper when only tracked changes matter.
+        """
+    def submodule_status(self, /, name: str, ignore: str = "none") -> SubmoduleStatus |None:
+        """
+        The status of a single submodule, by name.
+        
+        `ignore` mirrors git's `submodule.<name>.ignore`: `"none"` (the
+        default) looks at everything, `"untracked"` skips untracked files,
+        `"dirty"` skips worktree changes altogether and `"all"` reports nothing
+        but the clone state — which also makes `is_dirty` report `False`, since
+        no change can be seen from there.
+        """
+    def submodules(self, /) -> list[Submodule]:
+        """
+        The submodules declared in `.gitmodules`.
+        """
+    def tags(self, /) -> list[str]:
+        """
+        Mirrors `gix::Repository::references().tags()`, flattened to names.
+        """
+    def tree_entries(self, /, rev: str = "HEAD") -> list[TreeEntry]:
+        """
+        The entries of the tree `rev` names, one level deep.
+        
+        `rev` may name a tree directly or anything that peels to one, such as
+        `HEAD` or `HEAD:subdir`.
+        """
+    @property
+    def workdir(self, /) -> Path |None: ...
+    def worktrees(self, /) -> list[Worktree]:
+        """
+        The linked worktrees registered under `.git/worktrees`.
+        
+        The main worktree is not among them, matching `git worktree list
+        --porcelain` minus its first entry.
+        """
+
+@final
+class Signature:
+    def __repr__(self, /) -> str: ...
+    @property
+    def email(self, /) -> str: ...
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def offset(self, /) -> int:
+        """
+        Seconds east of UTC in the timezone the signature was written in.
+        `time` alone loses it, and with it the local date the author saw.
+        """
+    @property
+    def time(self, /) -> int:
+        """
+        Unix timestamp (seconds).
+        """
+
+@final
+class StatusEntry:
+    def __repr__(self, /) -> str: ...
+    @property
+    def path(self, /) -> str: ...
+    @property
+    def previous_path(self, /) -> str |None: ...
+    @property
+    def staged(self, /) -> bool:
+        """
+        `True` for a `HEAD`-to-index difference, `False` for an
+        index-to-worktree one — the two columns of `git status --porcelain`.
+        """
+    @property
+    def status(self, /) -> str:
+        """
+        `"added"`, `"deleted"`, `"modified"`, `"typechange"`, `"renamed"`,
+        `"copied"`, `"conflicted"` or `"untracked"`.
+        """
+
+@final
+class Submodule:
+    def __repr__(self, /) -> str: ...
+    @property
+    def head_id(self, /) -> str |None:
+        """
+        The commit the submodule's own `HEAD` points at, `None` when it isn't
+        cloned yet.
+        """
+    @property
+    def index_id(self, /) -> str |None:
+        """
+        The commit the superproject's index records for the submodule.
+        """
+    @property
+    def is_active(self, /) -> bool: ...
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def path(self, /) -> str:
+        """
+        The path within the superproject's worktree.
+        """
+    @property
+    def url(self, /) -> str: ...
+
+@final
+class SubmoduleStatus:
+    def __repr__(self, /) -> str: ...
+    @property
+    def checked_out_head_id(self, /) -> str |None: ...
+    @property
+    def index_id(self, /) -> str |None: ...
+    @property
+    def is_dirty(self, /) -> bool |None:
+        """
+        `None` when the submodule is not cloned or not checked out, leaving it
+        to the caller to decide whether that counts as dirty.
+        """
+    @property
+    def name(self, /) -> str: ...
+    @property
+    def path(self, /) -> str:
+        """
+        The path within the superproject's worktree.
+        """
+    @property
+    def repository_exists(self, /) -> bool:
+        """
+        Whether the submodule has been cloned into `.git/modules`.
+        """
+    @property
+    def worktree_checkout(self, /) -> bool:
+        """
+        Whether the submodule's worktree is checked out.
+        """
+
+@final
+class TreeEntry:
+    def __repr__(self, /) -> str: ...
+    @property
+    def id(self, /) -> str: ...
+    @property
+    def kind(self, /) -> str:
+        """
+        `"blob"`, `"tree"`, `"link"` or `"commit"` (a submodule).
+        """
+    @property
+    def mode(self, /) -> str:
+        """
+        The entry mode in octal, e.g. `"100644"`.
+        """
+    @property
+    def name(self, /) -> str:
+        """
+        The entry's name within its tree, not a full path.
+        """
+
+@final
+class Worktree:
+    def __repr__(self, /) -> str: ...
+    @property
+    def git_dir(self, /) -> Path:
+        """
+        The private git directory backing this worktree.
+        """
+    @property
+    def is_locked(self, /) -> bool: ...
+    @property
+    def name(self, /) -> str:
+        """
+        The linked worktree's identifier, its directory name under
+        `.git/worktrees`.
+        """
+    @property
+    def path(self, /) -> Path |None:
+        """
+        The worktree's working directory, `None` if it is inaccessible.
+        """
+
+def _debug_detached_sleep(seconds: float) -> None:
+    """
+    Sleeps for `seconds` inside `Python::detach`.
+    
+    Not part of the `gix`-mirroring API surface: this exists so the test
+    suite can assert that `Python::detach` lets other Python threads make
+    progress while this call is in flight, independent of any particular
+    git repository's size or contents.
+    """
+
+def discover(path: str |PathLike[str]) -> Repository:
+    """
+    Mirrors `gix::ThreadSafeRepository::discover`.
+    """
+
+def gix_version() -> str:
+    """
+    The version of `gix` this extension was built against.
+    
+    The package version tracks `gix`'s major and minor, so this is how to
+    see the exact patch — worth quoting in a bug report, since most of the
+    behaviour here is `gix`'s.
+    """
+
+def init(path: str |PathLike[str], bare: bool = False) -> Repository:
+    """
+    Mirrors `gix::ThreadSafeRepository::init`, creating the destination first.
+    
+    `gix` expects the destination directory to exist already, where `git init
+    a/b/c` creates the whole path. The directory is created here so both agree.
+    """
+
+def open(path: str |PathLike[str]) -> Repository:
+    """
+    Mirrors `gix::ThreadSafeRepository::open`.
+    """