Skip to content

StatusOr

File: base/status/status_or.py

This file contains the StatusOr class.

A kern.StatusOr represents a class that holds a kern.Status object and a possible value of a certain type. The kern.StatusOr will either contain an object of a certain type (indicating a successful operation), or an error (of type kern.Status) explaining why such a value is not present.

In general, check the success of an operation returning an kern.StatusOr like you would an kern.Status by using the ok() member function.

Classes:

  • StatusOr –

    A container class that wraps either a value of a specified type or a Status object.

StatusOr

A container class that wraps either a value of a specified type or a Status object.

StatusOr is used to handle operations that might fail, allowing functions to return either a value or an error status. This pattern eliminates the need for exceptions in many cases and makes error handling more explicit.

Attributes:

  • _type (type) –

    The expected type for the value.

  • _val (object | None) –

    The value if the operation succeeded, None otherwise.

  • _status (Status) –

    A Status object representing the operation result. Will be an OK status if the operation succeeded.

Methods:

  • __init__ –

    Constructor.

  • from_exception –

    Alternative constructor that creates a StatusOr object from a Python exception.

  • status –

    Gets the Status object.

  • val –

    Gets the value.

  • ok –

    Checks if the StatusOr contains a valid value.

Source code in kern_comm_lib/base/status/status_or.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
class StatusOr:
  """A container class that wraps either a value of a specified type or a Status object.

  StatusOr is used to handle operations that might fail, allowing functions to return
  either a value or an error status. This pattern eliminates the need for exceptions
  in many cases and makes error handling more explicit.

  Attributes:
    _type: The expected type for the value.
    _val: The value if the operation succeeded, None otherwise.
    _status: A Status object representing the operation result.
        Will be an OK status if the operation succeeded.
  """

  def __init__(
      self, a_type: type, a_val_or_status: object | status.Status
  ) -> None:
    """Constructor.

    Args:
      a_type: The expected type for the value.
      a_val_or_status: Either a value of type `a_type` or a Status object.
          If a value is provided, it must match the specified type.
          If a Status object is provided, it represents an error condition.

    Raises:
      SystemExit: If a value is provided that doesn't match the expected type.
    """
    self._type: type = a_type
    if isinstance(a_val_or_status, status.Status):
      self._val: object | None = None
      self._status: status.Status = a_val_or_status
    else:
      # Check if the val is of the correct type or None
      if a_val_or_status is not None and not isinstance(
          a_val_or_status, a_type
      ):
        print(
            f"Expected value of type {a_type.__name__}, got {type(a_val_or_status).__name__}"
        )
        sys.exit(1)  # Crashes the program if the type is incorrect!
      self._val = a_val_or_status
      self._status = status.Status()

  # <editor-fold desc="Alternative constructors">
  @staticmethod
  def from_exception(
      exception: Exception, include_traceback: bool = True
  ) -> "StatusOr":
    """Alternative constructor that creates a StatusOr object from a Python exception.

    Args:
      exception: The Python exception.
      include_traceback: Whether to include the exception's traceback.

    Returns:
        Status: A Status object with the appropriate status code, message, and optionally traceback.
    """
    tmp_status = status.Status(
        status_code.get_status_code_for_exception(exception), str(exception)
    )
    if include_traceback:
      tmp_status.set_traceback(
          status_code.format_exception_traceback(exception)
      )
    return StatusOr(None, tmp_status)  # type: ignore

  # </editor-fold>

  # <editor-fold desc="Public methods">
  # <editor-fold desc="Getter">
  def status(self) -> "status.Status":
    """Gets the Status object.

    Returns:
      The Status object representing the operation result.
    """
    return self._status

  def val(self) -> object | None:
    """Gets the value.

    Returns:
      The value if the operation succeeded, None otherwise.
    """
    return self._val

  # </editor-fold>

  def ok(self) -> bool:
    """Checks if the StatusOr contains a valid value.

    Returns:
        True if the StatusOr contains a valid value, False if it contains an error.
    """
    return self._status.status_code() is status_code.StatusCode.OK

