Add specific exception classes for libgit2 error codes

The following libgit2 errors are now raised as specific pygit2
exceptions instead of plain ValueError or KeyError:

- AlreadyExistsError (also ValueError)
- InvalidSpecError (also ValueError)
- InvalidError (also ValueError)
- NotFoundError (also KeyError)
- AmbiguousError (also ValueError)
- AuthError
- CertificateError

All new exceptions inherit from GitError, so existing code catching
GitError, ValueError, KeyError, or Exception continues to work.

Fixes #830
Closes #998

Assisted-by: Kimi Code

Author: jdavid

CHANGELOG.md

@@ -1,3 +1,12 @@
+# 1.20.1 (UNRELEASED)
+
+- New exception hierarchy: `AlreadyExistsError`, `InvalidSpecError`,
+  `InvalidError`, `NotFoundError`, `AmbiguousError`, `AuthError`, and
+  `CertificateError` all inherit from `GitError` and the appropriate Python
+  built-in exception (`ValueError`/`KeyError`) for backward compatibility
+  [#830](https://github.com/libgit2/pygit2/issues/830).
+
+
 # 1.20.0 (2026-08-08)
 
 - New `RemoteCallbacks.custom_headers()`

docs/general.rst

@@ -81,10 +81,92 @@ Exception when trying to create an object (reference, etc) that already exists.
 
 Exception when an input specification such as a reference name is invalid.
 
+.. autoexception:: pygit2.InvalidError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception when an operation or input is invalid.
+
+.. autoexception:: pygit2.NotFoundError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception when a requested object could not be found.
+
+.. autoexception:: pygit2.AmbiguousError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception when more than one object matches.
+
+.. autoexception:: pygit2.AuthError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception when an authentication error occurs.
+
+.. autoexception:: pygit2.CertificateError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Exception when a server certificate is invalid.
+
 .. autoexception:: pygit2.Passthrough
    :members:
    :show-inheritance:
    :undoc-members:
 
 Exception that can be raised from a callback to tell libgit2 to behave as if
 that callback had not been set. See :doc:`callbacks` for details.
+
+Error mapping
+=============
+
+The following table shows how libgit2 error codes map to pygit2 exceptions.
+The new exception classes inherit from :py:exc:`pygit2.GitError` and, where
+noted, from a Python built-in exception for backward compatibility.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 35 30
+
+   * - pygit2 exception
+     - libgit2 code / class
+     - Built-in base
+
+   * - :py:exc:`AlreadyExistsError`
+     - ``GIT_EEXISTS``
+     - ``ValueError``
+
+   * - :py:exc:`InvalidSpecError`
+     - ``GIT_EINVALIDSPEC``
+     - ``ValueError``
+
+   * - :py:exc:`InvalidError`
+     - ``GIT_EINVALID``, ``GIT_ERROR_INVALID``
+     - ``ValueError``
+
+   * - :py:exc:`NotFoundError`
+     - ``GIT_ENOTFOUND``
+     - ``KeyError``
+
+   * - :py:exc:`AmbiguousError`
+     - ``GIT_EAMBIGUOUS``
+     - ``ValueError``
+
+   * - :py:exc:`AuthError`
+     - ``GIT_EAUTH``
+     -
+
+   * - :py:exc:`CertificateError`
+     - ``GIT_ECERTIFICATE``
+     -
+
+   * - :py:exc:`GitError`
+     - generic / other errors
+     -

pygit2/__init__.py

@@ -248,7 +248,6 @@
     LIBGIT2_VER_MINOR,
     LIBGIT2_VER_REVISION,
     LIBGIT2_VERSION,
-    AlreadyExistsError,
     Blob,
     Branch,
     Commit,
@@ -259,8 +258,6 @@
     DiffLine,
     DiffStats,
     FilterSource,
-    GitError,
-    InvalidSpecError,
     Mailmap,
     Note,
     Object,
@@ -306,7 +303,18 @@
 )
 from .config import Config
 from .credentials import *
-from .errors import Passthrough, check_error
+from .errors import (
+    AlreadyExistsError,
+    AmbiguousError,
+    AuthError,
+    CertificateError,
+    GitError,
+    InvalidError,
+    InvalidSpecError,
+    NotFoundError,
+    Passthrough,
+    check_error,
+)
 from .ffi import C, ffi
 from .filter import Filter
 from .index import Index, IndexEntry
