improve type according to test/test_blame.py

this change introduces a new interface file: _pygit2_c.pyi
the idea is to create python interfaces for c structs

Author: BenediktSeidl

pygit2/_pygit2.pyi

@@ -10,6 +10,7 @@ from .enums import (
     ApplyLocation,
     BranchType,
     BlobFilter,
+    BlameFlag,
     CheckoutStrategy,
     DeltaStatus,
     DiffFind,
@@ -28,10 +29,13 @@ from .enums import (
 )
 from collections.abc import Generator
 
+from ._pygit2_c import GitSignatureC, _Pointer
+
 from .repository import BaseRepository
 from .submodules import SubmoduleCollection, Submodule
 from .remotes import Remote
 from .callbacks import CheckoutCallbacks
+from .blame import Blame
 
 GIT_OBJ_BLOB = Literal[3]
 GIT_OBJ_COMMIT = Literal[1]
@@ -724,6 +728,16 @@ class Repository:
     def apply(
         self, diff: Diff, location: ApplyLocation = ApplyLocation.WORKDIR
     ) -> None: ...
+    def blame(
+        self,
+        path: str,
+        flags: BlameFlag = BlameFlag.NORMAL,
+        min_match_characters: int | None = None,
+        newest_commit: _OidArg | None = None,
+        oldest_commit: _OidArg | None = None,
+        min_line: int | None = None,
+        max_line: int | None = None,
+    ) -> Blame: ...
     def checkout(
         self,
         refname: Optional[_OidArg],
@@ -864,7 +878,7 @@ class RevSpec:
 
 class Signature:
     _encoding: str | None
-    _pointer: bytes
+    _pointer: _Pointer[GitSignatureC]
     email: str
     name: str
     offset: int

pygit2/_pygit2_c.pyi

@@ -0,0 +1,36 @@
+from typing import NewType, Generic, Literal, TypeVar, overload
+
+T = TypeVar('T')
+
+char = NewType('char', object)
+char_pointer = NewType('char_pointer', object)
+
+class _Pointer(Generic[T]):
+    @overload
+    def __getitem__(self, item: Literal[0]) -> T: ...
+    @overload
+    def __getitem__(self, item: slice[None, None, None]) -> bytes: ...
+
+class GitTimeC:
+    # incomplete
+    time: int
+    offset: int
+
+class GitSignatureC:
+    name: char_pointer
+    email: char_pointer
+    when: GitTimeC
+
+class GitHunkC:
+    # incomplete
+    boundary: char
+    final_start_line_number: int
+    final_signature: GitSignatureC
+    orig_signature: GitSignatureC
+    orig_start_line_number: int
+    orig_path: str
+    lines_in_hunk: int
+
+class GitBlameC:
+    # incomplete
+    pass

pygit2/blame.py

@@ -23,13 +23,18 @@
 # the Free Software Foundation, 51 Franklin Street, Fifth Floor,
 # Boston, MA 02110-1301, USA.
 
+from typing import Iterator, TYPE_CHECKING
+
 # Import from pygit2
 from .ffi import ffi, C
 from .utils import GenericIterator
-from ._pygit2 import Signature, Oid
+from ._pygit2 import Signature, Oid, Repository
+
+if TYPE_CHECKING:
+    from ._pygit2_c import GitSignatureC, GitHunkC, GitBlameC
 
 
-def wrap_signature(csig):
+def wrap_signature(csig: 'GitSignatureC') -> None | Signature:
     if not csig:
         return None
 
@@ -43,88 +48,94 @@ def wrap_signature(csig):
 
 
 class BlameHunk:
+    _blame: 'Blame'
+    _hunk: 'GitHunkC'
+
     @classmethod
-    def _from_c(cls, blame, ptr):
+    def _from_c(cls, blame: 'Blame', ptr: 'GitHunkC') -> 'BlameHunk':
         hunk = cls.__new__(cls)
         hunk._blame = blame
         hunk._hunk = ptr
         return hunk
 
     @property
-    def lines_in_hunk(self):
+    def lines_in_hunk(self) -> int:
         """Number of lines"""
         return self._hunk.lines_in_hunk
 
     @property
-    def boundary(self):
+    def boundary(self) -> bool:
         """Tracked to a boundary commit"""
         # Casting directly to bool via cffi does not seem to work
         return int(ffi.cast('int', self._hunk.boundary)) != 0
 
     @property
-    def final_start_line_number(self):
+    def final_start_line_number(self) -> int:
         """Final start line number"""
         return self._hunk.final_start_line_number
 
     @property
-    def final_committer(self):
+    def final_committer(self) -> None | Signature:
         """Final committer"""
         return wrap_signature(self._hunk.final_signature)
 
     @property
-    def final_commit_id(self):
+    def final_commit_id(self) -> Oid:
         return Oid(
             raw=bytes(ffi.buffer(ffi.addressof(self._hunk, 'final_commit_id'))[:])
         )
 
     @property
-    def orig_start_line_number(self):
+    def orig_start_line_number(self) -> int:
         """Origin start line number"""
         return self._hunk.orig_start_line_number
 
     @property
-    def orig_committer(self):
+    def orig_committer(self) -> None | Signature:
         """Original committer"""
         return wrap_signature(self._hunk.orig_signature)
 
     @property
-    def orig_commit_id(self):
+    def orig_commit_id(self) -> Oid:
         return Oid(
             raw=bytes(ffi.buffer(ffi.addressof(self._hunk, 'orig_commit_id'))[:])
         )
 
     @property
-    def orig_path(self):
+    def orig_path(self) -> None | str:
         """Original path"""
         path = self._hunk.orig_path
         if not path:
             return None
 
-        return ffi.string(path).decode('utf-8')
+        return ffi.string(path).decode('utf-8')  # type: ignore[no-any-return]
 
 
 class Blame:
+    _repo: Repository
+    _blame: 'GitBlameC'
+
     @classmethod
-    def _from_c(cls, repo, ptr):
+    def _from_c(cls, repo: Repository, ptr: 'GitBlameC') -> 'Blame':
         blame = cls.__new__(cls)
         blame._repo = repo
         blame._blame = ptr
         return blame
 
-    def __del__(self):
+    def __del__(self) -> None:
         C.git_blame_free(self._blame)
 
-    def __len__(self):
-        return C.git_blame_get_hunk_count(self._blame)
+    def __len__(self) -> int:
+        return C.git_blame_get_hunk_count(self._blame)  # type: ignore[no-any-return]
 
-    def __getitem__(self, index):
+    def __getitem__(self, index: int) -> BlameHunk:
         chunk = C.git_blame_get_hunk_byindex(self._blame, index)
         if not chunk:
             raise IndexError
 
         return BlameHunk._from_c(self, chunk)
 
-    def for_line(self, line_no):
+    def for_line(self, line_no: int) -> BlameHunk:
         """
         Returns the <BlameHunk> object for a given line given its number in the
         current Blame.
@@ -143,5 +154,5 @@ def for_line(self, line_no):
 
         return BlameHunk._from_c(self, chunk)
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[BlameHunk]:
         return GenericIterator(self)

pygit2/utils.py

@@ -29,6 +29,8 @@
 # Import from pygit2
 from .ffi import ffi, C
 
+from typing import Protocol, Iterator, TypeVar, Generic
+
 
 def maybe_string(ptr):
     if not ptr:
@@ -153,22 +155,31 @@ def assign_to(self, git_strarray):
             git_strarray.count = len(self.__strings)
 
 
-class GenericIterator:
+T = TypeVar('T')
+U = TypeVar('U', covariant=True)
+
+
+class SequenceProtocol(Protocol[U]):
+    def __len__(self) -> int: ...
+    def __getitem__(self, index: int) -> U: ...
+
+
+class GenericIterator(Generic[T]):
     """Helper to easily implement an iterator.
 
     The constructor gets a container which must implement __len__ and
     __getitem__
     """
 
-    def __init__(self, container):
+    def __init__(self, container: SequenceProtocol[T]) -> None:
         self.container = container
         self.length = len(container)
         self.idx = 0
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[T]:
         return self
 
-    def __next__(self):
+    def __next__(self) -> T:
         idx = self.idx
         if idx >= self.length:
             raise StopIteration

test/test_blame.py

@@ -27,7 +27,7 @@
 
 import pytest
 
-from pygit2 import Signature, Oid
+from pygit2 import Signature, Oid, Repository
 from pygit2.enums import BlameFlag
 
 
@@ -61,7 +61,7 @@
 ]
 
 
-def test_blame_index(testrepo):
+def test_blame_index(testrepo: Repository) -> None:
     blame = testrepo.blame(PATH)
 
     assert len(blame) == 3
@@ -78,7 +78,7 @@ def test_blame_index(testrepo):
         assert HUNKS[i][3] == hunk.boundary
 
 
-def test_blame_flags(blameflagsrepo):
+def test_blame_flags(blameflagsrepo: Repository) -> None:
     blame = blameflagsrepo.blame(PATH, flags=BlameFlag.IGNORE_WHITESPACE)
 
     assert len(blame) == 3
@@ -95,7 +95,7 @@ def test_blame_flags(blameflagsrepo):
         assert HUNKS[i][3] == hunk.boundary
 
 
-def test_blame_with_invalid_index(testrepo):
+def test_blame_with_invalid_index(testrepo: Repository) -> None:
     blame = testrepo.blame(PATH)
 
     def test():
@@ -106,7 +106,7 @@ def test():
         test()
 
 
-def test_blame_for_line(testrepo):
+def test_blame_for_line(testrepo: Repository) -> None:
     blame = testrepo.blame(PATH)
 
     for i, line in zip(range(0, 2), range(1, 3)):
@@ -123,19 +123,18 @@ def test_blame_for_line(testrepo):
         assert HUNKS[i][3] == hunk.boundary
 
 
-def test_blame_with_invalid_line(testrepo):
+def test_blame_with_invalid_line(testrepo: Repository) -> None:
     blame = testrepo.blame(PATH)
 
-    def test():
+    with pytest.raises(IndexError):
         blame.for_line(0)
+    with pytest.raises(IndexError):
         blame.for_line(100000)
-        blame.for_line(-1)
-
     with pytest.raises(IndexError):
-        test()
+        blame.for_line(-1)
 
 
-def test_blame_newest(testrepo):
+def test_blame_newest(testrepo: Repository) -> None:
     revs = [
         ('master^2', 3),
         ('master^2^', 2),