docs: added docstrings and return type hints

call_models/st_logs.py

@@ -22,8 +22,34 @@ log_pattern = re.compile(_log_n_re + _log_date_re + _sep + _log_mod_re + _sep +
 
 
 class StreamlitLogHandler(logging.Handler):
-    # Initializes a custom log handler with a Streamlit container for displaying logs
+    """
+    Custom Streamlit log handler to display logs in a Streamlit container
+
+    A custom logging handler for Streamlit applications that displays log
+    messages in a Streamlit container.
+
+    Attributes:
+        container (streamlit.DeltaGenerator): The Streamlit container where log messages will be displayed.
+        debug (bool): A flag to indicate whether to display debug messages.
+        ansi_escape (re.Pattern): A compiled regular expression to remove ANSI escape sequences from log messages.
+        log_area (streamlit.DeltaGenerator): An empty Streamlit container for log output.
+        buffer (collections.deque): A deque buffer to store log messages with a maximum length.
+        _n (int): A counter to keep track of the number of log messages seen.
+    Methods:
+        __init__(container, maxlen=15, debug=False):
+            Initializes the StreamlitLogHandler with a Streamlit container, buffer length, and debug flag.
+        n_elems(verb=False):
+            Returns a string with the total number of elements seen and the number of elements in the buffer.
+            If verb is True, returns a verbose string; otherwise, returns a concise string.
+        emit(record):
+            Processes a log record, formats it, appends it to the buffer, and displays it in the Streamlit container.
+            Strips ANSI escape sequences from the log message if present.
+        clear_logs():
+            Clears the log messages from the Streamlit container and the buffer.
+    """
+    # Initialize a custom log handler with a Streamlit container for displaying logs
     def __init__(self, container, maxlen:int=15, debug:bool=False):
+        #TODO: find the type for streamlit generic containers
         super().__init__()
         # Store the Streamlit container for log output
         self.container = container
@@ -34,7 +60,16 @@ class StreamlitLogHandler(logging.Handler):
         self.buffer = deque(maxlen=maxlen)
         self._n = 0
         
-    def n_elems(self, verb:bool=False):
+    def n_elems(self, verb:bool=False) -> str:
+        """
+        Return a string with the number of elements seen and the number of elements in the buffer.
+
+        Args:
+            verb (bool): If True, returns a verbose string. Defaults to False.
+
+        Returns:
+            str: A string representing the total number of elements seen and the number of elements in the buffer.
+        """
         ''' return a string with num elements seen and num elements in buffer '''
         if verb:
             return f"total: {self._n}|| in buffer:{len(self.buffer)}"
@@ -49,13 +84,28 @@ class StreamlitLogHandler(logging.Handler):
         if self.debug:
             self.log_area.markdown(clean_msg)
                 
-    def clear_logs(self):
+    def clear_logs(self) -> None:
+        """
+        Clears the log area and buffer.
+
+        This method empties the log area to remove any previous logs and clears the buffer to reset the log storage.
+        """
         self.log_area.empty()  # Clear previous logs
         self.buffer.clear()
 
 # Set up logging to capture all info level logs from the root logger
 @st.cache_resource
-def setup_logging(level: int=logging.INFO, buffer_len:int=15):
+def setup_logging(level:int=logging.INFO, buffer_len:int=15) -> StreamlitLogHandler:
+    """
+    Set up logging for the application using Streamlit's container for log display.
+
+    Args:
+        level (int): The logging level (e.g., logging.INFO, logging.DEBUG). Default is logging.INFO.
+        buffer_len (int): The maximum number of log messages to display in the Streamlit container. Default is 15.
+
+    Returns:
+        StreamlitLogHandler: The handler that has been added to the root logger.
+    """
     root_logger = logging.getLogger() # Get the root logger
     log_container = st.container() # Create a container within which we display logs
     handler = StreamlitLogHandler(log_container, maxlen=buffer_len)
@@ -70,7 +120,20 @@ def setup_logging(level: int=logging.INFO, buffer_len:int=15):
     return handler
 
 def parse_log_buffer(log_contents: deque) -> list:
-    ''' convert log buffer to a list of dictionaries '''
+    """
+    Convert log buffer to a list of dictionaries.
+    Args:
+        log_contents (deque): A deque containing log lines as strings.
+    Returns:
+        list: A list of dictionaries, each representing a parsed log entry with the following keys:
+            - 'timestamp' (datetime): The timestamp of the log entry.
+            - 'n' (str): The log entry number.
+            - 'level' (str): The log level (e.g., INFO, ERROR).
+            - 'module' (str): The name of the module.
+            - 'func' (str): The name of the function.
+            - 'message' (str): The log message.
+    """
+
     j = 0
     records = []
     for line in log_contents:
@@ -100,7 +163,7 @@ def parse_log_buffer(log_contents: deque) -> list:
                 continue
     return records
 
-def something():
+def demo_log_callback() -> None:
     '''function to demo adding log entries'''
     logger = logging.getLogger(__name__)
     logger.setLevel(logging.DEBUG)
@@ -121,7 +184,7 @@ if __name__ == "__main__":
 
     c1, c2 = st.columns([1, 3])
     with c1: 
-        button = st.button("do something", on_click=something)
+        button = st.button("do something", on_click=demo_log_callback)
     with c2:
         st.info(f"Length of records: {len(records)}")
     #tab = st.table(records)

call_models/whale_gallery.py

@@ -5,7 +5,13 @@ import whale_viewer as sw_wv
 
 def render_whale_gallery(n_cols:int = 4):
     """
-    A function to display a gallery of whale images in a grid
+    Renders a gallery of whale images + urls in a grid format using Streamlit.
+
+    Parameters:
+    n_cols (int): Number of columns in the grid. Default is 4.
+
+    The function formats whale names, creates a grid layout for images, and applies custom CSS styles
+    Each image is displayed with a caption and a link to a reference URL.
     """
     def format_whale_name(name):
         return name.replace("_", " ").capitalize()

call_models/whale_viewer.py

@@ -22,7 +22,7 @@ WHALE_CLASSES = [
         "melon_headed_whale",
         "minke_whale",
         "pantropic_spotted_dolphin",
-        "pygmy_killer_whale",
+        "pygmy_killer_whale",        
         "rough_toothed_dolphin",
         "sei_whale",
         "short_finned_pilot_whale",
@@ -102,7 +102,16 @@ df_whale_img_ref = pd.DataFrame(
     }
 ).set_index("WHALE_CLASSES")
 
-def format_whale_name(whale_class:str):
+def format_whale_name(whale_class:str) -> str:
+    """
+    Formats a whale class name by replacing underscores with spaces and capitalizing each word.
+
+    Args:
+        whale_class (str): The class name of the whale, with words separated by underscores.
+
+    Returns:
+        str: The formatted whale name with spaces instead of underscores and each word capitalized.
+    """
     whale_name = whale_class.replace("_", " ").title()
     return whale_name