doc: added docstrings to new functions

src/classifier/classifier_image.py

@@ -21,8 +21,20 @@ def add_classifier_header() -> None:
                 Once inference is complete, the top three predictions are shown.
                 You can override the prediction by selecting a species from the dropdown.*""")
 
+
 # func to just run classification, store results.
 def cetacean_just_classify(cetacean_classifier):
+    """
+    Infer cetacean species for all observations in the session state.
+    
+    - this function runs the classifier, and stores results in the session state. 
+    - the top 3 predictions are stored in the observation object, which is retained
+      in st.session_state.observations
+    - to display results use cetacean_show_results() or cetacean_show_results_and_review()
+    
+    Args:
+        cetacean_classifier ([type]):  saving-willy model from Saving Willy Hugging Face space
+    """
 
     images = st.session_state.images
     #observations = st.session_state.observations
@@ -44,7 +56,18 @@ def cetacean_just_classify(cetacean_classifier):
        
         
 # func to show results and allow review
-def cetacean_show_results_and_review():
+def cetacean_show_results_and_review() -> None:
+    """
+    Present classification results and allow user to review and override the prediction.
+    
+    - for each observation in the session state, displays the image, summarised 
+      metadata, and the top 3 predictions. 
+    - allows user to override the prediction by selecting a species from the dropdown.
+    - the selected species is stored in the observation object, which is retained in
+      st.session_state.observations
+
+    """
+
     images = st.session_state.images
     observations = st.session_state.observations
     hashes = st.session_state.image_hashes
@@ -105,6 +128,14 @@ def cetacean_show_results_and_review():
 
 # func to just present results
 def cetacean_show_results():
+    """
+    Present classification results that may be pushed to the online dataset.
+    
+    - for each observation in the session state, displays the image, summarised 
+      metadata, the top 3 predictions, and the selected species (which may have 
+      been manually selected, or the top prediction accepted). 
+
+    """
     images = st.session_state.images
     observations = st.session_state.observations
     hashes = st.session_state.image_hashes

src/input/input_validator.py

@@ -10,13 +10,24 @@ from PIL import ExifTags
 
 from streamlit.runtime.uploaded_file_manager import UploadedFile
 
-def generate_random_md5():
+def generate_random_md5(length:int=16) -> str:
+    """
+    Generate a random MD5 hash.
+
+    Args:
+        length (int): The length of the random string to generate. Default is 16.
+
+    Returns:
+        str: The MD5 hash of the generated random string.
+    """
+
     # Generate a random string
-    random_string = ''.join(random.choices(string.ascii_letters + string.digits, k=16))
+    random_string = ''.join(random.choices(string.ascii_letters + string.digits, length=16))
     # Encode the string and compute its MD5 hash
     md5_hash = hashlib.md5(random_string.encode()).hexdigest()
     return md5_hash
 
+
 def is_valid_number(number:str) -> bool:
     """
     Check if the given string is a valid number (int or float, sign ok)
@@ -30,6 +41,7 @@ def is_valid_number(number:str) -> bool:
     pattern = r'^[-+]?[0-9]*\.?[0-9]+$'
     return re.match(pattern, number) is not None
 
+
 # Function to validate email address
 def is_valid_email(email:str) -> bool:
     """
@@ -46,6 +58,7 @@ def is_valid_email(email:str) -> bool:
     pattern = r'^[a-zA-Z0-9_]+[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:UploadedFile) -> str | None: 
     """
@@ -71,6 +84,7 @@ def get_image_datetime(image_file:UploadedFile) -> str | None:
          # TODO: add to logger
     return None
 
+
 def decimal_coords(coords:tuple, ref:str) -> Fraction:
     """
     Converts coordinates from degrees, minutes, and seconds to decimal degrees.