Merging the Prototype branch into the Master branch

.gitignore

@@ -1,13 +1,13 @@
 .DS_Store
 
-## .legacy
-## *--legacy.*
+.legacy
+*--legacy.*
 
 .outputs
 .project
 
-## .prototypes
-## *--prototype.*
+.prototypes
+*--prototype.*
 
 logs/
 !logs/.gitkeep  # Keeps the logs directory in Git but ignores its content
@@ -56,9 +56,9 @@ pip-delete-this-directory.txt
 ## htmlcov/
 .tox/
 .nox/
-.coverage
 
-## .coverage.*
+# .coverage
+.coverage.*
 
 .cache
 nosetests.xml
@@ -75,7 +75,7 @@ cover/
 
 # Django stuff:
 
-## *.log
+# *.log
 
 local_settings.py
 db.sqlite3

.pydocs/pydoc.run.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
 
 # Python File: ./lib/run.py
+
+__module__ = "run"
 __version__ = "0.1.0"  # Documentation version
 
 # Module-level documentation

docs/coverage/lib/system_variables.coverage

@@ -1,5 +1,5 @@
 Name                      Stmts   Miss Branch BrPart  Cover
 -----------------------------------------------------------
-lib/system_variables.py      22     22      0      0     0%
+lib/system_variables.py      26     26      2      0     0%
 -----------------------------------------------------------
-TOTAL                        22     22      0      0     0%
+TOTAL                        26     26      2      0     0%

docs/coverage/lib/timezone_localoffset.coverage

@@ -1,5 +1,5 @@
 Name                          Stmts   Miss Branch BrPart  Cover
 ---------------------------------------------------------------
-lib/timezone_localoffset.py      42     42      4      0     0%
+lib/timezone_localoffset.py      44     44      4      0     0%
 ---------------------------------------------------------------
-TOTAL                            42     42      4      0     0%
+TOTAL                            44     44      4      0     0%

docs/coverage/packages/__init__.coverage

@@ -1,5 +1,5 @@
 Name                   Stmts   Miss Branch BrPart  Cover
 --------------------------------------------------------
-packages/__init__.py       6      6      0      0     0%
+packages/__init__.py       8      8      0      0     0%
 --------------------------------------------------------
-TOTAL                      6      6      0      0     0%
+TOTAL                      8      8      0      0     0%

docs/pydoc/lib/pkgconfig_loader.pydoc

@@ -75,6 +75,9 @@ FUNCTIONS
             - Otherwise, the logs directory from the configuration is used.
 
     main() -> None
+        Function: main() -> None
+        Description:
+            Placeholder function for module execution.
 
     package_configs(overrides: Optional[dict] = None) -> dict
         Function: package_configs(overrides: Optional[dict] = None) -> dict