__init__ 

__init__(a_type: type, a_val_or_status: object | Status) -> None

Constructor.

Parameters:

  • a_type (type) –

    The expected type for the value.

  • a_val_or_status (object | Status) –

    Either a value of type a_type or a Status object. If a value is provided, it must match the specified type. If a Status object is provided, it represents an error condition.

Raises:

  • SystemExit –

    If a value is provided that doesn't match the expected type.

Source code in kern_comm_lib/base/status/status_or.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def __init__(
    self, a_type: type, a_val_or_status: object | status.Status
) -> None:
  """Constructor.

  Args:
    a_type: The expected type for the value.
    a_val_or_status: Either a value of type `a_type` or a Status object.
        If a value is provided, it must match the specified type.
        If a Status object is provided, it represents an error condition.

  Raises:
    SystemExit: If a value is provided that doesn't match the expected type.
  """
  self._type: type = a_type
  if isinstance(a_val_or_status, status.Status):
    self._val: object | None = None
    self._status: status.Status = a_val_or_status
  else:
    # Check if the val is of the correct type or None
    if a_val_or_status is not None and not isinstance(
        a_val_or_status, a_type
    ):
      print(
          f"Expected value of type {a_type.__name__}, got {type(a_val_or_status).__name__}"
      )
      sys.exit(1)  # Crashes the program if the type is incorrect!
    self._val = a_val_or_status
    self._status = status.Status()

from_exception staticmethod 

from_exception(exception: Exception, include_traceback: bool = True) -> StatusOr

Alternative constructor that creates a StatusOr object from a Python exception.

Parameters:

  • exception (Exception) –

    The Python exception.

  • include_traceback (bool, default: True ) –

    Whether to include the exception's traceback.

Returns:

  • Status ( StatusOr ) –

    A Status object with the appropriate status code, message, and optionally traceback.

Source code in kern_comm_lib/base/status/status_or.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
@staticmethod
def from_exception(
    exception: Exception, include_traceback: bool = True
) -> "StatusOr":
  """Alternative constructor that creates a StatusOr object from a Python exception.

  Args:
    exception: The Python exception.
    include_traceback: Whether to include the exception's traceback.

  Returns:
      Status: A Status object with the appropriate status code, message, and optionally traceback.
  """
  tmp_status = status.Status(
      status_code.get_status_code_for_exception(exception), str(exception)
  )
  if include_traceback:
    tmp_status.set_traceback(
        status_code.format_exception_traceback(exception)
    )
  return StatusOr(None, tmp_status)  # type: ignore

status 

status() -> status.Status

Gets the Status object.

Returns:

  • Status –

    The Status object representing the operation result.

Source code in kern_comm_lib/base/status/status_or.py 
116
117
118
119
120
121
122
def status(self) -> "status.Status":
  """Gets the Status object.

  Returns:
    The Status object representing the operation result.
  """
  return self._status

val 

val() -> object | None

Gets the value.

Returns:

  • object | None –

    The value if the operation succeeded, None otherwise.

Source code in kern_comm_lib/base/status/status_or.py 
124
125
126
127
128
129
130
def val(self) -> object | None:
  """Gets the value.

  Returns:
    The value if the operation succeeded, None otherwise.
  """
  return self._val

ok 

ok() -> bool

Checks if the StatusOr contains a valid value.

Returns:

  • bool –

    True if the StatusOr contains a valid value, False if it contains an error.

Source code in kern_comm_lib/base/status/status_or.py 
134
135
136
137
138
139
140
def ok(self) -> bool:
  """Checks if the StatusOr contains a valid value.

  Returns:
      True if the StatusOr contains a valid value, False if it contains an error.
  """
  return self._status.status_code() is status_code.StatusCode.OK