@@ -592,8 +600,11 @@ def filter_unregister(name: str) -> None:
     'Object',
     'Reference',
     'AlreadyExistsError',
+    'AmbiguousError',
+    'AuthError',
     'Blob',
     'Branch',
+    'CertificateError',
     'Commit',
     'Diff',
     'DiffDelta',
@@ -602,9 +613,11 @@ def filter_unregister(name: str) -> None:
     'DiffLine',
     'DiffStats',
     'GitError',
+    'InvalidError',
     'InvalidSpecError',
     'Mailmap',
     'Note',
+    'NotFoundError',
     'Odb',
     'OdbBackend',
     'OdbBackendLoose',

pygit2/_pygit2.pyi

@@ -331,7 +331,10 @@ class Reference:
     def __lt__(self, other, /) -> bool: ...
     def __ne__(self, other, /) -> bool: ...
 
-class AlreadyExistsError(ValueError): ...
+class AlreadyExistsError(GitError, ValueError): ...
+class AmbiguousError(GitError, ValueError): ...
+class AuthError(GitError): ...
+class InvalidError(GitError, ValueError): ...
 
 @final
 class Blob(Object):
@@ -376,6 +379,8 @@ class Branch(Reference):  # type: ignore[misc]
     def is_head(self) -> bool: ...
     def rename(self, name: str, force: bool = False) -> 'Branch': ...  # type: ignore[override]
 
+class CertificateError(GitError): ...
+
 @final
 class Commit(_ObjectBase[GitCommitC]):
     _pointer: _Pointer[GitCommitC]
@@ -476,7 +481,7 @@ class FilterSource:
     flags: int
 
 class GitError(Exception): ...
-class InvalidSpecError(ValueError): ...
+class InvalidSpecError(GitError, ValueError): ...
 
 @final
 class Mailmap:
@@ -505,6 +510,8 @@ class Note:
         self, author: Signature, committer: Signature, ref: str = 'refs/notes/commits'
     ) -> None: ...
 
+class NotFoundError(GitError, KeyError): ...
+
 @final
 class Odb:
     backends: Iterator[OdbBackend]

pygit2/errors.py

@@ -24,12 +24,39 @@
 # Boston, MA 02110-1301, USA.
 
 # Import from pygit2
-from ._pygit2 import GitError
+from ._pygit2 import (
+    AlreadyExistsError,
+    AmbiguousError,
+    AuthError,
+    CertificateError,
+    GitError,
+    InvalidError,
+    InvalidSpecError,
+    NotFoundError,
+)
 from .ffi import C, ffi
 
-__all__ = ['GitError']
+__all__ = [
+    'AlreadyExistsError',
+    'AmbiguousError',
+    'AuthError',
+    'CertificateError',
+    'GitError',
+    'InvalidError',
+    'InvalidSpecError',
+    'NotFoundError',
+    'Passthrough',
+]
 
-value_errors = set([C.GIT_EEXISTS, C.GIT_EINVALIDSPEC, C.GIT_EAMBIGUOUS])
+# Docstrings for C-defined exception classes
+GitError.__doc__ = 'Generic libgit2 error.'
+AlreadyExistsError.__doc__ = 'Object already exists.'
+InvalidSpecError.__doc__ = 'Invalid name/ref spec.'
+NotFoundError.__doc__ = 'Requested object could not be found.'
+AmbiguousError.__doc__ = 'More than one object matches.'
+AuthError.__doc__ = 'Authentication error.'
+CertificateError.__doc__ = 'Server certificate is invalid.'
+InvalidError.__doc__ = 'Invalid operation or input.'
 
 
 def check_error(err: int, io: bool = False) -> None:
@@ -48,17 +75,32 @@ def check_error(err: int, io: bool = False) -> None:
         message = f'err {err} (no message provided)'
 
     # Translate to Python errors
-    if err in value_errors:
+    if err == C.GIT_EEXISTS:
+        raise AlreadyExistsError(message)
+
+    if err == C.GIT_EINVALIDSPEC:
+        raise InvalidSpecError(message)
+
+    if err == C.GIT_EINVALID:
+        raise InvalidError(message)
+
+    if err == C.GIT_EAMBIGUOUS:
+        raise AmbiguousError(message)
+
+    if err == C.GIT_EBUFS:
         raise ValueError(message)
 
