Coverage for src / lexigram / contracts / auth / exceptions.py: 88%

1"""Auth domain base error hierarchy. 

2 

3These are the base exception types that any package can catch at the 

4auth-domain boundary without depending on ``lexigram-auth``. 

5 

6Infrastructure failures (cache down, network errors, configuration errors) 

7must still be raised as exceptions — do not wrap them in ``Result``. 

8 

9Leaf exceptions (``InvalidCredentialsError``, ``TokenExpiredError``, etc.) 

10live in ``lexigram.auth.exceptions`` — import from there when you need to 

11distinguish specific auth failure modes. 

12 

13Error hierarchy 

14--------------- 

15:: 

16 

17 AuthError Base for all auth-domain failures 

18 TokenError Base for all expected token failures 

19 VerificationError Base for all account-verification failures 

20""" 

21 

22from __future__ import annotations 

23 

24from typing import Any 

25 

26from lexigram.contracts.exceptions.domain import DomainError 

27 

28 

29class AuthError(DomainError): 

30 """Base exception for all auth-domain errors. 

31 

32 This is the catch-all for authentication and authorization failures 

33 that clients are expected to handle gracefully. 

34 """ 

35 

36 _code = "LEX_ERR_AUTH_001" 

37 

38 def __init__( 

39 self, 

40 message: str = "Auth error", 

41 **kwargs: Any, 

42 ) -> None: 

43 super().__init__(message, **kwargs) 

44 

45 

46class TokenError(DomainError): 

47 """Base class for expected, recoverable token domain failures. 

48 

49 All subtypes indicate situations the caller is expected to handle 

50 gracefully (e.g. reject the request, ask for re-authentication). 

51 """ 

52 

53 _code = "LEX_ERR_AUTH_002" 

54 

55 def __init__( 

56 self, 

57 message: str = "Token error", 

58 **kwargs: Any, 

59 ) -> None: 

60 super().__init__(message, **kwargs) 

61 

62 

63class VerificationError(DomainError): 

64 """Base class for expected, recoverable account-verification failures. 

65 

66 All subtypes signal situations the caller should handle gracefully 

67 (e.g. redirect to a re-verification page or surface a user-facing error). 

68 """ 

69 

70 _code = "LEX_ERR_AUTH_003" 

71 

72 def __init__( 

73 self, 

74 message: str = "Account verification error", 

75 **kwargs: Any, 

76 ) -> None: 

77 super().__init__(message, **kwargs) 

78 

79 

80__all__ = [ 

81 "AuthError", 

82 "TokenError", 

83 "VerificationError", 

84]