sapiopycommons 2024.3.19a157__py3-none-any.whl → 2025.1.17a402__py3-none-any.whl

sapiopycommons/general/exceptions.py

@@ -1,26 +1,88 @@
+from enum import Enum
+
+
+class MessageDisplayType(Enum):
+    """
+    An enum representing the different ways in which a message can be displayed to the user.
+    """
+    TOASTER_SUCCESS = 0
+    TOASTER_INFO = 1
+    TOASTER_WARNING = 2
+    TOASTER_ERROR = 3
+    OK_DIALOG = 4
+    DISPLAY_INFO = 5
+    DISPLAY_WARNING = 6
+    DISPLAY_ERROR = 7
+
+
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class SapioException(Exception):
     """
     A generic exception thrown by sapiopycommons methods. Typically caused by programmer error, but may also be from
     extremely edge case user errors. For expected user errors, use SapioUserErrorException.
+
+    CommonsWebhookHandler's default behavior for this and any other exception that doesn't extend SapioException is
+    to return a generic toaster message saying that an unexpected error has occurred.
+    """
+    pass
+
+
+class SapioUserCancelledException(SapioException):
+    """
+    An exception thrown when the user cancels a client callback.
+
+    CommonsWebhookHandler's default behavior is to simply end the webhook session with a true result without logging
+    the exception.
     """
     pass
 
 
-class SapioUserErrorException(SapioException):
+class SapioDialogTimeoutException(SapioException):
+    """
+    An exception thrown when the user leaves a client callback open for too long.
+
+    CommonsWebhookHandler's default behavior is to display an OK popup notifying the user that the dialog has timed out.
+    """
+    pass
+
+
+class DisplayableException(SapioException):
+    """
+    A generic exception that promises to return a user-friendly message explaining the error that should be displayed to
+    the user. Note that it is up to whichever class that catches this exception to actually display the message.
+    """
+    msg: str
+    display_type: MessageDisplayType | None
+    title: str | None
+
+    def __init__(self, msg: str, display_type: MessageDisplayType | None = None, title: str | None = None):
+        """
+        :param msg: The message that should be displayed to the user.
+        :param display_type: The manner in which the message should be displayed. If None, then the display type should
+            be controlled by the class that catches this exception.
+        :param title: If the display type is able to have a title, this is the title that will be displayed. If None,
+            then the title should be controlled by the class that catches this exception.
+        """
+        self.msg = msg
+        self.display_type = display_type
+        self.title = title
+
+
+class SapioUserErrorException(DisplayableException):
     """
     An exception caused by user error (e.g. user provided a CSV when an XLSX was expected), which promises to return a
-    user-friendly message explaining the error that should be displayed to the user. It is the responsibility of the
-    programmer to catch any such exceptions and return the value in e.args[0] as text for the user to see (such as
-    through the display text of a webhook result).
+    user-friendly message explaining the error that should be displayed to the user.
+
+    CommonsWebhookHandler's default behavior is to return the error message in a toaster popup.
     """
     pass
 
 
-class SapioCriticalErrorException(SapioException):
+class SapioCriticalErrorException(DisplayableException):
     """
     A critical exception caused by user error, which promises to return a user-friendly message explaining the error
-    that should be displayed to the user. It is the responsibility of the programmer to catch any such exceptions and
-    return the value in e.args[0] as text for the user to see (such as through a dialog form client callback request).
+    that should be displayed to the user.
+
+    CommonsWebhookHandler's default behavior is to return the error message in a display_error callback.
     """
     pass

sapiopycommons/general/popup_util.py

@@ -1,4 +1,4 @@
-from typing import Any
+import warnings
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.pojo.datatype.DataType import DataTypeDefinition
@@ -10,7 +10,7 @@ from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 from sapiopylib.rest.pojo.webhook.WebhookResult import SapioWebhookResult
 from sapiopylib.rest.utils.FormBuilder import FormBuilder
 
-from sapiopycommons.general.aliases import SapioRecord, AliasUtil
+from sapiopycommons.general.aliases import SapioRecord, AliasUtil, FieldMap
 from sapiopycommons.general.exceptions import SapioException
 
 
