Improve typing: add References to Repository

pygit2 was removed from the python typeshed, but the built in types of
pygit2 are not complete.

This change tries to improve this situation, by fixing type errors that
occur when activating typing for the tests.
So first the test functions (for the public API) in test/test_refs.py
were adapted, in order to activate mypy type checking.
Then _pygit2.pyi was adapted to fix those mypy type checking errors.

The skeleton was provided by:
    stubgen -m pygit2.references -o /tmp/pygit2

The following command
    mypy test
returned the following summary before this change:
    Found 289 errors in 10 files (checked 50 source files)
and after this change:
    Found 289 errors in 10 files (checked 50 source files)

Author: BenediktSeidl

pygit2/_pygit2.pyi

@@ -1,4 +1,4 @@
-from typing import Iterator, Literal, Optional, overload
+from typing import Iterator, Literal, Optional, overload, Type
 from io import IOBase
 from . import Index
 from .enums import (
@@ -20,6 +20,8 @@ from .enums import (
     SortMode,
 )
 
+from .repository import BaseRepository
+
 GIT_OBJ_BLOB = Literal[3]
 GIT_OBJ_COMMIT = Literal[1]
 GIT_OBJ_TAG = Literal[4]
@@ -73,15 +75,15 @@ class Reference:
     def delete(self) -> None: ...
     def log(self) -> Iterator[RefLogEntry]: ...
     @overload
-    def peel(self, type: 'Literal[GIT_OBJ_COMMIT]') -> 'Commit': ...
+    def peel(self, type: 'Literal[GIT_OBJ_COMMIT] | Type[Commit]') -> 'Commit': ...
     @overload
-    def peel(self, type: 'Literal[GIT_OBJ_TREE]') -> 'Tree': ...
+    def peel(self, type: 'Literal[GIT_OBJ_TREE] | Type[Tree]') -> 'Tree': ...
     @overload
-    def peel(self, type: 'Literal[GIT_OBJ_TAG]') -> 'Tag': ...
+    def peel(self, type: 'Literal[GIT_OBJ_TAG] | Type[Tag]') -> 'Tag': ...
     @overload
-    def peel(self, type: 'Literal[GIT_OBJ_BLOB]') -> 'Blob': ...
+    def peel(self, type: 'Literal[GIT_OBJ_BLOB] | Type[Blob]') -> 'Blob': ...
     @overload
-    def peel(self, type: 'None') -> 'Commit|Tree|Blob': ...
+    def peel(self, type: 'None' = None) -> 'Commit|Tree|Tag|Blob': ...
     def rename(self, new_name: str) -> None: ...
     def resolve(self) -> Reference: ...
     def set_target(self, target: _OidArg, message: str = ...) -> None: ...
@@ -329,6 +331,21 @@ class RefdbBackend:
 class RefdbFsBackend(RefdbBackend):
     def __init__(self, *args, **kwargs) -> None: ...
 
+class References:
+    def __init__(self, repository: BaseRepository) -> None: ...
+    def __getitem__(self, name: str) -> Reference: ...
+    def get(self, key: str) -> Reference: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def iterator(
+        self, references_return_type: ReferenceFilter = ...
+    ) -> Iterator[Reference]: ...
+    def create(self, name: str, target: _OidArg, force: bool = False) -> Reference: ...
+    def delete(self, name: str) -> None: ...
+    def __contains__(self, name: str) -> bool: ...
+    @property
+    def objects(self) -> list[Reference]: ...
+    def compress(self) -> None: ...
+
 class Repository:
     _pointer: bytes
     default_signature: Signature
@@ -342,10 +359,12 @@ class Repository:
     path: str
     refdb: Refdb
     workdir: str
+    references: References
     def __init__(self, *args, **kwargs) -> None: ...
     def TreeBuilder(self, src: Tree | _OidArg = ...) -> TreeBuilder: ...
     def _disown(self, *args, **kwargs) -> None: ...
     def _from_c(self, *args, **kwargs) -> None: ...
+    def __getitem__(self, key: str | bytes | Oid | Reference) -> Commit: ...
     def add_worktree(self, name: str, path: str, ref: Reference = ...) -> Worktree: ...
     def applies(
         self,
@@ -394,6 +413,9 @@ class Repository:
         ref: str = 'refs/notes/commits',
         force: bool = False,
     ) -> Oid: ...
+    def create_reference(
+        self, name: str, target: _OidArg, force: bool = False
+    ) -> Reference: ...
     def create_reference_direct(
         self, name: str, target: _OidArg, force: bool, message: Optional[str] = None
     ) -> Reference: ...
@@ -443,6 +465,7 @@ class Repository:
     def revparse(self, revspec: str) -> RevSpec: ...
     def revparse_ext(self, revision: str) -> tuple[Object, Reference]: ...
     def revparse_single(self, revision: str) -> Object: ...
+    def set_ident(self, name: str, email: str) -> None: ...
     def set_odb(self, odb: Odb) -> None: ...
     def set_refdb(self, refdb: Refdb) -> None: ...
     def status(

test/test_refs.py

@@ -29,7 +29,7 @@
 
 import pytest
 
-from pygit2 import Commit, Signature, Tree, reference_is_valid_name
+from pygit2 import Commit, Signature, Tree, reference_is_valid_name, Repository
 from pygit2 import AlreadyExistsError, GitError, InvalidSpecError
 from pygit2.enums import ReferenceType
 
@@ -45,7 +45,7 @@ def test_refs_list_objects(testrepo):
     ]
 
 
-def test_refs_list(testrepo):
+def test_refs_list(testrepo: Repository) -> None:
     # Without argument
     assert sorted(testrepo.references) == ['refs/heads/i18n', 'refs/heads/master']
 
@@ -58,13 +58,13 @@ def test_refs_list(testrepo):
     ]
 
 
