From d1b06d3d44d953ea1c73baa6cfe2ab646564cfcf Mon Sep 17 00:00:00 2001
From: theonepath <ethan.sc@closedless.xyz>
Date: Tue, 3 May 2022 18:18:52 +0100
Subject: [PATCH] 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 | 42 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 5 deletions(-)

diff --git a/utils/common.py b/utils/common.py
index fe75921..b14d851 100644
--- a/utils/common.py
+++ b/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:
-    __OS: str = os.name
-    # define the path spec pattern depending on OS
-    __REGEX_PAT = re.compile(r'^(.+)[\\]([^\\]+)\\*$') \
-        if __OS == "nt" else re.compile(r'^(.+)[\/]([^\/]+)$')
+def is_path_spec(path_spec: str) -> bool:
+    """Evaluate if a given string is a valid pathspec identifier.
+    Pathspec evaluation is matched against the following regular
+    expression patterns:
+    ```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(