@@ -19,16 +19,21 @@ from sapiopycommons.general.exceptions import SapioException
 # and one FormEntryDialogRequest methods.)
 # CR-46332 - For any functions that use temporary data types, set the data type name, display name, and plural display
 # name in the form builder.
+# FR-46716 - Add comments noting that this class is deprecated in favor of CallbackUtil.
 class PopupUtil:
     """
+    DEPRECATED: Make use of CallbackUtil as of 24.5.
+
     Methods for creating boilerplate SapioWebhookResults with client callback requests to create popup dialogs.
     """
     @staticmethod
-    def form_popup(title: str, msg: str, fields: list[AbstractVeloxFieldDefinition], values: dict[str, Any] = None,
+    def form_popup(title: str, msg: str, fields: list[AbstractVeloxFieldDefinition], values: FieldMap = None,
                    column_positions: dict[str, tuple[int, int]] = None, data_type: str = "Default",
                    *, display_name: str | None = None, plural_display_name: str | None = None,
                    request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a basic form entry dialog.
 
         The calling webhook must catch the FormEntryDialogResult that the client will send back.
@@ -48,6 +53,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -74,12 +80,14 @@ class PopupUtil:
                           column_positions: dict[str, tuple[int, int]] = None, editable: bool | None = True,
                           *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a basic form dialog for a record with displayed fields from the record data type.
 
         Makes webservice calls to get the data field and type definitions of the given data type.
         The calling webhook must catch the FormEntryDialogResult that the client will send back.
 
-        :param context: The current webhook context
+        :param context: The current webhook context.
         :param title: The title of the dialog.
         :param msg: The message to display in the dialog.
         :param fields: The data field names of the fields from the record to display in the form. Fields will be
@@ -92,6 +100,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         # Get the field definitions of the data type.
         data_type: str = record.data_type_name
         type_man = DataMgmtServer.get_data_type_manager(context.user)
@@ -128,6 +137,8 @@ class PopupUtil:
                            *, display_name: str | None = None, plural_display_name: str | None = None,
                            request_context: str | None = None, **kwargs) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a form dialog with a single string field. May take additional parameters to be passed to the string field
         definition.
 
@@ -148,6 +159,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if max_length is None:
             max_length = len(default_value) if default_value else 100
         string_field = VeloxStringFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -161,6 +173,8 @@ class PopupUtil:
                             *, display_name: str | None = None, plural_display_name: str | None = None,
                             request_context: str | None = None, **kwargs) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a form dialog with a single integer field. May take additional parameters to be passed to the integer
         field definition.
 
@@ -182,6 +196,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = max(0, min_value)
         integer_field = VeloxIntegerFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -197,6 +212,8 @@ class PopupUtil:
                            plural_display_name: str | None = None, request_context: str | None = None, **kwargs) \
             -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a form dialog with a single double field. May take additional parameters to be passed to the double
         field definition.
 
@@ -218,6 +235,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = min_value
         double_field = VeloxDoubleFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -226,10 +244,12 @@ class PopupUtil:
                                     plural_display_name=plural_display_name, request_context=request_context)
 
     @staticmethod
