Udpated utils/common.py

Added docstrings to module functions and classes, explaining purpose and
function of the function/class. Outline the parameters and return types.

`is_path_spec` renamed to use snake_case. Constants also made globally
to the module.

utils/common.py

@@ -1,18 +1,50 @@
 import os
 import re
 
+
+## get the name of the OS
+__OS: str = os.name
+# define the path spec pattern depending on OS
+__REGEX_PAT = re.compile(r'^(.+)[\\]([^\\]+)\\*$') \
+    if __OS == "nt" else re.compile(r'^(.+)[\/]([^\/]+)$')
+
+
 class LogLevel:
+    """Enumerator structure to map an integer against a log level.
+    
+    Higher `int` value means higher severity of level for logging.
+    """
     NORMAL = 0
     PASS   = 1
     DEBUG  = 2
     WARN   = 3
     ERROR  = 4
 
-def isPathspec(path_spec: str) -> bool:
+def is_path_spec(path_spec: str) -> bool:
-    __OS: str = os.name
+    """Evaluate if a given string is a valid pathspec identifier.
-    # define the path spec pattern depending on OS
+    Pathspec evaluation is matched against the following regular
-    __REGEX_PAT = re.compile(r'^(.+)[\\]([^\\]+)\\*$') \
+    expression patterns:
-        if __OS == "nt" else re.compile(r'^(.+)[\/]([^\/]+)$')
+    ```plaintext
+    OS Pathspec
+        NT:     ^(.+)[\\]([^\\]+)\\*$
+        Other:  ^(.+)[\/]([^\/]+)$
+    OR
+    Valid names of CWD subdirectories
+                ^[\w\d\-_]+$
+    ```
+    The following pathspecs are evaluated as valid pathspec identifiers
+    (OS implicitly implied):
+        - C:\\User\\user-1\\Documents\\my-project
+        - $HOME/.local/bin/my_project
+        - ".\\Python Examples\\my-project1"
+
+    The following pathspecs are evaluated as invalid pathspec identifiers
+    (OS implicitly implied)
+        - ./this,_is-a(bad)+pathspec
+
+    `@Params`: path_spec - `str`
+    `@Return`: `bool`
+    """
     ## perform a regex match to ensure that the given path is a
     ## valid pathspec for the system.
     return bool(re.match(