Update util.py functions' docstrings

sohstationviewer/controller/util.py

@@ -5,11 +5,14 @@ basic functions: format, validate, display tracking
 import os
 import re
 from datetime import datetime
+from typing import Tuple
+
+from PySide2.QtWidgets import QTextBrowser
 from obspy import UTCDateTime
 import numpy as np
 
 
-def validateFile(path2file, fileName):
+def validateFile(path2file: str, fileName: str):
     """
     Check if fileName given is a file and not info file
     :param path2file: str - absolute path to file
@@ -26,7 +29,8 @@ def validateFile(path2file, fileName):
     return True
 
 
-def displayTrackingInfo(trackingBox, text, type='info'):
+def displayTrackingInfo(trackingBox: QTextBrowser, text: str,
+                        type: str = 'info'):
     """
     Display text in the given widget with different background and text colors
     :param trackingBox: QTextBrowser - widget to display tracking info
@@ -59,7 +63,7 @@ def displayTrackingInfo(trackingBox, text, type='info'):
     trackingBox.repaint()
 
 
-def getDirSize(dir):
+def getDirSize(dir: str) -> Tuple[int, int]:
     """
     Get size of directory and size of file.
     :param dir: str - absolute path to directory
@@ -81,13 +85,15 @@ def getDirSize(dir):
     return totalSize, totalFile
 
 
-def getTime6(timeStr):
+def getTime6(timeStr: str) -> Tuple[float, int]:
     """
     Get time from 6 parts string.
     (year:day of year:hour:minute:second:millisecond)
     Ex: 01:251:09:41:35:656/ 2001:251:09:41:35:656
     in which year in the first part can be 2 digits or 6 digits
     :param timeStr: str - 6 part time string
+    :return the epoch time and the year of timeStr.
+    :rtype float, int
     """
     year = timeStr.split(':')[0]
     if len(year) == 2:
@@ -96,11 +102,13 @@ def getTime6(timeStr):
         return getTime6_4y(timeStr)
 
 
-def getTime6_2y(timeStr):
+def getTime6_2y(timeStr: str) -> Tuple[float, int]:
     """
     Get time from 6 parts string in which year has 2 digits.
     Ex: 01:251:09:41:35:656
     :param timeStr: str - 6 part time string with 2 digits for year
+    :return the epoch time and the year of timeStr.
+    :rtype float, int
     """
     # pad 0 so the last part has 6 digits to match with the format str
     timeStr = timeStr.ljust(22, "0")
@@ -109,11 +117,13 @@ def getTime6_2y(timeStr):
     return utcTime.timestamp, time.year
 
 
-def getTime6_4y(timeStr):
+def getTime6_4y(timeStr: str) -> Tuple[float, int]:
     """
     Get time from 6 parts string in which year has 4 digits.
     Ex: 2001:251:09:41:35:656
     :param timeStr: str - 6 part time string with 4 digits for year
+    :return the epoch time and the year of timeStr.
+    :rtype float, int
     """
     # pad 0 so the last part has 6 digits to match with the format str
     timeStr = timeStr.ljust(24, "0")
@@ -122,7 +132,8 @@ def getTime6_4y(timeStr):
     return utcTime.timestamp, time.year
 
 
-def getTime4(timeStr, trackingYear, yAdded):
+def getTime4(timeStr: str, trackingYear: int, yAdded: bool
+             ) -> Tuple[float, int, bool]:
     """
     Get time from 4 parts string. (day of year:hour:minute:second)
     Ex: 253:19:41:42
@@ -146,7 +157,7 @@ def getTime4(timeStr, trackingYear, yAdded):
     return utcTime.timestamp, time.year, yAdded
 
 
-def getVal(text):
+def getVal(text: str) -> float:
     """
     Get the value part of a string with non-number substring following.
     :param text: str - value string including unit
@@ -165,7 +176,7 @@ def isBinaryStr(text):
     return lambda b: bool(b.translate(None, text))
 
 
-def rtnPattern(text, upper=False):
+def rtnPattern(text: str, upper: bool = False) -> str:
     """
     This function is from logpeek's rtnPattern.
     return routine pattern of the string with:
@@ -174,6 +185,8 @@ def rtnPattern(text, upper=False):
      + A for upper case
      + remain special character
     :param text: str - text to get format
+    :param upper: bool - flag of whether to convert all alphabetic characters
+        to A
     :return rtn: str - routine pattern of the string
     """
     rtn = ""
@@ -192,7 +205,7 @@ def rtnPattern(text, upper=False):
     return rtn
 
 
-def fmti(Value):
+def fmti(Value: str) -> str:
     """
     This function is from logpeek's fmti
     Given Value will be convert to a string integer with thousand separators