-    def table_popup(title: str, msg: str, fields: list[AbstractVeloxFieldDefinition], values: list[dict[str, Any]],
+    def table_popup(title: str, msg: str, fields: list[AbstractVeloxFieldDefinition], values: list[FieldMap],
                     *, data_type: str = "Default", display_name: str | None = None,
                     plural_display_name: str | None = None, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a basic table entry dialog.
 
         The calling webhook must catch the TableEntryDialogResult that the client will send back.
@@ -247,6 +267,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -264,6 +285,8 @@ class PopupUtil:
                            title: str, msg: str, fields: list[str], records: list[SapioRecord],
                            editable: bool | None = True, *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a table dialog for a list of record where the columns are specific fields from the record data type.
 
         Makes webservice calls to get the data field and type definitions of the given data type.
@@ -280,12 +303,15 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
+        if not records:
+            raise SapioException("No records provided.")
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
         data_type: str = data_types.pop()
         # Get the field maps from the records.
-        field_map_list: list[dict[str, Any]] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
         # Get the field definitions of the data type.
         type_man = DataMgmtServer.get_data_type_manager(context.user)
         type_def: DataTypeDefinition = type_man.get_data_type_definition(data_type)
@@ -315,6 +341,8 @@ class PopupUtil:
                                msg: str, fields: list[str], records: list[SapioRecord], multi_select: bool = True,
                                *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a record selection dialog for a list of record where the columns are specific fields from the record data
         type.
 
@@ -330,12 +358,15 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
+        if not records:
+            raise SapioException("No records provided.")
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
         data_type: str = data_types.pop()
         # Get the field maps from the records.
-        field_map_list: list[dict[str, Any]] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
         # Get the field definitions of the data type.
         type_man = DataMgmtServer.get_data_type_manager(context.user)
         type_def: DataTypeDefinition = type_man.get_data_type_definition(data_type)
@@ -362,6 +393,8 @@ class PopupUtil:
     def list_popup(title: str, options: list[str], multi_select: bool = False,
                    *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create a list dialog with the given options for the user to choose from.
 
         The calling webhook must catch the ListDialogResult that the client will send back.
@@ -372,6 +405,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = ListDialogRequest(title, multi_select, options,
                                      callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -380,6 +414,8 @@ class PopupUtil:
     def option_popup(title: str, msg: str, options: list[str], default_option: int = 0, user_can_cancel: bool = False,
                      *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create an option dialog with the given options for the user to choose from.
 
         The calling webhook must catch the OptionDialogResult that the client will send back.
@@ -394,6 +430,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = OptionDialogRequest(title, msg, options, default_option, user_can_cancel,
                                        callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -402,6 +439,8 @@ class PopupUtil:
     def ok_popup(title: str, msg: str, user_can_cancel: bool = False, *, request_context: str | None = None) \
             -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create an option dialog where the only option is "OK".
 
         The calling webhook must catch the OptionDialogResult that the client will send back.
@@ -414,12 +453,15 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["OK"], 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
     def yes_no_popup(title: str, msg: str, default_yes: bool = True, user_can_cancel: bool = False,
                      *, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Create an option dialog where the only options are "Yes" and "No".
 
         The calling webhook must catch the OptionDialogResult that the client will send back.
@@ -433,6 +475,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["Yes", "No"], 0 if default_yes else 1, user_can_cancel,
                                       request_context=request_context)
 
@@ -441,8 +484,11 @@ class PopupUtil:
     def display_form_popup(title: str, field_name: str, msg: str, data_type: str = "Popup",
                            request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Deprecated for PopupUtil.text_field_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.string_field_popup(title, "", field_name, msg, len(msg), False, data_type,
                                             request_context=request_context, auto_size=True)
 
@@ -450,13 +496,19 @@ class PopupUtil:
     def display_option_popup(title: str, msg: str, options: list[str], user_can_cancel: bool = False,
                              request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Deprecated for PopupUtil.option_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, options, 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
     def display_ok_popup(title: str, msg: str, request_context: str | None = None) -> SapioWebhookResult:
         """
+        DEPRECATED: Make use of CallbackUtil as of 24.5.
+
         Deprecated for PopupUtil.ok_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.ok_popup(title, msg, False, request_context=request_context)

sapiopycommons/general/sapio_links.py

@@ -0,0 +1,50 @@
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import RecordIdentifier, ExperimentIdentifier, AliasUtil, DataTypeIdentifier
+from sapiopycommons.general.exceptions import SapioException
+
+
+class SapioNavigationLinker:
+    """
+    Given a URL to a system's webservice API (example: https://company.exemplareln.com/webservice/api), construct
+    URLs for navigation links to various locations in the system.
+    """
+    base_url: str
+
+    def __init__(self, url: str | SapioUser | SapioWebhookContext):
+        """
+        :param url: A user or context object that is being used to send requests to a Sapio system, or a URL to a
+            system's webservice API.
+        """
+        if isinstance(url, SapioWebhookContext):
+            url = url.user.url
+        elif isinstance(url, SapioUser):
+            url = url.url
+        self.base_url = url.rstrip("/").replace('webservice/api', 'veloxClient')
+
+    def data_record(self, record_identifier: RecordIdentifier, data_type_name: DataTypeIdentifier | None = None) -> str:
+        """
+        :param record_identifier: An object that can be used to identify a record in the system, be that a record ID,
+            a data record, or a record model.
+        :param data_type_name: If the provided record identifier is a record ID, then the data type name of the record
+            must be provided in this parameter. Otherwise, this parameter is ignored.
+        :return: A URL for navigating to the input record.
+        """
+        record_id: int = AliasUtil.to_record_id(record_identifier)
+        if data_type_name:
+            data_type_name = AliasUtil.to_data_type_name(data_type_name)
+        if not isinstance(record_identifier, int):
+            data_type_name = AliasUtil.to_data_type_name(record_identifier)
+        if not data_type_name:
+            raise SapioException("Unable to create a data record link without a data type name. "
+                                 "Only a record ID was provided.")
+        return self.base_url + f"/#dataType={data_type_name};recordId={record_id};view=dataRecord"
+
+    def experiment(self, experiment: ExperimentIdentifier) -> str:
+        """
+        :param experiment: An object that can be used to identify an experiment in the system, be that an experiment
+            object, experiment protocol, or a notebook ID.
+        :return: A URL for navigating to the input experiment.
+        """
+        return self.base_url + f"/#notebookExperimentId={AliasUtil.to_notebook_id(experiment)};view=eln"

sapiopycommons/general/storage_util.py

@@ -0,0 +1,148 @@
+class StorageUtil:
+    """
+    A collection of utilities intended for converting to and from various forms of representing positions on a storage
+    unit, such as character + integer (e.g. A1), two integers (e.g. (0, 0)), or a single integer index (e.g. 1).
+    Integers are also sometimes zero-indexed and sometimes one-indexed, so both are supported.
+    """
+    @staticmethod
+    def map_index_to_coordinate(index: int, size: int, fill_by_row: bool = True, zero_indexed_input: bool = False,
+                                zero_indexed_output: bool = False, char_row_output: bool = True) \
+            -> tuple[int | str, int]:
+        """
+        Convert an index representing a position on a plate/storage unit to a coordinate pair on that plate/storage
+        unit, able to be used in row/column storage fields on records. This will output a value for any input index;
+        it is up to the caller to determine if the output will actually fit on the plate/storage unit.
+        (The index should be within the range [1 < index < rows * columns] for one-indexed values.)
+
+        By default, expects the input to be a one-indexed integer filled row-by-row with the output being a
+        character, integer pair where the output integer is one-indexed.
+
+        :param index: The index to map to a coordinate position.
+        :param size: The number of columns or rows in the plate/storage unit, depending on whether you are filling by
+            row or by column.
+        :param fill_by_row: If true, map positions row-by-row (A1, A2, A3... B1, B2...) and use the above size as the
+            number of columns in the plate/storage unit. If false, map positions column-by-column (A1, B1, C1... A2,
+            B2...) and use the above size as the number of rows.
+        :param zero_indexed_input: If true, the input index is zero-indexed. If false, then they are one-indexed.
+            This does not influence the output, only the function's understanding of the input.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+            Has no effect on the column output if the column is set to output as a character.
+        :param char_row_output: If true, the output row value is converted to a character where 0 = A, 1 = B, 25 = Z,
+            26 = AA, 27 = AB, etc. If false, then it is returned as an integer.
+        :return: A tuple representing a coordinate pair (row value, column value). The row value may be either an
+            integer or a string, while the column value is always an integer, influenced by the input parameters.
+        """
+        # If the given index isn't zero-indexed, then make it zero-indexed by subtracting one.
+        if not zero_indexed_input:
+            index -= 1
+
+        row: int = index // size
+        col: int = index % size
+
+        # If fill by row is false, then the above calculations are flipped,
+        # meaning the row is actually the column and vice versa.
+        if not fill_by_row:
+            temp = row
+            row = col
+            col = temp
+        # The column and row are zero-indexed by default. If it should be one-indexed, add one.
+        if not zero_indexed_output:
+            col += 1
+            # Only add one to the row if it won't be converted to a character.
+            if not char_row_output:
+                row += 1
+        return StorageUtil.map_index_to_char(row, True) if char_row_output else row, col
+
+    @staticmethod
+    def map_coordinate_to_index(row: int | str, col: int | str, size: int, fill_by_row: bool = True,
+                                zero_indexed_input: bool = False, zero_indexed_output: bool = False) -> int:
+        """
+        Map row and column coordinates on a plate/storage unit to the index of that position.
+
+        By default, expects the input to be provided as a character, integer pair and outputs a single row-by-row
+        one-indexed integer.
+
+        :param row: The row coordinate of the position as a string of characters from A-Z or a zero-indexed integer.
+        :param col: The column coordinate of the position as an integer which may be zero-indexed or one-indexed.
+            (This integer may be in string form, such as is the case with column fields on storable records.)
+        :param size: The number of columns or rows in the plate/storage unit, depending on whether you are filling by
+            row or by column.
+        :param fill_by_row: If true, map positions row-by-row (A1, A2, A3... B1, B2...) and use the above size as the
+            number of columns in the plate/storage unit. If false, map positions column-by-column (A1, B1, C1... A2,
+            B2...) and use the above size as the number of rows.
+        :param zero_indexed_input: If true, the input coordinates for the row and column is zero-indexed. If false,
+            then they are one-indexed. This does not influence the output, only the function's understanding of the
+            input. This also has no effect if the input row is a string.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+        :return: The index of the storage position at the input row and column.
+        """
+        # If the column was provided as a string, cast it to an int.
+        if isinstance(col, str):
+            col: int = int(col)
+        # If the input isn't zero-indexed, then make it zero-indexed.
+        if not zero_indexed_input:
+            col -= 1
+            # Only subtract from the row if it's already in integer form.
+            # If it's a string, it'll be converted to a zero-indexed integer.
+            if isinstance(row, int):
+                row -= 1
+        # If the input row is a string, convert it to a zero-indexed integer.
+        if isinstance(row, str):
+            row: int = StorageUtil.map_char_to_index(row, True)
+
+        # Convert the row and column indices to a singular index across the entire storage unit.
+        index: int = row * size + col if fill_by_row else col * size + row
+
+        # The index is zero-indexed by default. If it should be one-indexed, add one.
+        if not zero_indexed_output:
+            index += 1
+        return index
+
+    @staticmethod
+    def map_index_to_char(index: int, zero_indexed_input: bool = False) -> str:
+        """
+        Map a given base-10 integer to a base-26 value where 0 = A, 1 = B, 25 = Z, 26 = AA, 27 = AB, etc.
+        Useful for mapping the index of a row to the character(s) representing that row in a storage unit.
+        May also be used for mapping the index to an Excel sheet's columns.
+
+        By default, expects the input as a one-indexed value.
+
+        :param index: The index to map to a character.
+        :param zero_indexed_input: If true, the input index is zero-indexed. If false, then they are one-indexed.
+            This does not influence the output, only the function's understanding of the input.
+        :return: The input integer mapped to a string representing that integer's position.
+        """
+        # If the given index isn't zero-indexed, then make it zero-indexed by subtracting one.
+        if not zero_indexed_input:
+            index -= 1
+        chars: str = ""
+        while index >= 0:
+            # Add new characters to the front of the string.
+            chars = chr(ord("A") + index % 26) + chars
+            # Reduce the index by the amount accounted for by the character that was just added.
+            index = index // 26 - 1
+        return chars
+
+    @staticmethod
+    def map_char_to_index(chars: str, zero_indexed_output: bool = False) -> int:
+        """
+        Map a given base-26 value of characters to a base-10 integer where A = 0, B = 1, Z = 25, AA = 26, AB = 27, etc.
+        Useful for mapping the character(s) representing a row in a storage unit to that row's index.
+        May also be used for mapping the index of an Excel sheet's columns.
+
+        By default, provides the output as a one-indexed value.
+
+        :param chars: A string of characters to be converted to an index. Characters are expected to be uppercase
+            characters in the range A to Z.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+        :return: The input character(s) converted to an index.
+        """
+        # Reverse iterate over the characters of the string and determine the value of each individual character.
+        # The value is multiplied by the base of the character given its digit position (26^0, 26^1, etc.)
+        value: int = 0
+        for i, c in enumerate(reversed(chars)):
+            value += (ord(c) - ord("A") + 1) * (26 ** i)
+        # The character value is one-indexed by default. If it should be zero-indexed, subtract one.
+        if zero_indexed_output:
+            value -= 1
+        return value