Skip to content

either

The either package provides both functions and an Either class, that allows both method chaining and do notation style syntax.

Either[L, R]

Either[L, R] is roughly defined as:

class Left(Generic[L]):
  value: L
  tag: Literal['left']

class Right(Generic[R]):
  value: R
  tag: Literal['right']

Either[L, R] = Left[L] | Right[R]

Do Notation

Thought it supports both method chaining and either.tag == 'left' branching, the most common way to use an either is with a sort of do notation:

from haskellian import either as E, Either

def fetch_this() -> Either[KeyError, str]:
  ...

def fetch_that() -> Either[ValueError, str]:
  ...

@E.do[KeyError|ValueError]()
def do_function() -> str:
  this = fetch_this().unwrap() # str
  that = fetch_that().unwrap() # str
  return f'{this} and {that}'

do_function() # Either[KeyError|ValueError, str]

If you're familiar with Rust's ? operator, this should be familiar.

Functions

The either module has just a few utility functions:

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

Next up, asyn_iter