+    if err == C.GIT_EAUTH:
+        raise AuthError(message)
+
+    if err == C.GIT_ECERTIFICATE:
+        raise CertificateError(message)
+
     if err == C.GIT_ENOTFOUND:
         if io:
             raise IOError(message)
 
-        raise KeyError(message)
-
-    if err == C.GIT_EINVALIDSPEC:
-        raise ValueError(message)
+        raise NotFoundError(message)
 
     if err == C.GIT_ITEROVER:
         raise StopIteration()

src/error.c

@@ -30,6 +30,11 @@
 extern PyObject *GitError;
 extern PyObject *AlreadyExistsError;
 extern PyObject *InvalidSpecError;
+extern PyObject *InvalidError;
+extern PyObject *NotFoundError;
+extern PyObject *AmbiguousError;
+extern PyObject *AuthError;
+extern PyObject *CertificateError;
 
 PyObject *
 Error_type(int type)
@@ -39,15 +44,15 @@ Error_type(int type)
     switch (type) {
         /* Input does not exist in the scope searched. */
         case GIT_ENOTFOUND:
-            return PyExc_KeyError;
+            return NotFoundError;
 
         /* A reference with this name already exists */
         case GIT_EEXISTS:
             return AlreadyExistsError;
 
         /* The given short oid is ambiguous */
         case GIT_EAMBIGUOUS:
-            return PyExc_ValueError;
+            return AmbiguousError;
 
         /* The buffer is too short to satisfy the request */
         case GIT_EBUFS:
@@ -57,6 +62,18 @@ Error_type(int type)
         case GIT_EINVALIDSPEC:
             return InvalidSpecError;
 
+        /* Invalid operation or input */
+        case GIT_EINVALID:
+            return InvalidError;
+
+        /* Authentication error */
+        case GIT_EAUTH:
+            return AuthError;
+
+        /* Server certificate is invalid */
+        case GIT_ECERTIFICATE:
+            return CertificateError;
+
         /* Skip and passthrough the given ODB backend */
         case GIT_PASSTHROUGH:
             return GitError;
@@ -75,7 +92,7 @@ Error_type(int type)
             case GITERR_OS:
                 return PyExc_OSError;
             case GITERR_INVALID:
-                return PyExc_ValueError;
+                return InvalidError;
         }
     }
     return GitError;
@@ -106,8 +123,8 @@ PyObject *
 Error_set_str(int err, const char *str)
 {
     if (err == GIT_ENOTFOUND) {
-        /* KeyError expects the arg to be the missing key. */
-        PyErr_SetString(PyExc_KeyError, str);
+        /* NotFoundError inherits from KeyError; the argument is the missing key. */
+        PyErr_SetString(NotFoundError, str);
         return NULL;
     }
 

src/pygit2.c

@@ -40,6 +40,11 @@
 PyObject *GitError;
 PyObject *AlreadyExistsError;
 PyObject *InvalidSpecError;
+PyObject *InvalidError;
+PyObject *NotFoundError;
+PyObject *AmbiguousError;
+PyObject *AuthError;
+PyObject *CertificateError;
 
 PyObject *DeltaStatusEnum;
 PyObject *DiffFlagEnum;
@@ -461,8 +466,13 @@ PyInit__pygit2(void)
 
     /* Exceptions */
     ADD_EXC(m, GitError, NULL);
-    ADD_EXC(m, AlreadyExistsError, PyExc_ValueError);
-    ADD_EXC(m, InvalidSpecError, PyExc_ValueError);
+    ADD_EXC2(m, AlreadyExistsError, GitError, PyExc_ValueError);
+    ADD_EXC2(m, InvalidSpecError, GitError, PyExc_ValueError);
+    ADD_EXC2(m, InvalidError, GitError, PyExc_ValueError);
+    ADD_EXC2(m, NotFoundError, GitError, PyExc_KeyError);
+    ADD_EXC2(m, AmbiguousError, GitError, PyExc_ValueError);
+    ADD_EXC(m, AuthError, GitError);
+    ADD_EXC(m, CertificateError, GitError);
 
     /* Repository */
     INIT_TYPE(RepositoryType, NULL, PyType_GenericNew)