Coverage for src/monadc/either/left.py: 100%

1 from typing import Callable, Union, Any, Optional, cast

2 from .either import Either, L, R, U

3

4

5 class Left(Either[L, R]):

6 """

7 Represents a failed computation in an Either monad.

8

9 Left values pass through transformations unchanged, allowing error information

10 to propagate through a chain of operations.

11 """

12

13 __match_args__ = ("_value",)

14

15 def __new__(cls, value: L) -> 'Left[L, R]':

16 """Create a new Left instance directly, bypassing Either.__new__."""

17 return object.__new__(cls)

18

19 def __init__(self, value: Any = None, **kwargs: Any) -> None:

20 # If _value already exists, this is a second call from Python's object creation process

21 # We should ignore it since the object has already been properly initialized

22 if hasattr(self, '_value'):

23 return

24

25 # Handle factory construction: Either(left=x) calls Left.__init__(left_obj, left=x)

26 if 'left' in kwargs:

27 self._value = kwargs['left']

28 # Handle direct construction: Left(value)

29 else:

30 self._value = value

31

32 def __eq__(self, other: object) -> bool:

33 if isinstance(other, Left):

34 return self._value == other._value # type: ignore[no-any-return]

35 return False

36

37 def __repr__(self) -> str:

38 return f"Left({self._value! r})"

39

40 def __str__(self) -> str:

41 return self.__repr__()

42

43 # ========================================

44 # Rust / Scala Common API

45 # ========================================

46

47 def is_left(self) -> bool:

48 return True

49

50 def is_right(self) -> bool:

51 return False

52

53 def left(self) -> Any: # Returns Option[L]

54 from ..option import Some

55 return Some(self._value)

56

57 def right(self) -> Any: # Returns Option[R]

58 from ..option import Nil

59 return Nil()

60

61 def map(self, func: Callable[[Union[L, R]], U]) -> U:

62 return func(self._value)

63

64 def map_left(self, func: Callable[[L], U]) -> Either[U, R]:

65 result = func(self._value)

66 return Left(result)

67

68 def map_right(self, func: Callable[[R], U]) -> Either[L, U]:

69 # Left passes through unchanged

70 return cast(Either[L, U], self)

71

72 # ========================================

73 # RUST API

74 # ========================================

75

76 def either(self, left_func: Callable[[L], U], right_func: Callable[[R], U]) -> U:

77 """Apply left_func to Left value or right_func to Right value. Alias for fold."""

78 return self.fold(left_func, right_func)

79

80 def map_either(self, left_func: Callable[[L], U], right_func: Callable[[R], U]) -> U:

81 return left_func(self._value)

82

83 def unwrap_left(self) -> L:

84 return self._value # type: ignore[no-any-return]

85

86 def unwrap_right(self) -> R:

87 raise ValueError("Cannot unwrap right value from Left")

88

89 def expect_left(self, message: str) -> L:

90 return self._value # type: ignore[no-any-return]

91

92 def expect_right(self, message: str) -> R:

93 raise ValueError(message)

94

95 def left_or(self, other: Either[U, R]) -> Either[U, R]:

96 # Return self (Left) rather than other

97 return cast(Either[U, R], self)

98

99 def right_or(self, other: Either[L, U]) -> Either[L, U]:

100 # Return other since self is Left

101 return other

102

103 def left_or_else(self, func: Callable[[], Either[U, R]]) -> Either[U, R]:

104 # Return self (Left) rather than calling func

105 return cast(Either[U, R], self)

106

107 def right_or_else(self, func: Callable[[], Either[L, U]]) -> Either[L, U]:

108 # Call func and return result since self is Left

109 return func()

110

111 def left_and_then(self, func: Callable[[L], Either[U, R]]) -> Either[U, R]:

112 return func(self._value)

113

114 def right_and_then(self, func: Callable[[R], Either[L, U]]) -> Either[L, U]:

115 # Left passes through unchanged

116 return cast(Either[L, U], self)

117

118 def flip(self) -> Either[R, L]:

119 from .right import Right

120 return Right(self._value)

121

122 # ========================================

123 # SCALA API

124 # ========================================

125

126 def swap(self) -> Either[R, L]:

127 from .right import Right

128 return Right(self._value)

129

130 def fold(self, if_left: Callable[[L], U], if_right: Callable[[R], U]) -> U:

131 return if_left(self._value)

132

133 def foreach(self, func: Callable[[R], Any]) -> None:

134 # Left does nothing - Scala style right-biased behavior

135 pass

136

137 def get(self) -> R:

138 raise ValueError("Cannot get Right value from Left")

139

140 def get_or_else(self, default: Union[R, Callable[[], R]]) -> R:

141 if callable(default):

142 return default()

143 return default

144

145 def to_option(self) -> Any: # Returns Option[R]

146 from ..option import Nil

147 return Nil()

148

149 def contains(self, value: Any) -> bool:

150 # Left never contains a Right value

151 return False

152

153 def exists(self, predicate: Callable[[R], bool]) -> bool:

154 # Left has no Right value to test predicate against

155 return False

156

157 def or_else(self, other: Union['Either[L, U]', Callable[[], 'Either[L, U]']]) -> 'Either[L, Union[R, U]]':

158 # Return other since this is a Left

159 if callable(other):

160 return other()

161 return other