-def test_head(testrepo):
+def test_head(testrepo: Repository) -> None:
     head = testrepo.head
     assert LAST_COMMIT == testrepo[head.target].id
     assert LAST_COMMIT == testrepo[head.raw_target].id
 
 
-def test_refs_getitem(testrepo):
+def test_refs_getitem(testrepo: Repository) -> None:
     refname = 'refs/foo'
     # Raise KeyError ?
     with pytest.raises(KeyError):
@@ -78,37 +78,37 @@ def test_refs_getitem(testrepo):
     assert reference.name == 'refs/heads/master'
 
 
-def test_refs_get_sha(testrepo):
+def test_refs_get_sha(testrepo: Repository) -> None:
     reference = testrepo.references['refs/heads/master']
     assert reference.target == LAST_COMMIT
 
 
-def test_refs_set_sha(testrepo):
+def test_refs_set_sha(testrepo: Repository) -> None:
     NEW_COMMIT = '5ebeeebb320790caf276b9fc8b24546d63316533'
     reference = testrepo.references.get('refs/heads/master')
     reference.set_target(NEW_COMMIT)
     assert reference.target == NEW_COMMIT
 
 
-def test_refs_set_sha_prefix(testrepo):
+def test_refs_set_sha_prefix(testrepo: Repository) -> None:
     NEW_COMMIT = '5ebeeebb320790caf276b9fc8b24546d63316533'
     reference = testrepo.references.get('refs/heads/master')
     reference.set_target(NEW_COMMIT[0:6])
     assert reference.target == NEW_COMMIT
 
 
-def test_refs_get_type(testrepo):
+def test_refs_get_type(testrepo: Repository) -> None:
     reference = testrepo.references.get('refs/heads/master')
     assert reference.type == ReferenceType.DIRECT
 
 
-def test_refs_get_target(testrepo):
+def test_refs_get_target(testrepo: Repository) -> None:
     reference = testrepo.references.get('HEAD')
     assert reference.target == 'refs/heads/master'
     assert reference.raw_target == b'refs/heads/master'
 
 
-def test_refs_set_target(testrepo):
+def test_refs_set_target(testrepo: Repository) -> None:
     reference = testrepo.references.get('HEAD')
     assert reference.target == 'refs/heads/master'
     assert reference.raw_target == b'refs/heads/master'
@@ -117,14 +117,14 @@ def test_refs_set_target(testrepo):
     assert reference.raw_target == b'refs/heads/i18n'
 
 
-def test_refs_get_shorthand(testrepo):
+def test_refs_get_shorthand(testrepo: Repository) -> None:
     reference = testrepo.references.get('refs/heads/master')
     assert reference.shorthand == 'master'
     reference = testrepo.references.create('refs/remotes/origin/master', LAST_COMMIT)
     assert reference.shorthand == 'origin/master'
 
 
