Skip to content

either Module Reference

do

Bases: Generic[L]

Lift a function with do notation 

@do[LeftType]()
def myfn(e: Either[LeftType, int]):
  value = e.unsafe()
  return value + 1

myfn(Left('err')) # Left('err')
myfn(Right(1)) # Right(2)

Source code in haskellian/src/haskellian/either/do_notation.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class do(Generic[L]):
  """Lift a function with do notation
  ```
  @do[LeftType]()
  def myfn(e: Either[LeftType, int]):
    value = e.unsafe()
    return value + 1

  myfn(Left('err')) # Left('err')
  myfn(Right(1)) # Right(2)
  ```
  """
  @overload
  def __call__(self, fn: Callable[P, Coroutine[None, None, R]]) -> Callable[P, Coroutine[None, None, Either[L, R]]]: # type: ignore
    ...
  @overload
  def __call__(self, fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[Either[L, R]]]: # type: ignore
    ...
  @overload
  def __call__(self, fn: Callable[P, R]) -> Callable[P, Either[L, R]]:
    ...

  def __call__(self, fn): # type: ignore
    if iscoroutinefunction(fn):
      @wraps(fn)
      async def _wrapper(*args: P.args, **kwargs: P.kwargs):
        try:
          return Right(await fn(*args, **kwargs))
        except IsLeft as e:
          return Left(e.value)
      return _wrapper
    else:
      @wraps(fn)
      def wrapper(*args: P.args, **kwargs: P.kwargs):
        try:
          return Right(fn(*args, **kwargs))
        except IsLeft as e:
          return Left(e.value)
      return wrapper

safe

Bases: Generic[Err]

A decorator to catch exceptions and return them as Left.

@E.safe[OSError]()
def safe_write(path: str, content: bytes):
  with open(path, 'wb') as f:
    f.write(content)

result = safe_write('file.txt', b'content') # Either[OSError, None]
Source code in haskellian/src/haskellian/either/funcs.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class safe(Generic[Err]):
  """A decorator to catch exceptions and return them as `Left`.

  ```python
  @E.safe[OSError]()
  def safe_write(path: str, content: bytes):
    with open(path, 'wb') as f:
      f.write(content)

  result = safe_write('file.txt', b'content') # Either[OSError, None]
  ```
  """

  @property
  def exc(self) -> type[Err]:
    return get_args(self.__orig_class__)[0] # type: ignore (yep, typing internals are messed up)

  @overload
  def __call__(self, fn: Callable[P, Coroutine[None, None, R]]) -> Callable[P, Coroutine[None, None, Either[Err, R]]]: # type: ignore
    ...
  @overload
  def __call__(self, fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[Either[Err, R]]]: # type: ignore
    ...
  @overload
  def __call__(self, fn: Callable[P, R]) -> Callable[P, Either[Err, R]]:
    ...

  def __call__(self, fn): # type: ignore
    if iscoroutinefunction(fn):
      @wraps(fn)
      async def _wrapper(*args: P.args, **kwargs: P.kwargs):
        try:
          return Right(await fn(*args, **kwargs))
        except Exception as e:
          if isinstance(e, self.exc):
            return Left(e)
          raise e
      return _wrapper
    else:
      @wraps(fn)
      def wrapper(*args: P.args, **kwargs: P.kwargs):
        try:
          return Right(fn(*args, **kwargs))
        except Exception as e:
          if isinstance(e, self.exc):
            return Left(e)
          raise e
      return wrapper

filter(eithers)

Source code in haskellian/src/haskellian/either/funcs.py 
88
89
90
91
92
93
def filter(eithers: Iterable[Either[L, R]]) -> Iterable[R]:
  """"""
  for e in eithers:
    match e:
      case Right(value):
        yield value

filter_lefts(eithers)

Source code in haskellian/src/haskellian/either/funcs.py 
 95
 96
 97
 98
 99
100
def filter_lefts(eithers: Iterable[Either[L, R]]) -> Iterable[L]:
  """"""
  for e in eithers:
    match e:
      case Left(err):
        yield err

maybe(x)

Converts a nullable value to Either

Source code in haskellian/src/haskellian/either/funcs.py 
64
65
66
def maybe(x: R | None) -> 'Either[None, R]':
  """Converts a nullable value to `Either`"""
  return Left(None) if x is None else Right(x)

sequence(eithers)

List of lefts if any, otherwise list of all rights.

E.sequence([Left(1), Right(2), Right(3), Left(4)]) # Left([1, 4])
E.sequence([Right(2), Right(3)]) # Right([2, 3])
Source code in haskellian/src/haskellian/either/funcs.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
def sequence(eithers: Iterable[Either[L, R]]) -> Either[list[L], list[R]]:
  """List of lefts if any, otherwise list of all rights.

  ```python
  E.sequence([Left(1), Right(2), Right(3), Left(4)]) # Left([1, 4])
  E.sequence([Right(2), Right(3)]) # Right([2, 3])
  ```
  """
  lefts: list[L] = []
  rights: list[R] = []
  for x in eithers:
    x.match(lefts.append, rights.append)
  return Right(rights) if lefts == [] else Left(lefts)

take_while(eithers)

Source code in haskellian/src/haskellian/either/funcs.py 
102
103
104
105
106
107
108
109
def take_while(eithers: Iterable[Either[L, R]]) -> Iterable[R]:
  """"""
  for e in eithers:
    match e:
      case Right(x):
        yield x
      case _:
        return

is_left(either)

Type guard for Left

Source code in haskellian/src/haskellian/either/narrowing.py 
7
8
9
def is_left(either: Either[L, R]) -> TypeGuard[Left[L, R]]:
  """Type guard for `Left`"""
  return either.tag == 'left'

is_right(either)

Type guard for Right

Source code in haskellian/src/haskellian/either/narrowing.py 
11
12
13
def is_right(either: Either[L, R]) -> TypeGuard[Right[L, R]]:
  """Type guard for `Right`"""
  return either.tag == 'right'