docs: docstrings, typehints for input_handling

call_models/input_handling.py

@@ -6,6 +6,9 @@ import hashlib
 import logging
 
 import streamlit as st
+from streamlit.runtime.uploaded_file_manager import UploadedFile # for type hinting
+from streamlit.delta_generator import DeltaGenerator
+
 import cv2
 import numpy as np
 
@@ -25,6 +28,47 @@ allowed_image_types = ['jpg', 'jpeg', 'png', 'webp']
 
 # autogenerated class to hold the input data
 class InputObservation:
+    """
+    A class to hold an input observation and associated metadata
+
+    Attributes:
+        image (Any): 
+            The image associated with the observation.
+        latitude (float): 
+            The latitude where the observation was made.
+        longitude (float): 
+            The longitude where the observation was made.
+        author_email (str): 
+            The email of the author of the observation.
+        date (str): 
+            The date when the observation was made.
+        time (str): 
+            The time when the observation was made.
+        date_option (str): 
+            Additional date option for the observation.
+        time_option (str): 
+            Additional time option for the observation.
+        uploaded_filename (Any): 
+            The uploaded filename associated with the observation.
+
+    Methods:
+        __str__():
+            Returns a string representation of the observation.
+        __repr__():
+            Returns a string representation of the observation.
+        __eq__(other):
+            Checks if two observations are equal.
+        __ne__(other):
+            Checks if two observations are not equal.
+        __hash__():
+            Returns the hash of the observation.
+        to_dict():
+            Converts the observation to a dictionary.
+        from_dict(data):
+            Creates an observation from a dictionary.
+        from_input(input):
+            Creates an observation from another input observation.
+    """
     def __init__(self, image=None, latitude=None, longitude=None, author_email=None, date=None, time=None, date_option=None, time_option=None, uploaded_filename=None):
         self.image = image
         self.latitude = latitude
@@ -84,19 +128,49 @@ class InputObservation:
     def from_dict(data):
         return InputObservation(data["image"], data["latitude"], data["longitude"], data["author_email"], data["date"], data["time"], data["date_option"], data["time_option"], data["uploaded_filename"])
 
-# define function to validate number, allowing signed float
+
 def is_valid_number(number:str) -> bool:
+    """
+    Check if the given string is a valid number (int or float, sign ok)
+
+    Args:
+        number (str): The string to be checked.
+
+    Returns:
+        bool: True if the string is a valid number, False otherwise.
+    """
     pattern = r'^[-+]?[0-9]*\.?[0-9]+$'
     return re.match(pattern, number) is not None
 
 
 # Function to validate email address
-def is_valid_email(email):
+def is_valid_email(email:str) -> bool:
+    """
+    Validates if the provided email address is in a correct format.
+
+    Args:
+        email (str): The email address to validate.
+
+    Returns:
+        bool: True if the email address is valid, False otherwise.
+    """
     pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
     return re.match(pattern, email) is not None
 
 # Function to extract date and time from image metadata
-def get_image_datetime(image_file):
+def get_image_datetime(image_file: UploadedFile) -> str | None: 
+    """
+    Extracts the original date and time from the EXIF metadata of an uploaded image file.
+
+    Args:
+        image_file (UploadedFile): The uploaded image file from which to extract the date and time.
+
+    Returns:
+        str: The original date and time as a string if available, otherwise None.
+
+    Raises:
+        Warning: If the date and time could not be extracted from the image metadata.
+    """
     try:
         image = Image.open(image_file)
         exif_data = image._getexif()
@@ -104,8 +178,9 @@ def get_image_datetime(image_file):
             for tag, value in exif_data.items():
                 if ExifTags.TAGS.get(tag) == 'DateTimeOriginal':
                     return value
-    except Exception as e:
-        st.warning("Could not extract date from image metadata.")
+    except Exception as e: # FIXME: what types of exception?
+         st.warning(f"Could not extract date from image metadata. (file: {image_file.name})")
+         # TODO: add to logger
     return None
 
 
@@ -120,7 +195,23 @@ spoof_metadata = {
 }
 
 #def display_whale(whale_classes:List[str], i:int, viewcontainer=None):
-def setup_input(viewcontainer: st.delta_generator.DeltaGenerator=None, _allowed_image_types: list=None, ):
+def setup_input(
+    viewcontainer: DeltaGenerator=None,
+    _allowed_image_types: list=None, ) -> InputObservation:
+    """
+    Sets up the input interface for uploading an image and entering metadata.
+
+    It provides input fields for an image upload, lat/lon, author email, and date-time. 
+    In the ideal case, the image metadata will be used to populate location and datetime.
+
+    Parameters:
+        viewcontainer (DeltaGenerator, optional): The Streamlit container to use for the input interface. Defaults to st.sidebar.
+        _allowed_image_types (list, optional): List of allowed image file types for upload. Defaults to allowed_image_types.
+
+    Returns:
+        InputObservation: An object containing the uploaded image and entered metadata.
+
+    """
                 
     if viewcontainer is None:
         viewcontainer = st.sidebar

docs/input_handling.md

@@ -1,2 +1,8 @@
+This module focuses on image and metadata entry:
+
+- UI elements to upload an image and populate the metadata (or edit the
+  auto-discovered metadata)
+- a container class for an observation
+
 
 ::: call_models.input_handling