-def test_refs_set_target_with_message(testrepo):
+def test_refs_set_target_with_message(testrepo: Repository) -> None:
     reference = testrepo.references.get('HEAD')
     assert reference.target == 'refs/heads/master'
     assert reference.raw_target == b'refs/heads/master'
@@ -139,7 +139,7 @@ def test_refs_set_target_with_message(testrepo):
     assert first.committer == sig
 
 
-def test_refs_delete(testrepo):
+def test_refs_delete(testrepo: Repository) -> None:
     # We add a tag as a new reference that points to "origin/master"
     reference = testrepo.references.create('refs/tags/version1', LAST_COMMIT)
     assert 'refs/tags/version1' in testrepo.references
@@ -163,7 +163,7 @@ def test_refs_delete(testrepo):
         reference.rename('refs/tags/version2')
 
 
-def test_refs_rename(testrepo):
+def test_refs_rename(testrepo: Repository) -> None:
     # We add a tag as a new reference that points to "origin/master"
     reference = testrepo.references.create('refs/tags/version1', LAST_COMMIT)
     assert reference.name == 'refs/tags/version1'
@@ -177,7 +177,7 @@ def test_refs_rename(testrepo):
         reference.rename('b1')
 
 
-# def test_reload(testrepo):
+# def test_reload(testrepo: Repository) -> None:
 #    name = 'refs/tags/version1'
 #    ref = testrepo.create_reference(name, "refs/heads/master", symbolic=True)
 #    ref2 = testrepo.lookup_reference(name)
@@ -187,21 +187,21 @@ def test_refs_rename(testrepo):
 #    with pytest.raises(GitError): getattr(ref2, 'name')
 
 
-def test_refs_resolve(testrepo):
+def test_refs_resolve(testrepo: Repository) -> None:
     reference = testrepo.references.get('HEAD')
     assert reference.type == ReferenceType.SYMBOLIC
     reference = reference.resolve()
     assert reference.type == ReferenceType.DIRECT
     assert reference.target == LAST_COMMIT
 
 
-def test_refs_resolve_identity(testrepo):
+def test_refs_resolve_identity(testrepo: Repository) -> None:
     head = testrepo.references.get('HEAD')
     ref = head.resolve()
     assert ref.resolve() is ref
 
 
-def test_refs_create(testrepo):
+def test_refs_create(testrepo: Repository) -> None:
     # We add a tag as a new reference that points to "origin/master"
     reference = testrepo.references.create('refs/tags/version1', LAST_COMMIT)
     refs = testrepo.references
@@ -220,7 +220,7 @@ def test_refs_create(testrepo):
     assert reference.target == LAST_COMMIT
 
 
-def test_refs_create_symbolic(testrepo):
+def test_refs_create_symbolic(testrepo: Repository) -> None:
     # We add a tag as a new symbolic reference that always points to
     # "refs/heads/master"
     reference = testrepo.references.create('refs/tags/beta', 'refs/heads/master')
@@ -241,11 +241,11 @@ def test_refs_create_symbolic(testrepo):
     assert reference.raw_target == b'refs/heads/master'
 
 
-# def test_packall_references(testrepo):
+# def test_packall_references(testrepo: Repository) -> None:
 #    testrepo.packall_references()
 
 
-def test_refs_peel(testrepo):
+def test_refs_peel(testrepo: Repository) -> None:
     ref = testrepo.references.get('refs/heads/master')
     assert testrepo[ref.target].id == ref.peel().id
     assert testrepo[ref.raw_target].id == ref.peel().id
@@ -254,7 +254,7 @@ def test_refs_peel(testrepo):
     assert commit.tree.id == ref.peel(Tree).id
 
 
-def test_refs_equality(testrepo):
+def test_refs_equality(testrepo: Repository) -> None:
     ref1 = testrepo.references.get('refs/heads/master')
     ref2 = testrepo.references.get('refs/heads/master')
     ref3 = testrepo.references.get('refs/heads/i18n')
@@ -267,7 +267,7 @@ def test_refs_equality(testrepo):
     assert not ref1 == ref3
 
 
-def test_refs_compress(testrepo):
+def test_refs_compress(testrepo: Repository) -> None:
     packed_refs_file = Path(testrepo.path) / 'packed-refs'
     assert not packed_refs_file.exists()
     old_refs = [(ref.name, ref.target) for ref in testrepo.references.objects]