@@ -162,7 +165,7 @@ DATA
     project_logs = PosixPath('<project-location>/logs...
     project_packages = PosixPath('<project-location>/...
     project_root = PosixPath('<project-location>')
-    timestamp = '20250309231457'
+    timestamp = '20250310091339'
 
 VERSION
     0.1.0

docs/pydoc/lib/system_variables.pydoc

@@ -49,6 +49,9 @@ DESCRIPTION
         - 0: Execution completed successfully.
         - 1: Error encountered during variable initialization.
 
+FUNCTIONS
+    main() -> None
+
 DATA
     category = namespace(calls=namespace(id='CALL', color='\x1b...'), rese...
     default_indent = 4

docs/pydoc/lib/timezone_localoffset.pydoc

@@ -3,12 +3,104 @@
 Help on module lib.timezone_localoffset in lib:
 
 NAME
-    lib.timezone_localoffset - # File: ./lib/timezone_localoffset.py
+    lib.timezone_localoffset - File Path: ./lib/timezone_localoffset.py
+
+DESCRIPTION
+    Description:
+        The timezone_localoffset.py module retrieves and calculates the local time zone and its offset from UTC.
+        It ensures accurate timekeeping and synchronization within the framework.
+
+    Core Features:
+        - **Time Zone Detection**: Determines the local time zone using `pytz`.
+        - **UTC Offset Calculation**: Computes the difference between local time and UTC.
+        - **Command-Line Execution**: Provides CLI debugging for time zone information.
+
+    Usage:
+        Retrieving Local Time Zone and Offset:
+            from lib.timezone_localoffset import get_local_offset
+            offset = get_local_offset(debug=True)
+
+        Running as a CLI tool:
+            ```bash
+            python timezone_localoffset.py --debug
+            ```
+
+    Dependencies:
+        - sys - Handles system error logging.
+        - pytz - Provides accurate time zone calculations.
+        - datetime - Retrieves current timestamps.
+        - argparse - Parses command-line arguments.
+
+    Global Behavior:
+        - Fetches local time zone details dynamically.
+        - Computes the UTC offset in hours.
+        - Supports CLI execution with optional debug output.
+
+    CLI Integration:
+        This module supports command-line execution to retrieve and display time zone details.
+
+    Example Execution:
+        ```bash
+        python timezone_localoffset.py --debug
+        ```
+
+    Expected Behavior:
+        - Successfully retrieves and prints the local time zone and offset.
+        - Displays additional debug information when enabled.
+        - Logs errors and exits with status `1` if time zone retrieval fails.
+
+    Exit Codes:
+        - 0: Execution completed successfully.
+        - 1: Error encountered during time zone retrieval.
 
 FUNCTIONS
     get_local_offset(debug: bool = False) -> float
+        Function: get_local_offset(debug: bool = False) -> float
+        Description:
+            Retrieves and calculates the local time zone offset from UTC.
+
+        Parameters:
+            - debug (bool, optional): Enables additional debugging output. Defaults to False.
+
+        Returns:
+            - float: The UTC offset of the local time zone in hours.
+
+        Workflow:
+            1. Detects the system's local time zone using `pytz`.
+            2. Retrieves the current local time and UTC time.
+            3. Computes the time offset in hours.
+            4. Prints formatted output for debugging if `debug` is enabled.
+
+        Notes:
+            - The default time zone is set to `"America/Creston"`, but it should be dynamically
+              determined for broader applicability.
+            - If an error occurs, it is printed to `stderr`, and the function exits with a failure code.
+
+        Error Handling:
+            - Logs errors if time zone retrieval or UTC offset calculation fails.
 
     main(debug: bool = False) -> None
+        Function: main(debug: bool = False) -> None
+        Description:
+            Main entry point for processing time zone offset calculations.
+
+        Parameters:
+            - debug (bool, optional): Enables additional debugging output. Defaults to False.
+
+        Returns:
+            - None: This function does not return a value; it handles execution flow.
+
+        Workflow:
+            1. Calls `get_local_offset()` with the `debug` flag.
+            2. Captures and logs any errors.
+            3. Exits with a non-zero status code if an error occurs.
+
+        Notes:
+            - The function can be triggered via the command-line interface (CLI).
+            - Debug mode prints additional details about the local time zone.
+
+        Error Handling:
+            - If an error occurs during time zone retrieval, the script exits with status `1`.
 
 DATA
     LocalOffset = None

docs/pydoc/run.pydoc

@@ -117,7 +117,6 @@ FUNCTIONS
 
 DATA
     LIB_DIR = PosixPath('<project-location>/lib')
-    __module_name__ = 'run'
 
 VERSION
     0.1.0

docs/pydoc/scripts/__init__.pydoc

@@ -3,7 +3,38 @@
 Help on module scripts.__init__ in scripts:
 
 NAME
-    scripts.__init__ - # File: ./scripts/__init__.py
+    scripts.__init__ - File Path: scripts/__init__.py
+
+DESCRIPTION
+    Description:
+        Scripts Package Initialization
+
+        This module ensures that the `scripts/` directory is recognized as a Python package.
+        It provides a structured framework for organizing standalone scripts while maintaining
+        explicit import control.
+
+    Core Features:
+        - **Package Initialization**: Enables `scripts/` to function as a Python package.
+        - **Modular Script Management**: Ensures standalone scripts can be structured and executed efficiently.
+        - **Explicit Import Control**: Prevents unintended execution by requiring explicit script imports.
+        - **Future Expansion**: Can be extended to initialize common utilities if needed.
+
+    Usage:
+        Scripts within `scripts/` should be explicitly imported when needed:
+            from scripts import some_script
+            some_script.execute()
+
+    Important Notes:
+        - This file **does not** automatically import submodules to prevent unnecessary execution.
+        - Individual scripts must be explicitly imported as required to maintain modularity.
+
+    Dependencies:
+        - None (This module is solely responsible for initialization)
+
+    Example:
+        To execute a standalone script within `scripts/`:
+            from scripts import example_script
+            example_script.run()
 
 VERSION
     0.1.0

docs/pydoc/scripts/testing.pydoc

@@ -3,58 +3,59 @@
 Help on module scripts.testing in scripts:
 
 NAME
-    scripts.testing - File Path: ./scripts/testing.py
+    scripts.testing - File Path: scripts/testing.py
 
 DESCRIPTION
     Description:
+        Standalone Testing Script for Framework Logging
 
-    Standalone Testing Script for Framework Logging
-
-    This script serves as a test module to verify logging and tracing capabilities.
-    It initializes structured logging via `packages.appflow_tracer.tracing`,
-    prints configuration details, and runs a simple test output.
+        This script serves as a test module to verify logging and tracing capabilities.
+        It initializes structured logging via `packages.appflow_tracer.tracing`,
+        prints configuration details, and runs a simple test output.
 
     Features:
-
-    - Configures logging using `tracing.setup_logging()`.
-    - Prints the loaded logging configuration in JSON format.
-    - Serves as a standalone script that can be run independently.
+        - Configures logging using `tracing.setup_logging()`.
+        - Prints the loaded logging configuration in JSON format.
+        - Serves as a standalone script that can be run independently.
 
     Expected Behavior:
-
-    - The script prints the structured logging configuration.
-    - Demonstrates logging setup and verification for debugging purposes.
-    - Can be used as a simple test script for logging functionality.
+        - The script prints the structured logging configuration.
+        - Demonstrates logging setup and verification for debugging purposes.
+        - Can be used as a simple test script for logging functionality.
 
     Dependencies:
-
-    - `packages.appflow_tracer.tracing` (for structured logging)
-    - `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup)
+        - `packages.appflow_tracer.tracing` (for structured logging)
+        - `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup)
 
     Usage:
+        To execute the test:
+            python scripts/testing.py
 
-    To execute the test:
-    > python scripts/testing.py
+    Exit Codes:
+        - 0: Execution completed successfully.
+        - 1: Failure due to logging setup errors or missing configurations.
 
 FUNCTIONS
     main() -> None
-        Execute a standalone test to verify the structured logging system.
+        Function: main() -> None
 
-        This function:
-        - Configures logging using `tracing.setup_logging()`.
-        - Prints the loaded logging configuration in JSON format.
-        - Displays a test output message.
+        Description:
+            Execute a standalone test to verify the structured logging system.
+
+        Parameters:
+            - None
+
+        Returns:
+            - None: Executes logging setup and test message output.
 
-        Expected Behavior:
-        - The script prints structured logging configuration details.
-        - Demonstrates the integration of logging setup in a simple, standalone script.
+        Behavior:
+            - Configures logging using `tracing.setup_logging()`.
+            - Prints the loaded logging configuration in JSON format.
+            - Displays a test output message.
 
         Raises:
             Exception: If an error occurs during logging setup.
 
-        Returns:
-            None
-
         Example:
             >>> python scripts/testing.py
             CONFIGS: {
@@ -65,6 +66,9 @@ FUNCTIONS
 DATA
     PROJECT_ROOT = PosixPath('<project-location>')
 
+VERSION
+    0.1.0
+
 FILE
     <project-location>/scripts/testing.py
 

docs/pydoc/tests/mocks/__init__.pydoc

@@ -0,0 +1,17 @@
+### Documentation for tests/mocks/__init__.py
+
+⚠️ No .pydoc file found at <project-location>/tests/mocks/.pydocs/pydoc.__init__.py.
+⚠️ No .pydoc file found at <project-location>/tests/mocks/.pydocs/pydoc.__init__.py.
+Help on module tests.mocks.__init__ in tests.mocks:
+
+NAME
+    tests.mocks.__init__ - # File: ./scripts/__init__.py
+
+VERSION
+    0.1.0
+
+FILE
+    <project-location>/tests/mocks/__init__.py
+
+
+