create type interface for _libgit2.ffi

Author: BenediktSeidl

pygit2/__init__.py

@@ -164,7 +164,7 @@ def clone_repository(
     callbacks: RemoteCallbacks | None = None,
     depth: int = 0,
     proxy: None | bool | str = None,
-):
+) -> Repository:
     """
     Clones a new Git repository from *url* in the given *path*.
 

pygit2/_libgit2/ffi.pyi

@@ -0,0 +1,273 @@
+# Copyright 2010-2025 The pygit2 contributors
+#
+# This file is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License, version 2,
+# as published by the Free Software Foundation.
+#
+# In addition to the permissions in the GNU General Public License,
+# the authors give you unlimited permission to link the compiled
+# version of this file into combinations with other programs,
+# and to distribute those combinations without any restriction
+# coming from the use of this file.  (The General Public License
+# restrictions do apply in other respects; for example, they cover
+# modification of the file, and distribution when not linked into
+# a combined executable.)
+#
+# This file is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; see the file COPYING.  If not, write to
+# the Free Software Foundation, 51 Franklin Street, Fifth Floor,
+# Boston, MA 02110-1301, USA.
+
+from typing import Literal, overload, NewType, TypeVar, Generic, Any, SupportsIndex
+from typing import NewType, Literal, TypeVar, Generic, overload
+from pygit2._pygit2 import Repository
+
+T = TypeVar('T')
+
+NULL_TYPE = NewType('NULL_TYPE', object)
+NULL: NULL_TYPE = ...
+
+char = NewType('char', object)
+char_pointer = NewType('char_pointer', object)
+
+class _Pointer(Generic[T]):
+    def __setitem__(self, item: Literal[0], a: T) -> None: ...
+    @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: char_pointer
+    lines_in_hunk: int
+
+class GitRepositoryC:
+    # incomplete
+    # TODO: this has to be unified with pygit2._pygit2(pyi).Repository
+    def _from_c(cls, ptr: 'GitRepositoryC', owned: bool) -> 'Repository': ...
+
+class GitFetchOptionsC:
+    # TODO: FetchOptions exist in _pygit2.pyi
+    # incomplete
+    depth: int
+
+class GitSubmoduleC:
+    pass
+
+class GitSubmoduleUpdateOptionsC:
+    fetch_opts: GitFetchOptionsC
+
+class UnsignedIntC:
+    def __getitem__(self, item: Literal[0]) -> int: ...
+
+class GitOidC:
+    id: _Pointer[bytes]
+
+class GitBlameOptionsC:
+    flags: int
+    min_match_characters: int
+    newest_commit: object
+    oldest_commit: object
+    min_line: int
+    max_line: int
+
+class GitBlameC:
+    # incomplete
+    pass
+
+class GitMergeOptionsC:
+    file_favor: int
+    flags: int
+    file_flags: int
+
+class GitAnnotatedCommitC:
+    pass
+
+class GitAttrOptionsC:
+    # incomplete
+    version: int
+    flags: int
+
+class GitBufC:
+    ptr: char_pointer
+
+class GitCheckoutOptionsC:
+    # incomplete
+    checkout_strategy: int
+
+class GitCommitC:
+    pass
+
+class GitConfigC:
+    pass
+
+class GitDescribeFormatOptionsC:
+    version: int
+    abbreviated_size: int
+    always_use_long_format: int
+    dirty_suffix: char_pointer
+
+class GitDescribeOptionsC:
+    version: int
+    max_candidates_tags: int
+    describe_strategy: int
+    pattern: char_pointer
+    only_follow_first_parent: int
+    show_commit_oid_as_fallback: int
+
+class GitDescribeResultC:
+    pass
+
+class GitIndexC:
+    pass
+
+class GitMergeFileResultC:
+    pass
+
+class GitObjectC:
+    pass
+
+class GitStashSaveOptionsC:
+    version: int
+    flags: int
+    stasher: GitSignatureC
+    message: char_pointer
+    paths: GitStrrayC
+
+class GitStrrayC:
+    pass
+
+class GitTreeC:
+    pass
+
+class GitRepositoryInitOptionsC:
+    version: int
+    flags: int
+    mode: int
+    workdir_path: char_pointer
+    description: char_pointer
+    template_path: char_pointer
+    initial_head: char_pointer
+    origin_url: char_pointer
+
+class GitCloneOptionsC:
+    pass
+
+class GitProxyTC:
+    pass
+
+class GitProxyOptionsC:
+    version: int
+    type: GitProxyTC
+    url: char_pointer
+    # credentials
+    # certificate_check
+    # payload
+
+class GitRemoteC:
+    pass
+
+class GitReferenceC:
+    pass
+
+def string(a: char_pointer) -> bytes: ...
+@overload
+def new(a: Literal['git_repository **']) -> _Pointer[GitRepositoryC]: ...
+@overload
+def new(a: Literal['git_remote **']) -> _Pointer[GitRemoteC]: ...
+@overload
+def new(a: Literal['git_repository_init_options *']) -> GitRepositoryInitOptionsC: ...
+@overload
+def new(a: Literal['git_submodule_update_options *']) -> GitSubmoduleUpdateOptionsC: ...
+@overload
+def new(a: Literal['git_submodule **']) -> _Pointer[GitSubmoduleC]: ...
+@overload
+def new(a: Literal['unsigned int *']) -> UnsignedIntC: ...
+@overload
+def new(a: Literal['git_proxy_options *']) -> GitProxyOptionsC: ...
+@overload
+def new(a: Literal['git_oid *']) -> GitOidC: ...
+@overload
+def new(a: Literal['git_blame **']) -> _Pointer[GitBlameC]: ...
+@overload
+def new(a: Literal['git_clone_options *']) -> GitCloneOptionsC: ...
+@overload
+def new(a: Literal['git_merge_options *']) -> GitMergeOptionsC: ...
+@overload
+def new(a: Literal['git_blame_options *']) -> GitBlameOptionsC: ...
+@overload
+def new(a: Literal['git_annotated_commit **']) -> _Pointer[GitAnnotatedCommitC]: ...
+@overload
+def new(a: Literal['git_attr_options *']) -> GitAttrOptionsC: ...
+@overload
+def new(a: Literal['git_buf *']) -> GitBufC: ...
+@overload
+def new(a: Literal['git_checkout_options *']) -> GitCheckoutOptionsC: ...
+@overload
+def new(a: Literal['git_commit **']) -> _Pointer[GitCommitC]: ...
+@overload
+def new(a: Literal['git_config *']) -> GitConfigC: ...
+@overload
+def new(a: Literal['git_describe_format_options *']) -> GitDescribeFormatOptionsC: ...
+@overload
+def new(a: Literal['git_describe_options *']) -> GitDescribeOptionsC: ...
+@overload
+def new(a: Literal['git_describe_result *']) -> GitDescribeResultC: ...
+@overload
+def new(a: Literal['git_describe_result **']) -> _Pointer[GitDescribeResultC]: ...
+@overload
+def new(a: Literal['struct git_reference **']) -> _Pointer[GitReferenceC]: ...
+@overload
+def new(a: Literal['git_index **']) -> _Pointer[GitIndexC]: ...
+@overload
+def new(a: Literal['git_merge_file_result *']) -> GitMergeFileResultC: ...
+@overload
+def new(a: Literal['git_object *']) -> GitObjectC: ...
+@overload
+def new(a: Literal['git_object **']) -> _Pointer[GitObjectC]: ...
+@overload
+def new(a: Literal['git_signature *']) -> GitSignatureC: ...
+@overload
+def new(a: Literal['git_signature **']) -> _Pointer[GitSignatureC]: ...
+@overload
+def new(a: Literal['git_stash_save_options *']) -> GitStashSaveOptionsC: ...
+@overload
+def new(a: Literal['git_tree **']) -> _Pointer[GitTreeC]: ...
+@overload
+def new(a: Literal['git_buf *'], b: tuple[NULL_TYPE, Literal[0]]) -> GitBufC: ...
+@overload
+def new(a: Literal['char **']) -> _Pointer[char_pointer]: ...
+@overload
+def new(a: Literal['char[]', 'char []'], b: bytes | NULL_TYPE) -> char_pointer: ...
+def addressof(a: object, attribute: str) -> _Pointer[object]: ...
+
+class buffer(bytes):
+    def __init__(self, a: object) -> None: ...
+    def __setitem__(self, item: slice[None, None, None], value: bytes) -> None: ...
+    @overload
+    def __getitem__(self, item: SupportsIndex) -> int: ...
+    @overload
+    def __getitem__(self, item: slice[Any, Any, Any]) -> bytes: ...
+
+def cast(a: Literal['int'], b: object) -> int: ...

pygit2/_pygit2.pyi

@@ -1,4 +1,13 @@
-from typing import Iterator, Literal, Optional, overload, Type, TypedDict
+from typing import (
+    Iterator,
+    Literal,
+    Optional,
+    overload,
+    Type,
+    TypedDict,
+    TypeVar,
+    Generic,
+)
 from io import IOBase, DEFAULT_BUFFER_SIZE
 from pathlib import Path
 from queue import Queue
@@ -29,7 +38,14 @@ from .enums import (
 )
 from collections.abc import Generator
 
-from ._pygit2_c import GitSignatureC, _Pointer
+from ._libgit2.ffi import (
+    _Pointer,
+    GitObjectC,
+    GitCommitC,
+    GitRepositoryC,
+    GitProxyOptionsC,
+    GitSignatureC,
+)
 
 from .repository import BaseRepository
 from .submodules import SubmoduleCollection, Submodule
@@ -287,8 +303,10 @@ GIT_FILTER_NO_SYSTEM_ATTRIBUTES: int
 GIT_FILTER_ATTRIBUTES_FROM_HEAD: int
 GIT_FILTER_ATTRIBUTES_FROM_COMMIT: int
 
-class Object:
-    _pointer: bytes
+T = TypeVar('T')
+
+class _ObjectBase(Generic[T]):
+    _pointer: _Pointer[T]
     filemode: FileMode
     id: Oid
     name: str | None
@@ -320,6 +338,9 @@ class Object:
     def __lt__(self, other) -> bool: ...
     def __ne__(self, other) -> bool: ...
 
+class Object(_ObjectBase[GitObjectC]):
+    pass
+
 class Reference:
     name: str
     raw_name: bytes
@@ -395,7 +416,7 @@ class Branch(Reference):
 class FetchOptions:
     # incomplete
     depth: int
-    proxy_opts: ProxyOpts
+    proxy_opts: GitProxyOptionsC
 
 class CloneOptions:
     # incomplete
@@ -410,7 +431,8 @@ class CloneOptions:
     remote_cb: object
     remote_cb_payload: object
 
-class Commit(Object):
+class Commit(_ObjectBase[GitCommitC]):
+    _pointer: _Pointer[GitCommitC]
     author: Signature
     commit_time: int
     commit_time_offset: int
@@ -640,16 +662,11 @@ class _StrArray:
     # incomplete
     count: int
 
-class ProxyOpts:
-    # incomplete
-    type: object
-    url: str
-
 class PushOptions:
     version: int
     pb_parallelism: int
     callbacks: object  # TODO
-    proxy_opts: ProxyOpts
+    proxy_opts: GitProxyOptionsC
     follow_redirects: object  # TODO
     custom_headers: _StrArray
     remote_push_options: _StrArray
@@ -696,7 +713,7 @@ class Branches:
     def __contains__(self, name: _OidArg) -> bool: ...
 
 class Repository:
-    _pointer: bytes
+    _pointer: GitRepositoryC
     default_signature: Signature
     head: Reference
     head_is_detached: bool
@@ -716,7 +733,8 @@ class Repository:
     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) -> 'Repository': ...
+    @classmethod
+    def _from_c(cls, ptr: 'GitRepositoryC', owned: bool) -> 'Repository': ...
     def __getitem__(self, key: str | Oid) -> Object: ...
     def add_worktree(self, name: str, path: str, ref: Reference = ...) -> Worktree: ...
     def applies(