diff --git a/.coverage.emvaldes-imac-desktop.local.22118.XTRkvoox b/.coverage.emvaldes-imac-desktop.local.22118.XTRkvoox new file mode 100644 index 0000000..8ba002b Binary files /dev/null and b/.coverage.emvaldes-imac-desktop.local.22118.XTRkvoox differ diff --git a/docs/coverage/lib/pydoc_generator.coverage b/docs/coverage/lib/pydoc_generator.coverage index 93b5b7c..7fca6ac 100644 --- a/docs/coverage/lib/pydoc_generator.coverage +++ b/docs/coverage/lib/pydoc_generator.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ---------------------------------------------------------- -lib/pydoc_generator.py 86 60 10 3 28% +lib/pydoc_generator.py 86 45 10 1 46% ---------------------------------------------------------- -TOTAL 86 60 10 3 28% +TOTAL 86 45 10 1 46% diff --git a/docs/coverage/lib/system_variables.coverage b/docs/coverage/lib/system_variables.coverage index 2e8aeb4..df06058 100644 --- a/docs/coverage/lib/system_variables.coverage +++ b/docs/coverage/lib/system_variables.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ----------------------------------------------------------- -lib/system_variables.py 19 19 0 0 0% +lib/system_variables.py 22 22 0 0 0% ----------------------------------------------------------- -TOTAL 19 19 0 0 0% +TOTAL 22 22 0 0 0% diff --git a/docs/coverage/lib/timezone_localoffset.coverage b/docs/coverage/lib/timezone_localoffset.coverage index b58746d..968aaef 100644 --- a/docs/coverage/lib/timezone_localoffset.coverage +++ b/docs/coverage/lib/timezone_localoffset.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------- -lib/timezone_localoffset.py 43 43 4 0 0% +lib/timezone_localoffset.py 42 42 4 0 0% --------------------------------------------------------------- -TOTAL 43 43 4 0 0% +TOTAL 42 42 4 0 0% diff --git a/docs/coverage/packages/__init__.coverage b/docs/coverage/packages/__init__.coverage index 477b111..e3905dc 100644 --- a/docs/coverage/packages/__init__.coverage +++ b/docs/coverage/packages/__init__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover -------------------------------------------------------- -packages/__init__.py 2 2 0 0 0% +packages/__init__.py 6 6 0 0 0% -------------------------------------------------------- -TOTAL 2 2 0 0 0% +TOTAL 6 6 0 0 0% diff --git a/docs/coverage/packages/appflow_tracer/__init__.coverage b/docs/coverage/packages/appflow_tracer/__init__.coverage index f5d05ea..15edaf8 100644 --- a/docs/coverage/packages/appflow_tracer/__init__.coverage +++ b/docs/coverage/packages/appflow_tracer/__init__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ----------------------------------------------------------------------- -packages/appflow_tracer/__init__.py 5 5 0 0 0% +packages/appflow_tracer/__init__.py 9 9 0 0 0% ----------------------------------------------------------------------- -TOTAL 5 5 0 0 0% +TOTAL 9 9 0 0 0% diff --git a/docs/coverage/packages/appflow_tracer/__main__.coverage b/docs/coverage/packages/appflow_tracer/__main__.coverage index 4f89e46..44f004d 100644 --- a/docs/coverage/packages/appflow_tracer/__main__.coverage +++ b/docs/coverage/packages/appflow_tracer/__main__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ----------------------------------------------------------------------- -packages/appflow_tracer/__main__.py 5 5 2 0 0% +packages/appflow_tracer/__main__.py 9 9 2 0 0% ----------------------------------------------------------------------- -TOTAL 5 5 2 0 0% +TOTAL 9 9 2 0 0% diff --git a/docs/coverage/packages/appflow_tracer/lib/__init__.coverage b/docs/coverage/packages/appflow_tracer/lib/__init__.coverage index d9e8af2..1e17856 100644 --- a/docs/coverage/packages/appflow_tracer/lib/__init__.coverage +++ b/docs/coverage/packages/appflow_tracer/lib/__init__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------------------- -packages/appflow_tracer/lib/__init__.py 4 4 0 0 0% +packages/appflow_tracer/lib/__init__.py 8 8 0 0 0% --------------------------------------------------------------------------- -TOTAL 4 4 0 0 0% +TOTAL 8 8 0 0 0% diff --git a/docs/coverage/packages/appflow_tracer/lib/file_utils.coverage b/docs/coverage/packages/appflow_tracer/lib/file_utils.coverage index e95f9a7..ed19fdc 100644 --- a/docs/coverage/packages/appflow_tracer/lib/file_utils.coverage +++ b/docs/coverage/packages/appflow_tracer/lib/file_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ----------------------------------------------------------------------------- -packages/appflow_tracer/lib/file_utils.py 42 42 12 0 0% +packages/appflow_tracer/lib/file_utils.py 48 48 14 0 0% ----------------------------------------------------------------------------- -TOTAL 42 42 12 0 0% +TOTAL 48 48 14 0 0% diff --git a/docs/coverage/packages/appflow_tracer/lib/log_utils.coverage b/docs/coverage/packages/appflow_tracer/lib/log_utils.coverage index 0b3c5a1..f39393e 100644 --- a/docs/coverage/packages/appflow_tracer/lib/log_utils.coverage +++ b/docs/coverage/packages/appflow_tracer/lib/log_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ---------------------------------------------------------------------------- -packages/appflow_tracer/lib/log_utils.py 39 27 24 6 29% +packages/appflow_tracer/lib/log_utils.py 46 34 26 6 25% ---------------------------------------------------------------------------- -TOTAL 39 27 24 6 29% +TOTAL 46 34 26 6 25% diff --git a/docs/coverage/packages/appflow_tracer/lib/serialize_utils.coverage b/docs/coverage/packages/appflow_tracer/lib/serialize_utils.coverage index cd37c6c..67d87a7 100644 --- a/docs/coverage/packages/appflow_tracer/lib/serialize_utils.coverage +++ b/docs/coverage/packages/appflow_tracer/lib/serialize_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ---------------------------------------------------------------------------------- -packages/appflow_tracer/lib/serialize_utils.py 41 41 12 0 0% +packages/appflow_tracer/lib/serialize_utils.py 48 48 14 0 0% ---------------------------------------------------------------------------------- -TOTAL 41 41 12 0 0% +TOTAL 48 48 14 0 0% diff --git a/docs/coverage/packages/appflow_tracer/lib/trace_utils.coverage b/docs/coverage/packages/appflow_tracer/lib/trace_utils.coverage index 6eb1212..93a5465 100644 --- a/docs/coverage/packages/appflow_tracer/lib/trace_utils.coverage +++ b/docs/coverage/packages/appflow_tracer/lib/trace_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ------------------------------------------------------------------------------ -packages/appflow_tracer/lib/trace_utils.py 116 116 44 0 0% +packages/appflow_tracer/lib/trace_utils.py 123 123 46 0 0% ------------------------------------------------------------------------------ -TOTAL 116 116 44 0 0% +TOTAL 123 123 46 0 0% diff --git a/docs/coverage/packages/appflow_tracer/tracing.coverage b/docs/coverage/packages/appflow_tracer/tracing.coverage index f9dd973..3805732 100644 --- a/docs/coverage/packages/appflow_tracer/tracing.coverage +++ b/docs/coverage/packages/appflow_tracer/tracing.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ---------------------------------------------------------------------- -packages/appflow_tracer/tracing.py 86 80 28 1 6% +packages/appflow_tracer/tracing.py 88 82 28 1 6% ---------------------------------------------------------------------- -TOTAL 86 80 28 1 6% +TOTAL 88 82 28 1 6% diff --git a/docs/coverage/packages/requirements/__init__.coverage b/docs/coverage/packages/requirements/__init__.coverage index edb7cf8..e4b66eb 100644 --- a/docs/coverage/packages/requirements/__init__.coverage +++ b/docs/coverage/packages/requirements/__init__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------------- -packages/requirements/__init__.py 4 4 0 0 0% +packages/requirements/__init__.py 8 8 0 0 0% --------------------------------------------------------------------- -TOTAL 4 4 0 0 0% +TOTAL 8 8 0 0 0% diff --git a/docs/coverage/packages/requirements/__main__.coverage b/docs/coverage/packages/requirements/__main__.coverage index 43b3727..ae70bb6 100644 --- a/docs/coverage/packages/requirements/__main__.coverage +++ b/docs/coverage/packages/requirements/__main__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------------- -packages/requirements/__main__.py 5 5 2 0 0% +packages/requirements/__main__.py 9 9 2 0 0% --------------------------------------------------------------------- -TOTAL 5 5 2 0 0% +TOTAL 9 9 2 0 0% diff --git a/docs/coverage/packages/requirements/dependencies.coverage b/docs/coverage/packages/requirements/dependencies.coverage index 0605f09..896f7b0 100644 --- a/docs/coverage/packages/requirements/dependencies.coverage +++ b/docs/coverage/packages/requirements/dependencies.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ------------------------------------------------------------------------- -packages/requirements/dependencies.py 69 69 18 0 0% +packages/requirements/dependencies.py 71 71 18 0 0% ------------------------------------------------------------------------- -TOTAL 69 69 18 0 0% +TOTAL 71 71 18 0 0% diff --git a/docs/coverage/packages/requirements/lib/__init__.coverage b/docs/coverage/packages/requirements/lib/__init__.coverage index e7fc86b..6e6d7ed 100644 --- a/docs/coverage/packages/requirements/lib/__init__.coverage +++ b/docs/coverage/packages/requirements/lib/__init__.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ------------------------------------------------------------------------- -packages/requirements/lib/__init__.py 3 3 0 0 0% +packages/requirements/lib/__init__.py 8 8 0 0 0% ------------------------------------------------------------------------- -TOTAL 3 3 0 0 0% +TOTAL 8 8 0 0 0% diff --git a/docs/coverage/packages/requirements/lib/brew_utils.coverage b/docs/coverage/packages/requirements/lib/brew_utils.coverage index e2e89aa..91d6c00 100644 --- a/docs/coverage/packages/requirements/lib/brew_utils.coverage +++ b/docs/coverage/packages/requirements/lib/brew_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------------------- -packages/requirements/lib/brew_utils.py 90 90 30 0 0% +packages/requirements/lib/brew_utils.py 97 97 32 0 0% --------------------------------------------------------------------------- -TOTAL 90 90 30 0 0% +TOTAL 97 97 32 0 0% diff --git a/docs/coverage/packages/requirements/lib/package_utils.coverage b/docs/coverage/packages/requirements/lib/package_utils.coverage index 74238be..b31c53b 100644 --- a/docs/coverage/packages/requirements/lib/package_utils.coverage +++ b/docs/coverage/packages/requirements/lib/package_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ------------------------------------------------------------------------------ -packages/requirements/lib/package_utils.py 181 181 54 0 0% +packages/requirements/lib/package_utils.py 187 187 56 0 0% ------------------------------------------------------------------------------ -TOTAL 181 181 54 0 0% +TOTAL 187 187 56 0 0% diff --git a/docs/coverage/packages/requirements/lib/policy_utils.coverage b/docs/coverage/packages/requirements/lib/policy_utils.coverage index 1d221b2..8d8685d 100644 --- a/docs/coverage/packages/requirements/lib/policy_utils.coverage +++ b/docs/coverage/packages/requirements/lib/policy_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ----------------------------------------------------------------------------- -packages/requirements/lib/policy_utils.py 65 65 18 0 0% +packages/requirements/lib/policy_utils.py 72 72 20 0 0% ----------------------------------------------------------------------------- -TOTAL 65 65 18 0 0% +TOTAL 72 72 20 0 0% diff --git a/docs/coverage/packages/requirements/lib/version_utils.coverage b/docs/coverage/packages/requirements/lib/version_utils.coverage index a819651..d23caf2 100644 --- a/docs/coverage/packages/requirements/lib/version_utils.coverage +++ b/docs/coverage/packages/requirements/lib/version_utils.coverage @@ -1,5 +1,5 @@ Name Stmts Miss Branch BrPart Cover ------------------------------------------------------------------------------ -packages/requirements/lib/version_utils.py 119 119 32 0 0% +packages/requirements/lib/version_utils.py 126 126 34 0 0% ------------------------------------------------------------------------------ -TOTAL 119 119 32 0 0% +TOTAL 126 126 34 0 0% diff --git a/docs/pydoc/lib/__init__.pydoc b/docs/pydoc/lib/__init__.pydoc index a116402..c1138fa 100644 --- a/docs/pydoc/lib/__init__.pydoc +++ b/docs/pydoc/lib/__init__.pydoc @@ -3,32 +3,41 @@ Help on module lib.__init__ in lib: NAME - lib.__init__ + lib.__init__ - File Path: ./lib/__init__.py DESCRIPTION Overview: - The __init__.py file is responsible for marking the 'lib' directory as a Python package, - allowing its modules to be imported properly within the project. + The __init__.py file initializes the 'lib' directory as a Python package, + enabling structured imports for internal modules. - This file serves as the entry point for the 'lib' package and may include shared imports, - initialization logic, or package-wide configuration settings. + Purpose: + - Ensures the directory is recognized as a Python package. + - Provides a centralized location for shared configurations or imports. + - Dynamically loads external documentation to maintain code clarity. Core Features: - - Package Initialization: Ensures 'lib' is recognized as a Python package. - - Shared Module Accessibility: Provides a central location for utility imports. - - Extensibility: Can be modified to include package-wide configurations if necessary. + - **Package Initialization**: Marks 'lib' as an importable package. + - **Dynamic Documentation Loading**: Uses 'pydoc_loader' to apply docstrings at runtime. + - **Shared Path Handling**: Adds the package directory to `sys.path` for accessibility. + - **Minimal Overhead**: Avoids automatic imports of all submodules unless explicitly required. Expected Behavior & Usage: Importing Modules from 'lib': from lib import system_variables, file_utils - Example Integration: - from lib import log_utils - log_utils.log_message("Initialization successful.") + Using a Specific Submodule: + from lib.log_utils import log_message + log_message("Initialization successful.") + + Dynamically Applying Documentation: + from lib.pydoc_loader import load_pydocs + load_pydocs(__file__, sys.modules[__name__]) Important Notes: - - This file does not automatically import all submodules to prevent unnecessary overhead. + - This file **does not** automatically import all submodules to prevent unnecessary overhead. - Individual submodules must be explicitly imported when required. + - The `sys.path.insert()` modification ensures package accessibility but should not be removed unless explicitly handled elsewhere. + - Future extensions may include package-wide constants, configurations, or logging initialization. VERSION 0.1.0 diff --git a/docs/pydoc/lib/accesstoken_expiration.pydoc b/docs/pydoc/lib/accesstoken_expiration.pydoc index 617c2af..96f499e 100644 --- a/docs/pydoc/lib/accesstoken_expiration.pydoc +++ b/docs/pydoc/lib/accesstoken_expiration.pydoc @@ -3,55 +3,247 @@ Help on module lib.accesstoken_expiration in lib: NAME - lib.accesstoken_expiration + lib.accesstoken_expiration - File Path: ./lib/accesstoken_expiration.py DESCRIPTION - Overview - The `accesstoken_expiration.py` module manages Azure access tokens, retrieving expiration times and displaying the remaining validity duration. + Description: + The accesstoken_expiration.py module provides functionality to retrieve, manage, and monitor Azure access tokens using the azure-identity SDK. It ensures proper handling of access token expiration, facilitating secure interactions with Azure services. Core Features: - - Fetches an Azure access token using `InteractiveBrowserCredential`. - - Extracts and displays token expiration information. - - Provides a function to check the remaining time before expiration. - - Handles Azure authentication errors gracefully. + - Access Token Retrieval: Uses InteractiveBrowserCredential to authenticate and retrieve an access token. + - Token Expiration Handling: Extracts and displays expiration details of the access token. + - Remaining Time Calculation: Computes and prints the duration until token expiration. + - Error Handling & Debugging: Catches Azure authentication errors and provides debugging output if enabled. + - CLI Integration: Supports command-line execution with debug options. - Expected Behavior & Usage: + Usage: Retrieving Token Expiration: from lib.accesstoken_expiration import print_token_expiration expiration = print_token_expiration(debug=True) - Checking Remaining Validity: - from lib.accesstoken_expiration import print_remaining_time - print_remaining_time() + Checking Remaining Validity: + from lib.accesstoken_expiration import print_remaining_time + print_remaining_time() + + Dependencies: + - sys - Used for error output and process control. + - datetime - Handles timestamp conversions and expiration calculations. + - pathlib - Resolves file paths dynamically. + - azure.identity - Provides Azure authentication via InteractiveBrowserCredential. + - azure.core.exceptions - Captures Azure-related authentication exceptions. + + Global Variables: + - TokenScope: The authentication scope used for obtaining Azure access tokens. + - AccessToken: Stores the retrieved Azure access token. Defaults to None until set. + - TokenExpiration: Holds the expiration timestamp of the current access token. + + Primary Functions: + + get_access_token() -> Optional[datetime] + Retrieves an Azure access token using InteractiveBrowserCredential and extracts its expiration timestamp. + + Returns: + - datetime: Expiration timestamp of the token if successful. + - None: If token retrieval fails due to an authentication error. + + Error Handling: + - Captures and prints authentication errors if Azure SDK fails. + + print_token_expiration(debug: bool = False) -> Optional[datetime] + Fetches and prints the expiration timestamp of the access token. + + Parameters: + - debug (bool, optional): Enables debugging mode to print additional token details. Defaults to False. + + Returns: + - datetime: Token expiration timestamp if retrieval succeeds. + - None: If token fetching fails or is unavailable. + + Behavior: + - If debug=True, prints the token details as a JSON structure. + - If expiration details are missing, outputs an error message. + + print_remaining_time() -> None + Calculates and prints the remaining duration before the access token expires. + + Displays: + - Hours, minutes, and seconds left before token expiration. + - Error message if expiration details are not available. + + Behavior: + - If TokenExpiration is set, computes and prints remaining validity. + - If TokenExpiration is None, alerts the user. + + main(debug: bool = False) -> None + Entry point function that coordinates token retrieval, expiration handling, and remaining time computation. + + Parameters: + - debug (bool, optional): Enables debug output. Defaults to False. + + Behavior: + - Calls print_token_expiration(debug) to retrieve and print expiration details. + - Calls print_remaining_time() to compute remaining validity duration. + - Captures critical failures and exits with an error code if necessary. + + CLI Integration: + This script can be executed via CLI using the argument_parser module. + + Example Execution: + python accesstoken_expiration.py --debug + + Supported CLI Arguments: + - --debug: Enables verbose logging and prints token details in JSON format. + + Expected Behavior: + - Successfully retrieves and prints the expiration timestamp of an Azure access token. + - Computes and displays the remaining time before expiration. + - Handles authentication failures gracefully and prints error messages. + - Provides an interactive experience when executed via CLI, allowing Azure authentication through a browser prompt. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Critical error encountered, script execution halted. + + Example Usage: + Fetch and Print Token Expiration: + from lib.accesstoken_expiration import print_token_expiration + print_token_expiration(debug=True) + + Compute and Print Remaining Time: + from lib.accesstoken_expiration import print_remaining_time + print_remaining_time() + + This documentation provides a structured reference for developers and administrators integrating Azure authentication within their Python applications. + + Objects & External Dependencies: + InteractiveBrowserCredential (from azure.identity): + - Description: Handles authentication by launching an interactive browser window. + - Behavior: + - Uses the default browser to prompt the user for authentication. + - Retrieves an authentication token with the provided scope. + - Used In: get_access_token() + + datetime (from datetime module): + - Description: Provides timestamp operations for token expiration calculations. + - Usage: + - Converts Unix timestamp from the Azure SDK response to a datetime object. + - Computes time differences to determine token validity duration. + - Used In: get_access_token(), print_remaining_time() + + Path (from pathlib module): + - Description: Resolves the file path of the current script. + - Behavior: + - Ensures that the current directory is added to sys.path. + - Used In: sys.path.insert(0, str(Path(__file__).resolve().parent)) + + sys: + - Description: Provides access to system-related functions such as stderr and process exit. + - Usage: + - Prints error messages to stderr. + - Exits the script with a non-zero exit code on failure. + - Used In: get_access_token(), print_token_expiration(), print_remaining_time(), main() + + Global Behavior: + - The script maintains AccessToken and TokenExpiration as global variables to avoid redundant authentication requests. + - The first execution of get_access_token() updates both AccessToken and TokenExpiration. + - print_token_expiration() and print_remaining_time() depend on TokenExpiration being set to function correctly. + - If TokenExpiration is missing, print_remaining_time() will log an error and exit. + + File Structure & Loading: + sys.path.insert(0, str(Path(__file__).resolve().parent)): + - Ensures the script can reference modules in the same directory. + - Resolves the absolute path of the script’s directory dynamically. + + from lib.pydoc_loader import load_pydocs: + - Dynamically loads documentation from external .pydoc files if available. + - Ensures that documentation is available at runtime. + + from argument_parser import parse_arguments: + - Parses command-line arguments passed during execution. + - Supports flags such as --debug to enable verbose logging. FUNCTIONS get_access_token() -> Optional[datetime.datetime] - Retrieves an Azure access token and determines its expiration time. + Function: get_access_token() -> Optional[datetime] + Description: + Retrieves an Azure access token using InteractiveBrowserCredential and extracts its expiration timestamp. + This function utilizes an interactive authentication flow, prompting the user to log in via a browser. Returns: - Optional[datetime]: The expiration time of the access token, or None if retrieval fails. + - datetime: Expiration timestamp of the token if retrieval is successful. + - None: If authentication fails or the token cannot be retrieved. + + Behavior: + - Instantiates an InteractiveBrowserCredential object for user authentication. + - Requests an access token from Azure with the specified scope: "https://management.azure.com/.default". + - Extracts the expiration timestamp from the token response. + - Stores the access token in the global AccessToken variable for subsequent use. + + Error Handling: + - Captures Azure SDK errors and prints a descriptive error message to stderr. + - Catches general exceptions and logs an error message if token retrieval fails. main(debug: bool = False) -> None - Entry point function that executes the token retrieval and expiration checks. + Function: main(debug: bool = False) -> None + Description: + Entry point function that executes the access token retrieval and expiration checks. + This function orchestrates the workflow by calling print_token_expiration() and print_remaining_time(). Parameters: - debug (bool, optional): Enables debugging mode. Defaults to False. + - debug (bool, optional): Enables debug mode to print detailed token information. Defaults to False. + + Behavior: + - Calls print_token_expiration(debug) to fetch and display the token expiration time. + - Calls print_remaining_time() to compute and print the remaining time before expiration. + - If any unexpected error occurs, logs a critical error message and exits with a non-zero status code. + + Error Handling: + - Captures critical exceptions and logs an error message. + - If an unrecoverable error occurs, the script exits with an error code (1). print_remaining_time() -> None - Computes and prints the remaining validity duration of the access token. + Function: print_remaining_time() -> None + Description: + Computes and prints the remaining time before the access token expires. + If the token expiration is not set, it prints an error message. Displays: - - Hours, minutes, and seconds left before expiration. - - An error message if expiration is not available. + - Remaining validity of the access token in hours, minutes, and seconds. + - Error message if the expiration timestamp is not available. + + Behavior: + - Retrieves the current system time. + - Computes the difference between the token expiration time and the current time. + - Extracts hours, minutes, and seconds from the computed time difference. + - Prints the remaining time in a formatted string. + + Error Handling: + - If TokenExpiration is not set, prints an error message and exits. + - Catches unexpected exceptions and logs an error message. print_token_expiration(debug: bool = False) -> Optional[datetime.datetime] - Fetches and prints the access token expiration time. + Function: print_token_expiration(debug: bool = False) -> Optional[datetime] + Description: + Fetches the access token and prints its expiration timestamp in a readable format. + If debugging is enabled, it also prints the full token details in JSON format. Parameters: - debug (bool, optional): Enables debug logging of token details. Defaults to False. + - debug (bool, optional): Enables debugging mode to print token details. Defaults to False. Returns: - Optional[datetime]: The token expiration timestamp or None if unavailable. + - datetime: Expiration timestamp of the token if retrieval succeeds. + - None: If the token is not available or cannot be retrieved. + + Behavior: + - Calls get_access_token() to fetch an access token and its expiration. + - Stores the expiration timestamp in the global TokenExpiration variable. + - If debug=True, prints the full token details in JSON format. + - Converts the expiration timestamp into a human-readable string and prints it. + - If the expiration timestamp is missing or empty, logs an error. + + Error Handling: + - Captures errors related to token retrieval and prints an appropriate error message. + - Handles exceptions during string conversion and prints debugging information. DATA AccessToken = None diff --git a/docs/pydoc/lib/argument_parser.pydoc b/docs/pydoc/lib/argument_parser.pydoc index a8ce001..329d19d 100644 --- a/docs/pydoc/lib/argument_parser.pydoc +++ b/docs/pydoc/lib/argument_parser.pydoc @@ -3,65 +3,145 @@ Help on module lib.argument_parser in lib: NAME - lib.argument_parser + lib.argument_parser - File Path: ./lib/argument_parser.py DESCRIPTION - Overview - The `argument_parser.py` module provides command-line argument parsing for system configurations. - It supports structured argument definitions from JSON configuration files. + Description: + The argument_parser.py module provides structured argument parsing capabilities for CLI-based Python applications. + It dynamically loads argument configurations from a system-defined JSON file and ensures type conversions, validation, and error handling. + This module simplifies command-line argument management while maintaining flexibility for different contexts. Core Features: - - Loads argument configurations from system parameter files. - - Parses command-line arguments based on predefined options. - - Supports type conversion and validation for arguments. - - Enables debug mode for detailed argument inspection. - - Expected Behavior & Usage: - Parsing CLI Arguments: + - Argument Configuration Loading: Reads argument structures from an external JSON configuration file. + - Dynamic Argument Parsing: Uses argparse to define CLI arguments dynamically based on pre-configured rules. + - Type Conversion: Automatically converts CLI arguments to expected data types. + - Debugging & Validation: Provides debugging output for parsed arguments and handles incorrect JSON structures gracefully. + - CLI Integration: Supports manual and pre-configured argument handling. + + Usage: + Basic Argument Parsing: from lib.argument_parser import parse_arguments - args = parse_arguments(context=["debug", "verbose"], description="Azure CLI utility") - print(args.debug, args.verbose) + args = parse_arguments(context={"debug", "verbose"}) + + Loading External Configurations: + from lib.argument_parser import load_argument_config + config = load_argument_config() + + Dependencies: + - sys - Used for argument handling and error output. + - os - Provides system-related utilities. + - json - Parses JSON-based argument configuration. + - logging - Logs debugging information and errors. + - argparse - Handles CLI argument parsing. + - pathlib - Resolves system file paths dynamically. + - typing (Dict, Any) - Defines type hints for functions. + + Global Variables: + - system_params_filepath: The file path for the system-defined argument configuration file. + + CLI Integration: + This script can be executed via CLI to test argument parsing. + + Example Execution: + python argument_parser.py --debug + + Expected Behavior: + - Successfully loads and parses CLI arguments. + - Converts arguments to expected types. + - Handles missing or invalid arguments gracefully. + - Provides debugging output when enabled. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during argument parsing. FUNCTIONS convert_types(kwargs: Dict[str, Any]) -> Dict[str, Any] - Converts type annotations in argument definitions from string format to Python types. + Function: convert_types(kwargs: Dict[str, Any]) -> Dict[str, Any] + Description: + Converts string-based type definitions into callable Python types. Parameters: - kwargs (Dict[str, Any]): Argument definition containing type annotations. + - kwargs (Dict[str, Any]): Dictionary containing argument properties. Returns: - Dict[str, Any]: The argument definition with correct type mappings. + - Dict[str, Any]: Updated dictionary with correct type mappings. + + Behavior: + - If 'store_true' is used as an action, removes the 'type' property to prevent conflicts. + - Converts 'type' values from string format (e.g., 'str', 'int', 'bool') to actual Python types. load_argument_config() -> Dict[str, Any] - Loads argument definitions from a predefined JSON configuration file. + Function: load_argument_config() -> Dict[str, Any] + Description: + Loads CLI argument configurations from a JSON file. Ensures the file exists and contains a valid JSON structure. Returns: - Dict[str, Any]: Parsed argument definitions categorized by section. + - Dict[str, Any]: Parsed JSON dictionary containing argument configurations. + + Behavior: + - Checks if the argument configuration file exists. + - Reads the file contents and attempts to parse JSON data. + - Ensures the file is not empty and contains a valid JSON structure. + + Error Handling: + - Raises FileNotFoundError if the configuration file is missing. + - Raises ValueError if the JSON structure is invalid or empty. + - Raises RuntimeError if any other error occurs while reading the file. main() -> None - Main function to execute argument parsing and display parsed results. + Function: main() -> None + Description: + Main execution function that initializes argument parsing. + + Behavior: + - Calls parse_arguments() to retrieve argument values. + - Prints parsed argument values for debugging. parse_arguments(args: Dict[str, Any]) -> argparse.Namespace - Parses command-line arguments using a structured parameter definition. + Function: parse_arguments(args: Dict[str, Any]) -> argparse.Namespace + Description: + Parses command-line arguments from a structured dictionary format. Parameters: - args (Dict[str, Any]): System parameter configurations defining available arguments. + - args (Dict[str, Any]): Dictionary containing argument structures, including options and flags. Returns: - argparse.Namespace: The parsed arguments as an object. + - argparse.Namespace: Parsed CLI arguments stored in a namespace. + + Behavior: + - Iterates through argument sections and processes options dynamically. + - Ensures type conversion for numerical and boolean values. + - Logs and reports unknown or missing argument definitions. + - Uses argparse to add dynamically defined arguments. + + Error Handling: + - Captures missing 'flags' definitions and logs an error. + - Catches failures in argument parsing and logs a critical error. parse_arguments__prototype( context: Dict[str, Any] = None, description: str = 'Azure CLI utility' ) -> argparse.Namespace - Parses command-line arguments based on predefined configurations. + Function: parse_arguments__prototype(context: Dict[str, Any] = None, description: str = "Azure CLI utility") -> argparse.Namespace + Description: + Parses command-line arguments using pre-configured settings, allowing context-based filtering. Parameters: - context (Dict[str, Any], optional): Limits parsed arguments to the specified context. Defaults to None. - description (str, optional): Custom description for the argument parser. Defaults to "Azure CLI utility". + - context (Dict[str, Any], optional): Defines which arguments should be considered. Defaults to None. + - description (str, optional): Description displayed in the CLI help text. Defaults to "Azure CLI utility". Returns: - argparse.Namespace: Parsed command-line arguments. + - argparse.Namespace: Parsed CLI arguments stored in a namespace. + + Behavior: + - Loads argument configurations from load_argument_config(). + - Iterates through sections and parameters, dynamically adding them to the argparse parser. + - Uses convert_types() to ensure argument types are properly handled. + - If debugging is enabled, prints parsed arguments in JSON format. + + Error Handling: + - Captures and reports errors related to missing or malformed argument configurations. DATA Dict = typing.Dict diff --git a/docs/pydoc/lib/configure_params.pydoc b/docs/pydoc/lib/configure_params.pydoc index dc43f9a..2c3be08 100644 --- a/docs/pydoc/lib/configure_params.pydoc +++ b/docs/pydoc/lib/configure_params.pydoc @@ -3,76 +3,201 @@ Help on module lib.configure_params in lib: NAME - lib.configure_params + lib.configure_params - File Path: ./lib/configure_params.py DESCRIPTION - Overview - The `configure_params.py` module manages system configuration by loading environment variables - and runtime parameters from structured JSON configuration files. + Description: + The configure_params.py module handles the initialization, validation, and loading of environment + variables and runtime configuration files. It is responsible for managing JSON-based system parameters, + merging multiple configuration sources, and ensuring environment consistency. Core Features: - - Loads system parameters from predefined JSON sources. - - Initializes and validates environment variables in `.env`. - - Generates and maintains a runtime configuration file. - - Dynamically updates values based on system settings. - - Expected Behavior & Usage: - Initializing Configuration: - from lib.configure_params import main - system_params, runtime_params = main() + - JSON Configuration Loading: Reads and merges JSON system parameter files. + - Environment Variable Management: Loads, validates, and updates `.env` files dynamically. + - Runtime Parameter Initialization: Ensures runtime parameters are stored and accessible. + - Type-Safe Data Retrieval: Extracts and processes system parameters with error handling. + - Logging and Debugging: Provides structured logs for validation and processing errors. + + Usage: + Loading System Parameters: + from lib.configure_params import load_json_sources + config = load_json_sources(["config1.json", "config2.json"], mode="merge") + + Fetching Runtime Variables: + from lib.configure_params import fetching_runtime_variables + runtime_vars = fetching_runtime_variables() + + Environment File Initialization: + from lib.configure_params import initialize_env_file + initialize_env_file() + + Dependencies: + - sys - System-level functions such as error handling and process termination. + - os - Provides access to file system operations. + - json - Loads, parses, and merges JSON configuration files. + - logging - Handles structured logs and debugging. + - dotenv (load_dotenv, dotenv_values) - Manages environment variables in `.env` files. + - typing (List, Dict, Tuple, Union) - Provides type hints for structured data. + - pathlib - Ensures safe file path resolution. + + Global Variables: + - env_file_header: Defines the header content for the auto-generated .env file. + + CLI Integration: + This module is executed automatically when run as a standalone script. + + Example Execution: + python configure_params.py + + Expected Behavior: + - Loads system parameters from multiple JSON sources. + - Initializes and validates `.env` and runtime parameter files. + - Logs structured debugging information. + - Handles missing configuration files gracefully. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Critical error encountered during processing. FUNCTIONS fetching_runtime_variables() -> Dict[str, Dict[str, Union[str, Dict[str, str]]]] - Extracts and structures runtime variables from system configuration files. + Function: fetching_runtime_variables() -> Dict[str, Dict[str, Union[str, Dict[str, str]]]] + Description: + Extracts structured runtime variables from system parameter files. Returns: - Dict[str, Dict[str, Union[str, Dict[str, str]]]]: Organized runtime variables by section. + - Dict[str, Dict[str, Union[str, Dict[str, str]]]]: Structured runtime variables. + + Behavior: + - Loads system parameters using load_json_sources(). + - Iterates over sections and extracts options. + - Ensures type safety for section options. + + Error Handling: + - Logs errors and exits on failures. initialize_env_file() -> None - Ensures the `.env` file exists and is populated with valid environment variables. + Function: initialize_env_file() -> None + Description: + Ensures that the .env file exists and is properly initialized. + + Behavior: + - Validates the .env file. + - If missing or invalid, attempts to populate it. + + Error Handling: + - Logs errors and exits on failure. initialize_runtime_file() -> None - Ensures the runtime parameters file exists and is updated with structured values. + Function: initialize_runtime_file() -> None + Description: + Ensures that the runtime parameters file exists and is correctly initialized. + + Behavior: + - Validates the runtime parameters file. + - If missing or invalid, attempts to repopulate it. + + Error Handling: + - Logs errors and exits on failure. load_json_sources(filepaths: List[str], mode: str = 'merge') -> Union[Dict, Tuple[Dict]] - Loads JSON data from multiple files and merges them if required. + Function: load_json_sources(filepaths: List[str], mode: str = "merge") -> Union[Dict, Tuple[Dict]] + Description: + Loads and merges multiple JSON configuration files. Parameters: - filepaths (List[str]): List of JSON file paths to load. - mode (str, optional): Determines if data should be merged or returned separately. Defaults to "merge". + - filepaths (List[str]): List of JSON file paths to load. + - mode (str, optional): Mode of operation ('merge' to combine, 'fetch' to return separate dictionaries). Defaults to "merge". Returns: - Union[Dict, Tuple[Dict]]: Merged dictionary or tuple of dictionaries based on mode. + - Dict: Merged JSON data when mode="merge". + - Tuple[Dict]: Tuple of JSON objects when mode="fetch". + + Behavior: + - Iterates over the provided file paths. + - Reads and parses JSON data while ensuring valid structure. + - Merges JSON contents into a single dictionary if mode="merge". + + Error Handling: + - Raises ValueError for invalid JSON structures. + - Raises RuntimeError for file read failures. main() -> Tuple[Dict, Dict] - Orchestrates the initialization and validation of system configurations. + Function: main() -> Tuple[Dict, Dict] + Description: + Orchestrates the environment initialization process. Returns: - Tuple[Dict, Dict]: Loaded system parameters and runtime parameters. + - Tuple[Dict, Dict]: The loaded system and runtime parameters. + + Behavior: + - Calls initialization functions. + - Loads system parameters. + - Loads runtime parameters. + + Error Handling: + - Logs errors and returns an empty dictionary if failures occur. populate_env_file() -> bool - Generates and writes environment variables to the `.env` file from system configuration. + Function: populate_env_file() -> bool + Description: + Generates and writes structured environment variables to the .env file. Returns: - bool: True if successful, False otherwise. + - bool: True if the file was successfully populated, False otherwise. + + Behavior: + - Fetches runtime variables from fetching_runtime_variables(). + - Writes the extracted values to the .env file in a structured format. + + Error Handling: + - Logs errors and returns False on failure. populate_runtime_file() -> bool - Updates the runtime parameters JSON file with values extracted from system configurations and `.env`. + Function: populate_runtime_file() -> bool + Description: + Updates and writes runtime parameters to the runtime-params.json file. Returns: - bool: True if successful, False otherwise. + - bool: True if the file was successfully updated, False otherwise. + + Behavior: + - Loads existing environment values from the .env file. + - Updates runtime parameters dynamically. + - Saves the updated structure to the runtime-params.json file. + + Error Handling: + - Logs errors and exits on failure. validate_env_file() -> bool - Validates the `.env` file to ensure it exists and contains valid data. + Function: validate_env_file() -> bool + Description: + Checks the existence and validity of the .env file. Returns: - bool: True if valid, False otherwise. + - bool: True if the file is valid, False otherwise. + + Behavior: + - Reads the .env file contents. + - Ensures it is non-empty and formatted correctly. + + Error Handling: + - Logs warnings and returns False if the file is missing or invalid. validate_runtime_file() -> bool - Validates the runtime parameters JSON file to ensure it is correctly structured. + Function: validate_runtime_file() -> bool + Description: + Checks the existence and validity of the runtime parameters file. Returns: - bool: True if valid, False otherwise. + - bool: True if the file is valid, False otherwise. + + Behavior: + - Reads the runtime parameters file. + - Ensures it is non-empty and formatted correctly. + + Error Handling: + - Logs warnings and returns False if the file is missing or invalid. DATA Dict = typing.Dict diff --git a/docs/pydoc/lib/manage_accesstoken.pydoc b/docs/pydoc/lib/manage_accesstoken.pydoc index b387a68..ba672c4 100644 --- a/docs/pydoc/lib/manage_accesstoken.pydoc +++ b/docs/pydoc/lib/manage_accesstoken.pydoc @@ -3,69 +3,81 @@ Help on module lib.manage_accesstoken in lib: NAME - lib.manage_accesstoken + lib.manage_accesstoken - File Path: ./lib/manage_accesstoken.py DESCRIPTION - Overview: - The manage_accesstoken.py module is responsible for handling Azure authentication - and managing access token expiration. It ensures that valid access tokens are available - for API interactions while also integrating timezone detection for better session tracking. - - This module provides a command-line interface for checking and managing Azure sessions, - retrieving local timezone offsets, and logging authentication details. + Description: + The manage_accesstoken.py module manages Azure authentication token expiration and local timezone offset retrieval. + It integrates utilities from accesstoken_expiration, timezone_localoffset, and argument_parser to streamline session handling. Core Features: - - Retrieves and verifies Azure access token expiration. - - Integrates with local timezone offset detection. - - Provides command-line arguments for debugging and verbosity. - - Handles authentication failures gracefully. - - Expected Behavior & Usage: - Running the Script: - python manage_accesstoken.py --debug + - Access Token Management: Calls print_token_expiration() to retrieve and print token expiration details. + - Timezone Offset Handling: Fetches local timezone offset via get_local_offset(). + - Command-line Argument Parsing: Uses parse_arguments() to extract CLI options (e.g., debug, verbose). + - Error Handling: Captures and logs errors in token expiration and timezone retrieval. - Example Integration: + Usage: + Executing Token and Timezone Management: from lib.manage_accesstoken import manage_accesstoken manage_accesstoken() + CLI Execution: + python manage_accesstoken.py --debug + Dependencies: - - accesstoken_expiration: Handles Azure authentication and access token expiration. - - timezone_localoffset: Retrieves and processes the local timezone offset. - - argument_parser: Parses CLI arguments for debug and verbose flags. + - sys - Handles system-level exit calls for error handling. + - pathlib - Ensures dynamic resolution of the script’s directory path. + - lib.timezone_localoffset.get_local_offset - Retrieves the system’s local timezone offset. + - lib.accesstoken_expiration.print_token_expiration - Fetches and prints Azure token expiration. + - lib.argument_parser.parse_arguments - Parses CLI arguments for session management. -FUNCTIONS - main() -> None - Main entry point for managing Azure session and token expiration. + Global Behavior: + - Retrieves Azure access token expiration details. + - Computes local timezone offsets. + - Supports command-line execution with debugging and verbosity options. - Behavior: - - Parses command-line arguments to configure debug and verbose modes. - - Calls manage_accesstoken() to validate authentication and session expiration. + CLI Integration: + This module can be executed via the command line for interactive token and timezone management. - Raises: - - Exception: If argument parsing or authentication handling fails. + Example Execution: + python manage_accesstoken.py --debug - Returns: - - None: This function does not return values; it orchestrates session management. + Expected Behavior: + - Successfully retrieves the Azure authentication token expiration timestamp. + - Computes and displays the local timezone offset. + - Handles token retrieval failures gracefully with error messages. - Example Usage: - python manage_accesstoken.py --debug + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during execution. - manage_accesstoken() -> None - Manages Azure authentication and session expiration handling. +FUNCTIONS + main() -> None + Function: main() -> None + Description: + Main entry point for executing access token and timezone offset management. Behavior: - - Calls print_token_expiration() to check the Azure token status. - - Calls get_local_offset() to determine the local timezone offset. - - Logs authentication and timezone details. + - Calls parse_arguments() to retrieve command-line arguments. + - Extracts debug and verbose mode flags. + - Calls manage_accesstoken() to perform token expiration and timezone retrieval. - Raises: - - Exception: If an error occurs during token retrieval or timezone processing. + Error Handling: + - Logs errors and exits on failure. - Returns: - - None: This function does not return values; it handles session validation. + manage_accesstoken() -> None + Function: manage_accesstoken() -> None + Description: + Manages Azure access token expiration and timezone offset retrieval. - Example Usage: - manage_accesstoken() + Behavior: + - Calls print_token_expiration() to fetch and display token expiration details. + - Calls get_local_offset() to retrieve the local timezone offset. + - Handles errors in authentication token retrieval or timezone processing. + + Error Handling: + - Captures exceptions and prints error messages to stderr. + - If an error occurs, exits the script with status code 1. VERSION 0.1.0 diff --git a/docs/pydoc/lib/parsing_userinput.pydoc b/docs/pydoc/lib/parsing_userinput.pydoc index 9edc926..47e7105 100644 --- a/docs/pydoc/lib/parsing_userinput.pydoc +++ b/docs/pydoc/lib/parsing_userinput.pydoc @@ -3,86 +3,134 @@ Help on module lib.parsing_userinput in lib: NAME - lib.parsing_userinput + lib.parsing_userinput - File Path: ./lib/parsing_userinput.py DESCRIPTION - Overview: - The parsing_userinput.py module is responsible for collecting user input interactively. - It ensures all required runtime parameters are provided by prompting users dynamically, - while also integrating configuration-based input handling. + Description: + The parsing_userinput.py module provides functions to request user input interactively when required environment + variables are missing. It supports structured user interviews, input validation, and environmental updates. Core Features: - - Interactive Input Requests: Prompts users for required input dynamically. - - Configuration-Based Prompts: Loads argument configurations from a JSON file. - - Environment Variable Management: Updates system environment variables at runtime. - - Error Handling: Ensures non-interactive environments exit safely with meaningful errors. + - Interactive User Input: Requests input dynamically from users when required environment variables are missing. + - Default Values: Supports default values for prompts to simplify user interaction. + - Structured User Interview: Guides users through missing configurations. + - Environment Variable Management: Updates environment variables dynamically based on user input. + - Error Handling: Handles non-interactive environments and user interruptions gracefully. + + Usage: + Requesting User Input: + from lib.parsing_userinput import request_input + value = request_input("Enter your API Key:", required=True) + + Conducting a User Interview: + from lib.parsing_userinput import user_interview + user_inputs = user_interview(arguments_config, missing_vars) + + Parsing and Collecting Inputs: + from lib.parsing_userinput import parse_and_collect_user_inputs + inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) - Expected Behavior & Usage: - Running the Script: - python parsing_userinput.py + Dependencies: + - sys - Handles user input and process termination. + - json - Loads structured configuration files for argument processing. + - os - Manages environment variables dynamically. + - logging - Provides structured logging and debugging output. + - pathlib - Resolves script file paths safely. - Example Integration: - from lib.parsing_userinput import parse_and_collect_user_inputs - user_inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) + Global Behavior: + - Checks for missing environment variables. + - Prompts users for required input dynamically. + - Updates environment variables based on user responses. + - Supports command-line execution in interactive environments. + + CLI Integration: + This module is primarily used as a supporting library but can be extended for CLI interaction. + + Example Execution: + python parsing_userinput.py + + Expected Behavior: + - Requests missing user inputs interactively. + - Handles default values when provided. + - Updates missing environment variables dynamically. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered in input retrieval or processing. FUNCTIONS main() -> None + Function: main() -> None + Description: + Placeholder for module execution. parse_and_collect_user_inputs( arguments_config_path: str, required_runtime_vars: list ) -> dict - Load argument configuration, identify missing variables, and prompt the user. + Function: parse_and_collect_user_inputs(arguments_config_path: str, required_runtime_vars: list) -> dict + Description: + Loads argument configuration from a JSON file and prompts users for missing required variables. Parameters: - arguments_config_path (str): Path to the JSON configuration file. - - required_runtime_vars (list): List of required runtime variables. + - required_runtime_vars (list): List of required runtime environment variables. Returns: - - dict: A dictionary of user-provided environment variable values. + - dict: Dictionary containing user-provided values. Behavior: - - Loads the argument configuration from a JSON file. - - Identifies missing environment variables and prompts the user. - - Updates os.environ dynamically based on user input. + - Loads argument configuration from the provided JSON file. + - Identifies missing environment variables. + - Initiates a user interview process for missing values. + - Updates environment variables dynamically. - Example Usage: - user_inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) + Error Handling: + - Logs and raises an error if the configuration file is missing. + - Ensures input follows expected formats before applying updates. request_input(prompt: str, required: bool = True, default: str = None) -> str - Prompt the user for input with an optional default value. + Function: request_input(prompt: str, required: bool = True, default: str = None) -> str + Description: + Prompts the user for input interactively, enforcing required fields and handling default values. Parameters: - - prompt (str): The message displayed to the user. - - required (bool): Whether the input is mandatory. Defaults to True. - - default (str, optional): The default value if no input is provided. + - prompt (str): The message displayed to the user for input. + - required (bool, optional): Determines if input is mandatory. Defaults to True. + - default (str, optional): Default value if no input is provided. Defaults to None. Returns: - str: The user-provided input or the default value. Behavior: - - If sys.stdin.isatty() is False, logs an error and exits since interactive input is not possible. - - If the user presses Ctrl+C, logs the interruption and exits. + - If stdin is non-interactive, exits with an error. + - Displays the prompt message with a default value if provided. + - Ensures required inputs are not skipped. + - Captures keyboard interruptions cleanly. - Example Usage: - user_value = request_input("Enter your name", required=True, default="Guest") + Error Handling: + - If stdin is non-interactive and input is required, logs an error and exits. + - Handles KeyboardInterrupt gracefully, allowing clean exit. user_interview(arguments_config: dict, missing_vars: list) -> dict - Collect required user input for missing environment variables. + Function: user_interview(arguments_config: dict, missing_vars: list) -> dict + Description: + Conducts a structured user interview to gather missing environment variables. Parameters: - - arguments_config (dict): Dictionary containing argument configurations. - - missing_vars (list): List of required variables that are missing. + - arguments_config (dict): Dictionary defining input prompts and default values. + - missing_vars (list): List of required variables that are missing from the environment. Returns: - - dict: A dictionary mapping missing variable names to user-provided values. + - dict: A dictionary of collected user inputs. Behavior: - - Cross-references arguments_config to determine the prompt and default values. - - Calls request_input() for each missing variable. + - Iterates through missing environment variables. + - Matches them against argument configuration definitions. + - Requests input interactively and applies default values when available. - Example Usage: - user_inputs = user_interview(config, ["API_KEY", "USERNAME"]) + Error Handling: + - Ensures user input follows expected formats. VERSION 0.1.0 diff --git a/docs/pydoc/lib/pkgconfig_loader.pydoc b/docs/pydoc/lib/pkgconfig_loader.pydoc index e097f4c..7e57aa9 100644 --- a/docs/pydoc/lib/pkgconfig_loader.pydoc +++ b/docs/pydoc/lib/pkgconfig_loader.pydoc @@ -3,75 +3,124 @@ Help on module lib.pkgconfig_loader in lib: NAME - lib.pkgconfig_loader + lib.pkgconfig_loader - File Path: ./lib/pkgconfig_loader.py DESCRIPTION - Overview: - The pkgconfig_loader.py module is responsible for loading and managing package configuration files. - It provides methods for parsing, validating, and retrieving configuration data from structured files (e.g., JSON). + Description: + The pkgconfig_loader.py module provides utilities for dynamically loading, validating, and managing + package configurations. It ensures structured configuration handling, logging setup, and package-specific + settings retrieval. Core Features: - - Configuration File Loading: Reads and parses package configuration files. - - Validation Support: Ensures required parameters are present. - - Structured Access: Provides a structured interface for retrieving configuration values. - - Logging and Debugging: Ensures consistent logging across packages. + - JSON Configuration Loading: Reads and validates structured configuration files. + - Dynamic Logging Setup: Generates unique log file names and directories. + - Configuration Overrides: Allows runtime overrides of configuration parameters. + - Automatic Configuration Updates: Ensures settings are refreshed dynamically. + - Error Handling: Captures and logs errors for missing or malformed configuration files. Usage: - Loading a package-specific configuration: + Loading Package Configurations: from lib.pkgconfig_loader import package_configs config = package_configs() - Setting up logging for a module: - setup_configs("/path/to/module.py") + Setting Up Configurations: + from lib.pkgconfig_loader import setup_configs + config = setup_configs(Path("/path/to/module")) Dependencies: - - os, sys, json, pathlib, datetime - - system_variables: Provides project-wide settings and configurations. + - sys - Handles system path modifications and process exits. + - os - Provides file system utilities. + - json - Loads, modifies, and validates configuration data. + - datetime - Handles timestamps for logging and configuration updates. + - pathlib - Ensures safe file path resolution. + - typing (Optional, Union) - Defines flexible function return types. + + Global Behavior: + - Loads package configurations dynamically. + - Generates structured logging paths. + - Handles missing or invalid configuration files gracefully. + - Updates timestamps when configurations change. + + CLI Integration: + This module primarily supports configuration loading for other scripts but can be executed for testing. + + Example Execution: + python pkgconfig_loader.py + + Expected Behavior: + - Reads JSON-based configuration files. + - Ensures logging directories and filenames are structured. + - Handles missing configuration files with default fallbacks. Exit Codes: - - 0: Successful execution. - - 1: Failure due to missing or invalid configuration files. + - 0: Execution completed successfully. + - 1: Error encountered in configuration processing. FUNCTIONS config_logfile(config: dict, caller_log_path: Optional[str] = None) -> pathlib._local.Path - Determines the correct log file path based on the caller module's request or self-inspection. + Function: config_logfile(config: dict, caller_log_path: Optional[str] = None) -> Path + Description: + Generates a structured log file path based on package settings. Parameters: - config (dict): Configuration dictionary containing logging settings. - caller_log_path (Optional[str]): A specific log directory path requested by the caller. + - config (dict): Configuration dictionary containing logging details. + - caller_log_path (Optional[str]): Custom log file path if specified. Returns: - Path: The resolved log file path. + - Path: The computed log file path. + + Behavior: + - Uses package name and timestamp to generate a unique log filename. + - If a caller_log_path is provided, the log file is placed there. + - Otherwise, the logs directory from the configuration is used. main() -> None package_configs(overrides: Optional[dict] = None) -> dict - Loads a package-specific configuration from a JSON file or generates a default configuration. + Function: package_configs(overrides: Optional[dict] = None) -> dict + Description: + Loads and returns package configuration settings, applying overrides if provided. Parameters: - overrides (Optional[dict]): Configuration values to override defaults. + - overrides (Optional[dict]): Dictionary of settings to override. Returns: - dict: The loaded or generated package configuration. + - dict: The structured configuration dictionary. + + Behavior: + - Attempts to load a package-specific JSON configuration file. + - If no file exists, generates a default configuration. + - Merges any overrides provided by the caller. + - Generates a log filename and updates timestamps dynamically. - Raises: - FileNotFoundError: If the configuration file is missing. - json.JSONDecodeError: If the file contains invalid JSON. + Error Handling: + - Logs and exits if the JSON file is missing or malformed. setup_configs( absolute_path: pathlib._local.Path, logname_override: Optional[str] = None, events: Union[bool, list, dict, NoneType] = None ) -> dict - Dynamically initializes and updates logging configuration for the calling module. + Function: setup_configs(absolute_path: Path, logname_override: Optional[str] = None, events: Optional[Union[bool, list, dict]] = None) -> dict + Description: + Initializes and updates configuration settings based on the caller’s package details. Parameters: - absolute_path (Path): The absolute path of the module requesting logging setup. - logname_override (Optional[str]): A custom name for the log file. - events (Optional[Union[bool, list, dict]]): Event control settings. + - absolute_path (Path): Path to the module requiring configuration. + - logname_override (Optional[str]): Allows overriding the default log filename. + - events (Optional[Union[bool, list, dict]]): Specifies which logging events should be enabled. Returns: - dict: The updated logging configuration. + - dict: The final configuration dictionary. + + Behavior: + - Identifies the calling module and determines package name. + - Loads or generates the expected configuration file. + - Adjusts logging settings, including log directory and filename. + - Updates the configuration file dynamically with new settings. + + Error Handling: + - Logs and exits if configuration updates fail. DATA Optional = typing.Optional @@ -113,7 +162,7 @@ DATA project_logs = PosixPath('/logs... project_packages = PosixPath('/... project_root = PosixPath('') - timestamp = '20250309181620' + timestamp = '20250309231457' VERSION 0.1.0 diff --git a/docs/pydoc/lib/pydoc_generator.pydoc b/docs/pydoc/lib/pydoc_generator.pydoc index 9d11bbb..8b86320 100644 --- a/docs/pydoc/lib/pydoc_generator.pydoc +++ b/docs/pydoc/lib/pydoc_generator.pydoc @@ -3,40 +3,58 @@ Help on module lib.pydoc_generator in lib: NAME - lib.pydoc_generator + lib.pydoc_generator - File Path: ./lib/pydoc_generator.py DESCRIPTION - Overview - Automated Python Documentation Generator (PyDoc) - This module provides a framework for generating documentation for Python scripts and packages - within a project using the `pydoc` module. It ensures that documentation is structured correctly - and saved in an organized manner. + Description: + The pydoc_generator.py module automates the generation of structured documentation for Python modules + by leveraging Python's built-in pydoc utility. It also integrates test coverage analysis and logging. Core Features: - - Dynamic Documentation Generation: Automates the process of generating PyDoc documentation. - - Path Handling: Uses `pathlib` for robust and cross-platform path operations. - - Error Handling & Logging: Captures errors and logs messages for debugging. - - Flexible Execution: Distinguishes between modules and standalone scripts for correct PyDoc execution. - - Output Sanitization: Redacts sensitive system paths from generated documentation. - - Coverage Integration: Generates separate `.coverage` files per module. + - **Automatic Documentation Generation**: Uses pydoc to generate structured `.pydoc` files. + - **Test Coverage Reporting**: Integrates with `coverage.py` to produce detailed reports. + - **Dynamic File Structure Creation**: Ensures documentation files are stored systematically. + - **Error Handling and Logging**: Provides structured logs for troubleshooting and debugging. + - **Path Normalization**: Handles absolute and relative paths across various environments. - Expected Behavior & Usage: - Generating PyDoc Documentation: - python run.py --pydoc + Usage: + Creating a PyDoc Structure: + from lib.pydoc_generator import create_structure + doc_dir = create_structure(Path("/docs"), "my_package") + + Generating Documentation for a Module: + from lib.pydoc_generator import generate_pydoc + generate_pydoc(Path("/project"), Path("/project/lib/my_module.py"), Path("/docs")) Dependencies: - - os - - sys - - re - - subprocess - - pathlib - - system_variables (for project environment settings) - - log_utils (for structured logging) - - coverage (for tracking execution coverage) + - sys - Handles system path modifications and process exits. + - os - Provides file system utilities. + - re - Regular expressions for text sanitization. + - subprocess - Executes external commands (`pydoc`, `coverage`). + - pathlib - Ensures safe and platform-independent file path resolution. + - coverage - Generates code coverage reports. + + Global Behavior: + - Generates documentation for Python modules. + - Captures and logs errors encountered during the process. + - Normalizes paths for consistent file system operations. + - Applies automated test coverage validation. + + CLI Integration: + This module primarily runs as part of an automated documentation pipeline but can be executed manually. + + Example Execution: + python pydoc_generator.py + + Expected Behavior: + - Successfully generates `.pydoc` documentation files. + - Produces test coverage reports if coverage data is available. + - Handles missing documentation files gracefully. + - Logs all key actions and errors. Exit Codes: - - 0: Successful execution. - - 1: Failure due to incorrect file paths or PyDoc errors. + - 0: Execution completed successfully. + - 1: Error encountered during documentation generation. FUNCTIONS create_pydocs( @@ -45,11 +63,42 @@ FUNCTIONS files_list: list[pathlib._local.Path], configs: dict = None ) + Function: create_pydocs(project_path: Path, base_path: Path, files_list: list[Path], configs: dict = None) + Description: + Automates the generation of documentation for multiple Python files. + + Parameters: + - project_path (Path): Root directory of the project. + - base_path (Path): Directory where generated documentation will be stored. + - files_list (list[Path]): List of Python files to document. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Iterates over the list of Python files. + - Calls generate_pydoc() for each file. + - Logs progress and reports any errors encountered. + + Error Handling: + - Logs any subprocess errors during documentation generation. create_structure( base_path: pathlib._local.Path, package_name: pathlib._local.Path ) -> pathlib._local.Path + Function: create_structure(base_path: Path, package_name: Path) -> Path + Description: + Creates a directory structure for storing generated documentation files. + + Parameters: + - base_path (Path): The root directory for documentation files. + - package_name (Path): The subdirectory name for organizing files. + + Returns: + - Path: The created directory path. + + Behavior: + - Creates the specified directory if it does not already exist. + - Ensures parent directories are also created. generate_coverage( project_path: pathlib._local.Path, @@ -57,6 +106,24 @@ FUNCTIONS base_path: pathlib._local.Path, configs: dict = None ) + Function: generate_coverage(project_path: Path, file_path: Path, base_path: Path, configs: dict = None) + Description: + Generates a coverage report for a specific Python file. + + Parameters: + - project_path (Path): Root directory of the project. + - file_path (Path): The target Python file for coverage analysis. + - base_path (Path): Directory where coverage reports should be saved. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Executes `coverage report --include=` for precise coverage analysis. + - Saves the output to a `.coverage` file within the structured documentation directory. + - Logs the coverage report details. + + Error Handling: + - Skips processing if no coverage data is found. + - Logs an error if the subprocess call fails. generate_pydoc( project_path: pathlib._local.Path, @@ -64,23 +131,42 @@ FUNCTIONS docs_path: pathlib._local.Path, configs: dict = None ) - Generate and store PyDoc documentation for a given Python file. + Function: generate_pydoc(project_path: Path, file_path: Path, docs_path: Path, configs: dict = None) + Description: + Generates a `.pydoc` documentation file for a given Python module. Parameters: - project_path (Path): The root path of the project. - file_path (Path): The Python file for which documentation will be generated. - docs_path (Path): The directory where the generated documentation will be stored. - configs (dict, optional): Additional configuration parameters for logging. - - Returns: - None: This function does not return any value but writes documentation or error messages to disk. + - project_path (Path): Root directory of the project. + - file_path (Path): The target Python module for documentation. + - docs_path (Path): Directory where the documentation will be stored. + - configs (dict, optional): Configuration settings for logging. Behavior: - - Differentiates between scripts and modules to invoke `pydoc` correctly. - - Stores the generated documentation in `docs/pydoc/.pydoc`. - - Sanitizes system paths in the output to avoid exposing absolute paths. + - Converts file paths into module names compatible with `pydoc`. + - Runs `pydoc` as a subprocess to generate documentation. + - Saves the generated documentation to a `.pydoc` file. + - Cleans paths to remove absolute locations for better portability. + + Error Handling: + - Captures errors from `pydoc` and logs them. + - Renames failed documentation files to `.error` for debugging. generate_report(coverage_report: pathlib._local.Path, configs: dict = None) + Function: generate_report(coverage_report: Path, configs: dict = None) + Description: + Generates a test coverage report using `coverage.py` and saves it to a specified file. + + Parameters: + - coverage_report (Path): The file path where the coverage report will be stored. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Runs `coverage report` via subprocess to generate test coverage. + - Redirects output to the specified coverage report file. + - Logs a warning if the coverage report is empty. + + Error Handling: + - Logs an error message if the coverage command fails. main() -> None diff --git a/docs/pydoc/lib/pydoc_loader.pydoc b/docs/pydoc/lib/pydoc_loader.pydoc index c6f76db..415c7a6 100644 --- a/docs/pydoc/lib/pydoc_loader.pydoc +++ b/docs/pydoc/lib/pydoc_loader.pydoc @@ -7,40 +7,61 @@ NAME FUNCTIONS apply_docstrings(module: module, function_docs: Dict[str, str]) -> None - Dynamically assigns function docstrings from a loaded `.pydoc` file to a given module. + Function: apply_docstrings(module: ModuleType, function_docs: Dict[str, str]) -> None + Description: + Dynamically assigns function docstrings from an external `.pydoc` file to a given module. Parameters: - module (ModuleType): The module in which function docstrings should be applied. - function_docs (Dict[str, str]): A dictionary mapping function names to their respective docstrings. + - module (ModuleType): The module where function docstrings should be applied. + - function_docs (Dict[str, str]): A dictionary mapping function names to their respective docstrings. + + Behavior: + - Iterates through the dictionary of function docstrings. + - Assigns each docstring to the corresponding function in the target module. + + Error Handling: + - Logs a warning if a function does not exist in the module. apply_variable_docstrings(module: module, variable_docs: Dict[str, str]) -> None - Stores variable docstrings in a global dictionary instead of modifying __doc__, - since primitive types (str, int, list, etc.) do not support docstring assignment. + Function: apply_variable_docstrings(module: ModuleType, variable_docs: Dict[str, str]) -> None + Description: + Stores variable docstrings in a dictionary instead of modifying `__doc__`, as primitive types + (str, int, list, etc.) do not support direct docstring assignments. Parameters: - module (ModuleType): The module in which variable docstrings should be applied. - variable_docs (Dict[str, str]): A dictionary mapping variable names to their respective descriptions. + - module (ModuleType): The module where variable docstrings should be applied. + - variable_docs (Dict[str, str]): A dictionary mapping variable names to their respective descriptions. Behavior: - - Stores variable docstrings in a separate dictionary for retrieval. - - Ensures variables that cannot have __doc__ modified still have documentation available. + - Stores variable docstrings in a global dictionary for easy retrieval. + - Ensures that variables without `__doc__` support are documented separately. + + Error Handling: + - Logs a warning if a variable is not found in the module. load_pydocs(script_path: str, module: module) -> None - Loads module-level, function-level, and variable-level documentation from an external `.pydoc` file. + Function: load_pydocs(script_path: str, module: ModuleType) -> None + Description: + Loads external documentation from a `.pydoc` file and applies it to a given module. Parameters: - script_path (str): The full path of the script whose documentation should be loaded. - module (ModuleType): The module in which function and variable docstrings should be applied. + - script_path (str): The absolute path of the script whose documentation should be loaded. + - module (ModuleType): The module where function and variable docstrings should be applied. Behavior: - - Searches for a `.pydoc` file matching the script's name in the `.pydocs/` directory. + - Searches for a `.pydoc` file matching the script name in the `.pydocs/` directory. - Loads and parses the module docstring (`MODULE_DOCSTRING`), function docstrings (`FUNCTION_DOCSTRINGS`), and variable docstrings (`VARIABLE_DOCSTRINGS`). - - Assigns function and variable docstrings dynamically to the specified module. - - Does **not** return `MODULE_DOCSTRING`, `FUNCTION_DOCSTRINGS`, or `VARIABLE_DOCSTRINGS` to prevent them - from appearing as global variables in `pydoc` output. + - Assigns function and variable docstrings dynamically to the target module. + + Error Handling: + - Logs a warning if no corresponding `.pydoc` file is found. + - Logs an error if the `.pydoc` file fails to load or parse. main() -> None + Function: main() -> None + Description: + Placeholder function for module execution. DATA Dict = typing.Dict diff --git a/docs/pydoc/lib/system_params.pydoc b/docs/pydoc/lib/system_params.pydoc index 0edb826..d734d83 100644 --- a/docs/pydoc/lib/system_params.pydoc +++ b/docs/pydoc/lib/system_params.pydoc @@ -3,87 +3,120 @@ Help on module lib.system_params in lib: NAME - lib.system_params - File: ./lib/system_params.py + lib.system_params - File Path: ./lib/system_params.py DESCRIPTION Description: - System Parameter Management - This module handles system-wide parameter management by loading runtime - parameters from JSON configuration files and merging them with environment variables. + The system_params.py module handles the management and validation of runtime system parameters. + It ensures that required environment variables are loaded, validated, and structured correctly. Core Features: - - **Configuration Loading**: Reads parameters from `runtime-params.json`, `project-params.json`, and `default-params.json`. - - **Environment Variable Management**: Dynamically sets system-wide environment variables. - - **Validation and Error Handling**: Ensures required parameters are initialized before execution. + - **JSON Configuration Loading**: Reads and validates structured JSON configuration files. + - **Environment Variable Management**: Dynamically loads and sets environment variables. + - **Runtime Parameter Validation**: Ensures required parameters are available before execution. + - **Logging and Error Handling**: Provides structured logging for debugging and troubleshooting. + - **Automatic File Creation**: Generates missing configuration files when necessary. Usage: - To load and initialize system parameters: - python system_params.py + Loading Runtime Configuration: + from lib.system_params import load_json_config + config = load_json_config(runtime_params_filepath) - Dependencies: - - os - - json - - logging - - dotenv - - pathlib - - lib.configure_params (for JSON merging and validation) + Retrieving Environment Variables: + from lib.system_params import get_runtime_variable + api_key = get_runtime_variable("API_KEY", required=True) + + Validating Runtime Parameters: + from lib.system_params import validate_runtime_params + validate_runtime_params(runtime_params_filepath) - Global Variables: - - `SYSTEM_PARAMS` (dict): Loaded system-wide parameters. - - `RUNTIME_PARAMS` (dict): Parameters dynamically merged at runtime. + Dependencies: + - sys - Handles system-level functions such as process termination. + - os - Manages environment variables and file system interactions. + - json - Loads, parses, and validates configuration data. + - logging - Provides structured logging for debugging and execution tracking. + - dotenv (load_dotenv) - Loads environment variables from a `.env` file. + - typing (Optional) - Defines flexible function return types. + - pathlib - Ensures safe and platform-independent file path resolution. + + Global Behavior: + - Loads runtime configuration from structured JSON files. + - Validates that all required system parameters are available. + - Generates missing configuration files when needed. + - Ensures environment variables are set correctly. + + CLI Integration: + This module is primarily used as an internal component but can be executed manually for debugging. + + Example Execution: + python system_params.py + + Expected Behavior: + - Successfully loads and validates system parameters. + - Creates missing runtime parameter files when necessary. + - Logs missing or malformed configurations for troubleshooting. Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to missing configuration files or invalid environment variables. + - 0: Execution completed successfully. + - 1: Error encountered during configuration processing. FUNCTIONS get_runtime_variable(name: str, required: bool = False) -> Optional[str] - Retrieve an environment variable safely, handling missing or empty values. + Function: get_runtime_variable(name: str, required: bool = False) -> Optional[str] + Description: + Retrieves an environment variable and validates its presence if required. - This function fetches an environment variable and logs a warning if a required - variable is missing or empty. + Parameters: + - name (str): The name of the environment variable to retrieve. + - required (bool, optional): Whether the variable is mandatory. Defaults to False. - Args: - name (str): The name of the environment variable to retrieve. - required (bool, optional): Whether the variable is mandatory. Defaults to False. + Returns: + - Optional[str]: The value of the environment variable or None if missing. - Raises: - RuntimeError: If there is an issue retrieving the environment variable. + Behavior: + - Retrieves the value of the specified environment variable. + - Logs a warning if a required variable is missing. - Returns: - Optional[str]: The value of the environment variable, or None if it is missing. + Error Handling: + - Raises RuntimeError if an error occurs while retrieving the variable. load_json_config(runtime_params_filepath: pathlib._local.Path) -> dict - Load environment variables from a JSON configuration file. + Function: load_json_config(runtime_params_filepath: Path) -> dict + Description: + Loads a JSON configuration file and validates its contents. - Reads a JSON file and ensures its structure is valid before returning - the parsed contents. + Parameters: + - runtime_params_filepath (Path): Path to the JSON configuration file. - Args: - runtime_params_filepath (Path): The file path of the JSON configuration file. + Returns: + - dict: The parsed configuration dictionary. - Raises: - ValueError: If the JSON file is empty or has an invalid structure. - RuntimeError: If the file cannot be read. + Behavior: + - Reads the specified JSON file. + - Ensures the file is not empty and contains valid JSON. + - Returns the parsed configuration dictionary. - Returns: - dict: The parsed JSON data containing system parameters. + Error Handling: + - Raises ValueError if the JSON file is empty or malformed. + - Raises RuntimeError if the file cannot be read. main() -> None validate_runtime_params(runtime_params_filepath) - Validates the existence and content of the runtime parameters JSON file. + Function: validate_runtime_params(runtime_params_filepath: Path) + Description: + Validates the structure and existence of the runtime parameters file. - This function checks whether the specified JSON file exists, is not empty, - and contains valid JSON. It raises appropriate exceptions if any of the - validation steps fail. + Parameters: + - runtime_params_filepath (Path): The file path of the runtime parameters JSON. - Args: - runtime_params_filepath (str or Path): The file path to the runtime parameters JSON file. + Behavior: + - Ensures the runtime parameters file exists. + - Checks that the file is non-empty and contains valid JSON. - Raises: - FileNotFoundError: If the file specified by `runtime_params_filepath` does not exist. - ValueError: If the file is empty or if it does not contain valid JSON. + Error Handling: + - Raises FileNotFoundError if the file is missing. + - Raises ValueError if the file is empty or contains invalid JSON. DATA Optional = typing.Optional diff --git a/docs/pydoc/lib/system_variables.pydoc b/docs/pydoc/lib/system_variables.pydoc index fefd075..1c69d3d 100644 --- a/docs/pydoc/lib/system_variables.pydoc +++ b/docs/pydoc/lib/system_variables.pydoc @@ -3,7 +3,51 @@ Help on module lib.system_variables in lib: NAME - lib.system_variables - # File: ./lib/system_variables.py + lib.system_variables - File Path: ./lib/system_variables.py + +DESCRIPTION + Description: + The system_variables.py module defines global paths, file names, and system-wide constants + for managing configurations, logging, and runtime parameter storage. + + Core Features: + - **Project Path Management**: Defines and resolves key project directories. + - **Configuration File Paths**: Stores paths to runtime, system, and default configuration files. + - **Logging System Variables**: Defines log storage locations and log file retention settings. + - **ANSI Color Categories**: Provides categorized ANSI escape codes for structured terminal output. + - **Global Constants**: Stores universal defaults such as JSON indentation levels and max log files. + + Usage: + Importing System Variables: + from lib.system_variables import project_root, project_logs + print(f"Project logs are stored in: {project_logs}") + + Using ANSI Log Categories: + from lib.system_variables import category + print(f"{category.info.color}INFO: This is a test log{category.reset.color}") + + Dependencies: + - types.SimpleNamespace - Defines structured namespaces for category-based logging. + - pathlib.Path - Ensures safe and platform-independent file path resolution. + + Global Behavior: + - Provides a centralized reference for all project-wide variables. + - Ensures consistency across modules by defining static paths and configurations. + - Enhances logging with structured color-coded categories. + + CLI Integration: + This module is designed as a global reference but can be imported for debugging system paths. + + Example Execution: + python system_variables.py + + Expected Behavior: + - Successfully defines all necessary global paths and system-wide constants. + - Provides a structured way to manage logging, configuration, and runtime parameters. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during variable initialization. DATA category = namespace(calls=namespace(id='CALL', color='\x1b...'), rese... diff --git a/docs/pydoc/lib/timezone_localoffset.pydoc b/docs/pydoc/lib/timezone_localoffset.pydoc index 6e41088..8f13b33 100644 --- a/docs/pydoc/lib/timezone_localoffset.pydoc +++ b/docs/pydoc/lib/timezone_localoffset.pydoc @@ -7,57 +7,8 @@ NAME FUNCTIONS get_local_offset(debug: bool = False) -> float - Retrieves and calculates the local time zone offset from UTC. - - This function: - - Determines the local time zone using `pytz`. - - Computes the time difference (offset) between local time and UTC. - - Prints local and UTC time information in a structured format. - - Args: - debug (bool, optional): Enables additional debugging output. Defaults to False. - - Raises: - Exception: If there is an error retrieving the time zone or calculating the offset. - - 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. main(debug: bool = False) -> None - Main entry point for processing time zone offset calculations. - - This function: - - Calls `get_local_offset()` to retrieve the local time zone and UTC offset. - - Handles exceptions that may arise during execution. - - Args: - debug (bool, optional): Enables additional debugging output. Defaults to False. - - Raises: - SystemExit: If an error occurs during time zone retrieval, the script exits with status `1`. - - 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. DATA LocalOffset = None diff --git a/docs/pydoc/packages/__init__.pydoc b/docs/pydoc/packages/__init__.pydoc index 790561f..ff24ed2 100644 --- a/docs/pydoc/packages/__init__.pydoc +++ b/docs/pydoc/packages/__init__.pydoc @@ -3,7 +3,42 @@ Help on module packages.__init__ in packages: NAME - packages.__init__ - # File: ./packages/__init__.py + packages.__init__ - File Path: packages/__init__.py + +DESCRIPTION + Description: + Packages Directory Initialization + + This module ensures that the `packages/` directory is recognized as a Python package. + It establishes a structured framework for organizing submodules while maintaining + explicit import control. + + Core Features: + - **Package Initialization**: Enables `packages/` to function as a Python package. + - **Explicit Import Control**: Prevents unintended execution by requiring explicit submodule imports. + - **Scalability**: Supports modular architecture by keeping dependencies well-structured. + - **Path Management**: Ensures that `sys.path` includes the `packages/` directory for correct imports. + + Usage: + Modules and submodules within `packages/` should be explicitly imported: + ```python + from packages.appflow_tracer import tracing + from packages.requirements import dependencies + ``` + + Important Notes: + - This file **does not** automatically import submodules to avoid unnecessary execution overhead. + - Individual submodules must be explicitly imported when needed to maintain modularity. + + Dependencies: + - None (This module is solely responsible for initialization) + + Example: + To initialize logging from within the `appflow_tracer` package: + ```python + from packages.appflow_tracer import setup_logging + CONFIGS = setup_logging() + ``` VERSION 0.1.0 diff --git a/docs/pydoc/packages/appflow_tracer/__init__.pydoc b/docs/pydoc/packages/appflow_tracer/__init__.pydoc index 974f786..a7bfcfd 100644 --- a/docs/pydoc/packages/appflow_tracer/__init__.pydoc +++ b/docs/pydoc/packages/appflow_tracer/__init__.pydoc @@ -3,7 +3,59 @@ Help on module packages.appflow_tracer.__init__ in packages.appflow_tracer: NAME - packages.appflow_tracer.__init__ - # File: ./packages/appflow_tracer/__init__.py + packages.appflow_tracer.__init__ - File Path: packages/appflow_tracer/__init__.py + +DESCRIPTION + Description: + AppFlow Tracing Package Initialization + + This module serves as the entry point for the `appflow_tracer` package, ensuring + the package is correctly recognized and exposing core functionalities for structured + logging and function execution tracing. + + Core Features: + - **Package Initialization**: Marks `appflow_tracer` as a Python package, enabling imports. + - **Logging Setup**: Provides `setup_logging` for configuring structured logging. + - **Utility Exposure**: Imports and exposes core framework utilities for tracing, file handling, and logging. + - **Modular Structure**: Ensures clean and organized access to tracing functionalities. + + Submodules: + - `tracing`: Handles structured event-based logging and tracing. + - `lib.file_utils`: Provides file and directory management utilities. + - `lib.log_utils`: Facilitates structured logging and debugging. + - `lib.trace_utils`: Supports runtime tracing and performance monitoring. + - `lib.serialize_utils`: Manages data serialization and deserialization. + + Usage: + Importing and initializing logging: + from packages.appflow_tracer import setup_logging + CONFIGS = setup_logging() + + Logging messages: + from packages.appflow_tracer import log_utils + log_utils.log_message("This is a test log message.") + + Accessing tracing utilities: + from packages.appflow_tracer import trace_utils + trace_utils.start_tracing() + + Dependencies: + - `tracing` - Manages function execution tracing and structured event logging. + - `log_utils` - Handles structured logging, formatting, and log management. + - `file_utils` - Provides file and directory-related utilities. + - `serialize_utils` - Ensures proper data serialization and deserialization. + - `trace_utils` - Supports real-time function call monitoring and execution tracing. + + Exit Codes: + - `0`: Successful package initialization. + - `1`: Failure due to import errors or incorrect setup. + + Example: + Initializing the AppFlow Tracer system: + from packages.appflow_tracer import setup_logging, log_utils + + CONFIGS = setup_logging() + log_utils.log_message("Framework initialized successfully.") FUNCTIONS setup_logging( @@ -11,39 +63,22 @@ FUNCTIONS logname_override: Optional[str] = None, events: Union[bool, dict, NoneType] = None ) -> Union[bool, dict] - Configures and initializes the global logging system. + Configures and initializes structured logging for the framework. - This function sets up the logging environment, creating log files and adding handlers - for both file-based and console-based logging. It ensures proper logging behavior - even when no configuration is provided. + This function sets up logging with file and console handlers, ensuring structured + log output. It integrates function call tracing and manages log file retention. Args: - configs (dict, optional): A dictionary containing logging configurations. - If None, the default global configurations are used. - logname_override (str, optional): A custom name for the log file. - If None, the log file name is derived from the calling script. - events (bool, list, or dict, optional): - - `None` / `False` → Disables all event logging. - - `True` → Enables all event logging. - - `list` → Enables only specified events (e.g., ["call", "return"]). - - `dict` → Enables/disables events per user settings (e.g., {"call": True, "return": False}). - - Raises: - ValueError: If the provided logging configurations are not in a dictionary format. + configs (dict, optional): Logging configuration dictionary. + logname_override (str, optional): Custom log file name. + events (bool, list, dict, optional): Controls which events are logged. Returns: - dict: The effective logging configuration after applying defaults. + dict: The effective logging configuration. Example: - >>> setup_logging() - { - "logging": { - "log_filename": "/path/to/logfile.log", - "max_logfiles": 5, - ... - }, - ... - } + >>> from packages.appflow_tracer import setup_logging + >>> CONFIGS = setup_logging() DATA __all__ = ['setup_logging', 'file_utils', 'log_utils', 'serialize_util... diff --git a/docs/pydoc/packages/appflow_tracer/__main__.pydoc b/docs/pydoc/packages/appflow_tracer/__main__.pydoc index a338342..b79b2ba 100644 --- a/docs/pydoc/packages/appflow_tracer/__main__.pydoc +++ b/docs/pydoc/packages/appflow_tracer/__main__.pydoc @@ -3,7 +3,46 @@ Help on module packages.appflow_tracer.__main__ in packages.appflow_tracer: NAME - packages.appflow_tracer.__main__ - # File: ./packages/appflow_tracer/__main__.py + packages.appflow_tracer.__main__ - File Path: packages/appflow_tracer/__main__.py + +DESCRIPTION + Description: + AppFlow Tracing Package Entry Point + + This module acts as the execution entry point for the `appflow_tracer` package when invoked + using `python -m packages.appflow_tracer`. It ensures structured logging and tracing + are properly initialized by delegating execution to the `main()` function within the `tracing` module. + + Core Features: + - **Standalone Execution**: Enables the package to run independently via `python -m packages.appflow_tracer`. + - **Automatic Logging Setup**: Ensures structured logging and tracing configurations are loaded. + - **Main Function Invocation**: Calls the `main()` function from the `tracing` module to handle execution flow. + + Usage: + Running the `appflow_tracer` package as a standalone application: + ```bash + python -m packages.appflow_tracer + ``` + + This will: + - Initialize structured logging. + - Start function execution tracing. + - Manage log file retention. + + Dependencies: + - `tracing` (Handles logging and execution flow management.) + + Exit Codes: + - `0`: Successful execution. + - `1`: Failure due to configuration or tracing errors. + + Example: + Running the package from the command line: + ```bash + python -m packages.appflow_tracer + ``` + + This will invoke the `main()` function from the `tracing` module, ensuring correct execution. VERSION 0.1.0 diff --git a/docs/pydoc/packages/appflow_tracer/lib/__init__.pydoc b/docs/pydoc/packages/appflow_tracer/lib/__init__.pydoc index d4d51ac..0743ca8 100644 --- a/docs/pydoc/packages/appflow_tracer/lib/__init__.pydoc +++ b/docs/pydoc/packages/appflow_tracer/lib/__init__.pydoc @@ -3,10 +3,53 @@ Help on module packages.appflow_tracer.lib.__init__ in packages.appflow_tracer.lib: NAME - packages.appflow_tracer.lib.__init__ - # File: ./packages/appflow_tracer/lib/__init__.py + packages.appflow_tracer.lib.__init__ - File Path: packages/appflow_tracer/lib/__init__.py + +DESCRIPTION + Description: + AppFlow Tracer Library Initialization + + This file defines the `lib` subpackage within the `appflow_tracer` framework. It provides + access to essential utility modules required for logging, file operations, tracing, and + serialization within the framework. + + Core Features: + - **Subpackage Initialization**: Ensures that the `lib` directory is recognized as a Python package. + - **Utility Module Exposure**: Facilitates direct access to key framework utilities. + - **Structured Imports**: Enables clean and maintainable access to core functionality. + - **Dynamic Documentation Loading**: Injects `.pydoc` documentation into the module. + + Submodules: + - `file_utils`: Provides file and directory management utilities. + - `log_utils`: Handles structured logging and message formatting. + - `trace_utils`: Supports runtime tracing and performance monitoring. + - `serialize_utils`: Manages data serialization and deserialization. + + Usage: + To import specific utilities from this package: + from packages.appflow_tracer.lib import log_utils, file_utils + + log_utils.log_message("Example log message") + file_utils.manage_logfiles() + + To enable tracing within the framework: + from packages.appflow_tracer.lib import trace_utils + trace_utils.start_tracing() + + Dependencies: + - `sys` - Provides access to system path management. + - `pathlib.Path` - Used for resolving package paths dynamically. + - `lib.pydoc_loader` - Dynamically loads module-level documentation. + + Example: + Importing core utilities from the `appflow_tracer` library: + from packages.appflow_tracer.lib import log_utils, serialize_utils + + log_utils.log_message("Structured logging enabled") + json_data = serialize_utils.safe_serialize({"example": "data"}) DATA - __all__ = ['file_utils', 'log_utils', 'trace_utils', 'serialize_utils'... + __all__ = ['file_utils', 'log_utils', 'serialize_utils', 'trace_utils'... VERSION 0.1.0 diff --git a/docs/pydoc/packages/appflow_tracer/lib/file_utils.pydoc b/docs/pydoc/packages/appflow_tracer/lib/file_utils.pydoc index 4f5e74c..746a199 100644 --- a/docs/pydoc/packages/appflow_tracer/lib/file_utils.pydoc +++ b/docs/pydoc/packages/appflow_tracer/lib/file_utils.pydoc @@ -3,20 +3,71 @@ Help on module packages.appflow_tracer.lib.file_utils in packages.appflow_tracer.lib: NAME - packages.appflow_tracer.lib.file_utils - # File: ./packages/appflow_tracer/lib/file_utils.py + packages.appflow_tracer.lib.file_utils - File Path: ./packages/appflow_tracer/lib/file_utils.py + +DESCRIPTION + Description: + The file_utils.py module provides helper functions for managing log files, + resolving relative paths, and cleaning terminal output by removing ANSI escape codes. + + Core Features: + - **Log File Management**: Removes old logs to prevent excessive storage usage. + - **Project File Detection**: Verifies whether a file belongs to the project. + - **Path Resolution**: Converts absolute paths into project-relative paths. + - **ANSI Escape Code Removal**: Cleans formatted terminal output. + - **Module Execution**: Supports a main entry point for potential extensions. + + Usage: + To clean up old log files: + from file_utils import manage_logfiles + manage_logfiles(configs=CONFIGS) + + To check if a file belongs to the project: + from file_utils import is_project_file + is_project_file("scripts/devops-workflow.py") + + Dependencies: + - sys - Handles system interactions. + - re - Provides regex utilities for ANSI escape sequence removal. + - pathlib - Handles file system operations. + - lib.system_variables - Imports project-wide settings. + - lib.log_utils - Logs file management operations. + + Global Behavior: + - Log files are removed only when exceeding the maximum allowed limit. + - Project-relative paths exclude `.py` extensions for consistency. + - ANSI escape codes are removed without altering message content. + - The `main()` function serves as a placeholder for future extensions. + + CLI Integration: + This module is primarily used for internal utilities but can be executed directly. + + Example Execution: + ```python + from file_utils import relative_path + print(relative_path("/absolute/path/to/script.py")) + ``` + + Expected Behavior: + - Successfully manages log files without exceeding storage limits. + - Converts absolute paths to project-relative paths when applicable. + - Strips ANSI escape sequences while preserving readable content. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to file system or logging issues. FUNCTIONS is_project_file(filename: str) -> bool - Determine if a given file path belongs to the project directory structure. + Function: is_project_file(filename: str) -> bool + Description: + Determines if a given file path belongs to the project directory structure. - This function verifies whether the specified `filename` is located within - the project's root directory and is not an external dependency. - - Args: - filename (str): The absolute or relative file path to be checked. + Parameters: + - filename (str): The absolute or relative file path to be checked. Returns: - bool: True if the file is within the project directory, False otherwise. + - bool: True if the file is within the project directory, False otherwise. Example: >>> is_project_file("appflow_tracer/tracing.py") @@ -24,80 +75,86 @@ FUNCTIONS >>> is_project_file("/usr/lib/python3.8/external.py") False - Notes: - - If the filename is `None` or an empty string, the function returns `False`. - - The function safely resolves the absolute path before performing the check. + Behavior: + - Resolves the absolute path before performing the check. + - Returns False if the filename is None or an empty string. - manage_logfiles(configs: dict = None) -> list - Manage log file storage by removing old logs if the number exceeds a configured limit. + Error Handling: + - Gracefully handles unexpected inputs such as None or invalid paths. - This function prevents log directories from growing indefinitely by: - - Checking the current number of log files in each log subdirectory. - - Deleting the oldest logs **only if** the total count exceeds the allowed limit. + main() -> None - Args: - configs (dict, optional): Configuration dictionary that specifies: - - `"max_logfiles"`: Maximum number of log files to retain. - Defaults to `None`, in which case the global `max_logfiles` setting is used. + manage_logfiles(configs: dict = None) -> list + Function: manage_logfiles(configs: dict = None) -> list + Description: + Manages log file storage by removing old logs if the number exceeds a configured limit. - Raises: - OSError: If an error occurs while attempting to delete log files. + Parameters: + - configs (dict, optional): Configuration dictionary specifying: + - `"max_logfiles"`: Maximum number of log files to retain. + Defaults to the global `max_logfiles` setting if missing. Returns: - list: A list of deleted log file paths. + - list: A list of deleted log file paths. Workflow: - 1. Sorts log files by modification time (oldest first). - 2. Identifies files exceeding the limit. - 3. Deletes excess log files. + 1. Identifies log files in the configured directory. + 2. Sorts log files by modification time. + 3. Deletes excess log files if the count exceeds the threshold. 4. Logs deletions using `log_utils.log_message()`. Notes: - - The function ensures logging operations respect the `configs["logging"]["enable"]` flag. - - If no logs exceed the threshold, no deletions occur, and an empty list is returned. + - Ensures logging operations respect `configs["logging"]["enable"]`. + - If no logs exceed the threshold, returns an empty list. - relative_path(filepath: str) -> str - Convert an absolute file path into a project-relative path. + Error Handling: + - Catches `OSError` if a file cannot be deleted. + - Logs errors using `log_utils.log_message()`. - This function maps the given absolute path to the project’s directory structure. - If the file is outside the project, it returns the original path as a fallback. - The `.py` extension is removed from the resulting path for consistency. + relative_path(filepath: str) -> str + Function: relative_path(filepath: str) -> str + Description: + Converts an absolute file path into a project-relative path. - Args: - filepath (str): The absolute file path to convert. + Parameters: + - filepath (str): The absolute file path to convert. Returns: - str: The relative path within the project, or the original path if it - cannot be converted. + - str: The relative path within the project, or the original path if it + cannot be converted. Example: >>> relative_path("/path/to/project/module.py") "module" - Notes: - - If the file is not within the project directory, the original path is returned. - - The `.py` extension is removed for consistency in logging and output formatting. + Behavior: + - If the file is outside the project directory, returns the original path. + - Removes the `.py` extension for consistency. - remove_ansi_escape_codes(text: str) -> str - Remove ANSI escape sequences from a string. + Error Handling: + - If the path is not within the project, returns the original file name. - This function is used to clean up log messages or terminal output by - stripping out escape codes that produce colored or formatted text. - The resulting string contains only plain text. + remove_ansi_escape_codes(text: str) -> str + Function: remove_ansi_escape_codes(text: str) -> str + Description: + Removes ANSI escape sequences from a string. - Args: - text (str): The input string that may contain ANSI escape codes. + Parameters: + - text (str): The input string that may contain ANSI escape codes. Returns: - str: A new string with all ANSI escape codes removed. + - str: A new string with all ANSI escape codes removed. Example: - >>> remove_ansi_escape_codes("This is red text") + >>> remove_ansi_escape_codes("\x1b[31mThis is red text\x1b[0m") "This is red text" - Notes: - - ANSI escape codes are commonly used for terminal colorization. - - The function ensures that formatted messages remain readable. + Behavior: + - Strips ANSI escape codes while preserving readable content. + - Used for cleaning log messages or terminal output. + + Error Handling: + - Ensures that formatted messages remain readable without altering text. DATA category = namespace(calls=namespace(id='CALL', color='\x1b...'), rese... diff --git a/docs/pydoc/packages/appflow_tracer/lib/log_utils.pydoc b/docs/pydoc/packages/appflow_tracer/lib/log_utils.pydoc index 76eb6a3..c112344 100644 --- a/docs/pydoc/packages/appflow_tracer/lib/log_utils.pydoc +++ b/docs/pydoc/packages/appflow_tracer/lib/log_utils.pydoc @@ -3,7 +3,59 @@ Help on module packages.appflow_tracer.lib.log_utils in packages.appflow_tracer.lib: NAME - packages.appflow_tracer.lib.log_utils - # File: ./packages/appflow_tracer/lib/log_utils.py + packages.appflow_tracer.lib.log_utils - File Path: ./packages/appflow_tracer/lib/log_utils.py + +DESCRIPTION + Description: + The log_utils.py module provides structured logging utilities for handling + console and file-based logging. It ensures formatted, categorized logs with + support for custom levels, structured data, and ANSI-colored output. + + Core Features: + - **Structured Log Messages**: Formats logs in a consistent manner. + - **Console and File Logging**: Sends logs to both the console and log files. + - **Custom Log Levels**: Supports INFO, WARNING, ERROR, DEBUG, etc. + - **ANSI Color Support**: Enables colored output for terminal logs. + - **JSON Data Logging**: Logs structured JSON data when required. + + Usage: + To log a structured message: + from log_utils import log_message + log_message("System initialized", category.info.id, json_data={"status": "ready"}) + + To log a warning message: + log_message("Configuration file missing", category.warning.id) + + Dependencies: + - sys - Handles system interactions. + - json - Enables structured JSON-based logging. + - logging - Provides core logging functionalities. + - datetime - Manages log timestamps. + - lib.system_variables - Loads global configuration settings. + + Global Behavior: + - Logs messages to both console and files based on configuration settings. + - Maps log categories to appropriate logging levels (INFO, DEBUG, ERROR, etc.). + - Ensures JSON data is formatted properly if included in log messages. + - Supports disabling console logs while retaining file-based logs. + + CLI Integration: + This module primarily serves as an internal utility but can be extended. + + Example Execution: + ```python + from log_utils import log_message + log_message("Initialization complete", category.info.id) + ``` + + Expected Behavior: + - Ensures that logging configurations determine output destinations. + - Formats log messages consistently with timestamps and levels. + - Applies ANSI color formatting to enhance log visibility in terminals. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to logging configuration issues. FUNCTIONS log_message( @@ -14,28 +66,31 @@ FUNCTIONS configs: dict = None, handler: logging.Logger = None ) -> None - Log a structured message with optional JSON data to both console and log files. - - This function supports multiple log levels, formats messages in a structured manner, - and appends additional structured JSON data if provided. The behavior is influenced - by global configurations, such as whether logs should be written to a file or displayed - on the console. - - Args: - message (str): The main log message. - log_category (str, optional): The log level/log_category. e.g.: - category.info.id, category.warning.id, category.error.id but defaults to category.info.id. - json_data (dict, optional): Additional structured JSON data to log. - serialize_json (bool, optional): If True, the `json_data` is serialized into a JSON string. - configs (dict, optional): Configuration dictionary. Defaults to global `CONFIGS` if not provided. - handler (logging.Logger, optional): The specific logger instance to use. Defaults to the global logger. + Function: log_message( + message: str, + log_category: str = "INFO", + json_data: dict = None, + serialize_json: bool = False, + configs: dict = None, + handler: logging.Logger = None + ) -> None + Description: + Logs a structured message with optional JSON data to both console and log files. + + Parameters: + - message (str): The main log message. + - log_category (str, optional): The log level/category (e.g., category.info.id, category.warning.id). + - json_data (dict, optional): Additional structured JSON data to log. + - serialize_json (bool, optional): If True, serializes `json_data` into a JSON string. + - configs (dict, optional): Configuration dictionary. Defaults to global `CONFIGS` if not provided. + - handler (logging.Logger, optional): The specific logger instance to use. Raises: - KeyError: If the log category provided is invalid. - TypeError: If `json_data` is not a dictionary when `serialize_json` is True. + - KeyError: If the provided log category is invalid. + - TypeError: If `json_data` is not a dictionary when `serialize_json` is True. Returns: - None + - None Workflow: 1. Determines the correct log level based on `log_category`. @@ -44,9 +99,11 @@ FUNCTIONS 4. Displays the message in the console if tracing is enabled. Example: - >>> log_message("This is an info message") - >>> log_message("This is a warning", category.warning.id) - >>> log_message("Structured log", json_data={"key": "value"}) + >>> log_message("System initialized", category.info.id) + >>> log_message("Missing config", category.warning.id) + >>> log_message("Debug details", json_data={"module": "log_utils"}) + + main() -> None output_console( message: str, @@ -54,25 +111,27 @@ FUNCTIONS json_data: dict = None, configs: dict = None ) -> None - Display a structured log message in the console with optional ANSI color formatting. - - This function formats the given message according to the specified logging log-category - and appends structured JSON data if provided. ANSI color codes are applied based on - the logging configuration. - - Args: - message (str): The main message to display. - log_category (str): The logging log_category. e.g.: - category.info.id, category.warning.id, category.error.id - json_data (dict, optional): Additional structured JSON data for output. - configs (dict, optional): Configuration dictionary for colors and formatting. + Function: output_console( + message: str, + log_category: str, + json_data: dict = None, + configs: dict = None + ) -> None + Description: + Displays a structured log message in the console with optional ANSI color formatting. + + Parameters: + - message (str): The main message to display. + - log_category (str): The logging category (e.g., category.info.id, category.error.id). + - json_data (dict, optional): Additional structured JSON data for output. + - configs (dict, optional): Configuration dictionary for colors and formatting. Raises: - KeyError: If an invalid log category is provided. - TypeError: If `json_data` is not a dictionary. + - KeyError: If an invalid log category is provided. + - TypeError: If `json_data` is not a dictionary. Returns: - None + - None Workflow: 1. Determines the ANSI color for the log category. @@ -81,8 +140,8 @@ FUNCTIONS 4. Displays structured JSON data if provided. Example: - >>> output_console("This is an info message", category.info.id) - >>> output_console("This is a warning", category.warning.id, {"details": "some data"}) + >>> output_console("Service started", category.info.id) + >>> output_console("Config warning", category.warning.id, {"path": "/etc/config"}) output_logfile( logger: logging.Logger, @@ -90,23 +149,26 @@ FUNCTIONS log_category: str = 'INFO', json_data: dict = None ) -> None - Write a structured log message to a log file. - - This function appends the formatted log message to a log file associated with the - given logger. If structured data (`json_data`) is provided, it is included in the - log entry. - - Args: - logger (logging.Logger): The logger instance used for writing logs. - message (str): The log message text. - log_category (str, optional): The log level/log_category. Defaults to "INFO". - json_data (dict, optional): Additional structured JSON data for the log entry. + Function: output_logfile( + logger: logging.Logger, + message: str, + log_category: str = "INFO", + json_data: dict = None + ) -> None + Description: + Writes a structured log message to a designated log file. + + Parameters: + - logger (logging.Logger): The logger instance used for writing logs. + - message (str): The log message text. + - log_category (str, optional): The log level/category (defaults to "INFO"). + - json_data (dict, optional): Additional structured JSON data for the log entry. Raises: - OSError: If the log file cannot be accessed or written to. + - OSError: If the log file cannot be accessed or written to. Returns: - None + - None Workflow: 1. Formats the log message with category and timestamp. @@ -114,8 +176,8 @@ FUNCTIONS 3. Writes the log entry to the designated log file. Example: - >>> logger = logging.getLogger("example_logger") - >>> output_logfile(logger, "This is a log message", {"extra_key": "value"}) + >>> logger = logging.getLogger("app_logger") + >>> output_logfile(logger, "This is a log message", category.debug.id) DATA category = namespace(calls=namespace(id='CALL', color='\x1b...'), rese... diff --git a/docs/pydoc/packages/appflow_tracer/lib/serialize_utils.pydoc b/docs/pydoc/packages/appflow_tracer/lib/serialize_utils.pydoc index 5466a58..26c92c0 100644 --- a/docs/pydoc/packages/appflow_tracer/lib/serialize_utils.pydoc +++ b/docs/pydoc/packages/appflow_tracer/lib/serialize_utils.pydoc @@ -3,40 +3,84 @@ Help on module packages.appflow_tracer.lib.serialize_utils in packages.appflow_tracer.lib: NAME - packages.appflow_tracer.lib.serialize_utils - # File: ./packages/appflow_tracer/lib/serialize_utils.py + packages.appflow_tracer.lib.serialize_utils - File Path: ./packages/appflow_tracer/lib/serialize_utils.py + +DESCRIPTION + Description: + The serialize_utils.py module provides functions for data serialization + and code sanitization, ensuring JSON compatibility and clean parsing. + + Core Features: + - **Safe Serialization**: Converts Python objects to JSON-friendly formats. + - **String Sanitization**: Cleans and trims code strings while removing comments. + - **Structured Logging Integration**: Logs serialization results using `log_utils`. + + Usage: + To safely serialize a Python object: + from serialize_utils import safe_serialize + result = safe_serialize({"key": "value"}, configs=CONFIGS) + + To remove comments from a line of code: + from serialize_utils import sanitize_token_string + clean_code = sanitize_token_string("some_code() # remove this comment") + + Dependencies: + - json - Enables structured JSON serialization. + - tokenize - Tokenizes code for proper comment removal. + - io.StringIO - Handles text processing for tokenization. + - lib.system_variables - Provides project-wide settings. + - log_utils - Supports structured logging of serialization operations. + + Global Behavior: + - `safe_serialize()` gracefully handles non-serializable objects. + - `sanitize_token_string()` removes comments while preserving meaningful text. + - Ensures logging is handled based on provided configurations. + + Expected Behavior: + - Logs structured serialization results when enabled. + - JSON serialization avoids breaking due to unserializable objects. + - Comments are correctly stripped without altering the main code structure. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to serialization or parsing errors. FUNCTIONS + main() -> None + safe_serialize( data: , configs: dict, verbose: bool = False ) -> dict - Convert Python objects into a JSON-compatible serialized string with metadata. - - This function ensures that data is properly serialized into a JSON string format. - If an object is not serializable, it attempts to extract its attributes or provide - meaningful information instead of just a memory address. - - Args: - data (any): The Python object to serialize. - configs (dict): Configuration dictionary for logging and debugging. - verbose (bool, optional): If True, the JSON output is formatted with indentation. + Function: safe_serialize( + data: any, + configs: dict, + verbose: bool = False + ) -> dict + Description: + Converts Python objects into a JSON-compatible format with metadata. + + Parameters: + - data (any): The Python object to serialize. + - configs (dict): Configuration dictionary for logging and debugging. + - verbose (bool, optional): If True, formats JSON output with indentation. Raises: - TypeError: If the provided data is not serializable. - ValueError: If there is an issue converting data to JSON. + - TypeError: If the provided data is not serializable. + - ValueError: If there is an issue converting data to JSON. Returns: - dict: A structured response containing serialization results. - - `success` (bool): Whether serialization was successful. + - dict: A structured response containing serialization results: + - `success` (bool): Indicates if serialization was successful. - `serialized` (str): JSON string of serialized data or an error message. - `type` (str): The type of the original object. - `error` (str, optional): Error message if serialization failed. Workflow: 1. Attempts to serialize the input data using `json.dumps()`. - 2. If serialization fails, checks if the object has attributes (`__dict__`). - 3. If the object is iterable (list, tuple, set), converts it into a list. + 2. If serialization fails, checks for attributes (`__dict__`) and serializes them. + 3. If the object is iterable, converts it into a list. 4. Returns a structured response indicating success or failure. Example: @@ -47,20 +91,18 @@ FUNCTIONS {'success': False, 'serialized': '[Unserializable data]', 'type': 'object', 'error': 'TypeError'} sanitize_token_string(line: str) -> str - Remove trailing comments and excess whitespace from a line of code. - - This function processes a line of code and removes inline comments while preserving - meaningful text. The result is a clean line of code without unnecessary annotations. + Function: sanitize_token_string(line: str) -> str + Description: + Removes trailing comments and excess whitespace from a line of code. - Args: - line (str): A single line of text that may contain comments and extra spaces. + Parameters: + - line (str): A single line of text that may contain comments and extra spaces. Raises: - Exception: If an unexpected error occurs while parsing tokens. + - Exception: If an unexpected error occurs while parsing tokens. Returns: - str: The sanitized version of the input line, with comments and - unnecessary whitespace removed. + - str: The sanitized version of the input line with comments removed. Workflow: 1. Tokenizes the input string using Python's `tokenize` module. diff --git a/docs/pydoc/packages/appflow_tracer/lib/trace_utils.pydoc b/docs/pydoc/packages/appflow_tracer/lib/trace_utils.pydoc index c0b61ad..3ab383c 100644 --- a/docs/pydoc/packages/appflow_tracer/lib/trace_utils.pydoc +++ b/docs/pydoc/packages/appflow_tracer/lib/trace_utils.pydoc @@ -3,7 +3,55 @@ Help on module packages.appflow_tracer.lib.trace_utils in packages.appflow_tracer.lib: NAME - packages.appflow_tracer.lib.trace_utils - # File: ./packages/appflow_tracer/lib/trace_utils.py + packages.appflow_tracer.lib.trace_utils - File Path: ./packages/appflow_tracer/lib/trace_utils.py + +DESCRIPTION + Description: + Function Call and Execution Flow Tracing Utilities + This module provides **real-time function execution tracing** within the framework. + It captures **function calls and return values**, logs structured execution flow, + and ensures debugging visibility with minimal performance overhead. + + Core Features: + - **Function Call Tracing**: Logs function calls, arguments, and execution order. + - **Execution Flow Logging**: Captures return values and structured execution flow. + - **Project Scope Enforcement**: Excludes system functions and external dependencies. + - **Selective Filtering**: Ignores known logging utilities and non-essential functions. + - **Configurable Logging**: Enables logging dynamically based on configuration settings. + + Usage: + To enable tracing and track function calls: + import trace_utils + trace_utils.start_tracing() + + Dependencies: + - sys - Provides system-level tracing hooks. + - json - Enables structured JSON serialization for tracing. + - inspect - Extracts function metadata dynamically. + - logging - Supports structured execution logging. + - lib.system_variables - Provides logging categories. + - lib.log_utils - Manages structured logging output. + - lib.file_utils - Validates project file paths. + - lib.serialize_utils - Handles safe data serialization. + + Global Behavior: + - Tracing activates only when **enabled in the configuration**. + - Calls, returns, and execution paths are **logged dynamically**. + - Non-project files and system-level operations are **excluded from tracing**. + - Return values are **serialized safely** for structured logging. + + Expected Behavior: + - Tracing logs execution flow without excessive system-level noise. + - Only functions within the **project scope** are traced. + - Function return values are safely **serialized for debugging**. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to configuration issues or execution tracing errors. + + Example: + from trace_utils import start_tracing + start_tracing() FUNCTIONS call_events( @@ -13,22 +61,35 @@ FUNCTIONS arg: object, configs: dict ) -> None - Handles logging of function call events. + Function: call_events( + logger: logging.Logger, + frame: FrameType, + filename: str, + arg: object, + configs: dict + ) -> None + Description: + Handles logging of function call events. + + Parameters: + - logger (logging.Logger): Logger for structured execution. + - frame (FrameType): Execution frame at the function call site. + - filename (str): The file where the function call originated. + - arg (object): Arguments passed to the function. + - configs (dict): Configuration settings. - This function: - - **Extracts caller details** including filename and function name. - - **Logs function invocation metadata** such as arguments and execution flow. - - **Filters out system and non-project calls** to keep logs relevant. + Returns: + - None - Args: - logger (logging.Logger): Logger instance for logging structured execution. - frame (FrameType): The execution frame where the function call occurred. - filename (str): The source file where the function call was invoked. - arg (object): The arguments passed to the function. - configs (dict): The configuration dictionary. + Workflow: + 1. Extracts caller function details. + 2. Logs function execution metadata, including arguments. + 3. Filters out system and external function calls. - Returns: - None + Example: + >>> call_events(logger, frame, "file.py", args, configs) + + main() -> None return_events( logger: logging.Logger, @@ -37,66 +98,87 @@ FUNCTIONS arg: object, configs: dict ) -> None - Handles logging of function return events. + Function: return_events( + logger: logging.Logger, + frame: FrameType, + filename: str, + arg: object, + configs: dict + ) -> None + Description: + Handles logging of function return events. + + Parameters: + - logger (logging.Logger): Logger for structured execution. + - frame (FrameType): Execution frame at the function return site. + - filename (str): The file where the return event occurred. + - arg (object): The function's return value. + - configs (dict): Configuration settings. - This function: - - **Captures return values** including their data type. - - **Serializes complex return values** for structured logging. - - **Logs execution flow and prevents excessive logging** for system functions. + Returns: + - None - Args: - logger (logging.Logger): Logger instance for logging structured execution. - frame (FrameType): The execution frame where the function return occurred. - filename (str): The source file where the return event occurred. - arg (object): The function's return value. - configs (dict): The configuration dictionary. + Workflow: + 1. Captures return values and execution flow. + 2. Serializes return data for structured debugging. + 3. Filters out system-level returns to avoid excessive logs. - Returns: - None + Example: + >>> return_events(logger, frame, "file.py", return_value, configs) start_tracing(logger: logging.Logger = None, configs: dict = None) -> None - Initialize and activate function call tracing. - - This function sets up **function execution tracing**, ensuring: - - **Function call and return events** are logged in a structured manner. - - **Only project-specific files** are traced, excluding system libraries. - - **Logging is enabled dynamically** based on the provided configuration. + Function: start_tracing( + logger: logging.Logger = None, + configs: dict = None + ) -> None + Description: + Initializes function execution tracing. - Args: - logger (logging.Logger, optional): Logger instance for structured logging. If None, a default logger is used. - configs (dict, optional): A dictionary containing tracing configurations. If None, the global CONFIGS will be used. + Parameters: + - logger (logging.Logger, optional): Logger instance for structured logging. Defaults to None. + - configs (dict, optional): Configuration dictionary controlling tracing behavior. Raises: - RuntimeError: If tracing fails due to invalid configurations. + - RuntimeError: If tracing fails due to invalid configurations. Returns: - None + - None + + Workflow: + 1. Sets up function tracing based on configuration. + 2. Ensures logging is enabled before activating tracing. + 3. Calls `trace_all()` to generate a trace handler. Example: >>> start_tracing() - # Tracing begins using the global configuration. + # Tracing starts using the global configuration. trace_all(logger: logging.Logger, configs: dict) -> Callable - Generate a function that traces execution flow within project-specific files. + Function: trace_all( + logger: logging.Logger, + configs: dict + ) -> Callable + Description: + Generates a function that traces execution flow within project-specific files. - This function returns a **callable trace handler** that: - - **Logs function calls and returns**, including caller context. - - **Ensures logging is project-restricted**, excluding non-project dependencies. - - **Filters system function calls and internal logging utilities.** - - Args: - logger (logging.Logger): Logger instance for structured logging. - configs (dict): The configuration dictionary that controls tracing behavior. + Parameters: + - logger (logging.Logger): Logger instance for structured logging. + - configs (dict): Configuration dictionary controlling tracing behavior. Raises: - ValueError: If tracing configurations are missing or invalid. + - ValueError: If tracing configurations are missing or invalid. Returns: - Callable: A trace function that can be passed to `sys.settrace()`. + - Callable: A trace function that can be passed to `sys.settrace()`. + + Workflow: + 1. Ensures tracing configurations are valid. + 2. Defines `trace_events()` to handle function call and return tracing. + 3. Returns the trace handler function. Example: >>> sys.settrace(trace_all(logger, configs)) - # Tracing starts using the provided configuration. + # Function tracing begins dynamically. DATA Callable = typing.Callable diff --git a/docs/pydoc/packages/appflow_tracer/tracing.pydoc b/docs/pydoc/packages/appflow_tracer/tracing.pydoc index 9db0fda..3961b5a 100644 --- a/docs/pydoc/packages/appflow_tracer/tracing.pydoc +++ b/docs/pydoc/packages/appflow_tracer/tracing.pydoc @@ -3,7 +3,117 @@ Help on module packages.appflow_tracer.tracing in packages.appflow_tracer: NAME - packages.appflow_tracer.tracing - # File: ./packages/appflow_tracer/tracing.py + packages.appflow_tracer.tracing - File Path: packages/appflow_tracer/tracing.py + +DESCRIPTION + Description: + AppFlow Tracing System + This module provides structured logging and function call tracing, enabling + automatic function execution monitoring with minimal intrusion. It integrates + logging and tracing functionalities, ensuring accurate tracking of function + calls, return values, and execution flow. + + Core Features: + - **Function Call Tracing**: Automatically captures function calls, arguments, and return values. + - **Structured Logging**: Logs execution details in JSON format for debugging and auditing. + - **Self-Inspection**: When executed directly, logs its own execution for analysis. + - **Automatic Log Management**: Removes old log files to maintain storage efficiency. + - **Configurable Event Filtering**: Allows selective tracing of function calls and returns. + - **Console and File Logging**: Captures print statements and ensures logs do not contain ANSI escape sequences. + + Usage: + To enable function call tracing: + import tracing + tracing.setup_logging() + + To run the tracing system as a standalone tool: + python tracing.py + + Dependencies: + - `sys` - Provides system-level operations, including path management. + - `json` - Enables structured logging in JSON format. + - `inspect` - Used for function introspection and execution tracing. + - `logging` - Handles structured logging and message formatting. + - `builtins` - Overrides `print` statements for structured logging. + - `pathlib.Path` - Resolves file and directory paths dynamically. + - `datetime` - Used for timestamping and log file management. + - `lib.system_variables` - Provides global project-wide configurations. + - `lib.pkgconfig_loader` - Loads and manages logging and tracing configurations. + - `lib.file_utils` - Handles log file cleanup and path resolution. + - `lib.log_utils` - Provides structured logging utilities. + - `lib.trace_utils` - Implements function call tracing and execution flow monitoring. + + Global Variables: + - `LOGGING` (bool): Flag indicating whether logging has been initialized. + - `CONFIGS` (dict): Stores the effective logging and tracing configurations. + - `logger` (logging.Logger): Global logger instance used for structured logging. + + Primary Functions: + - `setup_logging(configs, logname_override, events)`: Initializes structured logging. + - `main()`: Entry point for standalone execution, setting up tracing and logging. + - `PrintCapture.emit(record)`: Captures print statements and redirects them to logs. + - `ANSIFileHandler.emit(record)`: Ensures log files do not contain ANSI escape sequences. + + Expected Behavior: + - Logs execution details when tracing is enabled. + - Logs function calls with arguments and return values. + - Maintains structured logs for debugging and execution tracking. + - Automatically removes older log files when exceeding retention limits. + + Exit Codes: + - `0`: Successful execution. + - `1`: Failure due to configuration or logging setup errors. + + Example: + Importing the tracing system and enabling structured logging: + from tracing import setup_logging + setup_logging() + + class PrintCapture(logging.StreamHandler): + + Custom logging handler that captures print statements and logs them + while ensuring they are displayed in the console. + + This ensures that print statements are properly logged without affecting + real-time console output. + + def emit(self, record: logging.LogRecord) -> None: + + Custom logging handler that captures print statements and logs them + while ensuring they are displayed in the console. + + This ensures that print statements are properly logged without affecting + real-time console output. + + Args: + record (logging.LogRecord): The log record that contains information + about the log message to be captured and displayed. + + Returns: + None + + class ANSIFileHandler(logging.FileHandler): + + Custom FileHandler that removes ANSI codes from log output + and filters out logs from the internal Python logging module. + + This prevents unnecessary ANSI escape codes from appearing in log files + and ensures only relevant logs are recorded. + + def emit(self, record: logging.LogRecord) -> None: + + Custom FileHandler that removes ANSI codes from log output + and filters out logs from the internal Python logging module. + + This prevents unnecessary ANSI escape codes from appearing in log files + and ensures only relevant logs are recorded. + + Args: + record (logging.LogRecord): The log record to be emitted, including + log message and additional context for filtering. + + Returns: + None CLASSES logging.FileHandler(logging.StreamHandler) @@ -14,12 +124,6 @@ CLASSES class ANSIFileHandler(logging.FileHandler) | ANSIFileHandler(filename, mode='a', encoding=None, delay=False, errors=None) | - | Custom FileHandler that removes ANSI codes from log output - | and filters out logs from the internal Python logging module. - | - | This prevents unnecessary ANSI escape codes from appearing in log files - | and ensures only relevant logs are recorded. - | | Method resolution order: | ANSIFileHandler | logging.FileHandler @@ -31,18 +135,13 @@ CLASSES | Methods defined here: | | emit(self, record: logging.LogRecord) -> None - | Custom FileHandler that removes ANSI codes from log output - | and filters out logs from the internal Python logging module. - | - | This prevents unnecessary ANSI escape codes from appearing in log files - | and ensures only relevant logs are recorded. + | Emit a record. | - | Args: - | record (logging.LogRecord): The log record to be emitted, including - | log message and additional context for filtering. + | If the stream was not opened because 'delay' was specified in the + | constructor, open it before calling the superclass's emit. | - | Returns: - | None + | If stream is not open, current mode is 'w' and `_closed=True`, record + | will not be emitted (see Issue #42378). | | ---------------------------------------------------------------------- | Methods inherited from logging.FileHandler: @@ -181,12 +280,6 @@ CLASSES class PrintCapture(logging.StreamHandler) | PrintCapture(stream=None) | - | Custom logging handler that captures print statements and logs them - | while ensuring they are displayed in the console. - | - | This ensures that print statements are properly logged without affecting - | real-time console output. - | | Method resolution order: | PrintCapture | logging.StreamHandler @@ -197,18 +290,14 @@ CLASSES | Methods defined here: | | emit(self, record: logging.LogRecord) -> None - | Custom logging handler that captures print statements and logs them - | while ensuring they are displayed in the console. - | - | This ensures that print statements are properly logged without affecting - | real-time console output. - | - | Args: - | record (logging.LogRecord): The log record that contains information - | about the log message to be captured and displayed. + | Emit a record. | - | Returns: - | None + | If a formatter is specified, it is used to format the record. + | The record is then written to the stream with a trailing newline. If + | exception information is present, it is formatted using + | traceback.print_exception and appended to the stream. If the stream + | has an 'encoding' attribute, it is used to determine how to do the + | output to the stream. | | ---------------------------------------------------------------------- | Methods inherited from logging.StreamHandler: @@ -371,39 +460,22 @@ FUNCTIONS logname_override: Optional[str] = None, events: Union[bool, dict, NoneType] = None ) -> Union[bool, dict] - Configures and initializes the global logging system. + Configures and initializes structured logging for the framework. - This function sets up the logging environment, creating log files and adding handlers - for both file-based and console-based logging. It ensures proper logging behavior - even when no configuration is provided. + This function sets up logging with file and console handlers, ensuring structured + log output. It integrates function call tracing and manages log file retention. Args: - configs (dict, optional): A dictionary containing logging configurations. - If None, the default global configurations are used. - logname_override (str, optional): A custom name for the log file. - If None, the log file name is derived from the calling script. - events (bool, list, or dict, optional): - - `None` / `False` → Disables all event logging. - - `True` → Enables all event logging. - - `list` → Enables only specified events (e.g., ["call", "return"]). - - `dict` → Enables/disables events per user settings (e.g., {"call": True, "return": False}). - - Raises: - ValueError: If the provided logging configurations are not in a dictionary format. + configs (dict, optional): Logging configuration dictionary. + logname_override (str, optional): Custom log file name. + events (bool, list, dict, optional): Controls which events are logged. Returns: - dict: The effective logging configuration after applying defaults. + dict: The effective logging configuration. Example: - >>> setup_logging() - { - "logging": { - "log_filename": "/path/to/logfile.log", - "max_logfiles": 5, - ... - }, - ... - } + >>> from packages.appflow_tracer import setup_logging + >>> CONFIGS = setup_logging() DATA CONFIGS = None diff --git a/docs/pydoc/packages/requirements/__init__.pydoc b/docs/pydoc/packages/requirements/__init__.pydoc index 8b882b5..d718836 100644 --- a/docs/pydoc/packages/requirements/__init__.pydoc +++ b/docs/pydoc/packages/requirements/__init__.pydoc @@ -3,52 +3,59 @@ Help on module packages.requirements.__init__ in packages.requirements: NAME - packages.requirements.__init__ - # File: ./packages/requirements/__init__.py + packages.requirements.__init__ - File Path: packages/requirements/__init__.py -FUNCTIONS - main() -> None - Entry point for the dependency management system. +DESCRIPTION + Description: + This file initializes the `requirements` package, ensuring it is correctly recognized + as a Python package. It provides an entry point for dependency management by exposing + the `main` function from `dependencies.py`. - This function initializes logging, processes command-line arguments, - and installs or updates dependencies from a JSON requirements file. - It dynamically determines the system's Python environment and applies - installation policies accordingly. + Core Features: + - **Package Initialization**: + - Marks `requirements/` as a valid Python package. + - Ensures explicit module control, preventing unintended imports. + - **Dependency Management**: + - Exposes `main()` from `dependencies.py` for managing package installations. + - Facilitates structured and policy-driven dependency handling. - ## Workflow: - 1. **Parse Command-Line Arguments** - - Loads configuration settings. - - Determines runtime settings. + Usage: + Importing and executing dependency management: - 2. **Load Requirements File** - - Reads `requirements.json` (or custom-specified file). - - Extracts dependency data. + from packages.requirements import main + main() - 3. **Setup Logging & Environment** - - Detects Python installation method. - - Logs detected system information. + Example execution: + python -m packages.requirements - 4. **Handle Backup & Restore Operations** - - Saves a package list for future restoration. - - Restores or migrates package environments if specified. + Dependencies: + - dependencies.py (Handles package dependency management) - 5. **Determine Dependency Policies** - - Calls `policy_utils.policy_management()` to enforce package rules. + Expected Behavior: + - The package remains passive until explicitly invoked. + - Calling `main()` triggers the dependency installation process. + - No automatic execution occurs upon import. - 6. **Install Dependencies** - - Uses `package_utils.install_requirements()` for installations. + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to dependency issues, missing configurations, or package errors. - 7. **Display Installed Packages (if requested)** - - Shows structured package information from `installed.json`. +FUNCTIONS + main() -> None + Function: main() -> None + Description: + Entry point for the dependency management system. - ## Args: - - `None` + Parameters: + - None - ## Returns: - - `None`: This function performs actions based on command-line arguments and manages dependencies. + Returns: + - None: Executes dependency installation and policy enforcement. - ## Notes: - - If an error occurs (e.g., missing `requirements.json`), the process will exit with `sys.exit(1)`. - - The function prevents breaking system-managed environments unless explicitly overridden (`--force`). + Behavior: + - Reads and processes package requirements from `requirements.json`. + - Installs, upgrades, or downgrades dependencies based on policies. + - Logs package operations for debugging and compliance tracking. DATA __all__ = ['main'] diff --git a/docs/pydoc/packages/requirements/__main__.pydoc b/docs/pydoc/packages/requirements/__main__.pydoc index 298409c..bb3a9b2 100644 --- a/docs/pydoc/packages/requirements/__main__.pydoc +++ b/docs/pydoc/packages/requirements/__main__.pydoc @@ -3,7 +3,44 @@ Help on module packages.requirements.__main__ in packages.requirements: NAME - packages.requirements.__main__ - # File: ./packages/requirements/__main__.py + packages.requirements.__main__ - File Path: packages/requirements/__main__.py + +DESCRIPTION + Description: + This file serves as the execution entry point for the `requirements` package when run + in standalone mode. It initializes and runs the dependency management system by calling + the `main()` function from `dependencies.py`. + + Core Features: + - **Standalone Execution**: + - Enables `python -m packages.requirements` execution. + - Allows the package to be run independently without direct imports. + - **Dependency Management**: + - Calls `main()` from `dependencies.py` to handle package installations. + - Applies structured package policies for controlled dependency enforcement. + - **Modular Design**: + - Supports both standalone execution and direct function imports. + + Usage: + To execute the `requirements` package as a standalone script: + + python -m packages.requirements + + Example execution: + + python -m packages.requirements + + Dependencies: + - dependencies.py (Handles package dependency management) + + Expected Behavior: + - When run as a module, it triggers dependency management automatically. + - Ensures dependencies are installed or updated based on predefined policies. + - Logs all package operations for debugging and compliance tracking. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to dependency issues, missing configurations, or package errors. VERSION 0.1.0 diff --git a/docs/pydoc/packages/requirements/dependencies.pydoc b/docs/pydoc/packages/requirements/dependencies.pydoc index 4ceca9e..1287010 100644 --- a/docs/pydoc/packages/requirements/dependencies.pydoc +++ b/docs/pydoc/packages/requirements/dependencies.pydoc @@ -3,79 +3,113 @@ Help on module packages.requirements.dependencies in packages.requirements: NAME - packages.requirements.dependencies - # File: ./packages/requirements/dependencies.py + packages.requirements.dependencies - File Path: ./packages/requirements/dependencies.py + +DESCRIPTION + Description: + The dependencies.py module is the core of the AppFlow Tracer - Dependency Management System, + providing structured and policy-driven package management. It integrates Homebrew (macOS) + and Pip (cross-platform) to ensure compliance with package versioning, + safe installations, and structured logging. + + Core Features: + - Environment Detection: Determines Python installation method (Homebrew, system-managed, or standalone). + - Package Management: Handles installation, upgrades, downgrades, and policy enforcement. + - Brew & Pip Integration: + - Uses Homebrew if Python is managed via Brew. + - Uses Pip for all other installations with controlled system package handling. + - Policy-Based Installation: + - Installs missing dependencies. + - Upgrades outdated packages if policy allows. + - Downgrades packages if strict versioning is required. + - Logging & Debugging: + - Captures package operations, warnings, and errors. + - Provides structured debugging messages. + - Backup & Restore: + - Saves the current package list for future restoration. + - Supports migration of package environments. + - Package Status Reporting: + - Displays installed dependencies, versions, and compliance details. + - Outputs structured reports to installed.json. + + Usage: + Parsing Command-Line Arguments: + from packages.requirements.dependencies import parse_arguments + args = parse_arguments() + + Installing Dependencies: + from packages.requirements.dependencies import main + main() + + Dependencies: + - sys - Manages system paths and process control. + - subprocess - Runs Homebrew and Pip commands. + - json - Handles structured storage of dependency data. + - pathlib - Ensures safe file path handling. + - functools - Optimizes frequently accessed functions with caching. + - argparse - Parses command-line arguments. + - platform - Detects system platform details. + - importlib.metadata - Retrieves installed package versions. + - brew_utils, package_utils, policy_utils, version_utils - Sub-modules managing dependency operations. + + Sub-Modules: + - brew_utils.py: Detects Homebrew availability and retrieves package versions. + - package_utils.py: Handles dependency installation using Brew or Pip. + - policy_utils.py: Enforces policy-driven installation, upgrades, and downgrades. + - version_utils.py: Fetches installed and latest package versions across multiple package managers. + + Expected Behavior: + - Dynamically adapts package installation based on system constraints. + - Installs, upgrades, or downgrades dependencies per predefined policies. + - Logs all package operations for debugging. + - Prevents unintended system modifications unless explicitly overridden (--force). + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to installation errors, missing configurations, or dependency issues. FUNCTIONS main() -> None - Entry point for the dependency management system. + Function: main() -> None + Description: + Entry point for the dependency management system. - This function initializes logging, processes command-line arguments, - and installs or updates dependencies from a JSON requirements file. - It dynamically determines the system's Python environment and applies - installation policies accordingly. + Parameters: + - None - ## Workflow: - 1. **Parse Command-Line Arguments** - - Loads configuration settings. - - Determines runtime settings. - - 2. **Load Requirements File** - - Reads `requirements.json` (or custom-specified file). - - Extracts dependency data. - - 3. **Setup Logging & Environment** - - Detects Python installation method. - - Logs detected system information. - - 4. **Handle Backup & Restore Operations** - - Saves a package list for future restoration. - - Restores or migrates package environments if specified. - - 5. **Determine Dependency Policies** - - Calls `policy_utils.policy_management()` to enforce package rules. - - 6. **Install Dependencies** - - Uses `package_utils.install_requirements()` for installations. - - 7. **Display Installed Packages (if requested)** - - Shows structured package information from `installed.json`. - - ## Args: - - `None` - - ## Returns: - - `None`: This function performs actions based on command-line arguments and manages dependencies. + Returns: + - None: Executes dependency installation and policy enforcement. - ## Notes: - - If an error occurs (e.g., missing `requirements.json`), the process will exit with `sys.exit(1)`. - - The function prevents breaking system-managed environments unless explicitly overridden (`--force`). + Behavior: + - Reads and processes package requirements from `requirements.json`. + - Installs, upgrades, or downgrades dependencies based on policies. + - Logs package operations for debugging and compliance tracking. parse_arguments() -> argparse.Namespace - Parse command-line arguments for package management. - - This function provides command-line options for managing dependencies, - allowing users to specify requirement files, enforce installations, - backup, restore, or migrate packages. - - ## Supported Arguments: - - `-c/--config`: Specify a custom JSON requirements file. - - `-f/--force`: Force Pip installations using `--break-system-packages`. - - `--backup-packages`: Save installed package list for future restoration. - - `--restore-packages`: Restore packages from a backup file. - - `--migrate-packages`: Migrate package environments. - - `--show-installed`: Display installed dependencies. - - ## Args: - - `None` + Function: parse_arguments() -> argparse.Namespace + Description: + Parses command-line arguments for package management, allowing users to define requirement files, enforce installations, + backup, restore, or migrate packages. Returns: - - `argparse.Namespace`: The parsed arguments object containing selected options. + - argparse.Namespace: Parsed arguments object containing selected options. + + Behavior: + - Supports JSON configuration for package management. + - Allows forcing installations with --force. + - Supports backup, restore, and migration of package environments. + - Enables listing installed packages. - Return Type: argparse.Namespace - Returns an argparse.Namespace object containing the parsed command-line arguments. + Supported Arguments: + - -c/--config: Specify a custom JSON requirements file. + - -f/--force: Force Pip installations with --break-system-packages. + - --backup-packages: Save installed packages for restoration. + - --restore-packages: Restore package environment from a backup file. + - --migrate-packages: Migrate legacy package environments. + - --show-installed: Display installed dependencies. - ## Notes: - - This function is critical for enabling dynamic dependency management. + Error Handling: + - Provides structured logging for missing configurations or invalid input. DATA LIB_DIR = PosixPath('/lib') @@ -113,7 +147,7 @@ DATA - You can use Optional[X] as a shorthand for Union[X, None]. VERSION - 0.2.0 + 0.1.0 FILE /packages/requirements/dependencies.py diff --git a/docs/pydoc/packages/requirements/lib/__init__.pydoc b/docs/pydoc/packages/requirements/lib/__init__.pydoc index 3ce15a5..45e894c 100644 --- a/docs/pydoc/packages/requirements/lib/__init__.pydoc +++ b/docs/pydoc/packages/requirements/lib/__init__.pydoc @@ -3,7 +3,52 @@ Help on module packages.requirements.lib.__init__ in packages.requirements.lib: NAME - packages.requirements.lib.__init__ - # File: ./packages/requirements/lib/__init__.py + packages.requirements.lib.__init__ - File Path: ./packages/requirements/lib/__init__.py + +DESCRIPTION + Description: + The __init__.py file serves as the entry point for the 'lib' package, integrating multiple + utility modules responsible for dependency management within the requirements system. + + Core Features: + - **Module Initialization**: + - Ensures all submodules (`brew_utils`, `package_utils`, `policy_utils`, `version_utils`) are properly imported. + - Dynamically adjusts `sys.path` for module resolution. + - **Structured Package Management**: + - Provides a unified interface for handling Homebrew, Pip, and system-wide package dependencies. + - Simplifies version tracking and policy enforcement across different package managers. + - **Dynamic Documentation Loading**: + - Uses `pydoc_loader` to inject external documentation at runtime. + + Usage: + Importing the module automatically loads all submodules: + from packages.requirements.lib import brew_utils, package_utils, policy_utils, version_utils + + Example usage: + from packages.requirements.lib.package_utils import install_requirements + install_requirements(configs) + + Checking Installed Packages: + from packages.requirements.lib.version_utils import installed_version + version = installed_version("requests", configs) + + Dependencies: + - sys - Handles system-level functions such as modifying `sys.path`. + - pathlib - Ensures platform-independent file path resolution. + - lib.pydoc_loader - Dynamically loads module documentation. + - brew_utils - Handles Homebrew-specific package management. + - package_utils - Provides functions for package installation and backup. + - policy_utils - Enforces policy-driven package installations. + - version_utils - Retrieves installed and latest package versions. + + Expected Behavior: + - Automatically exposes core submodules for streamlined package management. + - Ensures all required dependencies are correctly resolved before module execution. + - Loads documentation dynamically to maintain clean, structured code. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing submodules, system path errors, or incorrect module initialization. DATA __all__ = ['brew_utils', 'package_utils', 'policy_utils', 'version_uti... diff --git a/docs/pydoc/packages/requirements/lib/brew_utils.pydoc b/docs/pydoc/packages/requirements/lib/brew_utils.pydoc index dea06e2..ae3f9f8 100644 --- a/docs/pydoc/packages/requirements/lib/brew_utils.pydoc +++ b/docs/pydoc/packages/requirements/lib/brew_utils.pydoc @@ -3,125 +3,151 @@ Help on module packages.requirements.lib.brew_utils in packages.requirements.lib: NAME - packages.requirements.lib.brew_utils - # Homebrew Utilities for Dependency Management + packages.requirements.lib.brew_utils - File Path: ./packages/requirements/lib/brew_utils.py DESCRIPTION - ## Overview - This module provides utility functions for integrating Homebrew package management - within the dependency management system. It facilitates checking the availability - of Homebrew, detecting Python installation environments, and retrieving installed - and latest package versions from Homebrew. - - ## Features - - **Homebrew Availability Check:** Determines whether Homebrew is installed. - - **Python Environment Detection:** Identifies how Python is installed (Brew, system, standalone, etc.). - - **Package Version Retrieval:** Fetches the installed and latest versions of packages managed by Homebrew. - - ## Usage - The module is used internally by the dependency management system to dynamically - detect Python installation methods and ensure compliance with system constraints. - - ## Dependencies - - `subprocess`: For executing shell commands. - - `shutil`: To verify the presence of the `brew` command. - - `platform`: To determine the operating system. - - `importlib.metadata`: For alternative package version lookups. - - `functools.lru_cache`: To optimize repetitive queries. - - ## Notes - - This module is optimized for macOS but includes environment detection for Linux and Windows. - - The `check_availability()` function caches results to minimize system calls. - - The `detect_environment()` function ensures that externally managed environments are respected. + Description: + The brew_utils.py module provides utility functions for integrating Homebrew + package management within the dependency management system. It allows detection + of Homebrew availability, identification of Python installation methods, and + retrieval of installed and latest package versions. + + Core Features: + - Homebrew Availability Check: Determines whether Homebrew is installed. + - Python Environment Detection: Identifies if Python is installed via Brew, system package managers, or standalone. + - Package Version Retrieval: Fetches installed and latest versions of Homebrew-managed packages. + + Usage: + Checking Homebrew Availability: + from packages.requirements.lib.brew_utils import check_availability + is_brew_installed = check_availability() + + Detecting Python Installation Method: + from packages.requirements.lib.brew_utils import detect_environment + env_info = detect_environment() + + Fetching Homebrew Package Version: + from packages.requirements.lib.brew_utils import brew_info + version = brew_info("python3") + + Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Runs Homebrew commands and captures output. + - shutil - Checks if the `brew` command is available. + - re - Provides regex-based parsing of command output. + - json - Handles structured package information. + - argparse - Parses command-line arguments. + - platform - Identifies the operating system. + - logging - Logs system events and errors. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Optimizes function calls by caching results. + - pathlib - Ensures safe and platform-independent file path resolution. + + Expected Behavior: + - Accurately detects the presence and operational status of Homebrew. + - Determines Python installation method (Brew, system-managed, standalone). + - Retrieves package version details from Homebrew. + - Provides optimized querying with caching. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered in environment detection or package retrieval. FUNCTIONS brew_info(package: str) -> Optional[str] - Retrieve information about a Homebrew package. + Function: brew_info(package: str) -> Optional[str] + Description: + Queries Homebrew to determine if a package exists and fetches its version. - This function queries Homebrew to determine if a package exists and fetches its version. + Parameters: + - package (str): The name of the package to check. - ## Args: - - `package` (`str`): The name of the package to check. + Returns: + - Optional[str]: The installed version of the package if found, otherwise None. - ## Returns: - - `Optional[str]`: The package version if found, otherwise `None`. + Behavior: + - Runs 'brew info ' and extracts the version from output. + - If the package does not exist, returns None. - ## Notes: - - This function runs `brew info ` and parses the output. - - If Homebrew returns an error (`No formula found`), it returns `None`. + Error Handling: + - If Homebrew fails to retrieve package info, the function returns None. check_availability() -> bool - Check if Homebrew is available on macOS. + Function: check_availability() -> bool + Description: + Checks if Homebrew is installed and operational on macOS. - This function determines whether Homebrew is installed and operational. It first - checks for the existence of the `brew` binary using `shutil.which()`, then - verifies its functionality by running `brew --version`. + Returns: + - bool: + - True if Homebrew is installed and functional. + - False if Homebrew is unavailable or the system is not macOS. - ## Returns: - - `bool`: - - `True` if Homebrew is installed and operational. - - `False` if Homebrew is unavailable or the system is not macOS. + Behavior: + - Uses shutil.which() to detect the Brew binary. + - Runs 'brew --version' to verify Brew functionality. + - Uses an LRU cache to avoid redundant system calls. - ## Notes: - - Uses `lru_cache(maxsize=1)` to cache the result, avoiding redundant system calls. - - Returns `False` immediately if the system is not macOS. + Error Handling: + - If Homebrew is missing, the function returns False. detect_environment() -> dict - Detect the Python installation method and determine if it is externally managed. - - This function examines the system's Python installation method and whether - package installations are restricted. It identifies installations from: - - **Homebrew (macOS)** - - **System package managers (APT/DNF)** - - **Microsoft Store (Windows)** - - **Standalone Python installations** - - ## Returns: - - `dict`: A dictionary containing: - - `"OS"` (`str`): The detected operating system (`"darwin"`, `"linux"`, `"windows"`). - - `"INSTALL_METHOD"` (`str`): The detected Python installation method (`"brew"`, `"system"`, `"standalone"`, `"microsoft_store"`). - - `"EXTERNALLY_MANAGED"` (`bool`): Indicates whether the system restricts package installations. - - `"BREW_AVAILABLE"` (`bool`): Specifies whether Homebrew is installed. - - ## Notes: - - The function respects `EXTERNALLY-MANAGED` environments on Linux/macOS. - - If Homebrew is available, it attempts to detect whether Python was installed via Brew. - - Uses system commands like `dpkg -l`, `rpm -q`, and `ensurepip` to determine installation methods. + Function: detect_environment() -> dict + Description: + Detects the Python installation method and determines whether package installations are restricted. + + Returns: + - dict: A dictionary containing: + - "OS" (str): The detected operating system ("darwin", "linux", "windows"). + - "INSTALL_METHOD" (str): How Python is installed ("brew", "system", "standalone", "microsoft_store"). + - "EXTERNALLY_MANAGED" (bool): Whether the system restricts package installations. + - "BREW_AVAILABLE" (bool): Whether Homebrew is installed. + + Behavior: + - Detects if Python was installed via Brew. + - Checks for EXTERNALLY-MANAGED markers on Linux/macOS. + - Determines if Python is managed by APT/DNF on Linux or Microsoft Store on Windows. + + Error Handling: + - Uses subprocess calls to query system information. + - Returns a structured dictionary even if detection fails. latest_version(package: str) -> Optional[str] - Retrieve the latest available version of a package from Homebrew. + Function: latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a Homebrew package. - This function runs `brew info ` to extract the latest stable version - of a package from the Homebrew repository. + Parameters: + - package (str): The name of the package to check. - ## Args: - - `package` (`str`): The name of the package to check. + Returns: + - Optional[str]: The latest available version from Homebrew, otherwise None. - ## Returns: - - `Optional[str]`: - - The latest available version from Homebrew. - - `None` if the package is unknown or Brew fails. + Behavior: + - Runs 'brew info ' and extracts the stable version. + - Uses regex to parse the latest version from Homebrew output. - ## Notes: - - Parses the output of `brew info` to extract the stable version. - - If the command fails or the package is not found, it returns `None`. + Error Handling: + - If Brew command fails or package is missing, returns None. + + main() -> None version(package: str) -> Optional[str] - Retrieve the installed version of a Homebrew-managed package. + Function: version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a Homebrew-managed package. - This function executes `brew list --versions ` to check whether a package - is installed via Homebrew and extracts its version if available. + Parameters: + - package (str): The name of the package to check. - ## Args: - - `package` (`str`): The name of the package to check. + Returns: + - Optional[str]: The installed version of the package if found, otherwise None. - ## Returns: - - `Optional[str]`: - - The installed version of the package if found. - - `None` if the package is not installed via Homebrew. + Behavior: + - Runs 'brew list --versions ' and extracts the installed version. + - Returns None if the package is not installed via Homebrew. - ## Notes: - - Uses `subprocess.run()` to query Brew. - - Returns `None` if the package is not installed. + Error Handling: + - If Homebrew fails or the package is missing, the function returns None. DATA LIB_DIR = PosixPath('/packages/... diff --git a/docs/pydoc/packages/requirements/lib/package_utils.pydoc b/docs/pydoc/packages/requirements/lib/package_utils.pydoc index c9c940b..997a897 100644 --- a/docs/pydoc/packages/requirements/lib/package_utils.pydoc +++ b/docs/pydoc/packages/requirements/lib/package_utils.pydoc @@ -3,180 +3,212 @@ Help on module packages.requirements.lib.package_utils in packages.requirements.lib: NAME - packages.requirements.lib.package_utils - # Package Management Utilities for Dependency Handling + packages.requirements.lib.package_utils - File Path: ./packages/requirements/lib/package_utils.py DESCRIPTION - ## Overview - This module provides utility functions for managing Python package dependencies in a structured - and policy-driven approach. It facilitates installing, backing up, restoring, and reviewing package - versions while ensuring compliance with system constraints. - - ## Features - - **Backup & Restore Packages:** Saves and restores installed packages for migration or disaster recovery. - - **Policy-Based Package Installation:** Handles installation, upgrades, and downgrades based on predefined policies. - - **Dependency Review & Management:** Evaluates installed versions against required versions and logs compliance. - - **Homebrew & Pip Integration:** Uses Homebrew if applicable, otherwise falls back to Pip with appropriate safeguards. - - **Logging & Configuration Handling:** Ensures structured logging and configuration retrieval. - - ## Usage - This module is primarily used by the dependency management system to enforce structured package installations - and compliance checks. - - ## Dependencies - - `subprocess`: For executing Pip and Homebrew commands. - - `json`: For handling structured dependency configurations. - - `importlib.metadata`: For retrieving installed package versions. - - `shutil`: To check for external utilities. - - `pathlib`: For managing file paths. - - `functools.lru_cache`: To optimize repetitive queries. - - `log_utils`: Custom logging module for structured output. - - ## Notes - - The module respects externally managed Python environments, ensuring system integrity. - - It dynamically detects installation methods and applies package management policies accordingly. + Description: + The package_utils.py module provides structured functions for managing Python dependencies, + supporting backup, restore, installation, and compliance enforcement based on predefined policies. + + Core Features: + - Backup & Restore Packages: Saves and restores installed packages for migration or disaster recovery. + - Policy-Based Package Installation: Enforces version compliance through installation, upgrades, or downgrades. + - Dependency Review & Management: Evaluates installed versions against required versions. + - Homebrew & Pip Integration: Uses Homebrew when applicable or defaults to Pip for package installation. + - Logging & Configuration Handling: Ensures structured logging and configuration retrieval. + + Usage: + Backing Up Installed Packages: + from packages.requirements.lib.package_utils import backup_packages + backup_packages("backup.txt", configs) + + Installing a Specific Package: + from packages.requirements.lib.package_utils import install_package + install_package("requests", "2.26.0", configs) + + Installing Dependencies Based on Policy: + from packages.requirements.lib.package_utils import install_requirements + install_requirements(configs) + + Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - shutil - Verifies presence of external utilities. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + + Expected Behavior: + - Ensures all required packages are installed, upgraded, or downgraded as per defined policies. + - Respects externally managed environments and provides manual installation instructions when necessary. + - Logs all package operations for debugging and compliance tracking. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or restricted environments. FUNCTIONS backup_packages(file_path: str, configs: dict) -> None - Back up all installed Python packages to a requirements-style list. + Function: backup_packages(file_path: str, configs: dict) -> None + Description: + Saves all installed Python packages to a file for backup or migration. - This function generates a list of installed packages using `pip freeze` - and saves it to the specified file for later restoration. + Parameters: + - file_path (str): The file where the installed package list is saved. + - configs (dict): Configuration dictionary for logging. - ## Args: - - `file_path` (`str`): The file path where the installed package list will be saved. - - `configs` (`dict`): Configuration dictionary used for logging. + Returns: + - None: Writes the package list to the specified file. - ## Raises: - - `subprocess.CalledProcessError`: If the `pip freeze` command fails. + Behavior: + - Runs 'pip freeze' to capture all installed packages. + - Saves the package list to the specified file. + - Logs the operation success or failure. - ## Notes: - - This function is useful for backing up environments before upgrades. - - The saved file can be used for migration or disaster recovery. + Error Handling: + - Captures subprocess errors if the 'pip freeze' command fails. install_package( package: str, version: Optional[str] = None, configs: dict = None ) -> None - Install or update a package using Brew (if applicable) or Pip. + Function: install_package(package: str, version: Optional[str] = None, configs: dict = None) -> None + Description: + Installs or updates a package using Homebrew (if applicable) or Pip. - This function installs a package using the preferred method: - - If Python is installed via Homebrew and the package is available in Brew, it uses `brew install`. - - Otherwise, it falls back to Pip, considering: - - `--user` for standalone installations. - - `--break-system-packages` if the system is externally managed and forced installation is enabled. - - Otherwise, prints manual installation instructions. + Parameters: + - package (str): The package name to install. + - version (Optional[str]): The specific version to install (default: latest). + - configs (dict): Configuration dictionary for logging and system constraints. - ## Args: - - `package` (`str`): The package name to install. - - `version` (`Optional[str]`): The specific version to install (default: latest). - - `configs` (`dict`): Configuration dictionary for logging and environment handling. + Returns: + - None: Executes the installation process. - ## Returns: - - `None`: Executes the package installation process. + Behavior: + - Detects Python's installation method (Brew or standalone). + - Installs the package using Brew if available, otherwise uses Pip. + - Uses '--break-system-packages' when necessary to override restrictions. - ## Notes: - - Ensures safe installation, respecting system constraints. - - Uses structured logging to report installation status. + Error Handling: + - Logs an error if installation fails due to system constraints. + - Provides manual installation instructions when Pip installation is restricted. install_requirements(configs: dict, bypass: bool = False) -> None - Install, upgrade, or downgrade dependencies based on policy rules. + Function: install_requirements(configs: dict, bypass: bool = False) -> None + Description: + Installs, upgrades, or downgrades dependencies based on policy rules. - This function processes dependencies listed in `configs["requirements"]` and applies - necessary package actions (install, upgrade, downgrade). It first retrieves evaluated - package statuses using `review_packages()`, ensuring a structured decision-making process. + Parameters: + - configs (dict): Configuration dictionary containing dependency requirements. + - bypass (bool): If True, forces installation without policy evaluation. - ## Args: - - `configs` (`dict`): Configuration dictionary containing dependency requirements. - - `force_install` (`bool`): If True, all packages are installed immediately, ignoring policy. + Returns: + - None: Executes necessary package actions. - ## Returns: - - `None`: Executes the required package installations. + Behavior: + - Evaluates package policies for installation, upgrade, or downgrade. + - Installs packages using Brew or Pip based on system constraints. + - Logs installation steps and policy decisions. - ## Notes: - - This function enforces policy-based installation to maintain package consistency. - - It minimizes unnecessary installations by checking existing versions before applying changes. - - Dependencies are installed using either Brew or Pip, based on system constraints. + Error Handling: + - Logs warnings for missing configurations or restricted environments. install_requirements__legacy(configs: dict) -> None - Retrieve the path to `installed.json` from the configuration dictionary. - - This function extracts the configured path where installed package statuses are stored. - - ## Args: - - `configs` (`dict`): The configuration dictionary. - - ## Returns: - - `Path`: The resolved path to `installed.json`, or `None` if not configured. - - ## Notes: - - This function ensures consistent access to installed package records. installed_configfile(configs: dict) -> pathlib._local.Path - Retrieve the configured path to `installed.json`. + Function: installed_configfile(configs: dict) -> Path + Description: + Retrieves the configured path to `installed.json`, which tracks installed package statuses. - Args: - configs (dict): Configuration dictionary. + Parameters: + - configs (dict): The configuration dictionary. Returns: - Path: Path object pointing to `installed.json`. + - Path: The resolved path to `installed.json`. - Raises: - KeyError: If `configs["packages"]["installation"]["configs"]` is missing. + Error Handling: + - Raises KeyError if the configuration is missing the expected path. + + main() -> None migrate_packages(file_path: str, configs: dict) -> None - Review installed package versions and return an updated package status list. + Function: migrate_packages(file_path: str, configs: dict) -> None + Description: + Migrates installed packages from a previous environment and saves the package list. - This function checks all installed dependencies, compares them against target versions, - determines their status (installed, outdated, missing), and returns a structured package list. + Parameters: + - file_path (str): File path to save the list of installed packages. + - configs (dict): Configuration dictionary for logging. - ## Args: - - `configs` (`dict`): The configuration dictionary containing dependency policies. + Returns: + - None: Executes the migration process. - ## Returns: - - `list`: A structured list of reviewed packages, including installation status. + Behavior: + - Extracts installed packages using 'pip list'. + - Saves package names before re-installing them. + - Installs all packages in the new environment. - ## Notes: - - The function also updates `installed.json` with the latest package states. - - Ensures a structured package evaluation process before applying changes. + Error Handling: + - Logs errors if package retrieval or installation fails. packages_installed(configs: dict) -> None - Prints the installed dependencies in a readable format. + Function: packages_installed(configs: dict) -> None + Description: + Prints the installed dependencies in a readable format. - This function reads `installed.json` and logs package names, required versions, - installed versions, and compliance status. - - Args: - configs (dict): Configuration dictionary. + Parameters: + - configs (dict): Configuration dictionary. Returns: - None: Prints the installed package details. + - None: Displays installed packages and their status. + + Behavior: + - Reads `installed.json` and logs package names and versions. + - Checks compliance against required versions. + + Error Handling: + - Logs an error if `installed.json` is missing or corrupted. restore_packages(file_path: str, configs: dict) -> None - Restores all previously backed-up Python packages by reading - the specified file and installing the packages listed in it. + Function: restore_packages(file_path: str, configs: dict) -> None + Description: + Restores previously backed-up Python packages from a saved package list. + + Parameters: + - file_path (str): Path to the package list generated by `pip freeze`. + - configs (dict): Configuration dictionary for logging. - This function should be executed after upgrading Python to ensure that - the same packages are available in the new Python environment. + Returns: + - None: Installs packages from the saved list. - Args: - file_path (str): The file path to the package list generated by `pip freeze`. + Behavior: + - Reads the package list and installs them using Pip. + - Ensures compatibility with existing package versions. - Raises: - subprocess.CalledProcessError: If the package installation fails. + Error Handling: + - Logs errors if installation fails or if the backup file is missing. review_packages(configs: dict) -> list - Reviews installed package versions and returns an updated package status list. - - This function checks all installed dependencies, determines their status - (installed, outdated, missing), and returns the structured package data. - It also updates `installed.json` with the latest package states. + Function: review_packages(configs: dict) -> list + Description: + Reviews installed package versions and returns a structured package status list. - Args: - configs (dict): Configuration dictionary. + Parameters: + - configs (dict): Configuration dictionary. Returns: - list: A list of reviewed package data including installation status. + - list: A list of reviewed package data including installation status. + + Behavior: + - Compares installed versions against required versions. + - Determines whether a package is installed, outdated, or missing. + - Writes updated package statuses to `installed.json`. + + Error Handling: + - Logs an error if version comparisons fail. DATA LIB_DIR = PosixPath('/packages/... diff --git a/docs/pydoc/packages/requirements/lib/policy_utils.pydoc b/docs/pydoc/packages/requirements/lib/policy_utils.pydoc index 4c4c2a7..66d2b83 100644 --- a/docs/pydoc/packages/requirements/lib/policy_utils.pydoc +++ b/docs/pydoc/packages/requirements/lib/policy_utils.pydoc @@ -3,81 +3,89 @@ Help on module packages.requirements.lib.policy_utils in packages.requirements.lib: NAME - packages.requirements.lib.policy_utils - # Environment and Policy Management Utilities + packages.requirements.lib.policy_utils - File Path: ./packages/requirements/lib/policy_utils.py DESCRIPTION - ## Overview - This module provides functions for managing package policies and evaluating dependency - installation requirements within the dependency management system. It ensures that packages - are installed, upgraded, or downgraded based on predefined policies while maintaining compliance - with system constraints. - - ## Features - - **Policy-Based Dependency Evaluation:** Determines whether a package should be installed, upgraded, downgraded, or skipped. - - **Automated Compliance Checking:** Compares installed versions against target and latest versions. - - **Dynamic Policy Enforcement:** Adapts installation actions based on policies such as `"latest"` or `"restricted"`. - - **Structured Logging:** Provides detailed debugging and compliance logs for better traceability. - - **Integration with Installed Package Records:** Updates `installed.json` dynamically. - - ## Usage - This module is invoked by the dependency management workflow to analyze package states and - apply policy-driven installation decisions. - - ## Dependencies - - `subprocess`: For executing system commands. - - `json`: For handling structured package configurations. - - `platform`: For system detection. - - `importlib.metadata`: For retrieving installed package versions. - - `pathlib`: For managing configuration file paths. - - `log_utils`: Custom logging module for structured output. - - `package_utils`: Provides package management functions such as retrieving `installed.json`. - - `version_utils`: Handles installed and latest package version retrieval. - - ## Notes - - This module ensures a **structured decision-making** process for package installations. - - It dynamically adapts to the system's constraints, ensuring **safe package management**. + Description: + The policy_utils.py module provides structured policy evaluation for package management. + It ensures that packages are installed, upgraded, or downgraded according to predefined policies. + + Core Features: + - Policy-Based Dependency Evaluation: Determines whether a package should be installed, upgraded, downgraded, or skipped. + - Automated Compliance Checking: Compares installed versions against target and latest versions. + - Dynamic Policy Enforcement: Adapts installation actions based on policies such as "latest" or "restricted". + - Structured Logging: Provides detailed debugging and compliance logs for traceability. + - Integration with Installed Package Records: Updates installed.json dynamically. + + Usage: + Evaluating Package Policies: + from packages.requirements.lib.policy_utils import policy_management + updated_packages = policy_management(configs) + + Checking a Specific Package Status: + from packages.requirements.lib.version_utils import installed_version + current_version = installed_version("requests", configs) + + Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + - package_utils - Retrieves installed.json and manages package installation. + - version_utils - Retrieves installed and latest package versions. + + Expected Behavior: + - Ensures all required packages follow policy-based installation decisions. + - Prevents unintended upgrades/downgrades when policy is set to "restricted". + - Logs all policy enforcement actions for debugging and compliance tracking. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or policy conflicts. FUNCTIONS + main() -> None + policy_management(configs: dict) -> list - Evaluate package installation policies and update dependency statuses. + Function: policy_management(configs: dict) -> list + Description: + Evaluates package installation policies and updates dependency statuses. - This function analyzes each package in the dependency list, comparing its installed - version against the target and latest available versions. Based on the specified - policy, it determines whether the package should be installed, upgraded, downgraded, - or skipped. + Parameters: + - configs (dict): The configuration dictionary containing dependency policies. - ## Args: - - `configs` (`dict`): The configuration dictionary containing dependency policies. + Returns: + - list: The updated list of dependencies with policy-based statuses. - ## Returns: - - `list`: The updated list of dependencies with policy-based statuses. + Behavior: + - Analyzes installed packages and determines policy actions (install, upgrade, downgrade, or skip). + - Updates `installed.json` with the latest package states. + - Logs compliance decisions for debugging and tracking. - ## Policy Decision Logic: - 1. **Missing Package (`status = "installing"`)** - - If the package is not installed, it is marked for installation. - - Installs either the `"latest"` or `"target"` version based on policy. + Policy Decision Logic: + 1. **Missing Package (status = "installing")** + - Installs the package as per policy (either latest or target version). - 2. **Outdated Package (`status = "outdated" | "upgrading"`)** + 2. **Outdated Package (status = "outdated" | "upgrading")** - If installed version < target version: - - `"latest"` policy → Upgrade to latest available version. - - `"restricted"` policy → Keep outdated but log warning. + - "latest" policy → Upgrade to latest available version. + - "restricted" policy → Keep outdated but log a warning. - 3. **Target Version Matched (`status = "matched"`)** + 3. **Target Version Matched (status = "matched")** - If installed version == target version: - - `"latest"` policy → Check if a newer version exists; mark as `"outdated"`. - - Otherwise, mark as `"matched"` (no action needed). + - "latest" policy → Check for newer versions and mark as "outdated". + - Otherwise, mark as "matched" (no action needed). - 4. **Upgraded Version Installed (`status = "downgraded" | "upgraded"`)** + 4. **Upgraded Version Installed (status = "downgraded" | "upgraded")** - If installed version > target version: - - `"restricted"` policy → Downgrade to target version. - - `"latest"` policy → Keep upgraded. - - ## Logging: - - Each package's evaluation is logged, showing its target, installed, and latest versions. - - Policy enforcement decisions are logged with detailed status messages. + - "restricted" policy → Downgrade to target version. + - "latest" policy → Keep upgraded. - ## Notes: - - This function modifies `configs["requirements"]` and updates `installed.json`. + Error Handling: + - Logs policy violations or missing configurations. - Ensures structured compliance before initiating installation processes. DATA diff --git a/docs/pydoc/packages/requirements/lib/version_utils.pydoc b/docs/pydoc/packages/requirements/lib/version_utils.pydoc index ba26ea7..981be7b 100644 --- a/docs/pydoc/packages/requirements/lib/version_utils.pydoc +++ b/docs/pydoc/packages/requirements/lib/version_utils.pydoc @@ -3,155 +3,157 @@ Help on module packages.requirements.lib.version_utils in packages.requirements.lib: NAME - packages.requirements.lib.version_utils - # Version Management Utilities for Dependency Handling + packages.requirements.lib.version_utils - File Path: ./packages/requirements/lib/version_utils.py DESCRIPTION - ## Overview - This module provides utilities for retrieving and managing package versions across - various package managers. It supports version detection for Python packages installed - via Pip, Homebrew, APT, DNF, and Windows Package Manager (Microsoft Store). - - ## Features - - **Retrieve Installed Package Versions:** Determines the currently installed version of a package. - - **Check Latest Available Versions:** Queries the latest available package versions from the appropriate source. - - **Multi-Platform Support:** Detects package versions across macOS (Homebrew), Linux (APT/DNF), and Windows (Microsoft Store). - - **Optimized Performance:** Uses caching and structured queries to minimize redundant operations. - - **Logging & Debugging:** Provides detailed debug logs for package evaluations. - - ## Usage - This module is used internally by the dependency management system to dynamically - assess package versions before applying installation policies. - - ## Dependencies - - `subprocess`: For executing package manager commands. - - `json`: For parsing structured package data. - - `importlib.metadata`: For retrieving installed Python package versions. - - `pathlib`: For managing system paths. - - `log_utils`: Custom logging module for structured output. - - `brew_utils`: Handles Homebrew-specific package version retrieval. - - ## Notes - - This module prioritizes Pip-based queries before falling back to system-level package managers. - - It ensures **structured decision-making** when evaluating package versions. + Description: + The version_utils.py module provides structured utilities for retrieving and managing package versions. + It supports multi-platform package detection across Pip, Homebrew, APT, DNF, and Windows Package Manager. + + Core Features: + - Retrieve Installed Package Versions: Determines the currently installed version of a package. + - Check Latest Available Versions: Queries the latest available package versions from the appropriate source. + - Multi-Platform Support: Detects package versions across macOS (Homebrew), Linux (APT/DNF), and Windows (Microsoft Store). + - Optimized Performance: Uses caching and structured queries to minimize redundant operations. + - Logging & Debugging: Provides detailed debug logs for package evaluations. + + Usage: + Checking Installed Version: + from packages.requirements.lib.version_utils import installed_version + current_version = installed_version("requests", configs) + + Fetching Latest Available Version: + from packages.requirements.lib.version_utils import latest_version + latest_pip_version = latest_version("requests", configs) + + Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + - brew_utils - Retrieves Homebrew-specific package versions. + + Expected Behavior: + - Ensures all required packages follow version compliance checks. + - Prevents unintended upgrades/downgrades when policy is set to "restricted". + - Logs all package version evaluations for debugging and compliance tracking. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or policy conflicts. FUNCTIONS installed_version(package: str, configs: dict) -> Optional[str] - Retrieve the installed version of a package. + Function: installed_version(package: str, configs: dict) -> Optional[str] + Description: + Retrieves the installed version of a package. - This function checks for an installed package version using the following priority order: - 1. **Pip (`pip list --format=json`)** - Best for detecting all installed packages. - 2. **Pip (`importlib.metadata.version()`)** - Fallback for retrieving individual package metadata. - 3. **Homebrew (`brew list --versions`)** - If applicable on macOS. - 4. **APT/DNF (`dpkg -s` or `rpm -q`)** - If applicable on Linux. - 5. **Windows Package Manager (`powershell Get-AppxPackage`)** - If applicable on Windows. + Parameters: + - package (str): The package name to check. + - configs (dict): Configuration dictionary containing system environment details. - ## Args: - - `package` (`str`): The package name to check. - - `configs` (`dict`): Configuration dictionary containing system environment details. + Returns: + - Optional[str]: The installed package version if found, otherwise None. - ## Returns: - - `Optional[str]`: The installed package version if found, otherwise `None`. - - ## Notes: - - Uses structured logging to track package version retrieval. - - Ensures compatibility with externally managed Python environments. + Behavior: + - Uses multiple detection methods, prioritizing Pip before system-level package managers. + - Logs version evaluation details for debugging. latest_version(package: str, configs: dict) -> Optional[str] - Fetch the latest available version of a package using the appropriate package manager. - - This function determines the latest available version of a package by querying: - 1. **Pip** (default for Python packages). - 2. **Homebrew** (if Python is managed via Brew on macOS). - 3. **APT/DNF** (if applicable on Linux). - 4. **Windows Package Manager** (Microsoft Store). + Function: latest_version(package: str, configs: dict) -> Optional[str] + Description: + Fetches the latest available version of a package using the appropriate package manager. - ## Args: - - `package` (`str`): The package name to check. - - `configs` (`dict`): Configuration dictionary used for logging and environment detection. + Parameters: + - package (str): The package name to check. + - configs (dict): Configuration dictionary used for logging and environment detection. - ## Returns: - - `Optional[str]`: The latest available version as a string if found, otherwise `None`. + Returns: + - Optional[str]: The latest available version as a string if found, otherwise None. - ## Notes: - - Prioritizes Pip as it provides the most up-to-date package information. - - Uses `match` statements to route requests to the correct package manager. + Behavior: + - Prioritizes Pip for Python packages. + - Uses system-level package managers (Homebrew, APT/DNF, Microsoft Store) as applicable. linux_latest_version(package: str) -> Optional[str] - Retrieve the latest available version of a package via APT or DNF. - - This function checks: - - `apt-cache madison ` for APT (Debian-based systems). - - `dnf list available ` for DNF (Fedora-based systems). + Function: linux_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via APT or DNF. - ## Args: - - `package` (`str`): The package name to check. + Parameters: + - package (str): The package name to check. - ## Returns: - - `Optional[str]`: The latest available version if found, otherwise `None`. + Returns: + - Optional[str]: The latest available version if found, otherwise None. - ## Notes: - - If `apt-cache` is unavailable, it falls back to `dnf`. + Behavior: + - Uses `apt-cache madison ` for APT and `dnf list available ` for DNF. + - Ensures compatibility with system package management tools. linux_version(package: str) -> Optional[str] - Retrieve the installed version of a package via APT (Debian-based) or DNF (Fedora). + Function: linux_version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a package via APT (Debian-based) or DNF (Fedora). - This function attempts to determine the installed version using: - - `dpkg -s ` for APT (Debian-based systems). - - `rpm -q ` for DNF (Fedora-based systems). + Parameters: + - package (str): The package name to check. - ## Args: - - `package` (`str`): The package name to check. + Returns: + - Optional[str]: The installed version if found, otherwise None. - ## Returns: - - `Optional[str]`: The installed version if found, otherwise `None`. + Behavior: + - Uses `dpkg -s ` for APT and `rpm -q ` for DNF. + - Ensures compatibility with Linux-based package managers. - ## Notes: - - If `dpkg` is unavailable, it falls back to `rpm`. + main() -> None pip_latest_version(package: str) -> Optional[str] - Retrieve the latest available version of a package via Pip. + Function: pip_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via Pip. - This function executes `pip index versions ` to fetch a list of available - versions and extracts the latest one. + Parameters: + - package (str): The package name to check. - ## Args: - - `package` (`str`): The package name to check. + Returns: + - Optional[str]: The latest available version as a string if found, otherwise None. - ## Returns: - - `Optional[str]`: The latest available version as a string if found, otherwise `None`. - - ## Notes: + Behavior: + - Uses `pip index versions ` to retrieve the latest available version. - Requires internet access to fetch version information from PyPI. windows_latest_version(package: str) -> Optional[str] - Retrieve the latest available version of a package via Microsoft Store. - - This function runs a PowerShell command to check the latest available version - of a package using `Find-Package`. + Function: windows_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via Microsoft Store. - ## Args: - - `package` (`str`): The package name to check. + Parameters: + - package (str): The package name to check. - ## Returns: - - `Optional[str]`: The latest available version if found, otherwise `None`. + Returns: + - Optional[str]: The latest available version if found, otherwise None. - ## Notes: - - Requires PowerShell execution privileges. + Behavior: + - Uses PowerShell `Find-Package` to query available package versions. + - Requires administrator privileges for execution. windows_version(package: str) -> Optional[str] - Retrieve the installed version of a package via Microsoft Store. - - This function runs a PowerShell command to check the installed version of - a package using `Get-AppxPackage`. + Function: windows_version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a package via Microsoft Store. - ## Args: - - `package` (`str`): The package name to check. + Parameters: + - package (str): The package name to check. - ## Returns: - - `Optional[str]`: The installed version if found, otherwise `None`. + Returns: + - Optional[str]: The installed version if found, otherwise None. - ## Notes: - - Uses PowerShell commands, which require administrator privileges. + Behavior: + - Uses PowerShell `Get-AppxPackage` to check installed package versions. + - Requires administrator privileges for execution. DATA LIB_DIR = PosixPath('/packages/... diff --git a/lib/.pydocs/pydoc.__init__.py b/lib/.pydocs/pydoc.__init__.py index 1477045..385dce1 100644 --- a/lib/.pydocs/pydoc.__init__.py +++ b/lib/.pydocs/pydoc.__init__.py @@ -3,33 +3,45 @@ # Python File: ./lib/__init__.py __version__ = "0.1.0" # Documentation version -# Module-level documentation MODULE_DOCSTRING = """ +File Path: ./lib/__init__.py + Overview: - The __init__.py file is responsible for marking the 'lib' directory as a Python package, - allowing its modules to be imported properly within the project. + The __init__.py file initializes the 'lib' directory as a Python package, + enabling structured imports for internal modules. - This file serves as the entry point for the 'lib' package and may include shared imports, - initialization logic, or package-wide configuration settings. +Purpose: + - Ensures the directory is recognized as a Python package. + - Provides a centralized location for shared configurations or imports. + - Dynamically loads external documentation to maintain code clarity. Core Features: - - Package Initialization: Ensures 'lib' is recognized as a Python package. - - Shared Module Accessibility: Provides a central location for utility imports. - - Extensibility: Can be modified to include package-wide configurations if necessary. + - **Package Initialization**: Marks 'lib' as an importable package. + - **Dynamic Documentation Loading**: Uses 'pydoc_loader' to apply docstrings at runtime. + - **Shared Path Handling**: Adds the package directory to `sys.path` for accessibility. + - **Minimal Overhead**: Avoids automatic imports of all submodules unless explicitly required. Expected Behavior & Usage: Importing Modules from 'lib': from lib import system_variables, file_utils -Example Integration: - from lib import log_utils - log_utils.log_message("Initialization successful.") + Using a Specific Submodule: + from lib.log_utils import log_message + log_message("Initialization successful.") + + Dynamically Applying Documentation: + from lib.pydoc_loader import load_pydocs + load_pydocs(__file__, sys.modules[__name__]) Important Notes: - - This file does not automatically import all submodules to prevent unnecessary overhead. + - This file **does not** automatically import all submodules to prevent unnecessary overhead. - Individual submodules must be explicitly imported when required. + - The `sys.path.insert()` modification ensures package accessibility but should not be removed unless explicitly handled elsewhere. + - Future extensions may include package-wide constants, configurations, or logging initialization. """ -# Function-level documentation +# Function-level documentation (None needed for now) FUNCTION_DOCSTRINGS = {} + +# Variable-level documentation (None needed for now) VARIABLE_DOCSTRINGS = {} diff --git a/lib/.pydocs/pydoc.accesstoken_expiration.py b/lib/.pydocs/pydoc.accesstoken_expiration.py index 45128d2..546b1be 100644 --- a/lib/.pydocs/pydoc.accesstoken_expiration.py +++ b/lib/.pydocs/pydoc.accesstoken_expiration.py @@ -4,58 +4,266 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -Overview - The `accesstoken_expiration.py` module manages Azure access tokens, retrieving expiration times and displaying the remaining validity duration. +File Path: ./lib/accesstoken_expiration.py + +Description: + The accesstoken_expiration.py module provides functionality to retrieve, manage, and monitor Azure access tokens using the azure-identity SDK. It ensures proper handling of access token expiration, facilitating secure interactions with Azure services. Core Features: - - Fetches an Azure access token using `InteractiveBrowserCredential`. - - Extracts and displays token expiration information. - - Provides a function to check the remaining time before expiration. - - Handles Azure authentication errors gracefully. + - Access Token Retrieval: Uses InteractiveBrowserCredential to authenticate and retrieve an access token. + - Token Expiration Handling: Extracts and displays expiration details of the access token. + - Remaining Time Calculation: Computes and prints the duration until token expiration. + - Error Handling & Debugging: Catches Azure authentication errors and provides debugging output if enabled. + - CLI Integration: Supports command-line execution with debug options. -Expected Behavior & Usage: +Usage: Retrieving Token Expiration: from lib.accesstoken_expiration import print_token_expiration expiration = print_token_expiration(debug=True) - Checking Remaining Validity: - from lib.accesstoken_expiration import print_remaining_time - print_remaining_time() +Checking Remaining Validity: + from lib.accesstoken_expiration import print_remaining_time + print_remaining_time() + +Dependencies: + - sys - Used for error output and process control. + - datetime - Handles timestamp conversions and expiration calculations. + - pathlib - Resolves file paths dynamically. + - azure.identity - Provides Azure authentication via InteractiveBrowserCredential. + - azure.core.exceptions - Captures Azure-related authentication exceptions. + +Global Variables: + - TokenScope: The authentication scope used for obtaining Azure access tokens. + - AccessToken: Stores the retrieved Azure access token. Defaults to None until set. + - TokenExpiration: Holds the expiration timestamp of the current access token. + +Primary Functions: + + get_access_token() -> Optional[datetime] + Retrieves an Azure access token using InteractiveBrowserCredential and extracts its expiration timestamp. + +Returns: + - datetime: Expiration timestamp of the token if successful. + - None: If token retrieval fails due to an authentication error. + +Error Handling: + - Captures and prints authentication errors if Azure SDK fails. + + print_token_expiration(debug: bool = False) -> Optional[datetime] + Fetches and prints the expiration timestamp of the access token. + +Parameters: + - debug (bool, optional): Enables debugging mode to print additional token details. Defaults to False. + +Returns: + - datetime: Token expiration timestamp if retrieval succeeds. + - None: If token fetching fails or is unavailable. + +Behavior: + - If debug=True, prints the token details as a JSON structure. + - If expiration details are missing, outputs an error message. + + print_remaining_time() -> None + Calculates and prints the remaining duration before the access token expires. + +Displays: + - Hours, minutes, and seconds left before token expiration. + - Error message if expiration details are not available. + +Behavior: + - If TokenExpiration is set, computes and prints remaining validity. + - If TokenExpiration is None, alerts the user. + + main(debug: bool = False) -> None + Entry point function that coordinates token retrieval, expiration handling, and remaining time computation. + +Parameters: + - debug (bool, optional): Enables debug output. Defaults to False. + +Behavior: + - Calls print_token_expiration(debug) to retrieve and print expiration details. + - Calls print_remaining_time() to compute remaining validity duration. + - Captures critical failures and exits with an error code if necessary. + +CLI Integration: + This script can be executed via CLI using the argument_parser module. + +Example Execution: + python accesstoken_expiration.py --debug + +Supported CLI Arguments: + - --debug: Enables verbose logging and prints token details in JSON format. + +Expected Behavior: + - Successfully retrieves and prints the expiration timestamp of an Azure access token. + - Computes and displays the remaining time before expiration. + - Handles authentication failures gracefully and prints error messages. + - Provides an interactive experience when executed via CLI, allowing Azure authentication through a browser prompt. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Critical error encountered, script execution halted. + +Example Usage: + Fetch and Print Token Expiration: + from lib.accesstoken_expiration import print_token_expiration + print_token_expiration(debug=True) + +Compute and Print Remaining Time: + from lib.accesstoken_expiration import print_remaining_time + print_remaining_time() + +This documentation provides a structured reference for developers and administrators integrating Azure authentication within their Python applications. + +Objects & External Dependencies: + InteractiveBrowserCredential (from azure.identity): + - Description: Handles authentication by launching an interactive browser window. + - Behavior: + - Uses the default browser to prompt the user for authentication. + - Retrieves an authentication token with the provided scope. + - Used In: get_access_token() + + datetime (from datetime module): + - Description: Provides timestamp operations for token expiration calculations. + - Usage: + - Converts Unix timestamp from the Azure SDK response to a datetime object. + - Computes time differences to determine token validity duration. + - Used In: get_access_token(), print_remaining_time() + + Path (from pathlib module): + - Description: Resolves the file path of the current script. + - Behavior: + - Ensures that the current directory is added to sys.path. + - Used In: sys.path.insert(0, str(Path(__file__).resolve().parent)) + + sys: + - Description: Provides access to system-related functions such as stderr and process exit. + - Usage: + - Prints error messages to stderr. + - Exits the script with a non-zero exit code on failure. + - Used In: get_access_token(), print_token_expiration(), print_remaining_time(), main() + +Global Behavior: + - The script maintains AccessToken and TokenExpiration as global variables to avoid redundant authentication requests. + - The first execution of get_access_token() updates both AccessToken and TokenExpiration. + - print_token_expiration() and print_remaining_time() depend on TokenExpiration being set to function correctly. + - If TokenExpiration is missing, print_remaining_time() will log an error and exit. + +File Structure & Loading: + sys.path.insert(0, str(Path(__file__).resolve().parent)): + - Ensures the script can reference modules in the same directory. + - Resolves the absolute path of the script’s directory dynamically. + + from lib.pydoc_loader import load_pydocs: + - Dynamically loads documentation from external .pydoc files if available. + - Ensures that documentation is available at runtime. + + from argument_parser import parse_arguments: + - Parses command-line arguments passed during execution. + - Supports flags such as --debug to enable verbose logging. """ FUNCTION_DOCSTRINGS = { "get_access_token": """ - Retrieves an Azure access token and determines its expiration time. + Function: get_access_token() -> Optional[datetime] + Description: + Retrieves an Azure access token using InteractiveBrowserCredential and extracts its expiration timestamp. + This function utilizes an interactive authentication flow, prompting the user to log in via a browser. Returns: - Optional[datetime]: The expiration time of the access token, or None if retrieval fails. + - datetime: Expiration timestamp of the token if retrieval is successful. + - None: If authentication fails or the token cannot be retrieved. + + Behavior: + - Instantiates an InteractiveBrowserCredential object for user authentication. + - Requests an access token from Azure with the specified scope: "https://management.azure.com/.default". + - Extracts the expiration timestamp from the token response. + - Stores the access token in the global AccessToken variable for subsequent use. + + Error Handling: + - Captures Azure SDK errors and prints a descriptive error message to stderr. + - Catches general exceptions and logs an error message if token retrieval fails. """, "print_token_expiration": """ - Fetches and prints the access token expiration time. + Function: print_token_expiration(debug: bool = False) -> Optional[datetime] + Description: + Fetches the access token and prints its expiration timestamp in a readable format. + If debugging is enabled, it also prints the full token details in JSON format. Parameters: - debug (bool, optional): Enables debug logging of token details. Defaults to False. + - debug (bool, optional): Enables debugging mode to print token details. Defaults to False. Returns: - Optional[datetime]: The token expiration timestamp or None if unavailable. + - datetime: Expiration timestamp of the token if retrieval succeeds. + - None: If the token is not available or cannot be retrieved. + + Behavior: + - Calls get_access_token() to fetch an access token and its expiration. + - Stores the expiration timestamp in the global TokenExpiration variable. + - If debug=True, prints the full token details in JSON format. + - Converts the expiration timestamp into a human-readable string and prints it. + - If the expiration timestamp is missing or empty, logs an error. + + Error Handling: + - Captures errors related to token retrieval and prints an appropriate error message. + - Handles exceptions during string conversion and prints debugging information. """, "print_remaining_time": """ - Computes and prints the remaining validity duration of the access token. + Function: print_remaining_time() -> None + Description: + Computes and prints the remaining time before the access token expires. + If the token expiration is not set, it prints an error message. Displays: - - Hours, minutes, and seconds left before expiration. - - An error message if expiration is not available. + - Remaining validity of the access token in hours, minutes, and seconds. + - Error message if the expiration timestamp is not available. + + Behavior: + - Retrieves the current system time. + - Computes the difference between the token expiration time and the current time. + - Extracts hours, minutes, and seconds from the computed time difference. + - Prints the remaining time in a formatted string. + + Error Handling: + - If TokenExpiration is not set, prints an error message and exits. + - Catches unexpected exceptions and logs an error message. """, "main": """ - Entry point function that executes the token retrieval and expiration checks. + Function: main(debug: bool = False) -> None + Description: + Entry point function that executes the access token retrieval and expiration checks. + This function orchestrates the workflow by calling print_token_expiration() and print_remaining_time(). Parameters: - debug (bool, optional): Enables debugging mode. Defaults to False. + - debug (bool, optional): Enables debug mode to print detailed token information. Defaults to False. + + Behavior: + - Calls print_token_expiration(debug) to fetch and display the token expiration time. + - Calls print_remaining_time() to compute and print the remaining time before expiration. + - If any unexpected error occurs, logs a critical error message and exits with a non-zero status code. + + Error Handling: + - Captures critical exceptions and logs an error message. + - If an unrecoverable error occurs, the script exits with an error code (1). """ } VARIABLE_DOCSTRINGS = { - "TokenScope": "The scope used for Azure authentication requests.", - "AccessToken": "Holds the retrieved access token. Defaults to None until fetched.", - "TokenExpiration": "Stores the expiration timestamp of the retrieved access token." + "TokenScope": """ + - Description: Defines the authentication scope for retrieving Azure access tokens. + - Value: "https://management.azure.com/" + - Usage: Passed during authentication requests to define resource access. + """, + "AccessToken": """ + - Description: Stores the Azure access token obtained from the authentication request. + - Default: None (until successfully retrieved) + - Usage: Used globally to access Azure resources that require authentication. + - Persistence: Updated when get_access_token() is executed. + """, + "TokenExpiration": """ + - Description: Stores the expiration timestamp of the currently retrieved access token. + - Default: None (until token retrieval is successful) + - Usage: Used in print_token_expiration() and print_remaining_time() to determine token validity. + - Persistence: Updated when get_access_token() is called. + """ } diff --git a/lib/.pydocs/pydoc.argument_parser.py b/lib/.pydocs/pydoc.argument_parser.py index 9049f13..c6bc378 100644 --- a/lib/.pydocs/pydoc.argument_parser.py +++ b/lib/.pydocs/pydoc.argument_parser.py @@ -4,63 +4,149 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -Overview - The `argument_parser.py` module provides command-line argument parsing for system configurations. - It supports structured argument definitions from JSON configuration files. +File Path: ./lib/argument_parser.py + +Description: + The argument_parser.py module provides structured argument parsing capabilities for CLI-based Python applications. + It dynamically loads argument configurations from a system-defined JSON file and ensures type conversions, validation, and error handling. + This module simplifies command-line argument management while maintaining flexibility for different contexts. Core Features: - - Loads argument configurations from system parameter files. - - Parses command-line arguments based on predefined options. - - Supports type conversion and validation for arguments. - - Enables debug mode for detailed argument inspection. + - Argument Configuration Loading: Reads argument structures from an external JSON configuration file. + - Dynamic Argument Parsing: Uses argparse to define CLI arguments dynamically based on pre-configured rules. + - Type Conversion: Automatically converts CLI arguments to expected data types. + - Debugging & Validation: Provides debugging output for parsed arguments and handles incorrect JSON structures gracefully. + - CLI Integration: Supports manual and pre-configured argument handling. -Expected Behavior & Usage: - Parsing CLI Arguments: +Usage: + Basic Argument Parsing: from lib.argument_parser import parse_arguments - args = parse_arguments(context=["debug", "verbose"], description="Azure CLI utility") - print(args.debug, args.verbose) + args = parse_arguments(context={"debug", "verbose"}) + + Loading External Configurations: + from lib.argument_parser import load_argument_config + config = load_argument_config() + +Dependencies: + - sys - Used for argument handling and error output. + - os - Provides system-related utilities. + - json - Parses JSON-based argument configuration. + - logging - Logs debugging information and errors. + - argparse - Handles CLI argument parsing. + - pathlib - Resolves system file paths dynamically. + - typing (Dict, Any) - Defines type hints for functions. + +Global Variables: + - system_params_filepath: The file path for the system-defined argument configuration file. + +CLI Integration: + This script can be executed via CLI to test argument parsing. + +Example Execution: + python argument_parser.py --debug + +Expected Behavior: + - Successfully loads and parses CLI arguments. + - Converts arguments to expected types. + - Handles missing or invalid arguments gracefully. + - Provides debugging output when enabled. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during argument parsing. """ FUNCTION_DOCSTRINGS = { "load_argument_config": """ - Loads argument definitions from a predefined JSON configuration file. + Function: load_argument_config() -> Dict[str, Any] + Description: + Loads CLI argument configurations from a JSON file. Ensures the file exists and contains a valid JSON structure. Returns: - Dict[str, Any]: Parsed argument definitions categorized by section. -""", + - Dict[str, Any]: Parsed JSON dictionary containing argument configurations. + + Behavior: + - Checks if the argument configuration file exists. + - Reads the file contents and attempts to parse JSON data. + - Ensures the file is not empty and contains a valid JSON structure. + + Error Handling: + - Raises FileNotFoundError if the configuration file is missing. + - Raises ValueError if the JSON structure is invalid or empty. + - Raises RuntimeError if any other error occurs while reading the file. + """, "convert_types": """ - Converts type annotations in argument definitions from string format to Python types. + Function: convert_types(kwargs: Dict[str, Any]) -> Dict[str, Any] + Description: + Converts string-based type definitions into callable Python types. Parameters: - kwargs (Dict[str, Any]): Argument definition containing type annotations. + - kwargs (Dict[str, Any]): Dictionary containing argument properties. Returns: - Dict[str, Any]: The argument definition with correct type mappings. -""", + - Dict[str, Any]: Updated dictionary with correct type mappings. + + Behavior: + - If 'store_true' is used as an action, removes the 'type' property to prevent conflicts. + - Converts 'type' values from string format (e.g., 'str', 'int', 'bool') to actual Python types. + """, "parse_arguments__prototype": """ - Parses command-line arguments based on predefined configurations. + Function: parse_arguments__prototype(context: Dict[str, Any] = None, description: str = "Azure CLI utility") -> argparse.Namespace + Description: + Parses command-line arguments using pre-configured settings, allowing context-based filtering. Parameters: - context (Dict[str, Any], optional): Limits parsed arguments to the specified context. Defaults to None. - description (str, optional): Custom description for the argument parser. Defaults to "Azure CLI utility". + - context (Dict[str, Any], optional): Defines which arguments should be considered. Defaults to None. + - description (str, optional): Description displayed in the CLI help text. Defaults to "Azure CLI utility". Returns: - argparse.Namespace: Parsed command-line arguments. -""", + - argparse.Namespace: Parsed CLI arguments stored in a namespace. + + Behavior: + - Loads argument configurations from load_argument_config(). + - Iterates through sections and parameters, dynamically adding them to the argparse parser. + - Uses convert_types() to ensure argument types are properly handled. + - If debugging is enabled, prints parsed arguments in JSON format. + + Error Handling: + - Captures and reports errors related to missing or malformed argument configurations. + """, "parse_arguments": """ - Parses command-line arguments using a structured parameter definition. + Function: parse_arguments(args: Dict[str, Any]) -> argparse.Namespace + Description: + Parses command-line arguments from a structured dictionary format. Parameters: - args (Dict[str, Any]): System parameter configurations defining available arguments. + - args (Dict[str, Any]): Dictionary containing argument structures, including options and flags. Returns: - argparse.Namespace: The parsed arguments as an object. -""", + - argparse.Namespace: Parsed CLI arguments stored in a namespace. + + Behavior: + - Iterates through argument sections and processes options dynamically. + - Ensures type conversion for numerical and boolean values. + - Logs and reports unknown or missing argument definitions. + - Uses argparse to add dynamically defined arguments. + + Error Handling: + - Captures missing 'flags' definitions and logs an error. + - Catches failures in argument parsing and logs a critical error. + """, "main": """ - Main function to execute argument parsing and display parsed results. -""" + Function: main() -> None + Description: + Main execution function that initializes argument parsing. + + Behavior: + - Calls parse_arguments() to retrieve argument values. + - Prints parsed argument values for debugging. + """, } VARIABLE_DOCSTRINGS = { - "system_params_filepath": "Path to the JSON file containing system argument definitions." + "system_params_filepath": """ + - Description: Defines the file path for the argument configuration JSON file. + - Type: Path + - Usage: Used by load_argument_config() to load CLI argument settings. + """ } diff --git a/lib/.pydocs/pydoc.configure_params.py b/lib/.pydocs/pydoc.configure_params.py index c466b7c..0257685 100644 --- a/lib/.pydocs/pydoc.configure_params.py +++ b/lib/.pydocs/pydoc.configure_params.py @@ -4,83 +4,208 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -Overview - The `configure_params.py` module manages system configuration by loading environment variables - and runtime parameters from structured JSON configuration files. +File Path: ./lib/configure_params.py + +Description: + The configure_params.py module handles the initialization, validation, and loading of environment + variables and runtime configuration files. It is responsible for managing JSON-based system parameters, + merging multiple configuration sources, and ensuring environment consistency. Core Features: - - Loads system parameters from predefined JSON sources. - - Initializes and validates environment variables in `.env`. - - Generates and maintains a runtime configuration file. - - Dynamically updates values based on system settings. - -Expected Behavior & Usage: - Initializing Configuration: - from lib.configure_params import main - system_params, runtime_params = main() + - JSON Configuration Loading: Reads and merges JSON system parameter files. + - Environment Variable Management: Loads, validates, and updates `.env` files dynamically. + - Runtime Parameter Initialization: Ensures runtime parameters are stored and accessible. + - Type-Safe Data Retrieval: Extracts and processes system parameters with error handling. + - Logging and Debugging: Provides structured logs for validation and processing errors. + +Usage: + Loading System Parameters: + from lib.configure_params import load_json_sources + config = load_json_sources(["config1.json", "config2.json"], mode="merge") + + Fetching Runtime Variables: + from lib.configure_params import fetching_runtime_variables + runtime_vars = fetching_runtime_variables() + + Environment File Initialization: + from lib.configure_params import initialize_env_file + initialize_env_file() + +Dependencies: + - sys - System-level functions such as error handling and process termination. + - os - Provides access to file system operations. + - json - Loads, parses, and merges JSON configuration files. + - logging - Handles structured logs and debugging. + - dotenv (load_dotenv, dotenv_values) - Manages environment variables in `.env` files. + - typing (List, Dict, Tuple, Union) - Provides type hints for structured data. + - pathlib - Ensures safe file path resolution. + +Global Variables: + - env_file_header: Defines the header content for the auto-generated .env file. + +CLI Integration: + This module is executed automatically when run as a standalone script. + +Example Execution: + python configure_params.py + +Expected Behavior: + - Loads system parameters from multiple JSON sources. + - Initializes and validates `.env` and runtime parameter files. + - Logs structured debugging information. + - Handles missing configuration files gracefully. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Critical error encountered during processing. """ FUNCTION_DOCSTRINGS = { "load_json_sources": """ - Loads JSON data from multiple files and merges them if required. + Function: load_json_sources(filepaths: List[str], mode: str = "merge") -> Union[Dict, Tuple[Dict]] + Description: + Loads and merges multiple JSON configuration files. Parameters: - filepaths (List[str]): List of JSON file paths to load. - mode (str, optional): Determines if data should be merged or returned separately. Defaults to "merge". + - filepaths (List[str]): List of JSON file paths to load. + - mode (str, optional): Mode of operation ('merge' to combine, 'fetch' to return separate dictionaries). Defaults to "merge". Returns: - Union[Dict, Tuple[Dict]]: Merged dictionary or tuple of dictionaries based on mode. -""", + - Dict: Merged JSON data when mode="merge". + - Tuple[Dict]: Tuple of JSON objects when mode="fetch". + + Behavior: + - Iterates over the provided file paths. + - Reads and parses JSON data while ensuring valid structure. + - Merges JSON contents into a single dictionary if mode="merge". + + Error Handling: + - Raises ValueError for invalid JSON structures. + - Raises RuntimeError for file read failures. + """, "fetching_runtime_variables": """ - Extracts and structures runtime variables from system configuration files. + Function: fetching_runtime_variables() -> Dict[str, Dict[str, Union[str, Dict[str, str]]]] + Description: + Extracts structured runtime variables from system parameter files. Returns: - Dict[str, Dict[str, Union[str, Dict[str, str]]]]: Organized runtime variables by section. -""", + - Dict[str, Dict[str, Union[str, Dict[str, str]]]]: Structured runtime variables. + + Behavior: + - Loads system parameters using load_json_sources(). + - Iterates over sections and extracts options. + - Ensures type safety for section options. + + Error Handling: + - Logs errors and exits on failures. + """, "initialize_env_file": """ - Ensures the `.env` file exists and is populated with valid environment variables. -""", + Function: initialize_env_file() -> None + Description: + Ensures that the .env file exists and is properly initialized. + + Behavior: + - Validates the .env file. + - If missing or invalid, attempts to populate it. + + Error Handling: + - Logs errors and exits on failure. + """, "initialize_runtime_file": """ - Ensures the runtime parameters file exists and is updated with structured values. -""", + Function: initialize_runtime_file() -> None + Description: + Ensures that the runtime parameters file exists and is correctly initialized. + + Behavior: + - Validates the runtime parameters file. + - If missing or invalid, attempts to repopulate it. + + Error Handling: + - Logs errors and exits on failure. + """, "populate_env_file": """ - Generates and writes environment variables to the `.env` file from system configuration. + Function: populate_env_file() -> bool + Description: + Generates and writes structured environment variables to the .env file. Returns: - bool: True if successful, False otherwise. -""", + - bool: True if the file was successfully populated, False otherwise. + + Behavior: + - Fetches runtime variables from fetching_runtime_variables(). + - Writes the extracted values to the .env file in a structured format. + + Error Handling: + - Logs errors and returns False on failure. + """, "populate_runtime_file": """ - Updates the runtime parameters JSON file with values extracted from system configurations and `.env`. + Function: populate_runtime_file() -> bool + Description: + Updates and writes runtime parameters to the runtime-params.json file. Returns: - bool: True if successful, False otherwise. -""", + - bool: True if the file was successfully updated, False otherwise. + + Behavior: + - Loads existing environment values from the .env file. + - Updates runtime parameters dynamically. + - Saves the updated structure to the runtime-params.json file. + + Error Handling: + - Logs errors and exits on failure. + """, "validate_env_file": """ - Validates the `.env` file to ensure it exists and contains valid data. + Function: validate_env_file() -> bool + Description: + Checks the existence and validity of the .env file. Returns: - bool: True if valid, False otherwise. -""", + - bool: True if the file is valid, False otherwise. + + Behavior: + - Reads the .env file contents. + - Ensures it is non-empty and formatted correctly. + + Error Handling: + - Logs warnings and returns False if the file is missing or invalid. + """, "validate_runtime_file": """ - Validates the runtime parameters JSON file to ensure it is correctly structured. + Function: validate_runtime_file() -> bool + Description: + Checks the existence and validity of the runtime parameters file. Returns: - bool: True if valid, False otherwise. -""", + - bool: True if the file is valid, False otherwise. + + Behavior: + - Reads the runtime parameters file. + - Ensures it is non-empty and formatted correctly. + + Error Handling: + - Logs warnings and returns False if the file is missing or invalid. + """, "main": """ - Orchestrates the initialization and validation of system configurations. + Function: main() -> Tuple[Dict, Dict] + Description: + Orchestrates the environment initialization process. Returns: - Tuple[Dict, Dict]: Loaded system parameters and runtime parameters. -""" + - Tuple[Dict, Dict]: The loaded system and runtime parameters. + + Behavior: + - Calls initialization functions. + - Loads system parameters. + - Loads runtime parameters. + + Error Handling: + - Logs errors and returns an empty dictionary if failures occur. + """, } VARIABLE_DOCSTRINGS = { - "project_root": "Root directory of the project.", - "env_filepath": "Path to the `.env` file storing environment variables.", - "runtime_params_filename": "Filename of the runtime parameters JSON file.", - "system_params_filename": "Filename of the system parameters JSON file.", - "runtime_params_filepath": "Path to the runtime parameters JSON file.", - "system_params_filepath": "Path to the system parameters JSON file.", - "system_params_listing": "List of paths to system configuration JSON files." + "env_file_header": """ + - Description: Defines the default header content for the .env file. + - Type: str + - Usage: Used when populating environment variables. + """, } diff --git a/lib/.pydocs/pydoc.manage_accesstoken.py b/lib/.pydocs/pydoc.manage_accesstoken.py index 4c84879..47c4a4e 100644 --- a/lib/.pydocs/pydoc.manage_accesstoken.py +++ b/lib/.pydocs/pydoc.manage_accesstoken.py @@ -3,76 +3,94 @@ # Python File: ./lib/manage_accesstoken.py __version__ = "0.1.0" # Documentation version -# Module-level documentation MODULE_DOCSTRING = """ -Overview: - The manage_accesstoken.py module is responsible for handling Azure authentication - and managing access token expiration. It ensures that valid access tokens are available - for API interactions while also integrating timezone detection for better session tracking. +File Path: ./lib/manage_accesstoken.py - This module provides a command-line interface for checking and managing Azure sessions, - retrieving local timezone offsets, and logging authentication details. +Description: + The manage_accesstoken.py module manages Azure authentication token expiration and local timezone offset retrieval. + It integrates utilities from accesstoken_expiration, timezone_localoffset, and argument_parser to streamline session handling. Core Features: - - Retrieves and verifies Azure access token expiration. - - Integrates with local timezone offset detection. - - Provides command-line arguments for debugging and verbosity. - - Handles authentication failures gracefully. + - Access Token Management: Calls print_token_expiration() to retrieve and print token expiration details. + - Timezone Offset Handling: Fetches local timezone offset via get_local_offset(). + - Command-line Argument Parsing: Uses parse_arguments() to extract CLI options (e.g., debug, verbose). + - Error Handling: Captures and logs errors in token expiration and timezone retrieval. -Expected Behavior & Usage: - Running the Script: - python manage_accesstoken.py --debug - - Example Integration: +Usage: + Executing Token and Timezone Management: from lib.manage_accesstoken import manage_accesstoken manage_accesstoken() + CLI Execution: + python manage_accesstoken.py --debug + Dependencies: - - accesstoken_expiration: Handles Azure authentication and access token expiration. - - timezone_localoffset: Retrieves and processes the local timezone offset. - - argument_parser: Parses CLI arguments for debug and verbose flags. + - sys - Handles system-level exit calls for error handling. + - pathlib - Ensures dynamic resolution of the script’s directory path. + - lib.timezone_localoffset.get_local_offset - Retrieves the system’s local timezone offset. + - lib.accesstoken_expiration.print_token_expiration - Fetches and prints Azure token expiration. + - lib.argument_parser.parse_arguments - Parses CLI arguments for session management. + +Global Behavior: + - Retrieves Azure access token expiration details. + - Computes local timezone offsets. + - Supports command-line execution with debugging and verbosity options. + +CLI Integration: + This module can be executed via the command line for interactive token and timezone management. + +Example Execution: + python manage_accesstoken.py --debug + +Expected Behavior: + - Successfully retrieves the Azure authentication token expiration timestamp. + - Computes and displays the local timezone offset. + - Handles token retrieval failures gracefully with error messages. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during execution. """ -# Function-level documentation FUNCTION_DOCSTRINGS = { "manage_accesstoken": """ - Manages Azure authentication and session expiration handling. + Function: manage_accesstoken() -> None + Description: + Manages Azure access token expiration and timezone offset retrieval. Behavior: - - Calls print_token_expiration() to check the Azure token status. - - Calls get_local_offset() to determine the local timezone offset. - - Logs authentication and timezone details. - - Raises: - - Exception: If an error occurs during token retrieval or timezone processing. - - Returns: - - None: This function does not return values; it handles session validation. - - Example Usage: - manage_accesstoken() - -""", - + - Calls print_token_expiration() to fetch and display token expiration details. + - Calls get_local_offset() to retrieve the local timezone offset. + - Handles errors in authentication token retrieval or timezone processing. + + Error Handling: + - Captures exceptions and prints error messages to stderr. + - If an error occurs, exits the script with status code 1. + """, "main": """ - Main entry point for managing Azure session and token expiration. + Function: main() -> None + Description: + Main entry point for executing access token and timezone offset management. Behavior: - - Parses command-line arguments to configure debug and verbose modes. - - Calls manage_accesstoken() to validate authentication and session expiration. - - Raises: - - Exception: If argument parsing or authentication handling fails. + - Calls parse_arguments() to retrieve command-line arguments. + - Extracts debug and verbose mode flags. + - Calls manage_accesstoken() to perform token expiration and timezone retrieval. - Returns: - - None: This function does not return values; it orchestrates session management. - - Example Usage: - python manage_accesstoken.py --debug -""" + Error Handling: + - Logs errors and exits on failure. + """, } VARIABLE_DOCSTRINGS = { - "debug_mode": "Boolean flag indicating whether debugging mode is enabled.", - "verbose_mode": "Boolean flag indicating whether verbose output is enabled." + "debug_mode": """ + - Description: Flag that enables debugging mode for detailed logging. + - Type: bool + - Usage: Passed to manage_accesstoken() to determine whether debug mode is active. + """, + "verbose_mode": """ + - Description: Flag that enables verbose mode for additional output. + - Type: bool + - Usage: Passed to manage_accesstoken() to determine whether verbose logging is enabled. + """, } diff --git a/lib/.pydocs/pydoc.parsing_userinput.py b/lib/.pydocs/pydoc.parsing_userinput.py index c6eb697..38fa4b8 100644 --- a/lib/.pydocs/pydoc.parsing_userinput.py +++ b/lib/.pydocs/pydoc.parsing_userinput.py @@ -3,85 +3,144 @@ # Python File: ./lib/parsing_userinput.py __version__ = "0.1.0" # Documentation version -# Module-level documentation MODULE_DOCSTRING = """ -Overview: - The parsing_userinput.py module is responsible for collecting user input interactively. - It ensures all required runtime parameters are provided by prompting users dynamically, - while also integrating configuration-based input handling. +File Path: ./lib/parsing_userinput.py -Core Features: - - Interactive Input Requests: Prompts users for required input dynamically. - - Configuration-Based Prompts: Loads argument configurations from a JSON file. - - Environment Variable Management: Updates system environment variables at runtime. - - Error Handling: Ensures non-interactive environments exit safely with meaningful errors. - -Expected Behavior & Usage: - Running the Script: - python parsing_userinput.py +Description: + The parsing_userinput.py module provides functions to request user input interactively when required environment + variables are missing. It supports structured user interviews, input validation, and environmental updates. - Example Integration: +Core Features: + - Interactive User Input: Requests input dynamically from users when required environment variables are missing. + - Default Values: Supports default values for prompts to simplify user interaction. + - Structured User Interview: Guides users through missing configurations. + - Environment Variable Management: Updates environment variables dynamically based on user input. + - Error Handling: Handles non-interactive environments and user interruptions gracefully. + +Usage: + Requesting User Input: + from lib.parsing_userinput import request_input + value = request_input("Enter your API Key:", required=True) + + Conducting a User Interview: + from lib.parsing_userinput import user_interview + user_inputs = user_interview(arguments_config, missing_vars) + + Parsing and Collecting Inputs: from lib.parsing_userinput import parse_and_collect_user_inputs - user_inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) + inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) + +Dependencies: + - sys - Handles user input and process termination. + - json - Loads structured configuration files for argument processing. + - os - Manages environment variables dynamically. + - logging - Provides structured logging and debugging output. + - pathlib - Resolves script file paths safely. + +Global Behavior: + - Checks for missing environment variables. + - Prompts users for required input dynamically. + - Updates environment variables based on user responses. + - Supports command-line execution in interactive environments. + +CLI Integration: + This module is primarily used as a supporting library but can be extended for CLI interaction. + +Example Execution: + python parsing_userinput.py + +Expected Behavior: + - Requests missing user inputs interactively. + - Handles default values when provided. + - Updates missing environment variables dynamically. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered in input retrieval or processing. """ -# Function-level documentation FUNCTION_DOCSTRINGS = { "request_input": """ - Prompt the user for input with an optional default value. + Function: request_input(prompt: str, required: bool = True, default: str = None) -> str + Description: + Prompts the user for input interactively, enforcing required fields and handling default values. Parameters: - - prompt (str): The message displayed to the user. - - required (bool): Whether the input is mandatory. Defaults to True. - - default (str, optional): The default value if no input is provided. + - prompt (str): The message displayed to the user for input. + - required (bool, optional): Determines if input is mandatory. Defaults to True. + - default (str, optional): Default value if no input is provided. Defaults to None. Returns: - str: The user-provided input or the default value. Behavior: - - If sys.stdin.isatty() is False, logs an error and exits since interactive input is not possible. - - If the user presses Ctrl+C, logs the interruption and exits. - - Example Usage: - user_value = request_input("Enter your name", required=True, default="Guest") -""", - + - If stdin is non-interactive, exits with an error. + - Displays the prompt message with a default value if provided. + - Ensures required inputs are not skipped. + - Captures keyboard interruptions cleanly. + + Error Handling: + - If stdin is non-interactive and input is required, logs an error and exits. + - Handles KeyboardInterrupt gracefully, allowing clean exit. + """, "user_interview": """ - Collect required user input for missing environment variables. + Function: user_interview(arguments_config: dict, missing_vars: list) -> dict + Description: + Conducts a structured user interview to gather missing environment variables. Parameters: - - arguments_config (dict): Dictionary containing argument configurations. - - missing_vars (list): List of required variables that are missing. + - arguments_config (dict): Dictionary defining input prompts and default values. + - missing_vars (list): List of required variables that are missing from the environment. Returns: - - dict: A dictionary mapping missing variable names to user-provided values. + - dict: A dictionary of collected user inputs. Behavior: - - Cross-references arguments_config to determine the prompt and default values. - - Calls request_input() for each missing variable. - - Example Usage: - user_inputs = user_interview(config, ["API_KEY", "USERNAME"]) -""", + - Iterates through missing environment variables. + - Matches them against argument configuration definitions. + - Requests input interactively and applies default values when available. + Error Handling: + - Ensures user input follows expected formats. + """, "parse_and_collect_user_inputs": """ - Load argument configuration, identify missing variables, and prompt the user. + Function: parse_and_collect_user_inputs(arguments_config_path: str, required_runtime_vars: list) -> dict + Description: + Loads argument configuration from a JSON file and prompts users for missing required variables. Parameters: - arguments_config_path (str): Path to the JSON configuration file. - - required_runtime_vars (list): List of required runtime variables. + - required_runtime_vars (list): List of required runtime environment variables. Returns: - - dict: A dictionary of user-provided environment variable values. + - dict: Dictionary containing user-provided values. Behavior: - - Loads the argument configuration from a JSON file. - - Identifies missing environment variables and prompts the user. - - Updates os.environ dynamically based on user input. - - Example Usage: - user_inputs = parse_and_collect_user_inputs("config.json", ["API_KEY", "USERNAME"]) -""" + - Loads argument configuration from the provided JSON file. + - Identifies missing environment variables. + - Initiates a user interview process for missing values. + - Updates environment variables dynamically. + + Error Handling: + - Logs and raises an error if the configuration file is missing. + - Ensures input follows expected formats before applying updates. + """, + "main": """ + Function: main() -> None + Description: + Placeholder for module execution. + """, } -VARIABLE_DOCSTRINGS = {} +VARIABLE_DOCSTRINGS = { + "arguments_config_path": """ + - Description: Defines the file path for the argument configuration JSON file. + - Type: str + - Usage: Used by parse_and_collect_user_inputs() to load structured argument configurations. + """, + "required_runtime_vars": """ + - Description: List of environment variables required for execution. + - Type: list + - Usage: Used to determine missing values and trigger user prompts. + """, +} diff --git a/lib/.pydocs/pydoc.pkgconfig_loader.py b/lib/.pydocs/pydoc.pkgconfig_loader.py index 1ddbedc..67675a4 100644 --- a/lib/.pydocs/pydoc.pkgconfig_loader.py +++ b/lib/.pydocs/pydoc.pkgconfig_loader.py @@ -3,80 +3,151 @@ # Python File: ./lib/pkgconfig_loader.py __version__ = "0.1.0" # Documentation version -# Module-level documentation MODULE_DOCSTRING = """ -Overview: - The pkgconfig_loader.py module is responsible for loading and managing package configuration files. - It provides methods for parsing, validating, and retrieving configuration data from structured files (e.g., JSON). +File Path: ./lib/pkgconfig_loader.py + +Description: + The pkgconfig_loader.py module provides utilities for dynamically loading, validating, and managing + package configurations. It ensures structured configuration handling, logging setup, and package-specific + settings retrieval. Core Features: - - Configuration File Loading: Reads and parses package configuration files. - - Validation Support: Ensures required parameters are present. - - Structured Access: Provides a structured interface for retrieving configuration values. - - Logging and Debugging: Ensures consistent logging across packages. + - JSON Configuration Loading: Reads and validates structured configuration files. + - Dynamic Logging Setup: Generates unique log file names and directories. + - Configuration Overrides: Allows runtime overrides of configuration parameters. + - Automatic Configuration Updates: Ensures settings are refreshed dynamically. + - Error Handling: Captures and logs errors for missing or malformed configuration files. Usage: - Loading a package-specific configuration: + Loading Package Configurations: from lib.pkgconfig_loader import package_configs config = package_configs() - Setting up logging for a module: - setup_configs("/path/to/module.py") + Setting Up Configurations: + from lib.pkgconfig_loader import setup_configs + config = setup_configs(Path("/path/to/module")) Dependencies: - - os, sys, json, pathlib, datetime - - system_variables: Provides project-wide settings and configurations. + - sys - Handles system path modifications and process exits. + - os - Provides file system utilities. + - json - Loads, modifies, and validates configuration data. + - datetime - Handles timestamps for logging and configuration updates. + - pathlib - Ensures safe file path resolution. + - typing (Optional, Union) - Defines flexible function return types. + +Global Behavior: + - Loads package configurations dynamically. + - Generates structured logging paths. + - Handles missing or invalid configuration files gracefully. + - Updates timestamps when configurations change. + +CLI Integration: + This module primarily supports configuration loading for other scripts but can be executed for testing. + +Example Execution: + python pkgconfig_loader.py + +Expected Behavior: + - Reads JSON-based configuration files. + - Ensures logging directories and filenames are structured. + - Handles missing configuration files with default fallbacks. Exit Codes: - - 0: Successful execution. - - 1: Failure due to missing or invalid configuration files. + - 0: Execution completed successfully. + - 1: Error encountered in configuration processing. """ -# Function-level documentation FUNCTION_DOCSTRINGS = { "config_logfile": """ - Determines the correct log file path based on the caller module's request or self-inspection. + Function: config_logfile(config: dict, caller_log_path: Optional[str] = None) -> Path + Description: + Generates a structured log file path based on package settings. Parameters: - config (dict): Configuration dictionary containing logging settings. - caller_log_path (Optional[str]): A specific log directory path requested by the caller. + - config (dict): Configuration dictionary containing logging details. + - caller_log_path (Optional[str]): Custom log file path if specified. Returns: - Path: The resolved log file path. -""", + - Path: The computed log file path. + Behavior: + - Uses package name and timestamp to generate a unique log filename. + - If a caller_log_path is provided, the log file is placed there. + - Otherwise, the logs directory from the configuration is used. + """, "package_configs": """ - Loads a package-specific configuration from a JSON file or generates a default configuration. + Function: package_configs(overrides: Optional[dict] = None) -> dict + Description: + Loads and returns package configuration settings, applying overrides if provided. Parameters: - overrides (Optional[dict]): Configuration values to override defaults. + - overrides (Optional[dict]): Dictionary of settings to override. Returns: - dict: The loaded or generated package configuration. + - dict: The structured configuration dictionary. - Raises: - FileNotFoundError: If the configuration file is missing. - json.JSONDecodeError: If the file contains invalid JSON. -""", + Behavior: + - Attempts to load a package-specific JSON configuration file. + - If no file exists, generates a default configuration. + - Merges any overrides provided by the caller. + - Generates a log filename and updates timestamps dynamically. + Error Handling: + - Logs and exits if the JSON file is missing or malformed. + """, "setup_configs": """ - Dynamically initializes and updates logging configuration for the calling module. + Function: setup_configs(absolute_path: Path, logname_override: Optional[str] = None, events: Optional[Union[bool, list, dict]] = None) -> dict + Description: + Initializes and updates configuration settings based on the caller’s package details. Parameters: - absolute_path (Path): The absolute path of the module requesting logging setup. - logname_override (Optional[str]): A custom name for the log file. - events (Optional[Union[bool, list, dict]]): Event control settings. + - absolute_path (Path): Path to the module requiring configuration. + - logname_override (Optional[str]): Allows overriding the default log filename. + - events (Optional[Union[bool, list, dict]]): Specifies which logging events should be enabled. Returns: - dict: The updated logging configuration. -""" + - dict: The final configuration dictionary. + + Behavior: + - Identifies the calling module and determines package name. + - Loads or generates the expected configuration file. + - Adjusts logging settings, including log directory and filename. + - Updates the configuration file dynamically with new settings. + + Error Handling: + - Logs and exits if configuration updates fail. + """, + "main": """ + Function: main() -> None + Description: + Placeholder function for module execution. + """, } VARIABLE_DOCSTRINGS = { - "timestamp": "Unique timestamp string used for log filenames.", - "project_root": "Root directory of the project, retrieved from system variables.", - "project_logs": "Directory path for storing logs, retrieved from system variables.", - "max_logfiles": "Maximum number of log files allowed before rotation.", - "default_indent": "Default indentation level for JSON output formatting.", - "category": "Dictionary containing log categories and their respective identifiers.", + "timestamp": """ + - Description: Unique timestamp used for log file naming. + - Type: str + - Usage: Ensures log filenames do not collide when created. + """, + "project_root": """ + - Description: Root directory of the project. + - Type: Path + - Usage: Used to resolve relative paths for configuration and logging. + """, + "project_logs": """ + - Description: Directory where log files are stored. + - Type: Path + - Usage: Configured dynamically in setup_configs(). + """, + "max_logfiles": """ + - Description: Maximum number of log files retained per package. + - Type: int + - Usage: Used to enforce log retention policies. + """, + "category": """ + - Description: Defines different log categories and their associated colors. + - Type: dict + - Usage: Used in package_configs() to set logging formats. + """, } diff --git a/lib/.pydocs/pydoc.pydoc_generator.py b/lib/.pydocs/pydoc.pydoc_generator.py index b71adb5..26c0930 100644 --- a/lib/.pydocs/pydoc.pydoc_generator.py +++ b/lib/.pydocs/pydoc.pydoc_generator.py @@ -3,62 +3,170 @@ # Python File: ./lib/pydoc_generator.py __version__ = "0.1.1" # Documentation version -# Module-level documentation MODULE_DOCSTRING = """ -Overview - Automated Python Documentation Generator (PyDoc) - This module provides a framework for generating documentation for Python scripts and packages - within a project using the `pydoc` module. It ensures that documentation is structured correctly - and saved in an organized manner. +File Path: ./lib/pydoc_generator.py + +Description: + The pydoc_generator.py module automates the generation of structured documentation for Python modules + by leveraging Python's built-in pydoc utility. It also integrates test coverage analysis and logging. Core Features: - - Dynamic Documentation Generation: Automates the process of generating PyDoc documentation. - - Path Handling: Uses `pathlib` for robust and cross-platform path operations. - - Error Handling & Logging: Captures errors and logs messages for debugging. - - Flexible Execution: Distinguishes between modules and standalone scripts for correct PyDoc execution. - - Output Sanitization: Redacts sensitive system paths from generated documentation. - - Coverage Integration: Generates separate `.coverage` files per module. + - **Automatic Documentation Generation**: Uses pydoc to generate structured `.pydoc` files. + - **Test Coverage Reporting**: Integrates with `coverage.py` to produce detailed reports. + - **Dynamic File Structure Creation**: Ensures documentation files are stored systematically. + - **Error Handling and Logging**: Provides structured logs for troubleshooting and debugging. + - **Path Normalization**: Handles absolute and relative paths across various environments. + +Usage: + Creating a PyDoc Structure: + from lib.pydoc_generator import create_structure + doc_dir = create_structure(Path("/docs"), "my_package") -Expected Behavior & Usage: - Generating PyDoc Documentation: - python run.py --pydoc + Generating Documentation for a Module: + from lib.pydoc_generator import generate_pydoc + generate_pydoc(Path("/project"), Path("/project/lib/my_module.py"), Path("/docs")) Dependencies: - - os - - sys - - re - - subprocess - - pathlib - - system_variables (for project environment settings) - - log_utils (for structured logging) - - coverage (for tracking execution coverage) + - sys - Handles system path modifications and process exits. + - os - Provides file system utilities. + - re - Regular expressions for text sanitization. + - subprocess - Executes external commands (`pydoc`, `coverage`). + - pathlib - Ensures safe and platform-independent file path resolution. + - coverage - Generates code coverage reports. + +Global Behavior: + - Generates documentation for Python modules. + - Captures and logs errors encountered during the process. + - Normalizes paths for consistent file system operations. + - Applies automated test coverage validation. + +CLI Integration: + This module primarily runs as part of an automated documentation pipeline but can be executed manually. + +Example Execution: + python pydoc_generator.py + +Expected Behavior: + - Successfully generates `.pydoc` documentation files. + - Produces test coverage reports if coverage data is available. + - Handles missing documentation files gracefully. + - Logs all key actions and errors. Exit Codes: - - 0: Successful execution. - - 1: Failure due to incorrect file paths or PyDoc errors. + - 0: Execution completed successfully. + - 1: Error encountered during documentation generation. """ -# Function-level documentation FUNCTION_DOCSTRINGS = { - "generate_pydoc": """ - Generate and store PyDoc documentation for a given Python file. + "create_structure": """ + Function: create_structure(base_path: Path, package_name: Path) -> Path + Description: + Creates a directory structure for storing generated documentation files. Parameters: - project_path (Path): The root path of the project. - file_path (Path): The Python file for which documentation will be generated. - docs_path (Path): The directory where the generated documentation will be stored. - configs (dict, optional): Additional configuration parameters for logging. + - base_path (Path): The root directory for documentation files. + - package_name (Path): The subdirectory name for organizing files. Returns: - None: This function does not return any value but writes documentation or error messages to disk. + - Path: The created directory path. Behavior: - - Differentiates between scripts and modules to invoke `pydoc` correctly. - - Stores the generated documentation in `docs/pydoc/.pydoc`. - - Sanitizes system paths in the output to avoid exposing absolute paths. -""" + - Creates the specified directory if it does not already exist. + - Ensures parent directories are also created. + """, + "generate_report": """ + Function: generate_report(coverage_report: Path, configs: dict = None) + Description: + Generates a test coverage report using `coverage.py` and saves it to a specified file. + + Parameters: + - coverage_report (Path): The file path where the coverage report will be stored. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Runs `coverage report` via subprocess to generate test coverage. + - Redirects output to the specified coverage report file. + - Logs a warning if the coverage report is empty. + + Error Handling: + - Logs an error message if the coverage command fails. + """, + "generate_coverage": """ + Function: generate_coverage(project_path: Path, file_path: Path, base_path: Path, configs: dict = None) + Description: + Generates a coverage report for a specific Python file. + + Parameters: + - project_path (Path): Root directory of the project. + - file_path (Path): The target Python file for coverage analysis. + - base_path (Path): Directory where coverage reports should be saved. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Executes `coverage report --include=` for precise coverage analysis. + - Saves the output to a `.coverage` file within the structured documentation directory. + - Logs the coverage report details. + + Error Handling: + - Skips processing if no coverage data is found. + - Logs an error if the subprocess call fails. + """, + "generate_pydoc": """ + Function: generate_pydoc(project_path: Path, file_path: Path, docs_path: Path, configs: dict = None) + Description: + Generates a `.pydoc` documentation file for a given Python module. + + Parameters: + - project_path (Path): Root directory of the project. + - file_path (Path): The target Python module for documentation. + - docs_path (Path): Directory where the documentation will be stored. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Converts file paths into module names compatible with `pydoc`. + - Runs `pydoc` as a subprocess to generate documentation. + - Saves the generated documentation to a `.pydoc` file. + - Cleans paths to remove absolute locations for better portability. + + Error Handling: + - Captures errors from `pydoc` and logs them. + - Renames failed documentation files to `.error` for debugging. + """, + "create_pydocs": """ + Function: create_pydocs(project_path: Path, base_path: Path, files_list: list[Path], configs: dict = None) + Description: + Automates the generation of documentation for multiple Python files. + + Parameters: + - project_path (Path): Root directory of the project. + - base_path (Path): Directory where generated documentation will be stored. + - files_list (list[Path]): List of Python files to document. + - configs (dict, optional): Configuration settings for logging. + + Behavior: + - Iterates over the list of Python files. + - Calls generate_pydoc() for each file. + - Logs progress and reports any errors encountered. + + Error Handling: + - Logs any subprocess errors during documentation generation. + """, + "main": """ + Function: main() -> None + Description: + Placeholder function for module execution. + """, } VARIABLE_DOCSTRINGS = { - "timestamp": "A unique timestamp string used for log filenames.", + "environment": """ + - Description: Module containing system-wide environment variables and configurations. + - Type: Module + - Usage: Provides global settings for logging, paths, and categories. + """, + "log_utils": """ + - Description: Utility module for structured logging. + - Type: Module + - Usage: Used throughout the script to log actions and errors. + """, } diff --git a/lib/.pydocs/pydoc.system_params.py b/lib/.pydocs/pydoc.system_params.py index b35dc2f..18ac0a6 100644 --- a/lib/.pydocs/pydoc.system_params.py +++ b/lib/.pydocs/pydoc.system_params.py @@ -4,89 +4,145 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -File: ./lib/system_params.py +File Path: ./lib/system_params.py Description: - System Parameter Management - This module handles system-wide parameter management by loading runtime - parameters from JSON configuration files and merging them with environment variables. + The system_params.py module handles the management and validation of runtime system parameters. + It ensures that required environment variables are loaded, validated, and structured correctly. Core Features: - - **Configuration Loading**: Reads parameters from `runtime-params.json`, `project-params.json`, and `default-params.json`. - - **Environment Variable Management**: Dynamically sets system-wide environment variables. - - **Validation and Error Handling**: Ensures required parameters are initialized before execution. + - **JSON Configuration Loading**: Reads and validates structured JSON configuration files. + - **Environment Variable Management**: Dynamically loads and sets environment variables. + - **Runtime Parameter Validation**: Ensures required parameters are available before execution. + - **Logging and Error Handling**: Provides structured logging for debugging and troubleshooting. + - **Automatic File Creation**: Generates missing configuration files when necessary. Usage: - To load and initialize system parameters: - python system_params.py + Loading Runtime Configuration: + from lib.system_params import load_json_config + config = load_json_config(runtime_params_filepath) -Dependencies: - - os - - json - - logging - - dotenv - - pathlib - - lib.configure_params (for JSON merging and validation) + Retrieving Environment Variables: + from lib.system_params import get_runtime_variable + api_key = get_runtime_variable("API_KEY", required=True) + + Validating Runtime Parameters: + from lib.system_params import validate_runtime_params + validate_runtime_params(runtime_params_filepath) -Global Variables: - - `SYSTEM_PARAMS` (dict): Loaded system-wide parameters. - - `RUNTIME_PARAMS` (dict): Parameters dynamically merged at runtime. +Dependencies: + - sys - Handles system-level functions such as process termination. + - os - Manages environment variables and file system interactions. + - json - Loads, parses, and validates configuration data. + - logging - Provides structured logging for debugging and execution tracking. + - dotenv (load_dotenv) - Loads environment variables from a `.env` file. + - typing (Optional) - Defines flexible function return types. + - pathlib - Ensures safe and platform-independent file path resolution. + +Global Behavior: + - Loads runtime configuration from structured JSON files. + - Validates that all required system parameters are available. + - Generates missing configuration files when needed. + - Ensures environment variables are set correctly. + +CLI Integration: + This module is primarily used as an internal component but can be executed manually for debugging. + +Example Execution: + python system_params.py + +Expected Behavior: + - Successfully loads and validates system parameters. + - Creates missing runtime parameter files when necessary. + - Logs missing or malformed configurations for troubleshooting. Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to missing configuration files or invalid environment variables. + - 0: Execution completed successfully. + - 1: Error encountered during configuration processing. """ FUNCTION_DOCSTRINGS = { "load_json_config": """ - Load environment variables from a JSON configuration file. + Function: load_json_config(runtime_params_filepath: Path) -> dict + Description: + Loads a JSON configuration file and validates its contents. - Reads a JSON file and ensures its structure is valid before returning - the parsed contents. - - Args: - runtime_params_filepath (Path): The file path of the JSON configuration file. - - Raises: - ValueError: If the JSON file is empty or has an invalid structure. - RuntimeError: If the file cannot be read. + Parameters: + - runtime_params_filepath (Path): Path to the JSON configuration file. Returns: - dict: The parsed JSON data containing system parameters. -""", - "get_runtime_variable": """ - Retrieve an environment variable safely, handling missing or empty values. + - dict: The parsed configuration dictionary. - This function fetches an environment variable and logs a warning if a required - variable is missing or empty. + Behavior: + - Reads the specified JSON file. + - Ensures the file is not empty and contains valid JSON. + - Returns the parsed configuration dictionary. - Args: - name (str): The name of the environment variable to retrieve. - required (bool, optional): Whether the variable is mandatory. Defaults to False. + Error Handling: + - Raises ValueError if the JSON file is empty or malformed. + - Raises RuntimeError if the file cannot be read. + """, + "get_runtime_variable": """ + Function: get_runtime_variable(name: str, required: bool = False) -> Optional[str] + Description: + Retrieves an environment variable and validates its presence if required. - Raises: - RuntimeError: If there is an issue retrieving the environment variable. + Parameters: + - name (str): The name of the environment variable to retrieve. + - required (bool, optional): Whether the variable is mandatory. Defaults to False. Returns: - Optional[str]: The value of the environment variable, or None if it is missing. -""", - "validate_runtime_params": """ - Validates the existence and content of the runtime parameters JSON file. - - This function checks whether the specified JSON file exists, is not empty, - and contains valid JSON. It raises appropriate exceptions if any of the - validation steps fail. + - Optional[str]: The value of the environment variable or None if missing. - Args: - runtime_params_filepath (str or Path): The file path to the runtime parameters JSON file. + Behavior: + - Retrieves the value of the specified environment variable. + - Logs a warning if a required variable is missing. - Raises: - FileNotFoundError: If the file specified by `runtime_params_filepath` does not exist. - ValueError: If the file is empty or if it does not contain valid JSON. -""" + Error Handling: + - Raises RuntimeError if an error occurs while retrieving the variable. + """, + "validate_runtime_params": """ + Function: validate_runtime_params(runtime_params_filepath: Path) + Description: + Validates the structure and existence of the runtime parameters file. + + Parameters: + - runtime_params_filepath (Path): The file path of the runtime parameters JSON. + + Behavior: + - Ensures the runtime parameters file exists. + - Checks that the file is non-empty and contains valid JSON. + + Error Handling: + - Raises FileNotFoundError if the file is missing. + - Raises ValueError if the file is empty or contains invalid JSON. + """, + "main": """ + Function: main() -> None + Description: + Placeholder function for module execution. + """, } VARIABLE_DOCSTRINGS = { - "SYSTEM_PARAMS": "Dictionary containing system-wide parameters loaded from configuration files.", - "RUNTIME_PARAMS": "Dictionary containing runtime parameters dynamically merged at execution time.", + "runtime_params_filepath": """ + - Description: Path to the runtime parameters JSON file. + - Type: Path + - Usage: Used for loading and validating runtime configurations. + """, + "system_params_listing": """ + - Description: List of system parameter files to merge. + - Type: list[Path] + - Usage: Used in configuration initialization to combine multiple sources. + """, + "project_root": """ + - Description: Root directory of the project. + - Type: Path + - Usage: Used for resolving relative file paths. + """, + "default_params_filepath": """ + - Description: Default system parameters file. + - Type: Path + - Usage: Serves as a fallback configuration file. + """, } diff --git a/lib/.pydocs/pydoc.system_variables.py b/lib/.pydocs/pydoc.system_variables.py index eec562f..aa0e674 100644 --- a/lib/.pydocs/pydoc.system_variables.py +++ b/lib/.pydocs/pydoc.system_variables.py @@ -4,44 +4,144 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -Overview: - The `system_variables.py` module defines system-wide configuration paths and constants - used throughout the framework. It provides standardized paths for configurations, - logs, and project directories to ensure consistency across different components. +File Path: ./lib/system_variables.py + +Description: + The system_variables.py module defines global paths, file names, and system-wide constants + for managing configurations, logging, and runtime parameter storage. Core Features: - - Standardized paths for runtime configurations, logs, and environment files. - - Predefined logging categories for structured logging. - - A dynamically resolved project root path for consistent reference. - - Aggregation of system parameter files for centralized configuration management. + - **Project Path Management**: Defines and resolves key project directories. + - **Configuration File Paths**: Stores paths to runtime, system, and default configuration files. + - **Logging System Variables**: Defines log storage locations and log file retention settings. + - **ANSI Color Categories**: Provides categorized ANSI escape codes for structured terminal output. + - **Global Constants**: Stores universal defaults such as JSON indentation levels and max log files. Usage: - Import this module wherever system-wide constants are required: - from lib.system_variables import project_root, system_params_filepath + Importing System Variables: + from lib.system_variables import project_root, project_logs + print(f"Project logs are stored in: {project_logs}") + + Using ANSI Log Categories: + from lib.system_variables import category + print(f"{category.info.color}INFO: This is a test log{category.reset.color}") + +Dependencies: + - types.SimpleNamespace - Defines structured namespaces for category-based logging. + - pathlib.Path - Ensures safe and platform-independent file path resolution. + +Global Behavior: + - Provides a centralized reference for all project-wide variables. + - Ensures consistency across modules by defining static paths and configurations. + - Enhances logging with structured color-coded categories. + +CLI Integration: + This module is designed as a global reference but can be imported for debugging system paths. + +Example Execution: + python system_variables.py Expected Behavior: - - Configuration paths should always resolve correctly, ensuring consistency. - - `max_logfiles` should ideally be configurable via an environment variable. - - System parameter files should be aggregated dynamically for flexibility. + - Successfully defines all necessary global paths and system-wide constants. + - Provides a structured way to manage logging, configuration, and runtime parameters. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during variable initialization. """ FUNCTION_DOCSTRINGS = {} VARIABLE_DOCSTRINGS = { - "project_root": "Root directory of the project, used for resolving paths dynamically.", - "project_logs": "Directory where all log files are stored, structured under logs//-.log.", - "project_packages": "Directory path where all Python packages are stored.", - "env_filepath": "Path to the .env file containing runtime environment variables.", - "runtime_params_filename": "Filename for the dynamically generated runtime parameters file.", - "runtime_params_filepath": "Path to the runtime-params.json file, dynamically generated by merging system-wide and project parameters.", - "system_params_filename": "Filename for the system-wide configuration parameters file.", - "system_params_filepath": "Path to the system-params.json file, storing global system-wide configurations.", - "project_params_filename": "Filename for the project-specific parameters file.", - "project_params_filepath": "Path to the project-params.json file, customized for user-specific configurations.", - "default_params_filename": "Filename for the default framework-wide parameters file.", - "default_params_filepath": "Path to the default-params.json file, containing standardized default settings.", - "system_params_listing": "List of JSON configuration files used for system parameter aggregation, including project-params.json and default-params.json.", - "max_logfiles": "Maximum number of log files allowed per module before pruning older logs. Default: 5.", - "default_indent": "Default indentation for JSON formatting (spaces per level).", - "category": "Predefined logging categories for structured logging, providing identifiers and colors for different log levels." + "project_root": """ + - Description: Root directory of the project. + - Type: Path + - Usage: Used as the base directory for resolving relative paths. + """, + "project_logs": """ + - Description: Directory where log files are stored. + - Type: Path + - Usage: Ensures centralized logging across the project. + """, + "project_packages": """ + - Description: Directory where Python packages are stored within the project. + - Type: Path + - Usage: Provides structured access to internal package modules. + """, + "env_filepath": """ + - Description: Path to the environment configuration file. + - Type: Path + - Usage: Stores environment variable settings loaded by dotenv. + """, + "runtime_params_filename": """ + - Description: Name of the JSON file that stores runtime parameters. + - Type: str + - Usage: Used for dynamically managing runtime configurations. + """, + "runtime_params_filepath": """ + - Description: Full path to the runtime parameters JSON file. + - Type: Path + - Usage: Used for loading and storing runtime configuration settings. + """, + "system_params_filename": """ + - Description: Name of the JSON file that stores system-wide parameters. + - Type: str + - Usage: Stores global system settings for application behavior. + """, + "system_params_filepath": """ + - Description: Full path to the system parameters JSON file. + - Type: Path + - Usage: Used for loading persistent system configuration settings. + """, + "project_params_filename": """ + - Description: Name of the JSON file that stores project-specific parameters. + - Type: str + - Usage: Stores project-related configuration settings. + """, + "project_params_filepath": """ + - Description: Full path to the project parameters JSON file. + - Type: Path + - Usage: Used to manage project-specific configuration settings. + """, + "default_params_filename": """ + - Description: Name of the JSON file that stores default parameters. + - Type: str + - Usage: Provides fallback values for missing configurations. + """, + "default_params_filepath": """ + - Description: Full path to the default parameters JSON file. + - Type: Path + - Usage: Ensures availability of base-level configurations. + """, + "system_params_listing": """ + - Description: List of system parameter files used for configuration merging. + - Type: list[Path] + - Usage: Used to merge multiple configuration sources dynamically. + """, + "max_logfiles": """ + - Description: Maximum number of log files to retain per package. + - Type: int + - Usage: Enforces log retention policies to prevent excessive storage use. + """, + "default_indent": """ + - Description: Default indentation level for JSON output. + - Type: int + - Usage: Ensures consistent formatting across configuration files. + """, + "category": """ + - Description: Namespace containing ANSI color codes for categorized logging. + - Type: SimpleNamespace + - Usage: Used in logging functions to color-code output messages. + + Categories: + - `calls` (Green): Logs function calls. + - `critical` (Red Background): Indicates critical errors. + - `debug` (Cyan): Logs debugging messages. + - `error` (Bright Red): Indicates errors. + - `imports` (Blue): Logs module imports. + - `info` (White): Logs informational messages. + - `returns` (Yellow): Logs function return values. + - `warning` (Red): Logs warning messages. + - `reset` (Default): Resets terminal color formatting. + """, } diff --git a/lib/.pydocs/pydoc.timezone_localoffset.py b/lib/.pydocs/pydoc.timezone_localoffset.py index e3bb8ba..b6d9759 100644 --- a/lib/.pydocs/pydoc.timezone_localoffset.py +++ b/lib/.pydocs/pydoc.timezone_localoffset.py @@ -4,62 +4,116 @@ __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ -Overview: - The `timezone_localoffset.py` module is responsible for retrieving and computing -the local time zone and its offset from UTC. This module ensures accurate timekeeping -and synchronization within the framework. +File Path: ./lib/timezone_localoffset.py + +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: - - Detects the local time zone using `pytz`. - - Computes the time difference (offset) between local time and UTC. - - Provides CLI debugging capabilities for time zone verification. + - **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) -Expected Behavior & Usage: - Retrieving and displaying the local time zone and offset: + Running as a CLI tool: + ```bash python timezone_localoffset.py --debug + ``` - Programmatically obtaining the local offset: - from lib.timezone_localoffset import get_local_offset - offset = get_local_offset() +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. """ FUNCTION_DOCSTRINGS = { "get_local_offset": """ - Retrieves and calculates the local time zone offset from UTC. + 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. + - debug (bool, optional): Enables additional debugging output. Defaults to False. Returns: - float: The UTC offset of the local time zone in hours. + - float: The UTC offset of the local time zone in hours. - Behavior: - - Detects the system's local time zone using `pytz`. - - Retrieves the current local time and UTC time. - - Computes the time offset in hours. - - Prints formatted output for debugging if `debug` is enabled. + 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 should be dynamically determined. - - If an error occurs, the function prints the error and exits with a failure code. + - 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": """ - Main execution function that processes time zone offset calculations. + 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. + - debug (bool, optional): Enables additional debugging output. Defaults to False. Returns: - None: Handles execution flow without returning a value. + - 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. - Behavior: - - Calls `get_local_offset()` to retrieve the local time zone and UTC offset. - - Captures and logs any errors that occur during execution. - - Exits with a non-zero status code if an error occurs. - """ + Error Handling: + - If an error occurs during time zone retrieval, the script exits with status `1`. + """, } VARIABLE_DOCSTRINGS = { - "LocalTimeZone": "Stores the detected local time zone as a `pytz.timezone` object.", - "LocalOffset": "Stores the computed UTC offset of the local time zone in hours." + "LocalTimeZone": """ + - Description: Stores the detected local time zone. + - Type: pytz.timezone + - Usage: Assigned dynamically in `get_local_offset()` to store the current system time zone. + """, + "LocalOffset": """ + - Description: Stores the UTC offset of the local time zone in hours. + - Type: float + - Usage: Assigned dynamically in `get_local_offset()` to store the computed UTC offset. + """, } diff --git a/lib/__init__.py b/lib/__init__.py index d5233e2..cfe79f5 100755 --- a/lib/__init__.py +++ b/lib/__init__.py @@ -3,7 +3,10 @@ # File: ./lib/__init__.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system module import sys + +# Standard library imports - File system-related module from pathlib import Path # Ensure the current directory is added to sys.path diff --git a/lib/accesstoken_expiration.py b/lib/accesstoken_expiration.py index 30b4041..f1ed6a8 100755 --- a/lib/accesstoken_expiration.py +++ b/lib/accesstoken_expiration.py @@ -3,15 +3,19 @@ # File: ./lib/accesstoken_expiration.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system modules import sys -from typing import Optional +# Standard library imports - Date and file handling modules from datetime import datetime - from pathlib import Path -from azure.identity import InteractiveBrowserCredential +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional + +# Third-party library imports - Azure SDK modules from azure.core.exceptions import AzureError +from azure.identity import InteractiveBrowserCredential # Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) diff --git a/lib/argument_parser.py b/lib/argument_parser.py index 740e17e..7d60323 100755 --- a/lib/argument_parser.py +++ b/lib/argument_parser.py @@ -3,17 +3,21 @@ # File: ./lib/argument_parser.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system modules import sys import os +# Standard library imports - Utility modules +import argparse import json import logging -import argparse - -from typing import Dict, Any +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (should be in a separate group) +from typing import Any, Dict + # Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) diff --git a/lib/configure_params.py b/lib/configure_params.py index 0babbb4..9ca077d 100755 --- a/lib/configure_params.py +++ b/lib/configure_params.py @@ -3,15 +3,21 @@ # File: ./lib/configure_params.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system modules import sys import os +# Standard library imports - Utility modules import json import logging +# Third-party library imports - Environment variable management from dotenv import load_dotenv, dotenv_values -from typing import List, Dict, Tuple, Union +# Standard library imports - Type hinting (kept in a separate group) +from typing import Dict, List, Tuple, Union + +# Standard library imports - File system-related module from pathlib import Path # Ensure the current directory is added to sys.path diff --git a/lib/manage_accesstoken.py b/lib/manage_accesstoken.py index 2cfaa87..ebe29b2 100755 --- a/lib/manage_accesstoken.py +++ b/lib/manage_accesstoken.py @@ -3,8 +3,10 @@ # File: ./lib/manage_accesstoken.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system module import sys +# Standard library imports - File system-related module from pathlib import Path # Ensure the current directory is added to sys.path diff --git a/lib/parsing_userinput.py b/lib/parsing_userinput.py index f711bd6..7e6b835 100755 --- a/lib/parsing_userinput.py +++ b/lib/parsing_userinput.py @@ -3,11 +3,15 @@ # File: ./lib/parsing_userinput.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system and OS interaction modules import sys -import json import os + +# Standard library imports - Utility modules +import json import logging +# Standard library imports - File system-related module from pathlib import Path # Ensure the current directory is added to sys.path diff --git a/lib/pkgconfig_loader.py b/lib/pkgconfig_loader.py index dc10f8d..0e496cb 100755 --- a/lib/pkgconfig_loader.py +++ b/lib/pkgconfig_loader.py @@ -3,17 +3,23 @@ # File: ./lib/pkgconfig_loader.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system and OS interaction modules import os import sys -import json +# Standard library imports - Utility modules import inspect +import json -from typing import Optional, Union +# Standard library imports - Date and time handling from datetime import datetime, timezone +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) diff --git a/lib/pydoc_generator.py b/lib/pydoc_generator.py index 90227f8..4e2963b 100755 --- a/lib/pydoc_generator.py +++ b/lib/pydoc_generator.py @@ -3,15 +3,20 @@ # File: lib/pydoc_generator.py __version__ = "0.1.1" ## Package version -import sys +# Standard library imports - Core system and OS interaction modules import os +import sys -import coverage +# Standard library imports - Utility modules import re import subprocess +# Standard library imports - File system-related module from pathlib import Path +# Third-party library imports - Coverage analysis +import coverage + sys.path.insert(0, str(Path(__file__).resolve().parent)) from lib import system_variables as environment diff --git a/lib/pydoc_loader.py b/lib/pydoc_loader.py index 0586988..ed839cd 100644 --- a/lib/pydoc_loader.py +++ b/lib/pydoc_loader.py @@ -4,49 +4,90 @@ __version__ = "0.1.0" # Documentation version """ -Overview - The `pydoc_loader.py` module is responsible for dynamically loading documentation for Python scripts - from external `.pydoc` files. This allows scripts to remain clean from embedded docstrings while still - supporting rich documentation that is accessible via tools like `pydoc` and `help()`. +File Path: ./lib/pydoc_loader.py + +Description: + The pydoc_loader.py module is responsible for dynamically loading external documentation for Python modules. + It assigns module-level, function-level, and variable-level docstrings from `.pydoc` files, ensuring scripts + remain clean from embedded documentation while still providing comprehensive API descriptions. Core Features: - - Dynamic Documentation Loading: Loads `.pydoc` files and assigns docstrings dynamically. - - Function-Level Docstring Assignment: Ensures function docstrings are correctly applied to the target module. - - Module-Level Documentation Injection: Injects the module docstring at runtime. - - Variable and Object Documentation: Captures and assigns documentation for global variables and objects. - - Error Handling & Debugging Support: Provides detailed logs to assist in debugging documentation loading issues. - -Expected Behavior & Usage: - Loading Documentation in a Python Script: + - **Dynamic Documentation Loading**: Reads `.pydoc` files and assigns docstrings to functions and variables. + - **Function-Level Docstring Injection**: Ensures functions have assigned documentation at runtime. + - **Module-Level Documentation Assignment**: Injects module docstrings dynamically. + - **Variable Docstring Storage**: Stores variable descriptions separately for retrieval. + - **Error Handling and Debugging Support**: Provides warnings and logs to assist in debugging docstring application. + +Usage: + Applying Documentation in a Python Script: from lib.pydoc_loader import load_pydocs load_pydocs(__file__, sys.modules[__name__]) Checking Documentation with pydoc: python -m pydoc my_script + +Dependencies: + - sys - Accesses runtime module references. + - importlib.util - Dynamically loads external Python modules. + - types.ModuleType - Provides type hints for module-level docstring assignment. + - typing.Dict - Defines dictionary type hints for function and variable docstrings. + - pathlib - Ensures safe and platform-independent file path resolution. + +Global Behavior: + - Dynamically assigns documentation at runtime. + - Searches for and loads `.pydoc` files located in the `.pydocs/` directory. + - Ensures function and variable docstrings are correctly applied to modules. + - Provides warnings if documentation files are missing. + +CLI Integration: + This module is designed as a helper utility for other scripts but can be manually tested. + +Example Execution: + python pydoc_loader.py + +Expected Behavior: + - Successfully loads `.pydoc` documentation files. + - Assigns function and variable docstrings dynamically. + - Logs missing documentation files with warnings. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during documentation loading. """ +# Standard library imports - Core system module import sys import importlib.util +# Standard library imports - File system-related module +from pathlib import Path + +# Standard library imports - Type-related modules from types import ModuleType from typing import Dict -from pathlib import Path + +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) def load_pydocs(script_path: str, module: ModuleType) -> None: """ - Loads module-level, function-level, and variable-level documentation from an external `.pydoc` file. + Function: load_pydocs(script_path: str, module: ModuleType) -> None + Description: + Loads external documentation from a `.pydoc` file and applies it to a given module. Parameters: - script_path (str): The full path of the script whose documentation should be loaded. - module (ModuleType): The module in which function and variable docstrings should be applied. + - script_path (str): The absolute path of the script whose documentation should be loaded. + - module (ModuleType): The module where function and variable docstrings should be applied. Behavior: - - Searches for a `.pydoc` file matching the script's name in the `.pydocs/` directory. + - Searches for a `.pydoc` file matching the script name in the `.pydocs/` directory. - Loads and parses the module docstring (`MODULE_DOCSTRING`), function docstrings (`FUNCTION_DOCSTRINGS`), and variable docstrings (`VARIABLE_DOCSTRINGS`). - - Assigns function and variable docstrings dynamically to the specified module. - - Does **not** return `MODULE_DOCSTRING`, `FUNCTION_DOCSTRINGS`, or `VARIABLE_DOCSTRINGS` to prevent them - from appearing as global variables in `pydoc` output. + - Assigns function and variable docstrings dynamically to the target module. + + Error Handling: + - Logs a warning if no corresponding `.pydoc` file is found. + - Logs an error if the `.pydoc` file fails to load or parse. """ script_name = Path(script_path).stem @@ -78,11 +119,20 @@ def load_pydocs(script_path: str, module: ModuleType) -> None: def apply_docstrings(module: ModuleType, function_docs: Dict[str, str]) -> None: """ - Dynamically assigns function docstrings from a loaded `.pydoc` file to a given module. + Function: apply_docstrings(module: ModuleType, function_docs: Dict[str, str]) -> None + Description: + Dynamically assigns function docstrings from an external `.pydoc` file to a given module. Parameters: - module (ModuleType): The module in which function docstrings should be applied. - function_docs (Dict[str, str]): A dictionary mapping function names to their respective docstrings. + - module (ModuleType): The module where function docstrings should be applied. + - function_docs (Dict[str, str]): A dictionary mapping function names to their respective docstrings. + + Behavior: + - Iterates through the dictionary of function docstrings. + - Assigns each docstring to the corresponding function in the target module. + + Error Handling: + - Logs a warning if a function does not exist in the module. """ if not isinstance(module, ModuleType): print("⚠️ Invalid module provided for docstring application.") @@ -91,21 +141,26 @@ def apply_docstrings(module: ModuleType, function_docs: Dict[str, str]) -> None: for func_name, docstring in function_docs.items(): if hasattr(module, func_name): getattr(module, func_name).__doc__ = docstring - else: - print(f"⚠️ Function {func_name} not found in module {module.__name__}.") + # else: + # print(f"⚠️ Function {func_name} not found in module {module.__name__}.") def apply_variable_docstrings(module: ModuleType, variable_docs: Dict[str, str]) -> None: """ - Stores variable docstrings in a global dictionary instead of modifying __doc__, - since primitive types (str, int, list, etc.) do not support docstring assignment. + Function: apply_variable_docstrings(module: ModuleType, variable_docs: Dict[str, str]) -> None + Description: + Stores variable docstrings in a dictionary instead of modifying `__doc__`, as primitive types + (str, int, list, etc.) do not support direct docstring assignments. Parameters: - module (ModuleType): The module in which variable docstrings should be applied. - variable_docs (Dict[str, str]): A dictionary mapping variable names to their respective descriptions. + - module (ModuleType): The module where variable docstrings should be applied. + - variable_docs (Dict[str, str]): A dictionary mapping variable names to their respective descriptions. Behavior: - - Stores variable docstrings in a separate dictionary for retrieval. - - Ensures variables that cannot have __doc__ modified still have documentation available. + - Stores variable docstrings in a global dictionary for easy retrieval. + - Ensures that variables without `__doc__` support are documented separately. + + Error Handling: + - Logs a warning if a variable is not found in the module. """ global VARIABLE_DOCSTRINGS @@ -119,6 +174,12 @@ def apply_variable_docstrings(module: ModuleType, variable_docs: Dict[str, str]) # print(f"⚠️ Variable {var_name} not found in module {module.__name__}.") def main() -> None: + """ + Function: main() -> None + Description: + Placeholder function for module execution. + """ + pass if __name__ == "__main__": diff --git a/lib/system_params.py b/lib/system_params.py index 2ecc2c6..fc32df8 100755 --- a/lib/system_params.py +++ b/lib/system_params.py @@ -3,17 +3,23 @@ # File: ./lib/system_params.py __version__ = "0.1.0" ## Package version -import sys +# Standard library imports - Core system and OS interaction modules import os +import sys +# Standard library imports - Utility modules import json import logging +# Third-party library imports - Environment variable management from dotenv import load_dotenv -from typing import Optional # Import Optional for type hints +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional # Import Optional for type hints + # Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) diff --git a/lib/system_variables.py b/lib/system_variables.py index 5095564..9378a32 100755 --- a/lib/system_variables.py +++ b/lib/system_variables.py @@ -3,9 +3,15 @@ # File: ./lib/system_variables.py __version__ = "0.1.0" ## Package version -from types import SimpleNamespace as simple +# Standard library imports - Core system module +import sys + +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type-related module +from types import SimpleNamespace as simple + project_root = Path(__file__).resolve().parent.parent project_logs = project_root / "logs" @@ -50,3 +56,7 @@ warning = simple(id="WARNING", color="\033[91m"), # Red reset = simple(id="RESET", color="\033[0m") # Reset to default ) + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/lib/timezone_localoffset.py b/lib/timezone_localoffset.py index 35b29c5..7b3a972 100755 --- a/lib/timezone_localoffset.py +++ b/lib/timezone_localoffset.py @@ -3,51 +3,18 @@ # File: ./lib/timezone_localoffset.py __version__ = "0.1.0" ## Package version -""" -File: ./lib/timezone_localoffset.py - -Description: - Local Time Zone and Offset Manager - This 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: - To retrieve and display the local time zone and offset: - ```bash - python timezone_localoffset.py --debug - ``` - -Dependencies: - - sys - - pytz - - datetime - - argparse - -Global Variables: - - `LocalTimeZone` (pytz.timezone): Stores the detected local time zone. - - `LocalOffset` (float): Stores the UTC offset of the local time zone in hours. - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to time zone retrieval errors. - -Example: - ```bash - python timezone_localoffset.py --debug - ``` -""" - +# Standard library imports - Core system module import sys -import pytz +# Standard library imports - Date and time handling from datetime import datetime + +# Standard library imports - File system-related module from pathlib import Path +# Third-party library imports - Timezone support +import pytz + # Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) @@ -60,34 +27,6 @@ def get_local_offset( debug: bool = False ) -> float: - """ - Retrieves and calculates the local time zone offset from UTC. - - This function: - - Determines the local time zone using `pytz`. - - Computes the time difference (offset) between local time and UTC. - - Prints local and UTC time information in a structured format. - - Args: - debug (bool, optional): Enables additional debugging output. Defaults to False. - - Raises: - Exception: If there is an error retrieving the time zone or calculating the offset. - - 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. - """ global LocalTimeZone, LocalOffset try: @@ -118,31 +57,6 @@ def get_local_offset( def main( debug: bool = False ) -> None: - """ - Main entry point for processing time zone offset calculations. - - This function: - - Calls `get_local_offset()` to retrieve the local time zone and UTC offset. - - Handles exceptions that may arise during execution. - - Args: - debug (bool, optional): Enables additional debugging output. Defaults to False. - - Raises: - SystemExit: If an error occurs during time zone retrieval, the script exits with status `1`. - - 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. - """ try: get_local_offset( debug ) @@ -151,6 +65,7 @@ def main( sys.exit( 1 ) if __name__ == "__main__": + # Command-line argument parsing for debug and verbose parser = argparse.ArgumentParser(description="Retrieve and print local time zone and offset.") parser.add_argument("-d", "--debug", action="store_true", help="Enable debug mode") diff --git a/packages/.pydocs/pydoc.__init__.py b/packages/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..36e8f3f --- /dev/null +++ b/packages/.pydocs/pydoc.__init__.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/__init__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/__init__.py + +Description: + Packages Directory Initialization + + This module ensures that the `packages/` directory is recognized as a Python package. + It establishes a structured framework for organizing submodules while maintaining + explicit import control. + +Core Features: + - **Package Initialization**: Enables `packages/` to function as a Python package. + - **Explicit Import Control**: Prevents unintended execution by requiring explicit submodule imports. + - **Scalability**: Supports modular architecture by keeping dependencies well-structured. + - **Path Management**: Ensures that `sys.path` includes the `packages/` directory for correct imports. + +Usage: + Modules and submodules within `packages/` should be explicitly imported: + ```python + from packages.appflow_tracer import tracing + from packages.requirements import dependencies + ``` + +Important Notes: + - This file **does not** automatically import submodules to avoid unnecessary execution overhead. + - Individual submodules must be explicitly imported when needed to maintain modularity. + +Dependencies: + - None (This module is solely responsible for initialization) + +Example: + To initialize logging from within the `appflow_tracer` package: + ```python + from packages.appflow_tracer import setup_logging + CONFIGS = setup_logging() + ``` +""" + +FUNCTION_DOCSTRINGS = {} + +VARIABLE_DOCSTRINGS = {} diff --git a/packages/__init__.py b/packages/__init__.py index bcd4570..c87f3ba 100755 --- a/packages/__init__.py +++ b/packages/__init__.py @@ -3,38 +3,15 @@ # File: ./packages/__init__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/__init__.py +# Standard library imports - Core system module +import sys -Description: - Packages Directory Initialization +# Standard library imports - File system-related module +from pathlib import Path - This file marks the `packages/` directory as a valid Python package. It ensures - that all submodules and packages within `packages/` can be imported correctly - without requiring additional path modifications. +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) -Core Features: - - **Package Initialization**: Enables `packages/` to be recognized as a valid Python package. - - **Explicit Import Control**: Prevents unintended execution by requiring manual submodule imports. - - **Scalability**: Supports a modular framework structure by keeping dependencies organized. - -Usage: - Modules within `packages/` should be imported explicitly as needed: - ```python - from packages.appflow_tracer import tracing - from packages.requirements import dependencies - ``` - -Important: - - This file **does not** automatically import submodules to avoid unnecessary execution overhead. - - Individual submodules must be explicitly imported by other modules when needed. - -Dependencies: - - None (This module solely serves as an initialization file) - -Example: - ```python - from packages.appflow_tracer import setup_logging - CONFIGS = setup_logging() - ``` -""" +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/appflow_tracer/.pydocs/pydoc.__init__.py b/packages/appflow_tracer/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..d2c09d7 --- /dev/null +++ b/packages/appflow_tracer/.pydocs/pydoc.__init__.py @@ -0,0 +1,93 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/__init__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/appflow_tracer/__init__.py + +Description: + AppFlow Tracing Package Initialization + + This module serves as the entry point for the `appflow_tracer` package, ensuring + the package is correctly recognized and exposing core functionalities for structured + logging and function execution tracing. + +Core Features: + - **Package Initialization**: Marks `appflow_tracer` as a Python package, enabling imports. + - **Logging Setup**: Provides `setup_logging` for configuring structured logging. + - **Utility Exposure**: Imports and exposes core framework utilities for tracing, file handling, and logging. + - **Modular Structure**: Ensures clean and organized access to tracing functionalities. + +Submodules: + - `tracing`: Handles structured event-based logging and tracing. + - `lib.file_utils`: Provides file and directory management utilities. + - `lib.log_utils`: Facilitates structured logging and debugging. + - `lib.trace_utils`: Supports runtime tracing and performance monitoring. + - `lib.serialize_utils`: Manages data serialization and deserialization. + +Usage: + Importing and initializing logging: + from packages.appflow_tracer import setup_logging + CONFIGS = setup_logging() + + Logging messages: + from packages.appflow_tracer import log_utils + log_utils.log_message("This is a test log message.") + + Accessing tracing utilities: + from packages.appflow_tracer import trace_utils + trace_utils.start_tracing() + +Dependencies: + - `tracing` - Manages function execution tracing and structured event logging. + - `log_utils` - Handles structured logging, formatting, and log management. + - `file_utils` - Provides file and directory-related utilities. + - `serialize_utils` - Ensures proper data serialization and deserialization. + - `trace_utils` - Supports real-time function call monitoring and execution tracing. + +Exit Codes: + - `0`: Successful package initialization. + - `1`: Failure due to import errors or incorrect setup. + +Example: + Initializing the AppFlow Tracer system: + from packages.appflow_tracer import setup_logging, log_utils + + CONFIGS = setup_logging() + log_utils.log_message("Framework initialized successfully.") +""" + +FUNCTION_DOCSTRINGS = { + "setup_logging": """ + Configures and initializes structured logging for the framework. + + This function sets up logging with file and console handlers, ensuring structured + log output. It integrates function call tracing and manages log file retention. + + Args: + configs (dict, optional): Logging configuration dictionary. + logname_override (str, optional): Custom log file name. + events (bool, list, dict, optional): Controls which events are logged. + + Returns: + dict: The effective logging configuration. + + Example: + >>> from packages.appflow_tracer import setup_logging + >>> CONFIGS = setup_logging() + """ +} + +VARIABLE_DOCSTRINGS = { + "__all__": """ + - Description: Defines the public API of the `appflow_tracer` package. + - Type: list + - Contents: + - "setup_logging": Initializes structured logging. + - "file_utils": Provides file management utilities. + - "log_utils": Handles structured logging. + - "serialize_utils": Supports safe serialization. + - "trace_utils": Implements function call tracing. + """ +} diff --git a/packages/appflow_tracer/.pydocs/pydoc.__main__.py b/packages/appflow_tracer/.pydocs/pydoc.__main__.py new file mode 100644 index 0000000..a9eac1d --- /dev/null +++ b/packages/appflow_tracer/.pydocs/pydoc.__main__.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/__main__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/appflow_tracer/__main__.py + +Description: + AppFlow Tracing Package Entry Point + + This module acts as the execution entry point for the `appflow_tracer` package when invoked + using `python -m packages.appflow_tracer`. It ensures structured logging and tracing + are properly initialized by delegating execution to the `main()` function within the `tracing` module. + +Core Features: + - **Standalone Execution**: Enables the package to run independently via `python -m packages.appflow_tracer`. + - **Automatic Logging Setup**: Ensures structured logging and tracing configurations are loaded. + - **Main Function Invocation**: Calls the `main()` function from the `tracing` module to handle execution flow. + +Usage: + Running the `appflow_tracer` package as a standalone application: + ```bash + python -m packages.appflow_tracer + ``` + + This will: + - Initialize structured logging. + - Start function execution tracing. + - Manage log file retention. + +Dependencies: + - `tracing` (Handles logging and execution flow management.) + +Exit Codes: + - `0`: Successful execution. + - `1`: Failure due to configuration or tracing errors. + +Example: + Running the package from the command line: + ```bash + python -m packages.appflow_tracer + ``` + + This will invoke the `main()` function from the `tracing` module, ensuring correct execution. +""" + +FUNCTION_DOCSTRINGS = { + "main": """ + Executes the main tracing function for the `appflow_tracer` package. + + This function serves as the primary execution entry point when the package is run as a module. + It initializes logging, sets up tracing, and ensures the framework operates as expected. + + Raises: + Exception: If an error occurs during logging or tracing initialization. + + Returns: + None + + Example: + Running `appflow_tracer` as a standalone application: + ```bash + python -m packages.appflow_tracer + ``` + """ +} diff --git a/packages/appflow_tracer/.pydocs/pydoc.tracing.py b/packages/appflow_tracer/.pydocs/pydoc.tracing.py new file mode 100644 index 0000000..6f960d1 --- /dev/null +++ b/packages/appflow_tracer/.pydocs/pydoc.tracing.py @@ -0,0 +1,193 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/tracing.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/appflow_tracer/tracing.py + +Description: + AppFlow Tracing System + This module provides structured logging and function call tracing, enabling + automatic function execution monitoring with minimal intrusion. It integrates + logging and tracing functionalities, ensuring accurate tracking of function + calls, return values, and execution flow. + +Core Features: + - **Function Call Tracing**: Automatically captures function calls, arguments, and return values. + - **Structured Logging**: Logs execution details in JSON format for debugging and auditing. + - **Self-Inspection**: When executed directly, logs its own execution for analysis. + - **Automatic Log Management**: Removes old log files to maintain storage efficiency. + - **Configurable Event Filtering**: Allows selective tracing of function calls and returns. + - **Console and File Logging**: Captures print statements and ensures logs do not contain ANSI escape sequences. + +Usage: + To enable function call tracing: + import tracing + tracing.setup_logging() + + To run the tracing system as a standalone tool: + python tracing.py + +Dependencies: + - `sys` - Provides system-level operations, including path management. + - `json` - Enables structured logging in JSON format. + - `inspect` - Used for function introspection and execution tracing. + - `logging` - Handles structured logging and message formatting. + - `builtins` - Overrides `print` statements for structured logging. + - `pathlib.Path` - Resolves file and directory paths dynamically. + - `datetime` - Used for timestamping and log file management. + - `lib.system_variables` - Provides global project-wide configurations. + - `lib.pkgconfig_loader` - Loads and manages logging and tracing configurations. + - `lib.file_utils` - Handles log file cleanup and path resolution. + - `lib.log_utils` - Provides structured logging utilities. + - `lib.trace_utils` - Implements function call tracing and execution flow monitoring. + +Global Variables: + - `LOGGING` (bool): Flag indicating whether logging has been initialized. + - `CONFIGS` (dict): Stores the effective logging and tracing configurations. + - `logger` (logging.Logger): Global logger instance used for structured logging. + +Primary Functions: + - `setup_logging(configs, logname_override, events)`: Initializes structured logging. + - `main()`: Entry point for standalone execution, setting up tracing and logging. + - `PrintCapture.emit(record)`: Captures print statements and redirects them to logs. + - `ANSIFileHandler.emit(record)`: Ensures log files do not contain ANSI escape sequences. + +Expected Behavior: + - Logs execution details when tracing is enabled. + - Logs function calls with arguments and return values. + - Maintains structured logs for debugging and execution tracking. + - Automatically removes older log files when exceeding retention limits. + +Exit Codes: + - `0`: Successful execution. + - `1`: Failure due to configuration or logging setup errors. + +Example: + Importing the tracing system and enabling structured logging: + from tracing import setup_logging + setup_logging() + +class PrintCapture(logging.StreamHandler): + + Custom logging handler that captures print statements and logs them + while ensuring they are displayed in the console. + + This ensures that print statements are properly logged without affecting + real-time console output. + + def emit(self, record: logging.LogRecord) -> None: + + Custom logging handler that captures print statements and logs them + while ensuring they are displayed in the console. + + This ensures that print statements are properly logged without affecting + real-time console output. + + Args: + record (logging.LogRecord): The log record that contains information + about the log message to be captured and displayed. + + Returns: + None + +class ANSIFileHandler(logging.FileHandler): + + Custom FileHandler that removes ANSI codes from log output + and filters out logs from the internal Python logging module. + + This prevents unnecessary ANSI escape codes from appearing in log files + and ensures only relevant logs are recorded. + + def emit(self, record: logging.LogRecord) -> None: + + Custom FileHandler that removes ANSI codes from log output + and filters out logs from the internal Python logging module. + + This prevents unnecessary ANSI escape codes from appearing in log files + and ensures only relevant logs are recorded. + + Args: + record (logging.LogRecord): The log record to be emitted, including + log message and additional context for filtering. + + Returns: + None +""" + +FUNCTION_DOCSTRINGS = { + "setup_logging": """ + Configures and initializes the global logging system. + + This function sets up the logging environment, creating log files and adding handlers + for both file-based and console-based logging. It ensures proper logging behavior + even when no configuration is provided. + + Args: + configs (dict, optional): A dictionary containing logging configurations. + If None, the default global configurations are used. + logname_override (str, optional): A custom name for the log file. + If None, the log file name is derived from the calling script. + events (bool, list, or dict, optional): + - `None` / `False` → Disables all event logging. + - `True` → Enables all event logging. + - `list` → Enables only specified events (e.g., ["call", "return"]). + - `dict` → Enables/disables events per user settings (e.g., {"call": True, "return": False}). + + Raises: + ValueError: If the provided logging configurations are not in a dictionary format. + + Returns: + dict: The effective logging configuration after applying defaults. + + Example: + >>> setup_logging() + { + "logging": { + "log_filename": "/path/to/logfile.log", + "max_logfiles": 5, + ... + }, + ... + } + """, + "main": """ + Entry point for running the tracing module as a standalone program. + + This function initializes the logging environment, manages log files, and + optionally starts the tracing system when executed directly. It helps with + self-inspection and ensures the module operates correctly in isolation. + + Raises: + Exception: If logging setup fails or an unexpected error occurs. + + Returns: + None + + Example: + >>> python tracing.py + # Sets up logging, manages logs, and starts tracing. + """ +} + +VARIABLE_DOCSTRINGS = { + "LOGGING": """ + - Description: Flag indicating whether logging has been initialized. + - Type: bool + - Default: None + - Usage: Prevents reinitialization of logging when tracing multiple functions. + """, + "CONFIGS": """ + - Description: Stores the effective logging and tracing configurations. + - Type: dict + - Default: None + - Usage: Provides access to logging, tracing, and structured log settings. + """, + "logger": """ + - Description: Global logger instance used for structured logging. + - Type: logging.Logger + - Default: None + - Usage: Handles structured logs for function calls, execution tracing, and errors. + """ +} diff --git a/packages/appflow_tracer/__init__.py b/packages/appflow_tracer/__init__.py index 48ff9d6..d62ddc2 100755 --- a/packages/appflow_tracer/__init__.py +++ b/packages/appflow_tracer/__init__.py @@ -3,56 +3,14 @@ # File: ./packages/appflow_tracer/__init__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/__init__.py +# Standard library imports - Core system module +import sys -Description: - AppFlow Tracing Package Initialization +# Standard library imports - File system-related module +from pathlib import Path - This file defines the `appflow_tracer` package and ensures it is properly recognized - as a Python package. It serves as the main entry point for tracing and logging functionalities - by exposing the core `setup_logging` function along with key utilities. - -Core Features: - - **Package Initialization**: Marks `appflow_tracer` as a valid Python package. - - **Logging Setup**: Provides `setup_logging` for configuring structured logging. - - **Utility Exposure**: Imports and exposes core framework utilities for tracing, file handling, and logging. - - **Modular Structure**: Ensures clean and organized access to tracing functionalities. - -Submodules: - - `tracing`: Handles structured event-based logging and tracing. - - `lib.file_utils`: Provides file and directory management utilities. - - `lib.log_utils`: Facilitates structured logging and debugging. - - `lib.trace_utils`: Supports runtime tracing and performance monitoring. - - `lib.serialize_utils`: Manages data serialization and deserialization. - -Usage: - To initialize logging within the framework: - ```python - from packages.appflow_tracer import setup_logging - CONFIGS = setup_logging() - ``` - - To log messages: - ```python - from packages.appflow_tracer import log_utils - log_utils.log_message("This is a test log message.") - ``` - -Dependencies: - - tracing (for structured event tracing) - - log_utils (for logging and debugging) - - file_utils (for file operations) - - serialize_utils (for serialization handling) - -Example: - ```python - from packages.appflow_tracer import setup_logging, log_utils - - CONFIGS = setup_logging() - log_utils.log_message("Framework initialized successfully.") - ``` -""" +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # from .tracing import ( from packages.appflow_tracer.tracing import ( @@ -75,3 +33,7 @@ "serialize_utils", "trace_utils" ] + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/appflow_tracer/__main__.py b/packages/appflow_tracer/__main__.py index bf4905d..bc77bf5 100755 --- a/packages/appflow_tracer/__main__.py +++ b/packages/appflow_tracer/__main__.py @@ -3,36 +3,20 @@ # File: ./packages/appflow_tracer/__main__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/__main__.py +# Standard library imports - Core system module +import sys -Description: - AppFlow Tracing Package Entry Point +# Standard library imports - File system-related module +from pathlib import Path - This file serves as the execution entry point for the `appflow_tracer` package when run - in standalone mode. It initializes the logging system and starts the tracing execution flow. - -Core Features: - - **Standalone Execution**: Allows the package to be executed directly using `python -m packages.appflow_tracer`. - - **Logging Initialization**: Ensures structured logging is properly configured. - - **Main Function Invocation**: Calls the `main()` function from the `tracing` module. - -Usage: - To run the `appflow_tracer` package as a standalone script: - ```bash - python -m packages.appflow_tracer - ``` - -Dependencies: - - tracing (for handling structured logging and execution flow) - -Example: - ```bash - python -m packages.appflow_tracer - ``` -""" +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) from packages.appflow_tracer.tracing import main if __name__ == "__main__": main() + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/appflow_tracer/lib/.pydocs/pydoc.__init__.py b/packages/appflow_tracer/lib/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..e65d6eb --- /dev/null +++ b/packages/appflow_tracer/lib/.pydocs/pydoc.__init__.py @@ -0,0 +1,66 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/lib/__init__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/appflow_tracer/lib/__init__.py + +Description: + AppFlow Tracer Library Initialization + + This file defines the `lib` subpackage within the `appflow_tracer` framework. It provides + access to essential utility modules required for logging, file operations, tracing, and + serialization within the framework. + +Core Features: + - **Subpackage Initialization**: Ensures that the `lib` directory is recognized as a Python package. + - **Utility Module Exposure**: Facilitates direct access to key framework utilities. + - **Structured Imports**: Enables clean and maintainable access to core functionality. + - **Dynamic Documentation Loading**: Injects `.pydoc` documentation into the module. + +Submodules: + - `file_utils`: Provides file and directory management utilities. + - `log_utils`: Handles structured logging and message formatting. + - `trace_utils`: Supports runtime tracing and performance monitoring. + - `serialize_utils`: Manages data serialization and deserialization. + +Usage: + To import specific utilities from this package: + from packages.appflow_tracer.lib import log_utils, file_utils + + log_utils.log_message("Example log message") + file_utils.manage_logfiles() + + To enable tracing within the framework: + from packages.appflow_tracer.lib import trace_utils + trace_utils.start_tracing() + +Dependencies: + - `sys` - Provides access to system path management. + - `pathlib.Path` - Used for resolving package paths dynamically. + - `lib.pydoc_loader` - Dynamically loads module-level documentation. + +Example: + Importing core utilities from the `appflow_tracer` library: + from packages.appflow_tracer.lib import log_utils, serialize_utils + + log_utils.log_message("Structured logging enabled") + json_data = serialize_utils.safe_serialize({"example": "data"}) +""" + +FUNCTION_DOCSTRINGS = {} + +VARIABLE_DOCSTRINGS = { + "__all__": """ + - Description: Specifies the public API for the `lib` package. + - Type: list[str] + - Usage: Defines the modules exposed when using `from lib import *`. + + Modules: + - `file_utils`: Provides file and directory management utilities. + - `log_utils`: Handles structured logging and message formatting. + - `trace_utils`: Supports runtime tracing and performance monitoring. + - `serialize_utils`: Manages data serialization and deserialization. + """ +} diff --git a/packages/appflow_tracer/lib/.pydocs/pydoc.file_utils.py b/packages/appflow_tracer/lib/.pydocs/pydoc.file_utils.py new file mode 100644 index 0000000..2a1cea7 --- /dev/null +++ b/packages/appflow_tracer/lib/.pydocs/pydoc.file_utils.py @@ -0,0 +1,207 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/lib/file_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/appflow_tracer/lib/file_utils.py + +Description: + The file_utils.py module provides helper functions for managing log files, + resolving relative paths, and cleaning terminal output by removing ANSI escape codes. + +Core Features: + - **Log File Management**: Removes old logs to prevent excessive storage usage. + - **Project File Detection**: Verifies whether a file belongs to the project. + - **Path Resolution**: Converts absolute paths into project-relative paths. + - **ANSI Escape Code Removal**: Cleans formatted terminal output. + - **Module Execution**: Supports a main entry point for potential extensions. + +Usage: + To clean up old log files: + from file_utils import manage_logfiles + manage_logfiles(configs=CONFIGS) + + To check if a file belongs to the project: + from file_utils import is_project_file + is_project_file("scripts/devops-workflow.py") + +Dependencies: + - sys - Handles system interactions. + - re - Provides regex utilities for ANSI escape sequence removal. + - pathlib - Handles file system operations. + - lib.system_variables - Imports project-wide settings. + - lib.log_utils - Logs file management operations. + +Global Behavior: + - Log files are removed only when exceeding the maximum allowed limit. + - Project-relative paths exclude `.py` extensions for consistency. + - ANSI escape codes are removed without altering message content. + - The `main()` function serves as a placeholder for future extensions. + +CLI Integration: + This module is primarily used for internal utilities but can be executed directly. + +Example Execution: + ```python + from file_utils import relative_path + print(relative_path("/absolute/path/to/script.py")) + ``` + +Expected Behavior: + - Successfully manages log files without exceeding storage limits. + - Converts absolute paths to project-relative paths when applicable. + - Strips ANSI escape sequences while preserving readable content. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to file system or logging issues. +""" + +FUNCTION_DOCSTRINGS = { + "is_project_file": """ + Function: is_project_file(filename: str) -> bool + Description: + Determines if a given file path belongs to the project directory structure. + + Parameters: + - filename (str): The absolute or relative file path to be checked. + + Returns: + - bool: True if the file is within the project directory, False otherwise. + + Example: + >>> is_project_file("appflow_tracer/tracing.py") + True + >>> is_project_file("/usr/lib/python3.8/external.py") + False + + Behavior: + - Resolves the absolute path before performing the check. + - Returns False if the filename is None or an empty string. + + Error Handling: + - Gracefully handles unexpected inputs such as None or invalid paths. + """, + "manage_logfiles": """ + Function: manage_logfiles(configs: dict = None) -> list + Description: + Manages log file storage by removing old logs if the number exceeds a configured limit. + + Parameters: + - configs (dict, optional): Configuration dictionary specifying: + - `"max_logfiles"`: Maximum number of log files to retain. + Defaults to the global `max_logfiles` setting if missing. + + Returns: + - list: A list of deleted log file paths. + + Workflow: + 1. Identifies log files in the configured directory. + 2. Sorts log files by modification time. + 3. Deletes excess log files if the count exceeds the threshold. + 4. Logs deletions using `log_utils.log_message()`. + + Notes: + - Ensures logging operations respect `configs["logging"]["enable"]`. + - If no logs exceed the threshold, returns an empty list. + + Error Handling: + - Catches `OSError` if a file cannot be deleted. + - Logs errors using `log_utils.log_message()`. + """, + "relative_path": """ + Function: relative_path(filepath: str) -> str + Description: + Converts an absolute file path into a project-relative path. + + Parameters: + - filepath (str): The absolute file path to convert. + + Returns: + - str: The relative path within the project, or the original path if it + cannot be converted. + + Example: + >>> relative_path("/path/to/project/module.py") + "module" + + Behavior: + - If the file is outside the project directory, returns the original path. + - Removes the `.py` extension for consistency. + + Error Handling: + - If the path is not within the project, returns the original file name. + """, + "remove_ansi_escape_codes": """ + Function: remove_ansi_escape_codes(text: str) -> str + Description: + Removes ANSI escape sequences from a string. + + Parameters: + - text (str): The input string that may contain ANSI escape codes. + + Returns: + - str: A new string with all ANSI escape codes removed. + + Example: + >>> remove_ansi_escape_codes("\\x1b[31mThis is red text\\x1b[0m") + "This is red text" + + Behavior: + - Strips ANSI escape codes while preserving readable content. + - Used for cleaning log messages or terminal output. + + Error Handling: + - Ensures that formatted messages remain readable without altering text. + """, + "main": """ + Function: main() -> None + Description: + Main entry point for the module. + + Returns: + - None: The function does not perform any operations. + + Behavior: + - Serves as a placeholder for future extensions. + - Ensures the module can be executed as a standalone script. + + Error Handling: + - None required as the function is currently a placeholder. + """, +} + +VARIABLE_DOCSTRINGS = { + "project_root": """ + - Description: Root directory of the project. + - Type: Path + - Usage: Used for resolving project-relative file paths. + """, + "project_logs": """ + - Description: Directory where log files are stored. + - Type: Path + - Usage: Ensures centralized logging across the project. + """, + "max_logfiles": """ + - Description: Maximum number of log files to retain per package. + - Type: int + - Usage: Enforces log retention policies to prevent excessive storage use. + """, + "category": """ + - Description: Namespace containing ANSI color codes for categorized logging. + - Type: SimpleNamespace + - Usage: Used in logging functions to color-code output messages. + + Categories: + - `calls` (Green): Logs function calls. + - `critical` (Red Background): Indicates critical errors. + - `debug` (Cyan): Logs debugging messages. + - `error` (Bright Red): Indicates errors. + - `imports` (Blue): Logs module imports. + - `info` (White): Logs informational messages. + - `returns` (Yellow): Logs function return values. + - `warning` (Red): Logs warning messages. + - `reset` (Default): Resets terminal color formatting. + """, +} diff --git a/packages/appflow_tracer/lib/.pydocs/pydoc.log_utils.py b/packages/appflow_tracer/lib/.pydocs/pydoc.log_utils.py new file mode 100644 index 0000000..90d6d3d --- /dev/null +++ b/packages/appflow_tracer/lib/.pydocs/pydoc.log_utils.py @@ -0,0 +1,215 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/lib/log_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/appflow_tracer/lib/log_utils.py + +Description: + The log_utils.py module provides structured logging utilities for handling + console and file-based logging. It ensures formatted, categorized logs with + support for custom levels, structured data, and ANSI-colored output. + +Core Features: + - **Structured Log Messages**: Formats logs in a consistent manner. + - **Console and File Logging**: Sends logs to both the console and log files. + - **Custom Log Levels**: Supports INFO, WARNING, ERROR, DEBUG, etc. + - **ANSI Color Support**: Enables colored output for terminal logs. + - **JSON Data Logging**: Logs structured JSON data when required. + +Usage: + To log a structured message: + from log_utils import log_message + log_message("System initialized", category.info.id, json_data={"status": "ready"}) + + To log a warning message: + log_message("Configuration file missing", category.warning.id) + +Dependencies: + - sys - Handles system interactions. + - json - Enables structured JSON-based logging. + - logging - Provides core logging functionalities. + - datetime - Manages log timestamps. + - lib.system_variables - Loads global configuration settings. + +Global Behavior: + - Logs messages to both console and files based on configuration settings. + - Maps log categories to appropriate logging levels (INFO, DEBUG, ERROR, etc.). + - Ensures JSON data is formatted properly if included in log messages. + - Supports disabling console logs while retaining file-based logs. + +CLI Integration: + This module primarily serves as an internal utility but can be extended. + +Example Execution: + ```python + from log_utils import log_message + log_message("Initialization complete", category.info.id) + ``` + +Expected Behavior: + - Ensures that logging configurations determine output destinations. + - Formats log messages consistently with timestamps and levels. + - Applies ANSI color formatting to enhance log visibility in terminals. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to logging configuration issues. +""" + +FUNCTION_DOCSTRINGS = { + "log_message": """ + Function: log_message( + message: str, + log_category: str = "INFO", + json_data: dict = None, + serialize_json: bool = False, + configs: dict = None, + handler: logging.Logger = None + ) -> None + Description: + Logs a structured message with optional JSON data to both console and log files. + + Parameters: + - message (str): The main log message. + - log_category (str, optional): The log level/category (e.g., category.info.id, category.warning.id). + - json_data (dict, optional): Additional structured JSON data to log. + - serialize_json (bool, optional): If True, serializes `json_data` into a JSON string. + - configs (dict, optional): Configuration dictionary. Defaults to global `CONFIGS` if not provided. + - handler (logging.Logger, optional): The specific logger instance to use. + + Raises: + - KeyError: If the provided log category is invalid. + - TypeError: If `json_data` is not a dictionary when `serialize_json` is True. + + Returns: + - None + + Workflow: + 1. Determines the correct log level based on `log_category`. + 2. Serializes JSON data if `serialize_json` is enabled. + 3. Logs the message to a file if file logging is enabled. + 4. Displays the message in the console if tracing is enabled. + + Example: + >>> log_message("System initialized", category.info.id) + >>> log_message("Missing config", category.warning.id) + >>> log_message("Debug details", json_data={"module": "log_utils"}) + """, + "output_logfile": """ + Function: output_logfile( + logger: logging.Logger, + message: str, + log_category: str = "INFO", + json_data: dict = None + ) -> None + Description: + Writes a structured log message to a designated log file. + + Parameters: + - logger (logging.Logger): The logger instance used for writing logs. + - message (str): The log message text. + - log_category (str, optional): The log level/category (defaults to "INFO"). + - json_data (dict, optional): Additional structured JSON data for the log entry. + + Raises: + - OSError: If the log file cannot be accessed or written to. + + Returns: + - None + + Workflow: + 1. Formats the log message with category and timestamp. + 2. Appends structured JSON data if provided. + 3. Writes the log entry to the designated log file. + + Example: + >>> logger = logging.getLogger("app_logger") + >>> output_logfile(logger, "This is a log message", category.debug.id) + """, + "output_console": """ + Function: output_console( + message: str, + log_category: str, + json_data: dict = None, + configs: dict = None + ) -> None + Description: + Displays a structured log message in the console with optional ANSI color formatting. + + Parameters: + - message (str): The main message to display. + - log_category (str): The logging category (e.g., category.info.id, category.error.id). + - json_data (dict, optional): Additional structured JSON data for output. + - configs (dict, optional): Configuration dictionary for colors and formatting. + + Raises: + - KeyError: If an invalid log category is provided. + - TypeError: If `json_data` is not a dictionary. + + Returns: + - None + + Workflow: + 1. Determines the ANSI color for the log category. + 2. Formats the message with ANSI color codes. + 3. Prints the formatted message to the console. + 4. Displays structured JSON data if provided. + + Example: + >>> output_console("Service started", category.info.id) + >>> output_console("Config warning", category.warning.id, {"path": "/etc/config"}) + """, + "main": """ + Function: main() -> None + Description: + Main entry point for the module. + + Returns: + - None: The function does not perform any operations. + + Behavior: + - Serves as a placeholder for future extensions. + - Ensures the module can be executed as a standalone script. + + Error Handling: + - None required as the function is currently a placeholder. + """, +} + +VARIABLE_DOCSTRINGS = { + "default_indent": """ + - Description: Defines the default indentation level for JSON output formatting. + - Type: int + - Usage: Used in JSON dumps to maintain structured formatting. + """, + "category": """ + - Description: Namespace containing ANSI color codes for categorized logging. + - Type: SimpleNamespace + - Usage: Used in logging functions to color-code output messages. + + Categories: + - `calls` (Green): Logs function calls. + - `critical` (Red Background): Indicates critical errors. + - `debug` (Cyan): Logs debugging messages. + - `error` (Bright Red): Indicates errors. + - `imports` (Blue): Logs module imports. + - `info` (White): Logs informational messages. + - `returns` (Yellow): Logs function return values. + - `warning` (Red): Logs warning messages. + - `reset` (Default): Resets terminal color formatting. + """, + "log_levels": """ + - Description: Maps log categories to their respective logging levels. + - Type: dict[str, int] + - Usage: Used in `log_message()` to determine the correct log level dynamically. + + Example Mapping: + - `category.calls.id` → `logging.INFO` + - `category.returns.id` → `logging.DEBUG` + - `category.warning.id` → `logging.WARNING` + - `category.error.id` → `logging.ERROR` + - `category.critical.id` → `logging.CRITICAL` + """, +} diff --git a/packages/appflow_tracer/lib/.pydocs/pydoc.serialize_utils.py b/packages/appflow_tracer/lib/.pydocs/pydoc.serialize_utils.py new file mode 100644 index 0000000..579880a --- /dev/null +++ b/packages/appflow_tracer/lib/.pydocs/pydoc.serialize_utils.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/lib/serialize_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/appflow_tracer/lib/serialize_utils.py + +Description: + The serialize_utils.py module provides functions for data serialization + and code sanitization, ensuring JSON compatibility and clean parsing. + +Core Features: + - **Safe Serialization**: Converts Python objects to JSON-friendly formats. + - **String Sanitization**: Cleans and trims code strings while removing comments. + - **Structured Logging Integration**: Logs serialization results using `log_utils`. + +Usage: + To safely serialize a Python object: + from serialize_utils import safe_serialize + result = safe_serialize({"key": "value"}, configs=CONFIGS) + + To remove comments from a line of code: + from serialize_utils import sanitize_token_string + clean_code = sanitize_token_string("some_code() # remove this comment") + +Dependencies: + - json - Enables structured JSON serialization. + - tokenize - Tokenizes code for proper comment removal. + - io.StringIO - Handles text processing for tokenization. + - lib.system_variables - Provides project-wide settings. + - log_utils - Supports structured logging of serialization operations. + +Global Behavior: + - `safe_serialize()` gracefully handles non-serializable objects. + - `sanitize_token_string()` removes comments while preserving meaningful text. + - Ensures logging is handled based on provided configurations. + +Expected Behavior: + - Logs structured serialization results when enabled. + - JSON serialization avoids breaking due to unserializable objects. + - Comments are correctly stripped without altering the main code structure. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to serialization or parsing errors. +""" + +FUNCTION_DOCSTRINGS = { + "safe_serialize": """ + Function: safe_serialize( + data: any, + configs: dict, + verbose: bool = False + ) -> dict + Description: + Converts Python objects into a JSON-compatible format with metadata. + + Parameters: + - data (any): The Python object to serialize. + - configs (dict): Configuration dictionary for logging and debugging. + - verbose (bool, optional): If True, formats JSON output with indentation. + + Raises: + - TypeError: If the provided data is not serializable. + - ValueError: If there is an issue converting data to JSON. + + Returns: + - dict: A structured response containing serialization results: + - `success` (bool): Indicates if serialization was successful. + - `serialized` (str): JSON string of serialized data or an error message. + - `type` (str): The type of the original object. + - `error` (str, optional): Error message if serialization failed. + + Workflow: + 1. Attempts to serialize the input data using `json.dumps()`. + 2. If serialization fails, checks for attributes (`__dict__`) and serializes them. + 3. If the object is iterable, converts it into a list. + 4. Returns a structured response indicating success or failure. + + Example: + >>> safe_serialize({"key": "value"}, configs=configs) + {'success': True, 'serialized': '{"key": "value"}', 'type': 'dict'} + + >>> safe_serialize(object(), configs=configs) + {'success': False, 'serialized': '[Unserializable data]', 'type': 'object', 'error': 'TypeError'} + """, + "sanitize_token_string": """ + Function: sanitize_token_string(line: str) -> str + Description: + Removes trailing comments and excess whitespace from a line of code. + + Parameters: + - line (str): A single line of text that may contain comments and extra spaces. + + Raises: + - Exception: If an unexpected error occurs while parsing tokens. + + Returns: + - str: The sanitized version of the input line with comments removed. + + Workflow: + 1. Tokenizes the input string using Python's `tokenize` module. + 2. Iterates through tokens and removes comments (`# ...`). + 3. Preserves meaningful text while ensuring proper spacing. + 4. Returns the cleaned version of the input line. + + Example: + >>> sanitize_token_string("some_code() # this is a comment") + 'some_code()' + + >>> sanitize_token_string(" another_line ") + 'another_line' + """, + "main": """ + Function: main() -> None + Description: + Main entry point for the module. + + Returns: + - None: The function does not perform any operations. + + Behavior: + - Serves as a placeholder for future extensions. + - Ensures the module can be executed as a standalone script. + + Error Handling: + - None required as the function is currently a placeholder. + """, +} + +VARIABLE_DOCSTRINGS = { + "default_indent": """ + - Description: Defines the default indentation level for JSON output formatting. + - Type: int + - Usage: Used in JSON dumps to maintain structured formatting. + """, + "category": """ + - Description: Namespace containing ANSI color codes for categorized logging. + - Type: SimpleNamespace + - Usage: Used in logging functions to color-code output messages. + + Categories: + - `calls` (Green): Logs function calls. + - `critical` (Red Background): Indicates critical errors. + - `debug` (Cyan): Logs debugging messages. + - `error` (Bright Red): Indicates errors. + - `imports` (Blue): Logs module imports. + - `info` (White): Logs informational messages. + - `returns` (Yellow): Logs function return values. + - `warning` (Red): Logs warning messages. + - `reset` (Default): Resets terminal color formatting. + """, +} diff --git a/packages/appflow_tracer/lib/.pydocs/pydoc.trace_utils.py b/packages/appflow_tracer/lib/.pydocs/pydoc.trace_utils.py new file mode 100644 index 0000000..a932a4f --- /dev/null +++ b/packages/appflow_tracer/lib/.pydocs/pydoc.trace_utils.py @@ -0,0 +1,235 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/appflow_tracer/lib/trace_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/appflow_tracer/lib/trace_utils.py + +Description: + Function Call and Execution Flow Tracing Utilities + This module provides **real-time function execution tracing** within the framework. + It captures **function calls and return values**, logs structured execution flow, + and ensures debugging visibility with minimal performance overhead. + +Core Features: + - **Function Call Tracing**: Logs function calls, arguments, and execution order. + - **Execution Flow Logging**: Captures return values and structured execution flow. + - **Project Scope Enforcement**: Excludes system functions and external dependencies. + - **Selective Filtering**: Ignores known logging utilities and non-essential functions. + - **Configurable Logging**: Enables logging dynamically based on configuration settings. + +Usage: + To enable tracing and track function calls: + import trace_utils + trace_utils.start_tracing() + +Dependencies: + - sys - Provides system-level tracing hooks. + - json - Enables structured JSON serialization for tracing. + - inspect - Extracts function metadata dynamically. + - logging - Supports structured execution logging. + - lib.system_variables - Provides logging categories. + - lib.log_utils - Manages structured logging output. + - lib.file_utils - Validates project file paths. + - lib.serialize_utils - Handles safe data serialization. + +Global Behavior: + - Tracing activates only when **enabled in the configuration**. + - Calls, returns, and execution paths are **logged dynamically**. + - Non-project files and system-level operations are **excluded from tracing**. + - Return values are **serialized safely** for structured logging. + +Expected Behavior: + - Tracing logs execution flow without excessive system-level noise. + - Only functions within the **project scope** are traced. + - Function return values are safely **serialized for debugging**. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to configuration issues or execution tracing errors. + +Example: + from trace_utils import start_tracing + start_tracing() +""" + +FUNCTION_DOCSTRINGS = { + "start_tracing": """ + Function: start_tracing( + logger: logging.Logger = None, + configs: dict = None + ) -> None + Description: + Initializes function execution tracing. + + Parameters: + - logger (logging.Logger, optional): Logger instance for structured logging. Defaults to None. + - configs (dict, optional): Configuration dictionary controlling tracing behavior. + + Raises: + - RuntimeError: If tracing fails due to invalid configurations. + + Returns: + - None + + Workflow: + 1. Sets up function tracing based on configuration. + 2. Ensures logging is enabled before activating tracing. + 3. Calls `trace_all()` to generate a trace handler. + + Example: + >>> start_tracing() + # Tracing starts using the global configuration. + """, + "trace_all": """ + Function: trace_all( + logger: logging.Logger, + configs: dict + ) -> Callable + Description: + Generates a function that traces execution flow within project-specific files. + + Parameters: + - logger (logging.Logger): Logger instance for structured logging. + - configs (dict): Configuration dictionary controlling tracing behavior. + + Raises: + - ValueError: If tracing configurations are missing or invalid. + + Returns: + - Callable: A trace function that can be passed to `sys.settrace()`. + + Workflow: + 1. Ensures tracing configurations are valid. + 2. Defines `trace_events()` to handle function call and return tracing. + 3. Returns the trace handler function. + + Example: + >>> sys.settrace(trace_all(logger, configs)) + # Function tracing begins dynamically. + """, + "trace_events": """ + Function: trace_events( + frame: FrameType, + event: str, + arg: object + ) -> None + Description: + Processes function execution events (calls and returns). + + Parameters: + - frame (FrameType): Execution frame of the function call. + - event (str): The event type ("call" or "return"). + - arg (object): Return value for "return" events. + + Raises: + - Exception: If an error occurs while processing the event. + + Returns: + - None + + Workflow: + 1. Identifies function call and return events. + 2. Ensures tracing is restricted to project-specific files. + 3. Calls `call_events()` for function calls. + 4. Calls `return_events()` for function returns. + + Example: + >>> trace_events(frame, "call", None) + # Logs the function call if it belongs to the project scope. + """, + "call_events": """ + Function: call_events( + logger: logging.Logger, + frame: FrameType, + filename: str, + arg: object, + configs: dict + ) -> None + Description: + Handles logging of function call events. + + Parameters: + - logger (logging.Logger): Logger for structured execution. + - frame (FrameType): Execution frame at the function call site. + - filename (str): The file where the function call originated. + - arg (object): Arguments passed to the function. + - configs (dict): Configuration settings. + + Returns: + - None + + Workflow: + 1. Extracts caller function details. + 2. Logs function execution metadata, including arguments. + 3. Filters out system and external function calls. + + Example: + >>> call_events(logger, frame, "file.py", args, configs) + """, + "return_events": """ + Function: return_events( + logger: logging.Logger, + frame: FrameType, + filename: str, + arg: object, + configs: dict + ) -> None + Description: + Handles logging of function return events. + + Parameters: + - logger (logging.Logger): Logger for structured execution. + - frame (FrameType): Execution frame at the function return site. + - filename (str): The file where the return event occurred. + - arg (object): The function's return value. + - configs (dict): Configuration settings. + + Returns: + - None + + Workflow: + 1. Captures return values and execution flow. + 2. Serializes return data for structured debugging. + 3. Filters out system-level returns to avoid excessive logs. + + Example: + >>> return_events(logger, frame, "file.py", return_value, configs) + """, + "main": """ + Function: main() -> None + Description: + Main entry point for the module. + + Returns: + - None: This function does not perform any operations. + + Behavior: + - Serves as a placeholder for future extensions. + - Ensures the module can be executed as a standalone script. + + Example: + >>> python trace_utils.py + # Runs the script without performing any operations. + """ +} + +VARIABLE_DOCSTRINGS = { + "category": """ + - Description: Namespace containing ANSI color codes for categorized logging. + - Type: SimpleNamespace + - Usage: Used in logging functions to color-code output messages. + + Categories: + - `calls` (Green): Logs function calls. + - `critical` (Red Background): Indicates critical errors. + - `debug` (Cyan): Logs debugging messages. + - `error` (Bright Red): Indicates errors. + - `imports` (Blue): Logs module imports. + - `info` (White): Logs informational messages. + - `returns` (Yellow): Logs function return values. + - `warning` (Red): Logs warning messages. + - `reset` (Default): Resets terminal color formatting. + """ +} diff --git a/packages/appflow_tracer/lib/__init__.py b/packages/appflow_tracer/lib/__init__.py index 4350997..3e42551 100755 --- a/packages/appflow_tracer/lib/__init__.py +++ b/packages/appflow_tracer/lib/__init__.py @@ -3,51 +3,19 @@ # File: ./packages/appflow_tracer/lib/__init__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/lib/__init__.py +# Standard library imports - Core system module +import sys -Description: - AppFlow Tracer Library Initialization +# Standard library imports - File system-related module +from pathlib import Path - This file defines the `lib` subpackage within the `appflow_tracer` framework. It provides - access to essential utility modules required for logging, file operations, tracing, and - serialization within the framework. - -Core Features: - - **Subpackage Initialization**: Ensures that the `lib` directory is recognized as a Python package. - - **Utility Module Exposure**: Facilitates direct access to key framework utilities. - - **Structured Imports**: Enables clean and maintainable access to core functionality. - -Submodules: - - `file_utils`: Provides file and directory management utilities. - - `log_utils`: Handles structured logging and message formatting. - - `trace_utils`: Supports runtime tracing and performance monitoring. - - `serialize_utils`: Manages data serialization and deserialization. - -Usage: - To import specific utilities from this package: - ```python - from packages.appflow_tracer.lib import log_utils, file_utils - - log_utils.log_message("Example log message") - file_utils.manage_logfiles() - ``` - -Dependencies: - - None (This module only manages imports) - -Example: - ```python - from packages.appflow_tracer.lib import trace_utils - trace_utils.start_tracing() - ``` -""" +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import and expose key submodules from . import ( file_utils, log_utils, - trace_utils, serialize_utils, trace_utils ) @@ -55,7 +23,10 @@ __all__ = [ "file_utils", "log_utils", - "trace_utils", "serialize_utils", "trace_utils" ] + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/appflow_tracer/lib/file_utils.py b/packages/appflow_tracer/lib/file_utils.py index ee984f5..8922bfc 100755 --- a/packages/appflow_tracer/lib/file_utils.py +++ b/packages/appflow_tracer/lib/file_utils.py @@ -3,61 +3,17 @@ # File: ./packages/appflow_tracer/lib/file_utils.py __version__ = "0.1.0" ## Package version -""" -File: packages/appflow_tracer/lib/file_utils.py - -Description: - File and Log Management Utilities - This module provides helper functions for managing log files, resolving - relative paths, and cleaning terminal output by removing ANSI escape codes. - -Core Features: - - **Log File Management**: Removes old logs to prevent excessive storage usage. - - **Project File Detection**: Verifies whether a file belongs to the project. - - **Path Resolution**: Converts absolute paths into project-relative paths. - - **ANSI Escape Code Removal**: Cleans formatted terminal output. - -Usage: - To clean up old log files: - ```python - manage_logfiles(configs=CONFIGS) - ``` - - To check if a file belongs to the project: - ```python - is_project_file("scripts/devops-workflow.py") - ``` - -Dependencies: - - sys - - re - - pathlib - - lib.system_variables (for project settings) - -Global Variables: - - Uses `project_root`, `project_logs`, and `category` from `lib.system_variables`. - -Expected Behavior: - - Log files are removed only when exceeding the maximum allowed limit. - - Project-relative paths exclude `.py` extensions for consistency. - - ANSI escape codes are removed without altering message content. - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to file system or logging issues. - -Example: - ```python - from file_utils import relative_path - print(relative_path("/absolute/path/to/script.py")) - ``` -""" - +# Standard library imports - Core system module import sys + +# Standard library imports - Utility module import re +# Standard library imports - File system-related module from pathlib import Path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + # Import system_variables from lib.system_variables from lib.system_variables import ( project_root, @@ -74,28 +30,6 @@ def is_project_file( filename: str ) -> bool: - """ - Determine if a given file path belongs to the project directory structure. - - This function verifies whether the specified `filename` is located within - the project's root directory and is not an external dependency. - - Args: - filename (str): The absolute or relative file path to be checked. - - Returns: - bool: True if the file is within the project directory, False otherwise. - - Example: - >>> is_project_file("appflow_tracer/tracing.py") - True - >>> is_project_file("/usr/lib/python3.8/external.py") - False - - Notes: - - If the filename is `None` or an empty string, the function returns `False`. - - The function safely resolves the absolute path before performing the check. - """ if not filename: # log_utils.log_message("is_project_file received None or empty filename.", category.info.id) @@ -111,34 +45,6 @@ def is_project_file( def manage_logfiles( configs: dict = None ) -> list: - """ - Manage log file storage by removing old logs if the number exceeds a configured limit. - - This function prevents log directories from growing indefinitely by: - - Checking the current number of log files in each log subdirectory. - - Deleting the oldest logs **only if** the total count exceeds the allowed limit. - - Args: - configs (dict, optional): Configuration dictionary that specifies: - - `"max_logfiles"`: Maximum number of log files to retain. - Defaults to `None`, in which case the global `max_logfiles` setting is used. - - Raises: - OSError: If an error occurs while attempting to delete log files. - - Returns: - list: A list of deleted log file paths. - - Workflow: - 1. Sorts log files by modification time (oldest first). - 2. Identifies files exceeding the limit. - 3. Deletes excess log files. - 4. Logs deletions using `log_utils.log_message()`. - - Notes: - - The function ensures logging operations respect the `configs["logging"]["enable"]` flag. - - If no logs exceed the threshold, no deletions occur, and an empty list is returned. - """ logs_dir = Path(configs["logging"]["logs_dirname"]) # Target the correct logs directory deleted_logs = [] @@ -166,28 +72,6 @@ def manage_logfiles( def relative_path( filepath: str ) -> str: - """ - Convert an absolute file path into a project-relative path. - - This function maps the given absolute path to the project’s directory structure. - If the file is outside the project, it returns the original path as a fallback. - The `.py` extension is removed from the resulting path for consistency. - - Args: - filepath (str): The absolute file path to convert. - - Returns: - str: The relative path within the project, or the original path if it - cannot be converted. - - Example: - >>> relative_path("/path/to/project/module.py") - "module" - - Notes: - - If the file is not within the project directory, the original path is returned. - - The `.py` extension is removed for consistency in logging and output formatting. - """ try: return str(Path(filepath).resolve().relative_to(project_root)).replace(".py", "") @@ -197,27 +81,16 @@ def relative_path( def remove_ansi_escape_codes( text: str ) -> str: - """ - Remove ANSI escape sequences from a string. - This function is used to clean up log messages or terminal output by - stripping out escape codes that produce colored or formatted text. - The resulting string contains only plain text. - - Args: - text (str): The input string that may contain ANSI escape codes. - - Returns: - str: A new string with all ANSI escape codes removed. + ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])') + return ansi_escape.sub('', text) - Example: - >>> remove_ansi_escape_codes("\x1b[31mThis is red text\x1b[0m") - "This is red text" +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) - Notes: - - ANSI escape codes are commonly used for terminal colorization. - - The function ensures that formatted messages remain readable. - """ +def main() -> None: + pass - ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])') - return ansi_escape.sub('', text) +if __name__ == "__main__": + main() diff --git a/packages/appflow_tracer/lib/log_utils.py b/packages/appflow_tracer/lib/log_utils.py index fabe87d..21a918f 100755 --- a/packages/appflow_tracer/lib/log_utils.py +++ b/packages/appflow_tracer/lib/log_utils.py @@ -3,66 +3,21 @@ # File: ./packages/appflow_tracer/lib/log_utils.py __version__ = "0.1.0" ## Package version -""" -File: packages/appflow_tracer/lib/log_utils.py - -Description: - Structured Logging Utilities - This module provides structured logging functionality, enabling detailed - logging to both console and log files. It supports logging levels, - custom formats, and structured data output. - -Core Features: - - **Structured Log Messages**: Formats logs in a consistent manner. - - **Console and File Logging**: Sends logs to both console and files. - - **Custom Log Levels**: Supports INFO, WARNING, ERROR, DEBUG, etc. - - **ANSI Color Support**: Enables colored output for console logs. - -Usage: - To log a structured message: - ```python - log_message("This is a log entry", category.info.id, json_data={"key": "value"}) - ``` - - To log a message with a warning level: - ```python - log_message("Something might be wrong", category.warning.id) - ``` - -Dependencies: - - sys - - json - - logging - - datetime - - lib.system_variables (for global settings) - - file_utils (for log file management) - -Global Variables: - - Uses `category` and `default_indent` from `lib.system_variables`. - -Expected Behavior: - - Logs are written to both the console and log files based on configuration settings. - - JSON data is formatted properly if included in log messages. - - Log categories map to appropriate logging levels (INFO, DEBUG, ERROR, etc.). - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to logging configuration issues. - -Example: - ```python - from log_utils import log_message - log_message("Initialization complete", category.info.id) - ``` -""" - +# Standard library imports - Core system module import sys +# Standard library imports - Utility modules import json # If structured data is part of logging import logging -# If timestamps are used or manipulated -from datetime import datetime +# Standard library imports - Date and time handling +from datetime import datetime # If timestamps are used or manipulated + +# Standard library imports - File system-related module +from pathlib import Path + +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import category from system_variables from lib.system_variables import ( @@ -90,41 +45,6 @@ def log_message( configs: dict = None, handler: logging.Logger = None ) -> None: - """ - Log a structured message with optional JSON data to both console and log files. - - This function supports multiple log levels, formats messages in a structured manner, - and appends additional structured JSON data if provided. The behavior is influenced - by global configurations, such as whether logs should be written to a file or displayed - on the console. - - Args: - message (str): The main log message. - log_category (str, optional): The log level/log_category. e.g.: - category.info.id, category.warning.id, category.error.id but defaults to category.info.id. - json_data (dict, optional): Additional structured JSON data to log. - serialize_json (bool, optional): If True, the `json_data` is serialized into a JSON string. - configs (dict, optional): Configuration dictionary. Defaults to global `CONFIGS` if not provided. - handler (logging.Logger, optional): The specific logger instance to use. Defaults to the global logger. - - Raises: - KeyError: If the log category provided is invalid. - TypeError: If `json_data` is not a dictionary when `serialize_json` is True. - - Returns: - None - - Workflow: - 1. Determines the correct log level based on `log_category`. - 2. Serializes JSON data if `serialize_json` is enabled. - 3. Logs the message to a file if file logging is enabled. - 4. Displays the message in the console if tracing is enabled. - - Example: - >>> log_message("This is an info message") - >>> log_message("This is a warning", category.warning.id) - >>> log_message("Structured log", json_data={"key": "value"}) - """ # configs = configs or CONFIGS # Default to global CONFIGS if not provided # print(f'log_message(configs): {json.dumps(configs, indent=default_indent, ensure_ascii=False)}') @@ -153,34 +73,6 @@ def output_logfile( log_category: str = "INFO", json_data: dict = None ) -> None: - """ - Write a structured log message to a log file. - - This function appends the formatted log message to a log file associated with the - given logger. If structured data (`json_data`) is provided, it is included in the - log entry. - - Args: - logger (logging.Logger): The logger instance used for writing logs. - message (str): The log message text. - log_category (str, optional): The log level/log_category. Defaults to "INFO". - json_data (dict, optional): Additional structured JSON data for the log entry. - - Raises: - OSError: If the log file cannot be accessed or written to. - - Returns: - None - - Workflow: - 1. Formats the log message with category and timestamp. - 2. Appends structured JSON data if provided. - 3. Writes the log entry to the designated log file. - - Example: - >>> logger = logging.getLogger("example_logger") - >>> output_logfile(logger, "This is a log message", {"extra_key": "value"}) - """ logfile_message = f'{log_category}: {message}' @@ -199,37 +91,6 @@ def output_console( json_data: dict = None, configs: dict = None ) -> None: - """ - Display a structured log message in the console with optional ANSI color formatting. - - This function formats the given message according to the specified logging log-category - and appends structured JSON data if provided. ANSI color codes are applied based on - the logging configuration. - - Args: - message (str): The main message to display. - log_category (str): The logging log_category. e.g.: - category.info.id, category.warning.id, category.error.id - json_data (dict, optional): Additional structured JSON data for output. - configs (dict, optional): Configuration dictionary for colors and formatting. - - Raises: - KeyError: If an invalid log category is provided. - TypeError: If `json_data` is not a dictionary. - - Returns: - None - - Workflow: - 1. Determines the ANSI color for the log category. - 2. Formats the message with ANSI color codes. - 3. Prints the formatted message to the console. - 4. Displays structured JSON data if provided. - - Example: - >>> output_console("This is an info message", category.info.id) - >>> output_console("This is a warning", category.warning.id, {"details": "some data"}) - """ color = configs["colors"].get(log_category.upper(), configs["colors"]["RESET"]) if not color.startswith("\033"): # Ensure it's an ANSI color code @@ -249,3 +110,13 @@ def output_console( else: # Pretty-print JSON while keeping Unicode characters print(json.dumps(json_data, indent=default_indent, ensure_ascii=False)) + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/appflow_tracer/lib/serialize_utils.py b/packages/appflow_tracer/lib/serialize_utils.py index 863c837..cf41462 100755 --- a/packages/appflow_tracer/lib/serialize_utils.py +++ b/packages/appflow_tracer/lib/serialize_utils.py @@ -3,60 +3,23 @@ # File: ./packages/appflow_tracer/lib/serialize_utils.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/lib/serialize_utils.py +# Standard library imports - Core system module +import sys -Description: - Serialization and String Sanitization Utilities - This module provides helper functions for data serialization and - code sanitization, ensuring JSON compatibility and clean parsing. +# Standard library imports - Utility modules +import json # Handles JSON serialization and deserialization +import tokenize # Used for tokenizing Python source code -Core Features: - - **Safe Serialization**: Converts Python objects to JSON-friendly formats. - - **String Sanitization**: Cleans and trims code strings while removing comments. +# Standard library imports - IO operations +from io import StringIO # In-memory file-like object -Usage: - To safely serialize a Python object: - ```python - safe_serialize(data={"key": "value"}, configs=CONFIGS) - ``` +# Standard library imports - File system-related module +from pathlib import Path - To remove comments from a line of code: - ```python - sanitize_token_string(data="some_code() # this is a comment", configs=CONFIGS) - ``` +# Duplicate import removed: `json` was imported twice -Dependencies: - - json - - tokenize - - io.StringIO (for text processing) - - lib.system_variables (for project settings) - - log_utils (for logging serialized data) - -Global Variables: - - Uses `category` and `default_indent` from `lib.system_variables`. - -Expected Behavior: - - `safe_serialize()` should gracefully handle non-serializable objects. - - `sanitize_token_string()` should remove comments and preserve meaningful text. - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to serialization errors. - -Example: - ```python - from serialize_utils import safe_serialize, sanitize_token_string - print(safe_serialize({"name": "Alice"})) - ``` -""" - -import json -import tokenize - -from io import StringIO - -import json +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import category from system_variables from lib.system_variables import ( @@ -73,42 +36,6 @@ def safe_serialize( configs: dict, verbose: bool = False ) -> dict: - """ - Convert Python objects into a JSON-compatible serialized string with metadata. - - This function ensures that data is properly serialized into a JSON string format. - If an object is not serializable, it attempts to extract its attributes or provide - meaningful information instead of just a memory address. - - Args: - data (any): The Python object to serialize. - configs (dict): Configuration dictionary for logging and debugging. - verbose (bool, optional): If True, the JSON output is formatted with indentation. - - Raises: - TypeError: If the provided data is not serializable. - ValueError: If there is an issue converting data to JSON. - - Returns: - dict: A structured response containing serialization results. - - `success` (bool): Whether serialization was successful. - - `serialized` (str): JSON string of serialized data or an error message. - - `type` (str): The type of the original object. - - `error` (str, optional): Error message if serialization failed. - - Workflow: - 1. Attempts to serialize the input data using `json.dumps()`. - 2. If serialization fails, checks if the object has attributes (`__dict__`). - 3. If the object is iterable (list, tuple, set), converts it into a list. - 4. Returns a structured response indicating success or failure. - - Example: - >>> safe_serialize({"key": "value"}, configs=configs) - {'success': True, 'serialized': '{"key": "value"}', 'type': 'dict'} - - >>> safe_serialize(object(), configs=configs) - {'success': False, 'serialized': '[Unserializable data]', 'type': 'object', 'error': 'TypeError'} - """ try: json_dumps = json.dumps( @@ -177,35 +104,6 @@ def safe_serialize( return serialized_data def sanitize_token_string(line: str) -> str: - """ - Remove trailing comments and excess whitespace from a line of code. - - This function processes a line of code and removes inline comments while preserving - meaningful text. The result is a clean line of code without unnecessary annotations. - - Args: - line (str): A single line of text that may contain comments and extra spaces. - - Raises: - Exception: If an unexpected error occurs while parsing tokens. - - Returns: - str: The sanitized version of the input line, with comments and - unnecessary whitespace removed. - - Workflow: - 1. Tokenizes the input string using Python's `tokenize` module. - 2. Iterates through tokens and removes comments (`# ...`). - 3. Preserves meaningful text while ensuring proper spacing. - 4. Returns the cleaned version of the input line. - - Example: - >>> sanitize_token_string("some_code() # this is a comment") - 'some_code()' - - >>> sanitize_token_string(" another_line ") - 'another_line' - """ # # Legacy code: # try: @@ -241,3 +139,13 @@ def sanitize_token_string(line: str) -> str: return "".join(new_line).strip() # Trim spaces/tabs/newlines except Exception: return line.strip() # Ensure fallback trims spaces + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/appflow_tracer/lib/trace_utils.py b/packages/appflow_tracer/lib/trace_utils.py index 8aa3cd7..1748210 100755 --- a/packages/appflow_tracer/lib/trace_utils.py +++ b/packages/appflow_tracer/lib/trace_utils.py @@ -3,74 +3,23 @@ # File: ./packages/appflow_tracer/lib/trace_utils.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/lib/trace_utils.py - -Description: - Function Call and Execution Flow Tracing Utilities - This module provides **real-time function execution tracing** within the framework. - It captures **function calls and return values**, logs structured execution flow, - and ensures debugging visibility with minimal performance overhead. - -Core Features: - - **Function Call Tracing**: Logs function calls, arguments, and execution order. - - **Execution Flow Logging**: Captures return values and structured execution flow. - - **Project Scope Enforcement**: Excludes system functions and external dependencies. - - **Selective Filtering**: Ignores known logging utilities and non-essential functions. - - **Configurable Logging**: Enables logging dynamically based on configuration settings. - -Usage: - To enable tracing and track function calls: - ```python - import trace_utils - trace_utils.start_tracing() - ``` - -Dependencies: - - sys - - json - - inspect - - logging - - lib.system_variables (for project settings) - - lib.log_utils (for structured logging) - - lib.file_utils (for project file validation) - - lib.serialize_utils (for safe data serialization) - -Global Variables: - - Uses `category` from `lib.system_variables`. - -Primary Functions: - - `start_tracing(logger, configs)`: Initializes function call tracing dynamically. - - `trace_all(logger, configs)`: Creates a **trace function** for `sys.settrace()`. - - `trace_events(frame, event, arg)`: Handles function call and return event logging. - - `call_events(logger, frame, filename, arg, configs)`: Logs function calls. - - `return_events(logger, frame, filename, arg, configs)`: Logs function return values. - -Expected Behavior: - - Tracing activates only when **enabled in the configuration**. - - Calls, returns, and execution paths are **logged dynamically**. - - Non-project files and system-level operations are **excluded from tracing**. - - Return values are **serialized safely** for structured logging. - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to invalid configurations or execution tracing errors. - -Example: - ```python - from trace_utils import start_tracing - start_tracing() - ``` -""" - +# Standard library imports - Core system module import sys -import json +# Standard library imports - Utility modules +import json import inspect import logging -from typing import Callable +# Standard library imports - Type-related modules from types import FrameType +from typing import Callable + +# Standard library imports - File system-related module +from pathlib import Path + +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) from . import ( log_utils, @@ -87,28 +36,6 @@ def start_tracing( logger: logging.Logger = None, configs: dict = None ) -> None: - """ - Initialize and activate function call tracing. - - This function sets up **function execution tracing**, ensuring: - - **Function call and return events** are logged in a structured manner. - - **Only project-specific files** are traced, excluding system libraries. - - **Logging is enabled dynamically** based on the provided configuration. - - Args: - logger (logging.Logger, optional): Logger instance for structured logging. If None, a default logger is used. - configs (dict, optional): A dictionary containing tracing configurations. If None, the global CONFIGS will be used. - - Raises: - RuntimeError: If tracing fails due to invalid configurations. - - Returns: - None - - Example: - >>> start_tracing() - # Tracing begins using the global configuration. - """ # Initialize logger (logging.Logger) if None if logger is None: @@ -138,28 +65,6 @@ def trace_all( logger: logging.Logger, configs: dict ) -> Callable: - """ - Generate a function that traces execution flow within project-specific files. - - This function returns a **callable trace handler** that: - - **Logs function calls and returns**, including caller context. - - **Ensures logging is project-restricted**, excluding non-project dependencies. - - **Filters system function calls and internal logging utilities.** - - Args: - logger (logging.Logger): Logger instance for structured logging. - configs (dict): The configuration dictionary that controls tracing behavior. - - Raises: - ValueError: If tracing configurations are missing or invalid. - - Returns: - Callable: A trace function that can be passed to `sys.settrace()`. - - Example: - >>> sys.settrace(trace_all(logger, configs)) - # Tracing starts using the provided configuration. - """ # Ensure configs is valid before using it if not configs or "logging" not in configs: @@ -175,29 +80,6 @@ def trace_events( event: str, arg: object ) -> None: - """ - Process and log function execution events (calls and returns). - - This function is invoked for **each function call and return**, and it: - - **Identifies function calls** and logs caller details. - - **Handles return values**, including structured serialization. - - **Filters out non-project files** to prevent unnecessary logging. - - Args: - frame (FrameType): The execution frame when the event occurred. - event (str): The event type (`"call"` for function calls, `"return"` for returns). - arg (object): The return value if the event is a return. - - Raises: - Exception: If an error occurs while processing the event. - - Returns: - None - - Example: - >>> trace_events(frame, "call", None) - # Logs the function call if it's within the project scope. - """ # print(f'\nTracing activated in {__name__}\n') @@ -261,24 +143,6 @@ def call_events( arg: object, configs: dict ) -> None: - """ - Handles logging of function call events. - - This function: - - **Extracts caller details** including filename and function name. - - **Logs function invocation metadata** such as arguments and execution flow. - - **Filters out system and non-project calls** to keep logs relevant. - - Args: - logger (logging.Logger): Logger instance for logging structured execution. - frame (FrameType): The execution frame where the function call occurred. - filename (str): The source file where the function call was invoked. - arg (object): The arguments passed to the function. - configs (dict): The configuration dictionary. - - Returns: - None - """ try: @@ -332,24 +196,6 @@ def return_events( arg: object, configs: dict ) -> None: - """ - Handles logging of function return events. - - This function: - - **Captures return values** including their data type. - - **Serializes complex return values** for structured logging. - - **Logs execution flow and prevents excessive logging** for system functions. - - Args: - logger (logging.Logger): Logger instance for logging structured execution. - frame (FrameType): The execution frame where the function return occurred. - filename (str): The source file where the return event occurred. - arg (object): The function's return value. - configs (dict): The configuration dictionary. - - Returns: - None - """ try: @@ -421,3 +267,13 @@ def return_events( # pass # Ignore frames that cannot be inspected except Exception as e: logger.error(f'Error in trace_all return handling: {e}') + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/appflow_tracer/tracing.py b/packages/appflow_tracer/tracing.py index b903861..9810f88 100755 --- a/packages/appflow_tracer/tracing.py +++ b/packages/appflow_tracer/tracing.py @@ -3,89 +3,27 @@ # File: ./packages/appflow_tracer/tracing.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/appflow_tracer/tracing.py - -Description: - AppFlow Tracing System - This module provides structured logging and function call tracing, enabling - automatic function execution monitoring with minimal intrusion. It integrates - logging and tracing functionalities, ensuring accurate tracking of function - calls, return values, and execution flow. - -Core Features: - - **Function Call Tracing**: Automatically captures function calls, arguments, and return values. - - **Structured Logging**: Logs execution details in JSON format for debugging and auditing. - - **Self-Inspection**: When executed directly, logs its own execution for analysis. - - **Automatic Log Management**: Removes old log files to maintain storage efficiency. - - **Configurable Event Filtering**: Allows selective tracing of function calls and returns. - -Usage: - To enable function call tracing: - ```python - import tracing - tracing.setup_logging() - ``` - - To run the tracing system as a standalone tool: - ```bash - python tracing.py - ``` - -Dependencies: - - sys - - json - - inspect - - logging - - builtins - - pathlib - - datetime - - lib.system_variables (for project-wide configurations) - - lib.pkgconfig_loader (for configuration handling) - - lib.file_utils (for log file management) - - lib.log_utils (for structured logging) - - lib.trace_utils (for function call tracing) - -Global Variables: - - `LOGGING`: Boolean flag indicating whether logging has been initialized. - - `CONFIGS`: Stores the effective logging and tracing configurations. - - `logger`: Global logger instance used for structured logging. - -Primary Functions: - - `setup_logging(configs, logname_override, events)`: Initializes structured logging. - - `main()`: Entry point for standalone execution, setting up tracing and logging. - - `PrintCapture.emit(record)`: Captures print statements and redirects them to logs. - - `ANSIFileHandler.emit(record)`: Ensures log files do not contain ANSI escape sequences. - -Expected Behavior: - - Logs execution details when tracing is enabled. - - Logs function calls with arguments and return values. - - Maintains structured logs for debugging and execution tracking. - - Automatically removes older log files when exceeding retention limits. - -Exit Codes: - - `0`: Successful execution. - - `1`: Failure due to configuration or logging setup errors. - -Example: - ```python - from tracing import setup_logging - setup_logging() - ``` -""" - +# Standard library imports - Core system module import sys + +# Standard library imports - Built-in utilities +import builtins +import warnings + +# Standard library imports - Utility modules import json import inspect import logging -import builtins -import warnings +# Standard library imports - Date and time handling from datetime import datetime -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -96,6 +34,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + # Import system_variables from lib.system_variables from lib.system_variables import ( project_root, @@ -121,41 +62,6 @@ def setup_logging( logname_override: Optional[str] = None, events: Optional[Union[bool, dict]] = None ) -> Union[bool, dict]: - """ - Configures and initializes the global logging system. - - This function sets up the logging environment, creating log files and adding handlers - for both file-based and console-based logging. It ensures proper logging behavior - even when no configuration is provided. - - Args: - configs (dict, optional): A dictionary containing logging configurations. - If None, the default global configurations are used. - logname_override (str, optional): A custom name for the log file. - If None, the log file name is derived from the calling script. - events (bool, list, or dict, optional): - - `None` / `False` → Disables all event logging. - - `True` → Enables all event logging. - - `list` → Enables only specified events (e.g., ["call", "return"]). - - `dict` → Enables/disables events per user settings (e.g., {"call": True, "return": False}). - - Raises: - ValueError: If the provided logging configurations are not in a dictionary format. - - Returns: - dict: The effective logging configuration after applying defaults. - - Example: - >>> setup_logging() - { - "logging": { - "log_filename": "/path/to/logfile.log", - "max_logfiles": 5, - ... - }, - ... - } - """ # Ensure the variable exists globally global LOGGING, CONFIGS, logger @@ -256,30 +162,9 @@ def setup_logging( return CONFIGS class PrintCapture(logging.StreamHandler): - """ - Custom logging handler that captures print statements and logs them - while ensuring they are displayed in the console. - - This ensures that print statements are properly logged without affecting - real-time console output. - """ # def emit(self, record): def emit(self, record: logging.LogRecord) -> None: - """ - Custom logging handler that captures print statements and logs them - while ensuring they are displayed in the console. - - This ensures that print statements are properly logged without affecting - real-time console output. - - Args: - record (logging.LogRecord): The log record that contains information - about the log message to be captured and displayed. - - Returns: - None - """ log_entry = self.format(record) sys.__stdout__.write(log_entry + "\n") # Write to actual stdout @@ -291,30 +176,9 @@ def emit(self, record: logging.LogRecord) -> None: # sys.__stdout__.flush() # Ensure immediate flushing class ANSIFileHandler(logging.FileHandler): - """ - Custom FileHandler that removes ANSI codes from log output - and filters out logs from the internal Python logging module. - - This prevents unnecessary ANSI escape codes from appearing in log files - and ensures only relevant logs are recorded. - """ # def emit(self, record): def emit(self, record: logging.LogRecord) -> None: - """ - Custom FileHandler that removes ANSI codes from log output - and filters out logs from the internal Python logging module. - - This prevents unnecessary ANSI escape codes from appearing in log files - and ensures only relevant logs are recorded. - - Args: - record (logging.LogRecord): The log record to be emitted, including - log message and additional context for filtering. - - Returns: - None - """ # Ensure only Python's internal logging system is ignored if "logging/__init__.py" in record.pathname: @@ -330,23 +194,6 @@ def emit(self, record: logging.LogRecord) -> None: # ---------- Module operations: def main() -> None: - """ - Entry point for running the tracing module as a standalone program. - - This function initializes the logging environment, manages log files, and - optionally starts the tracing system when executed directly. It helps with - self-inspection and ensures the module operates correctly in isolation. - - Raises: - Exception: If logging setup fails or an unexpected error occurs. - - Returns: - None - - Example: - >>> python tracing.py - # Sets up logging, manages logs, and starts tracing. - """ global LOGGING, CONFIGS, logger # Ensure CONFIGS is globally accessible @@ -355,6 +202,10 @@ def main() -> None: # CONFIGS = setup_logging(events={"call": True, "return": False}) # print( f'CONFIGS: {json.dumps(CONFIGS, indent=default_indent)}' ) +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + # Automatically start tracing when executed directly if __name__ == "__main__": main() diff --git a/packages/requirements/.pydocs/pydoc.__init__.py b/packages/requirements/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..711ad71 --- /dev/null +++ b/packages/requirements/.pydocs/pydoc.__init__.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/__init__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/requirements/__init__.py + +Description: + This file initializes the `requirements` package, ensuring it is correctly recognized + as a Python package. It provides an entry point for dependency management by exposing + the `main` function from `dependencies.py`. + +Core Features: + - **Package Initialization**: + - Marks `requirements/` as a valid Python package. + - Ensures explicit module control, preventing unintended imports. + - **Dependency Management**: + - Exposes `main()` from `dependencies.py` for managing package installations. + - Facilitates structured and policy-driven dependency handling. + +Usage: + Importing and executing dependency management: + + from packages.requirements import main + main() + + Example execution: + python -m packages.requirements + +Dependencies: + - dependencies.py (Handles package dependency management) + +Expected Behavior: + - The package remains passive until explicitly invoked. + - Calling `main()` triggers the dependency installation process. + - No automatic execution occurs upon import. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to dependency issues, missing configurations, or package errors. +""" + +FUNCTION_DOCSTRINGS = { + "main": """ + Function: main() -> None + Description: + Entry point for the dependency management system. + + Parameters: + - None + + Returns: + - None: Executes dependency installation and policy enforcement. + + Behavior: + - Reads and processes package requirements from `requirements.json`. + - Installs, upgrades, or downgrades dependencies based on policies. + - Logs package operations for debugging and compliance tracking. + """ +} diff --git a/packages/requirements/.pydocs/pydoc.__main__.py b/packages/requirements/.pydocs/pydoc.__main__.py new file mode 100644 index 0000000..4a59881 --- /dev/null +++ b/packages/requirements/.pydocs/pydoc.__main__.py @@ -0,0 +1,63 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/__main__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: packages/requirements/__main__.py + +Description: + This file serves as the execution entry point for the `requirements` package when run + in standalone mode. It initializes and runs the dependency management system by calling + the `main()` function from `dependencies.py`. + +Core Features: + - **Standalone Execution**: + - Enables `python -m packages.requirements` execution. + - Allows the package to be run independently without direct imports. + - **Dependency Management**: + - Calls `main()` from `dependencies.py` to handle package installations. + - Applies structured package policies for controlled dependency enforcement. + - **Modular Design**: + - Supports both standalone execution and direct function imports. + +Usage: + To execute the `requirements` package as a standalone script: + + python -m packages.requirements + + Example execution: + + python -m packages.requirements + +Dependencies: + - dependencies.py (Handles package dependency management) + +Expected Behavior: + - When run as a module, it triggers dependency management automatically. + - Ensures dependencies are installed or updated based on predefined policies. + - Logs all package operations for debugging and compliance tracking. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to dependency issues, missing configurations, or package errors. +""" + +FUNCTION_DOCSTRINGS = { + "main": """ + Function: main() -> None + Description: + Entry point for the dependency management system. + + Parameters: + - None + + Returns: + - None: Executes dependency installation and policy enforcement. + + Behavior: + - Reads and processes package requirements from `requirements.json`. + - Installs, upgrades, or downgrades dependencies based on policies. + - Logs package operations for debugging and compliance tracking. + """ +} diff --git a/packages/requirements/.pydocs/pydoc.dependencies.py b/packages/requirements/.pydocs/pydoc.dependencies.py new file mode 100644 index 0000000..8cc5f28 --- /dev/null +++ b/packages/requirements/.pydocs/pydoc.dependencies.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/dependencies.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/dependencies.py + +Description: + The dependencies.py module is the core of the AppFlow Tracer - Dependency Management System, + providing structured and policy-driven package management. It integrates Homebrew (macOS) + and Pip (cross-platform) to ensure compliance with package versioning, + safe installations, and structured logging. + +Core Features: + - Environment Detection: Determines Python installation method (Homebrew, system-managed, or standalone). + - Package Management: Handles installation, upgrades, downgrades, and policy enforcement. + - Brew & Pip Integration: + - Uses Homebrew if Python is managed via Brew. + - Uses Pip for all other installations with controlled system package handling. + - Policy-Based Installation: + - Installs missing dependencies. + - Upgrades outdated packages if policy allows. + - Downgrades packages if strict versioning is required. + - Logging & Debugging: + - Captures package operations, warnings, and errors. + - Provides structured debugging messages. + - Backup & Restore: + - Saves the current package list for future restoration. + - Supports migration of package environments. + - Package Status Reporting: + - Displays installed dependencies, versions, and compliance details. + - Outputs structured reports to installed.json. + +Usage: + Parsing Command-Line Arguments: + from packages.requirements.dependencies import parse_arguments + args = parse_arguments() + + Installing Dependencies: + from packages.requirements.dependencies import main + main() + +Dependencies: + - sys - Manages system paths and process control. + - subprocess - Runs Homebrew and Pip commands. + - json - Handles structured storage of dependency data. + - pathlib - Ensures safe file path handling. + - functools - Optimizes frequently accessed functions with caching. + - argparse - Parses command-line arguments. + - platform - Detects system platform details. + - importlib.metadata - Retrieves installed package versions. + - brew_utils, package_utils, policy_utils, version_utils - Sub-modules managing dependency operations. + +Sub-Modules: + - brew_utils.py: Detects Homebrew availability and retrieves package versions. + - package_utils.py: Handles dependency installation using Brew or Pip. + - policy_utils.py: Enforces policy-driven installation, upgrades, and downgrades. + - version_utils.py: Fetches installed and latest package versions across multiple package managers. + +Expected Behavior: + - Dynamically adapts package installation based on system constraints. + - Installs, upgrades, or downgrades dependencies per predefined policies. + - Logs all package operations for debugging. + - Prevents unintended system modifications unless explicitly overridden (--force). + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to installation errors, missing configurations, or dependency issues. +""" + +FUNCTION_DOCSTRINGS = { + "parse_arguments": """ + Function: parse_arguments() -> argparse.Namespace + Description: + Parses command-line arguments for package management, allowing users to define requirement files, enforce installations, + backup, restore, or migrate packages. + + Returns: + - argparse.Namespace: Parsed arguments object containing selected options. + + Behavior: + - Supports JSON configuration for package management. + - Allows forcing installations with --force. + - Supports backup, restore, and migration of package environments. + - Enables listing installed packages. + + Supported Arguments: + - -c/--config: Specify a custom JSON requirements file. + - -f/--force: Force Pip installations with --break-system-packages. + - --backup-packages: Save installed packages for restoration. + - --restore-packages: Restore package environment from a backup file. + - --migrate-packages: Migrate legacy package environments. + - --show-installed: Display installed dependencies. + + Error Handling: + - Provides structured logging for missing configurations or invalid input. + """, + "main": """ + Function: main() -> None + Description: + Entry point for the dependency management system, handling package installations, updates, and logging. + + Behavior: + - Parses command-line arguments. + - Loads package requirement definitions. + - Detects the system's Python environment and applies installation policies. + - Handles backup, restore, and migration operations. + - Enforces policy-based dependency management. + - Installs required dependencies. + - Logs execution details and environment information. + + Error Handling: + - Logs errors for missing requirements.json or failed installations. + - Prevents breaking system-managed environments unless explicitly overridden (--force). + + Exit Codes: + - 0: Execution completed successfully. + - 1: Critical error occurred during dependency management. + """, +} + +VARIABLE_DOCSTRINGS = { + "LIB_DIR": """ + - Description: Defines the library directory path. + - Type: Path + - Usage: Dynamically added to sys.path for resolving imports. + """, + "CONFIGS": """ + - Description: Stores runtime configuration settings for dependency management. + - Type: dict + - Usage: Used for logging, policy enforcement, and package tracking. + """, + "installed_filepath": """ + - Description: Path to installed.json, which stores installed package details. + - Type: Path + - Usage: Used to track installed packages and versions. + """, +} diff --git a/packages/requirements/__init__.py b/packages/requirements/__init__.py index b06fb0c..edd8a1b 100755 --- a/packages/requirements/__init__.py +++ b/packages/requirements/__init__.py @@ -3,44 +3,23 @@ # File: ./packages/requirements/__init__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/requirements/__init__.py +# Standard library imports - Core system module +import sys -Description: - Requirements Package Initialization +# Standard library imports - File system-related module +from pathlib import Path - This file defines the `requirements` package and ensures it is properly recognized - as a Python package. It provides an entry point for managing dependencies by exposing - the `main` function from `dependencies.py`. - -Core Features: - - **Package Initialization**: Marks `requirements/` as a valid Python package. - - **Dependency Management**: Exposes `main()` from `dependencies.py` for handling dependencies. - - **Explicit Module Control**: Prevents unintended imports by requiring explicit calls. - -Usage: - To execute the dependencies management function: - ```python - from packages.requirements import main - main() - ``` - -Important: - - This file **does not** execute any logic automatically. - - The `main()` function must be explicitly invoked when needed. - -Dependencies: - - dependencies (for handling package dependency management) - -Example: - ```python - from packages.requirements import main - main() - ``` -""" +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import the main function from dependencies.py for package-level execution from packages.requirements.dependencies import main # Explicitly define available functions -__all__ = ["main"] +__all__ = [ + "main" +] + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/requirements/__main__.py b/packages/requirements/__main__.py index 7df1eb3..531047a 100755 --- a/packages/requirements/__main__.py +++ b/packages/requirements/__main__.py @@ -3,38 +3,21 @@ # File: ./packages/requirements/__main__.py __version__ = "0.1.0" ## Package version -""" -File Path: packages/requirements/__main__.py +# Standard library imports - Core system module +import sys -Description: - Requirements Package Entry Point +# Standard library imports - File system-related module +from pathlib import Path - This file serves as the execution entry point for the `requirements` package when run - in standalone mode. It initializes and runs the dependency management system by calling - the `main()` function from `dependencies.py`. - -Core Features: - - **Standalone Execution**: Enables `python -m packages.requirements` execution. - - **Dependency Management**: Calls `main()` from `dependencies.py` to handle dependencies. - - **Modular Design**: Supports both standalone execution and direct function imports. - -Usage: - To execute the `requirements` package as a standalone script: - ```bash - python -m packages.requirements - ``` - -Dependencies: - - dependencies (for managing package dependencies) - -Example: - ```bash - python -m packages.requirements - ``` -""" +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import the main function from dependencies.py from packages.requirements.dependencies import main if __name__ == "__main__": main() + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/requirements/dependencies.json b/packages/requirements/dependencies.json index c236d31..607411d 100644 --- a/packages/requirements/dependencies.json +++ b/packages/requirements/dependencies.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:12:57.579484+00:00", - "updated": "2025-03-10T01:17:54.208527+00:00" + "updated": "2025-03-10T06:15:08.872914+00:00" } } \ No newline at end of file diff --git a/packages/requirements/dependencies.py b/packages/requirements/dependencies.py index ce3d14d..fb0104f 100644 --- a/packages/requirements/dependencies.py +++ b/packages/requirements/dependencies.py @@ -1,97 +1,33 @@ #!/usr/bin/env python3 # File: ./packages/requirements/dependencies.py -__version__ = "0.2.0" ## Package version - -""" -# Advanced Dependency Management System - -## Overview - This module serves as the core of the **AppFlow Tracer - Dependency Management System**, - providing a structured and policy-driven approach to handling dependencies. It supports - both **Homebrew (macOS)** and **Pip (cross-platform)** while ensuring package versioning - compliance, safe installation policies, and structured logging. - -## Features - - **Environment Detection**: Determines how Python is installed (Homebrew, system package managers, or standalone). - - **Package Management**: Handles installation, upgrades, downgrades, and compliance with predefined policies. - - **Brew & Pip Integration**: - - Uses **Homebrew** if Python is managed via Brew. - - Uses **Pip** for all other installations, with safe installation handling. - - **Policy-Based Installation**: - - Installs missing packages. - - Upgrades outdated packages to the latest version if policy allows. - - Downgrades packages if policy enforces strict versioning. - - **Logging & Debugging**: - - Logs all package operations, warnings, and errors. - - Provides structured debugging messages for troubleshooting. - - **Backup & Restore**: - - Saves the current list of installed packages for future restoration. - - Allows migration of package environments. - - **Package Status Reporting**: - - Displays installed packages with versioning and compliance details. - - Writes results into `installed.json` for tracking. - -## Dependencies - - `subprocess` - Runs Brew and Pip commands. - - `argparse` - Parses command-line arguments. - - `json` - Manages structured dependency files. - - `importlib.metadata` - Fetches installed package versions. - - `pathlib` - Ensures safe file path handling. - - `functools.lru_cache` - Optimizes frequently accessed functions. - - `brew_utils`, `package_utils`, `policy_utils`, `version_utils` - Sub-modules managing dependency operations. - -## Sub-Modules - - **`brew_utils.py`**: - - Detects if Homebrew is available on macOS. - - Retrieves installed and latest package versions from Homebrew. - - - **`package_utils.py`**: - - Handles package installations using Brew or Pip. - - Implements structured installation logic for policy-driven updates. - - - **`policy_utils.py`**: - - Evaluates package policies (install, upgrade, downgrade, skip). - - Updates `installed.json` to reflect policy-enforced status. - - - **`version_utils.py`**: - - Fetches installed and latest available package versions. - - Supports multi-platform version detection (Pip, Brew, APT, DNF, Windows Store). - -## Expected Behavior - - Dynamically adapts package installation based on system constraints. - - Installs, upgrades, or downgrades packages per predefined policies. - - Logs all package operations for debugging and troubleshooting. - - Prevents unintended system modifications unless explicitly overridden (`--force`). - -## Exit Codes - - `0`: Execution completed successfully. - - `1`: Failure due to installation errors, missing configurations, or dependency issues. - -## Example Usage - ### **Installing Dependencies** - ```python - from dependencies import package_utils - package_utils.install_requirements(configs=configs) -""" +__version__ = "0.1.0" ## Package version +# Standard library imports - Core system and OS interaction modules import sys import subprocess import shutil +# Standard library imports - Utility modules import json import argparse import platform +# Standard library imports - Import system import importlib.metadata +# Standard library imports - Function tools from functools import lru_cache +# Standard library imports - Date and time handling from datetime import datetime, timezone -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -102,6 +38,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from lib import system_variables as environment from packages.appflow_tracer import tracing @@ -118,34 +57,6 @@ ## ----------------------------------------------------------------------------- def parse_arguments() -> argparse.Namespace: - """ - Parse command-line arguments for package management. - - This function provides command-line options for managing dependencies, - allowing users to specify requirement files, enforce installations, - backup, restore, or migrate packages. - - ## Supported Arguments: - - `-c/--config`: Specify a custom JSON requirements file. - - `-f/--force`: Force Pip installations using `--break-system-packages`. - - `--backup-packages`: Save installed package list for future restoration. - - `--restore-packages`: Restore packages from a backup file. - - `--migrate-packages`: Migrate package environments. - - `--show-installed`: Display installed dependencies. - - ## Args: - - `None` - - Returns: - - `argparse.Namespace`: The parsed arguments object containing selected options. - - Return Type: argparse.Namespace - Returns an argparse.Namespace object containing the parsed command-line arguments. - - ## Notes: - - This function is critical for enabling dynamic dependency management. - """ - parser = argparse.ArgumentParser( description="Manage package dependencies using Brew and PIP using policy management." @@ -195,50 +106,6 @@ def parse_arguments() -> argparse.Namespace: ## ----------------------------------------------------------------------------- def main() -> None: - """ - Entry point for the dependency management system. - - This function initializes logging, processes command-line arguments, - and installs or updates dependencies from a JSON requirements file. - It dynamically determines the system's Python environment and applies - installation policies accordingly. - - ## Workflow: - 1. **Parse Command-Line Arguments** - - Loads configuration settings. - - Determines runtime settings. - - 2. **Load Requirements File** - - Reads `requirements.json` (or custom-specified file). - - Extracts dependency data. - - 3. **Setup Logging & Environment** - - Detects Python installation method. - - Logs detected system information. - - 4. **Handle Backup & Restore Operations** - - Saves a package list for future restoration. - - Restores or migrates package environments if specified. - - 5. **Determine Dependency Policies** - - Calls `policy_utils.policy_management()` to enforce package rules. - - 6. **Install Dependencies** - - Uses `package_utils.install_requirements()` for installations. - - 7. **Display Installed Packages (if requested)** - - Shows structured package information from `installed.json`. - - ## Args: - - `None` - - ## Returns: - - `None`: This function performs actions based on command-line arguments and manages dependencies. - - ## Notes: - - If an error occurs (e.g., missing `requirements.json`), the process will exit with `sys.exit(1)`. - - The function prevents breaking system-managed environments unless explicitly overridden (`--force`). - """ # Ensure the variable exists globally global CONFIGS @@ -357,5 +224,10 @@ def main() -> None: # configs=CONFIGS # ) +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +# Automatically start tracing when executed directly if __name__ == "__main__": main() diff --git a/packages/requirements/installed.json b/packages/requirements/installed.json index 1318d40..967e0a9 100644 --- a/packages/requirements/installed.json +++ b/packages/requirements/installed.json @@ -14,8 +14,8 @@ "version": { "policy": "latest", "target": "0.115.11", - "latest": null, - "status": "missing" + "latest": "0.115.11_1", + "status": "upgraded" } }, { @@ -32,8 +32,8 @@ "version": { "policy": "latest", "target": "0.28.0", - "latest": null, - "status": "missing" + "latest": "1.6.10", + "status": "upgraded" } }, { diff --git a/packages/requirements/lib/.pydocs/pydoc.__init__.py b/packages/requirements/lib/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..8bd931b --- /dev/null +++ b/packages/requirements/lib/.pydocs/pydoc.__init__.py @@ -0,0 +1,71 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/lib/__init__.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/lib/__init__.py + +Description: + The __init__.py file serves as the entry point for the 'lib' package, integrating multiple + utility modules responsible for dependency management within the requirements system. + +Core Features: + - **Module Initialization**: + - Ensures all submodules (`brew_utils`, `package_utils`, `policy_utils`, `version_utils`) are properly imported. + - Dynamically adjusts `sys.path` for module resolution. + - **Structured Package Management**: + - Provides a unified interface for handling Homebrew, Pip, and system-wide package dependencies. + - Simplifies version tracking and policy enforcement across different package managers. + - **Dynamic Documentation Loading**: + - Uses `pydoc_loader` to inject external documentation at runtime. + +Usage: + Importing the module automatically loads all submodules: + from packages.requirements.lib import brew_utils, package_utils, policy_utils, version_utils + + Example usage: + from packages.requirements.lib.package_utils import install_requirements + install_requirements(configs) + + Checking Installed Packages: + from packages.requirements.lib.version_utils import installed_version + version = installed_version("requests", configs) + +Dependencies: + - sys - Handles system-level functions such as modifying `sys.path`. + - pathlib - Ensures platform-independent file path resolution. + - lib.pydoc_loader - Dynamically loads module documentation. + - brew_utils - Handles Homebrew-specific package management. + - package_utils - Provides functions for package installation and backup. + - policy_utils - Enforces policy-driven package installations. + - version_utils - Retrieves installed and latest package versions. + +Expected Behavior: + - Automatically exposes core submodules for streamlined package management. + - Ensures all required dependencies are correctly resolved before module execution. + - Loads documentation dynamically to maintain clean, structured code. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing submodules, system path errors, or incorrect module initialization. +""" + +FUNCTION_DOCSTRINGS = { + "load_pydocs": """ + Function: load_pydocs(script_path: str, module: ModuleType) -> None + Description: + Loads and applies documentation dynamically from `.pydoc` files. + + Parameters: + - script_path (str): The full path of the script whose documentation should be loaded. + - module (ModuleType): The module in which function and variable docstrings should be applied. + + Returns: + - None: Modifies the module's docstrings dynamically at runtime. + + Behavior: + - Searches for a `.pydoc` file matching the script's name. + - Loads module, function, and variable docstrings from the `.pydoc` file. + """ +} diff --git a/packages/requirements/lib/.pydocs/pydoc.brew_utils.py b/packages/requirements/lib/.pydocs/pydoc.brew_utils.py new file mode 100644 index 0000000..ccab9e8 --- /dev/null +++ b/packages/requirements/lib/.pydocs/pydoc.brew_utils.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/lib/brew_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/lib/brew_utils.py + +Description: + The brew_utils.py module provides utility functions for integrating Homebrew + package management within the dependency management system. It allows detection + of Homebrew availability, identification of Python installation methods, and + retrieval of installed and latest package versions. + +Core Features: + - Homebrew Availability Check: Determines whether Homebrew is installed. + - Python Environment Detection: Identifies if Python is installed via Brew, system package managers, or standalone. + - Package Version Retrieval: Fetches installed and latest versions of Homebrew-managed packages. + +Usage: + Checking Homebrew Availability: + from packages.requirements.lib.brew_utils import check_availability + is_brew_installed = check_availability() + + Detecting Python Installation Method: + from packages.requirements.lib.brew_utils import detect_environment + env_info = detect_environment() + + Fetching Homebrew Package Version: + from packages.requirements.lib.brew_utils import brew_info + version = brew_info("python3") + +Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Runs Homebrew commands and captures output. + - shutil - Checks if the `brew` command is available. + - re - Provides regex-based parsing of command output. + - json - Handles structured package information. + - argparse - Parses command-line arguments. + - platform - Identifies the operating system. + - logging - Logs system events and errors. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Optimizes function calls by caching results. + - pathlib - Ensures safe and platform-independent file path resolution. + +Expected Behavior: + - Accurately detects the presence and operational status of Homebrew. + - Determines Python installation method (Brew, system-managed, standalone). + - Retrieves package version details from Homebrew. + - Provides optimized querying with caching. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered in environment detection or package retrieval. +""" + +FUNCTION_DOCSTRINGS = { + "check_availability": """ + Function: check_availability() -> bool + Description: + Checks if Homebrew is installed and operational on macOS. + + Returns: + - bool: + - True if Homebrew is installed and functional. + - False if Homebrew is unavailable or the system is not macOS. + + Behavior: + - Uses shutil.which() to detect the Brew binary. + - Runs 'brew --version' to verify Brew functionality. + - Uses an LRU cache to avoid redundant system calls. + + Error Handling: + - If Homebrew is missing, the function returns False. + """, + "brew_info": """ + Function: brew_info(package: str) -> Optional[str] + Description: + Queries Homebrew to determine if a package exists and fetches its version. + + Parameters: + - package (str): The name of the package to check. + + Returns: + - Optional[str]: The installed version of the package if found, otherwise None. + + Behavior: + - Runs 'brew info ' and extracts the version from output. + - If the package does not exist, returns None. + + Error Handling: + - If Homebrew fails to retrieve package info, the function returns None. + """, + "detect_environment": """ + Function: detect_environment() -> dict + Description: + Detects the Python installation method and determines whether package installations are restricted. + + Returns: + - dict: A dictionary containing: + - "OS" (str): The detected operating system ("darwin", "linux", "windows"). + - "INSTALL_METHOD" (str): How Python is installed ("brew", "system", "standalone", "microsoft_store"). + - "EXTERNALLY_MANAGED" (bool): Whether the system restricts package installations. + - "BREW_AVAILABLE" (bool): Whether Homebrew is installed. + + Behavior: + - Detects if Python was installed via Brew. + - Checks for EXTERNALLY-MANAGED markers on Linux/macOS. + - Determines if Python is managed by APT/DNF on Linux or Microsoft Store on Windows. + + Error Handling: + - Uses subprocess calls to query system information. + - Returns a structured dictionary even if detection fails. + """, + "version": """ + Function: version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a Homebrew-managed package. + + Parameters: + - package (str): The name of the package to check. + + Returns: + - Optional[str]: The installed version of the package if found, otherwise None. + + Behavior: + - Runs 'brew list --versions ' and extracts the installed version. + - Returns None if the package is not installed via Homebrew. + + Error Handling: + - If Homebrew fails or the package is missing, the function returns None. + """, + "latest_version": """ + Function: latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a Homebrew package. + + Parameters: + - package (str): The name of the package to check. + + Returns: + - Optional[str]: The latest available version from Homebrew, otherwise None. + + Behavior: + - Runs 'brew info ' and extracts the stable version. + - Uses regex to parse the latest version from Homebrew output. + + Error Handling: + - If Brew command fails or package is missing, returns None. + """, +} + +VARIABLE_DOCSTRINGS = { + "LIB_DIR": """ + - Description: Defines the library directory path. + - Type: Path + - Usage: Dynamically added to sys.path for resolving imports. + """, + "environment": """ + - Description: Stores system-wide environment variables for the dependency management system. + - Type: module + - Usage: Provides access to configuration and logging utilities. + """, +} diff --git a/packages/requirements/lib/.pydocs/pydoc.package_utils.py b/packages/requirements/lib/.pydocs/pydoc.package_utils.py new file mode 100644 index 0000000..126b5fe --- /dev/null +++ b/packages/requirements/lib/.pydocs/pydoc.package_utils.py @@ -0,0 +1,224 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/lib/package_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/lib/package_utils.py + +Description: + The package_utils.py module provides structured functions for managing Python dependencies, + supporting backup, restore, installation, and compliance enforcement based on predefined policies. + +Core Features: + - Backup & Restore Packages: Saves and restores installed packages for migration or disaster recovery. + - Policy-Based Package Installation: Enforces version compliance through installation, upgrades, or downgrades. + - Dependency Review & Management: Evaluates installed versions against required versions. + - Homebrew & Pip Integration: Uses Homebrew when applicable or defaults to Pip for package installation. + - Logging & Configuration Handling: Ensures structured logging and configuration retrieval. + +Usage: + Backing Up Installed Packages: + from packages.requirements.lib.package_utils import backup_packages + backup_packages("backup.txt", configs) + + Installing a Specific Package: + from packages.requirements.lib.package_utils import install_package + install_package("requests", "2.26.0", configs) + + Installing Dependencies Based on Policy: + from packages.requirements.lib.package_utils import install_requirements + install_requirements(configs) + +Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - shutil - Verifies presence of external utilities. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + +Expected Behavior: + - Ensures all required packages are installed, upgraded, or downgraded as per defined policies. + - Respects externally managed environments and provides manual installation instructions when necessary. + - Logs all package operations for debugging and compliance tracking. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or restricted environments. +""" + +FUNCTION_DOCSTRINGS = { + "backup_packages": """ + Function: backup_packages(file_path: str, configs: dict) -> None + Description: + Saves all installed Python packages to a file for backup or migration. + + Parameters: + - file_path (str): The file where the installed package list is saved. + - configs (dict): Configuration dictionary for logging. + + Returns: + - None: Writes the package list to the specified file. + + Behavior: + - Runs 'pip freeze' to capture all installed packages. + - Saves the package list to the specified file. + - Logs the operation success or failure. + + Error Handling: + - Captures subprocess errors if the 'pip freeze' command fails. + """, + "install_package": """ + Function: install_package(package: str, version: Optional[str] = None, configs: dict = None) -> None + Description: + Installs or updates a package using Homebrew (if applicable) or Pip. + + Parameters: + - package (str): The package name to install. + - version (Optional[str]): The specific version to install (default: latest). + - configs (dict): Configuration dictionary for logging and system constraints. + + Returns: + - None: Executes the installation process. + + Behavior: + - Detects Python's installation method (Brew or standalone). + - Installs the package using Brew if available, otherwise uses Pip. + - Uses '--break-system-packages' when necessary to override restrictions. + + Error Handling: + - Logs an error if installation fails due to system constraints. + - Provides manual installation instructions when Pip installation is restricted. + """, + "install_requirements": """ + Function: install_requirements(configs: dict, bypass: bool = False) -> None + Description: + Installs, upgrades, or downgrades dependencies based on policy rules. + + Parameters: + - configs (dict): Configuration dictionary containing dependency requirements. + - bypass (bool): If True, forces installation without policy evaluation. + + Returns: + - None: Executes necessary package actions. + + Behavior: + - Evaluates package policies for installation, upgrade, or downgrade. + - Installs packages using Brew or Pip based on system constraints. + - Logs installation steps and policy decisions. + + Error Handling: + - Logs warnings for missing configurations or restricted environments. + """, + "installed_configfile": """ + Function: installed_configfile(configs: dict) -> Path + Description: + Retrieves the configured path to `installed.json`, which tracks installed package statuses. + + Parameters: + - configs (dict): The configuration dictionary. + + Returns: + - Path: The resolved path to `installed.json`. + + Error Handling: + - Raises KeyError if the configuration is missing the expected path. + """, + "migrate_packages": """ + Function: migrate_packages(file_path: str, configs: dict) -> None + Description: + Migrates installed packages from a previous environment and saves the package list. + + Parameters: + - file_path (str): File path to save the list of installed packages. + - configs (dict): Configuration dictionary for logging. + + Returns: + - None: Executes the migration process. + + Behavior: + - Extracts installed packages using 'pip list'. + - Saves package names before re-installing them. + - Installs all packages in the new environment. + + Error Handling: + - Logs errors if package retrieval or installation fails. + """, + "packages_installed": """ + Function: packages_installed(configs: dict) -> None + Description: + Prints the installed dependencies in a readable format. + + Parameters: + - configs (dict): Configuration dictionary. + + Returns: + - None: Displays installed packages and their status. + + Behavior: + - Reads `installed.json` and logs package names and versions. + - Checks compliance against required versions. + + Error Handling: + - Logs an error if `installed.json` is missing or corrupted. + """, + "restore_packages": """ + Function: restore_packages(file_path: str, configs: dict) -> None + Description: + Restores previously backed-up Python packages from a saved package list. + + Parameters: + - file_path (str): Path to the package list generated by `pip freeze`. + - configs (dict): Configuration dictionary for logging. + + Returns: + - None: Installs packages from the saved list. + + Behavior: + - Reads the package list and installs them using Pip. + - Ensures compatibility with existing package versions. + + Error Handling: + - Logs errors if installation fails or if the backup file is missing. + """, + "review_packages": """ + Function: review_packages(configs: dict) -> list + Description: + Reviews installed package versions and returns a structured package status list. + + Parameters: + - configs (dict): Configuration dictionary. + + Returns: + - list: A list of reviewed package data including installation status. + + Behavior: + - Compares installed versions against required versions. + - Determines whether a package is installed, outdated, or missing. + - Writes updated package statuses to `installed.json`. + + Error Handling: + - Logs an error if version comparisons fail. + """, +} + +VARIABLE_DOCSTRINGS = { + "LIB_DIR": """ + - Description: Defines the library directory path. + - Type: Path + - Usage: Dynamically added to sys.path for resolving imports. + """, + "environment": """ + - Description: Stores system-wide environment variables for dependency management. + - Type: module + - Usage: Provides access to configuration and logging utilities. + """, + "installed_filepath": """ + - Description: Stores the path to `installed.json`, tracking installed package statuses. + - Type: Path + - Usage: Used for backup, restore, and compliance enforcement. + """, +} diff --git a/packages/requirements/lib/.pydocs/pydoc.policy_utils.py b/packages/requirements/lib/.pydocs/pydoc.policy_utils.py new file mode 100644 index 0000000..6988bc0 --- /dev/null +++ b/packages/requirements/lib/.pydocs/pydoc.policy_utils.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/lib/policy_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/lib/policy_utils.py + +Description: + The policy_utils.py module provides structured policy evaluation for package management. + It ensures that packages are installed, upgraded, or downgraded according to predefined policies. + +Core Features: + - Policy-Based Dependency Evaluation: Determines whether a package should be installed, upgraded, downgraded, or skipped. + - Automated Compliance Checking: Compares installed versions against target and latest versions. + - Dynamic Policy Enforcement: Adapts installation actions based on policies such as "latest" or "restricted". + - Structured Logging: Provides detailed debugging and compliance logs for traceability. + - Integration with Installed Package Records: Updates installed.json dynamically. + +Usage: + Evaluating Package Policies: + from packages.requirements.lib.policy_utils import policy_management + updated_packages = policy_management(configs) + + Checking a Specific Package Status: + from packages.requirements.lib.version_utils import installed_version + current_version = installed_version("requests", configs) + +Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + - package_utils - Retrieves installed.json and manages package installation. + - version_utils - Retrieves installed and latest package versions. + +Expected Behavior: + - Ensures all required packages follow policy-based installation decisions. + - Prevents unintended upgrades/downgrades when policy is set to "restricted". + - Logs all policy enforcement actions for debugging and compliance tracking. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or policy conflicts. +""" + +FUNCTION_DOCSTRINGS = { + "policy_management": """ + Function: policy_management(configs: dict) -> list + Description: + Evaluates package installation policies and updates dependency statuses. + + Parameters: + - configs (dict): The configuration dictionary containing dependency policies. + + Returns: + - list: The updated list of dependencies with policy-based statuses. + + Behavior: + - Analyzes installed packages and determines policy actions (install, upgrade, downgrade, or skip). + - Updates `installed.json` with the latest package states. + - Logs compliance decisions for debugging and tracking. + + Policy Decision Logic: + 1. **Missing Package (status = "installing")** + - Installs the package as per policy (either latest or target version). + + 2. **Outdated Package (status = "outdated" | "upgrading")** + - If installed version < target version: + - "latest" policy → Upgrade to latest available version. + - "restricted" policy → Keep outdated but log a warning. + + 3. **Target Version Matched (status = "matched")** + - If installed version == target version: + - "latest" policy → Check for newer versions and mark as "outdated". + - Otherwise, mark as "matched" (no action needed). + + 4. **Upgraded Version Installed (status = "downgraded" | "upgraded")** + - If installed version > target version: + - "restricted" policy → Downgrade to target version. + - "latest" policy → Keep upgraded. + + Error Handling: + - Logs policy violations or missing configurations. + - Ensures structured compliance before initiating installation processes. + """, +} diff --git a/packages/requirements/lib/.pydocs/pydoc.version_utils.py b/packages/requirements/lib/.pydocs/pydoc.version_utils.py new file mode 100644 index 0000000..d9c9e04 --- /dev/null +++ b/packages/requirements/lib/.pydocs/pydoc.version_utils.py @@ -0,0 +1,163 @@ +#!/usr/bin/env python3 + +# Python File: ./packages/requirements/lib/version_utils.py +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: ./packages/requirements/lib/version_utils.py + +Description: + The version_utils.py module provides structured utilities for retrieving and managing package versions. + It supports multi-platform package detection across Pip, Homebrew, APT, DNF, and Windows Package Manager. + +Core Features: + - Retrieve Installed Package Versions: Determines the currently installed version of a package. + - Check Latest Available Versions: Queries the latest available package versions from the appropriate source. + - Multi-Platform Support: Detects package versions across macOS (Homebrew), Linux (APT/DNF), and Windows (Microsoft Store). + - Optimized Performance: Uses caching and structured queries to minimize redundant operations. + - Logging & Debugging: Provides detailed debug logs for package evaluations. + +Usage: + Checking Installed Version: + from packages.requirements.lib.version_utils import installed_version + current_version = installed_version("requests", configs) + + Fetching Latest Available Version: + from packages.requirements.lib.version_utils import latest_version + latest_pip_version = latest_version("requests", configs) + +Dependencies: + - sys - Handles system-level functions such as process termination. + - subprocess - Executes shell commands for package management. + - json - Handles structured dependency files. + - importlib.metadata - Retrieves installed package versions. + - functools.lru_cache - Caches function calls for efficiency. + - pathlib - Ensures platform-independent file path resolution. + - packages.appflow_tracer.lib.log_utils - Provides structured logging. + - brew_utils - Retrieves Homebrew-specific package versions. + +Expected Behavior: + - Ensures all required packages follow version compliance checks. + - Prevents unintended upgrades/downgrades when policy is set to "restricted". + - Logs all package version evaluations for debugging and compliance tracking. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to missing configurations, package errors, or policy conflicts. +""" + +FUNCTION_DOCSTRINGS = { + "latest_version": """ + Function: latest_version(package: str, configs: dict) -> Optional[str] + Description: + Fetches the latest available version of a package using the appropriate package manager. + + Parameters: + - package (str): The package name to check. + - configs (dict): Configuration dictionary used for logging and environment detection. + + Returns: + - Optional[str]: The latest available version as a string if found, otherwise None. + + Behavior: + - Prioritizes Pip for Python packages. + - Uses system-level package managers (Homebrew, APT/DNF, Microsoft Store) as applicable. + """, + + "installed_version": """ + Function: installed_version(package: str, configs: dict) -> Optional[str] + Description: + Retrieves the installed version of a package. + + Parameters: + - package (str): The package name to check. + - configs (dict): Configuration dictionary containing system environment details. + + Returns: + - Optional[str]: The installed package version if found, otherwise None. + + Behavior: + - Uses multiple detection methods, prioritizing Pip before system-level package managers. + - Logs version evaluation details for debugging. + """, + + "pip_latest_version": """ + Function: pip_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via Pip. + + Parameters: + - package (str): The package name to check. + + Returns: + - Optional[str]: The latest available version as a string if found, otherwise None. + + Behavior: + - Uses `pip index versions ` to retrieve the latest available version. + - Requires internet access to fetch version information from PyPI. + """, + + "linux_version": """ + Function: linux_version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a package via APT (Debian-based) or DNF (Fedora). + + Parameters: + - package (str): The package name to check. + + Returns: + - Optional[str]: The installed version if found, otherwise None. + + Behavior: + - Uses `dpkg -s ` for APT and `rpm -q ` for DNF. + - Ensures compatibility with Linux-based package managers. + """, + + "linux_latest_version": """ + Function: linux_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via APT or DNF. + + Parameters: + - package (str): The package name to check. + + Returns: + - Optional[str]: The latest available version if found, otherwise None. + + Behavior: + - Uses `apt-cache madison ` for APT and `dnf list available ` for DNF. + - Ensures compatibility with system package management tools. + """, + + "windows_version": """ + Function: windows_version(package: str) -> Optional[str] + Description: + Retrieves the installed version of a package via Microsoft Store. + + Parameters: + - package (str): The package name to check. + + Returns: + - Optional[str]: The installed version if found, otherwise None. + + Behavior: + - Uses PowerShell `Get-AppxPackage` to check installed package versions. + - Requires administrator privileges for execution. + """, + + "windows_latest_version": """ + Function: windows_latest_version(package: str) -> Optional[str] + Description: + Retrieves the latest available version of a package via Microsoft Store. + + Parameters: + - package (str): The package name to check. + + Returns: + - Optional[str]: The latest available version if found, otherwise None. + + Behavior: + - Uses PowerShell `Find-Package` to query available package versions. + - Requires administrator privileges for execution. + """, +} diff --git a/packages/requirements/lib/__init__.py b/packages/requirements/lib/__init__.py index 2c25555..6dd4db3 100644 --- a/packages/requirements/lib/__init__.py +++ b/packages/requirements/lib/__init__.py @@ -3,6 +3,14 @@ # File: ./packages/requirements/lib/__init__.py __version__ = "0.1.0" ## Package version +# Standard library imports - Core system module +import sys + +# Standard library imports - File system-related module +from pathlib import Path + +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) # Import and expose key submodules from . import ( @@ -18,3 +26,7 @@ "policy_utils", "version_utils" ] + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) diff --git a/packages/requirements/lib/brew_utils.py b/packages/requirements/lib/brew_utils.py index b12f001..31bf303 100644 --- a/packages/requirements/lib/brew_utils.py +++ b/packages/requirements/lib/brew_utils.py @@ -3,55 +3,33 @@ # File: ./packages/requirements/lib/brew_utils.py # Version: 0.1.0 -""" -# Homebrew Utilities for Dependency Management - -## Overview - This module provides utility functions for integrating Homebrew package management - within the dependency management system. It facilitates checking the availability - of Homebrew, detecting Python installation environments, and retrieving installed - and latest package versions from Homebrew. - -## Features - - **Homebrew Availability Check:** Determines whether Homebrew is installed. - - **Python Environment Detection:** Identifies how Python is installed (Brew, system, standalone, etc.). - - **Package Version Retrieval:** Fetches the installed and latest versions of packages managed by Homebrew. - -## Usage - The module is used internally by the dependency management system to dynamically - detect Python installation methods and ensure compliance with system constraints. - -## Dependencies - - `subprocess`: For executing shell commands. - - `shutil`: To verify the presence of the `brew` command. - - `platform`: To determine the operating system. - - `importlib.metadata`: For alternative package version lookups. - - `functools.lru_cache`: To optimize repetitive queries. - -## Notes - - This module is optimized for macOS but includes environment detection for Linux and Windows. - - The `check_availability()` function caches results to minimize system calls. - - The `detect_environment()` function ensures that externally managed environments are respected. -""" - +# Standard library imports - Core system and OS interaction modules import sys import subprocess import shutil + +# Standard library imports - Utility modules import re import json import argparse import platform import logging +# Standard library imports - Import system import importlib.metadata +# Standard library imports - Function tools from functools import lru_cache +# Standard library imports - Date and time handling from datetime import datetime, timezone -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -62,6 +40,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from lib import system_variables as environment from packages.appflow_tracer.lib import log_utils @@ -69,22 +50,6 @@ @lru_cache(maxsize=1) # Cache the result to avoid redundant subprocess calls def check_availability() -> bool: - """ - Check if Homebrew is available on macOS. - - This function determines whether Homebrew is installed and operational. It first - checks for the existence of the `brew` binary using `shutil.which()`, then - verifies its functionality by running `brew --version`. - - ## Returns: - - `bool`: - - `True` if Homebrew is installed and operational. - - `False` if Homebrew is unavailable or the system is not macOS. - - ## Notes: - - Uses `lru_cache(maxsize=1)` to cache the result, avoiding redundant system calls. - - Returns `False` immediately if the system is not macOS. - """ if sys.platform != "darwin": # ✅ Ensure it only runs on macOS return False # ✅ Prevents false positives on Ubuntu runners @@ -108,21 +73,7 @@ def check_availability() -> bool: ## ----------------------------------------------------------------------------- def brew_info(package: str) -> Optional[str]: - """ - Retrieve information about a Homebrew package. - - This function queries Homebrew to determine if a package exists and fetches its version. - - ## Args: - - `package` (`str`): The name of the package to check. - - ## Returns: - - `Optional[str]`: The package version if found, otherwise `None`. - ## Notes: - - This function runs `brew info ` and parses the output. - - If Homebrew returns an error (`No formula found`), it returns `None`. - """ try: result = subprocess.run( ["brew", "info", package], @@ -144,28 +95,6 @@ def brew_info(package: str) -> Optional[str]: ## ----------------------------------------------------------------------------- def detect_environment() -> dict: - """ - Detect the Python installation method and determine if it is externally managed. - - This function examines the system's Python installation method and whether - package installations are restricted. It identifies installations from: - - **Homebrew (macOS)** - - **System package managers (APT/DNF)** - - **Microsoft Store (Windows)** - - **Standalone Python installations** - - ## Returns: - - `dict`: A dictionary containing: - - `"OS"` (`str`): The detected operating system (`"darwin"`, `"linux"`, `"windows"`). - - `"INSTALL_METHOD"` (`str`): The detected Python installation method (`"brew"`, `"system"`, `"standalone"`, `"microsoft_store"`). - - `"EXTERNALLY_MANAGED"` (`bool`): Indicates whether the system restricts package installations. - - `"BREW_AVAILABLE"` (`bool`): Specifies whether Homebrew is installed. - - ## Notes: - - The function respects `EXTERNALLY-MANAGED` environments on Linux/macOS. - - If Homebrew is available, it attempts to detect whether Python was installed via Brew. - - Uses system commands like `dpkg -l`, `rpm -q`, and `ensurepip` to determine installation methods. - """ brew_available = check_availability() @@ -237,24 +166,6 @@ def detect_environment() -> dict: # ------------------------------------------------------ def version(package: str) -> Optional[str]: - """ - Retrieve the installed version of a Homebrew-managed package. - - This function executes `brew list --versions ` to check whether a package - is installed via Homebrew and extracts its version if available. - - ## Args: - - `package` (`str`): The name of the package to check. - - ## Returns: - - `Optional[str]`: - - The installed version of the package if found. - - `None` if the package is not installed via Homebrew. - - ## Notes: - - Uses `subprocess.run()` to query Brew. - - Returns `None` if the package is not installed. - """ try: result = subprocess.run( @@ -270,24 +181,6 @@ def version(package: str) -> Optional[str]: ## ----------------------------------------------------------------------------- def latest_version(package: str) -> Optional[str]: - """ - Retrieve the latest available version of a package from Homebrew. - - This function runs `brew info ` to extract the latest stable version - of a package from the Homebrew repository. - - ## Args: - - `package` (`str`): The name of the package to check. - - ## Returns: - - `Optional[str]`: - - The latest available version from Homebrew. - - `None` if the package is unknown or Brew fails. - - ## Notes: - - Parses the output of `brew info` to extract the stable version. - - If the command fails or the package is not found, it returns `None`. - """ # try: # result = subprocess.run( @@ -317,3 +210,13 @@ def latest_version(package: str) -> Optional[str]: return None # Brew failed return None # No version found + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/requirements/lib/package_utils.py b/packages/requirements/lib/package_utils.py index f49b8fa..f54c0b3 100644 --- a/packages/requirements/lib/package_utils.py +++ b/packages/requirements/lib/package_utils.py @@ -3,57 +3,32 @@ # File: ./packages/requirements/lib/package_utils.py # Version: 0.1.0 -""" -# Package Management Utilities for Dependency Handling - -## Overview - This module provides utility functions for managing Python package dependencies in a structured - and policy-driven approach. It facilitates installing, backing up, restoring, and reviewing package - versions while ensuring compliance with system constraints. - -## Features - - **Backup & Restore Packages:** Saves and restores installed packages for migration or disaster recovery. - - **Policy-Based Package Installation:** Handles installation, upgrades, and downgrades based on predefined policies. - - **Dependency Review & Management:** Evaluates installed versions against required versions and logs compliance. - - **Homebrew & Pip Integration:** Uses Homebrew if applicable, otherwise falls back to Pip with appropriate safeguards. - - **Logging & Configuration Handling:** Ensures structured logging and configuration retrieval. - -## Usage - This module is primarily used by the dependency management system to enforce structured package installations - and compliance checks. - -## Dependencies - - `subprocess`: For executing Pip and Homebrew commands. - - `json`: For handling structured dependency configurations. - - `importlib.metadata`: For retrieving installed package versions. - - `shutil`: To check for external utilities. - - `pathlib`: For managing file paths. - - `functools.lru_cache`: To optimize repetitive queries. - - `log_utils`: Custom logging module for structured output. - -## Notes - - The module respects externally managed Python environments, ensuring system integrity. - - It dynamically detects installation methods and applies package management policies accordingly. -""" - +# Standard library imports - Core system and OS interaction modules import sys import subprocess import shutil +# Standard library imports - Utility modules import json import argparse import platform import logging +# Standard library imports - Import system import importlib.metadata +# Standard library imports - Function tools from functools import lru_cache +# Standard library imports - Date and time handling from datetime import datetime, timezone -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -64,6 +39,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from lib import system_variables as environment from packages.appflow_tracer.lib import log_utils @@ -72,23 +50,6 @@ ## ----------------------------------------------------------------------------- def backup_packages(file_path: str, configs: dict) -> None: - """ - Back up all installed Python packages to a requirements-style list. - - This function generates a list of installed packages using `pip freeze` - and saves it to the specified file for later restoration. - - ## Args: - - `file_path` (`str`): The file path where the installed package list will be saved. - - `configs` (`dict`): Configuration dictionary used for logging. - - ## Raises: - - `subprocess.CalledProcessError`: If the `pip freeze` command fails. - - ## Notes: - - This function is useful for backing up environments before upgrades. - - The saved file can be used for migration or disaster recovery. - """ try: with open(file_path, "w") as f: @@ -112,28 +73,6 @@ def backup_packages(file_path: str, configs: dict) -> None: ## ----------------------------------------------------------------------------- def install_package(package: str, version: Optional[str] = None, configs: dict = None) -> None: - """ - Install or update a package using Brew (if applicable) or Pip. - - This function installs a package using the preferred method: - - If Python is installed via Homebrew and the package is available in Brew, it uses `brew install`. - - Otherwise, it falls back to Pip, considering: - - `--user` for standalone installations. - - `--break-system-packages` if the system is externally managed and forced installation is enabled. - - Otherwise, prints manual installation instructions. - - ## Args: - - `package` (`str`): The package name to install. - - `version` (`Optional[str]`): The specific version to install (default: latest). - - `configs` (`dict`): Configuration dictionary for logging and environment handling. - - ## Returns: - - `None`: Executes the package installation process. - - ## Notes: - - Ensures safe installation, respecting system constraints. - - Uses structured logging to report installation status. - """ # Fetch environment details env_info = configs.get("environment", {}) @@ -207,25 +146,6 @@ def install_package(package: str, version: Optional[str] = None, configs: dict = ## ----------------------------------------------------------------------------- def install_requirements(configs: dict, bypass: bool = False) -> None: - """ - Install, upgrade, or downgrade dependencies based on policy rules. - - This function processes dependencies listed in `configs["requirements"]` and applies - necessary package actions (install, upgrade, downgrade). It first retrieves evaluated - package statuses using `review_packages()`, ensuring a structured decision-making process. - - ## Args: - - `configs` (`dict`): Configuration dictionary containing dependency requirements. - - `force_install` (`bool`): If True, all packages are installed immediately, ignoring policy. - - ## Returns: - - `None`: Executes the required package installations. - - ## Notes: - - This function enforces policy-based installation to maintain package consistency. - - It minimizes unnecessary installations by checking existing versions before applying changes. - - Dependencies are installed using either Brew or Pip, based on system constraints. - """ log_utils.log_message( f'\n[INSTALL] Starting installation process...', @@ -317,20 +237,6 @@ def install_requirements(configs: dict, bypass: bool = False) -> None: ## ----------------------------------------------------------------------------- def install_requirements__legacy(configs: dict) -> None: - """ - Retrieve the path to `installed.json` from the configuration dictionary. - - This function extracts the configured path where installed package statuses are stored. - - ## Args: - - `configs` (`dict`): The configuration dictionary. - - ## Returns: - - `Path`: The resolved path to `installed.json`, or `None` if not configured. - - ## Notes: - - This function ensures consistent access to installed package records. - """ log_utils.log_message( f'\n[INSTALL] Starting installation process...', @@ -407,21 +313,7 @@ def install_requirements__legacy(configs: dict) -> None: ## ----------------------------------------------------------------------------- -from pathlib import Path - def installed_configfile(configs: dict) -> Path: - """ - Retrieve the configured path to `installed.json`. - - Args: - configs (dict): Configuration dictionary. - - Returns: - Path: Path object pointing to `installed.json`. - - Raises: - KeyError: If `configs["packages"]["installation"]["configs"]` is missing. - """ # return configs.get("packages", {}).get("installation", {}).get("configs", None) try: @@ -433,22 +325,6 @@ def installed_configfile(configs: dict) -> Path: ## ----------------------------------------------------------------------------- def migrate_packages(file_path: str, configs: dict) -> None: - """ - Review installed package versions and return an updated package status list. - - This function checks all installed dependencies, compares them against target versions, - determines their status (installed, outdated, missing), and returns a structured package list. - - ## Args: - - `configs` (`dict`): The configuration dictionary containing dependency policies. - - ## Returns: - - `list`: A structured list of reviewed packages, including installation status. - - ## Notes: - - The function also updates `installed.json` with the latest package states. - - Ensures a structured package evaluation process before applying changes. - """ try: result = subprocess.run( @@ -486,18 +362,6 @@ def migrate_packages(file_path: str, configs: dict) -> None: ## ----------------------------------------------------------------------------- def packages_installed(configs: dict) -> None: - """ - Prints the installed dependencies in a readable format. - - This function reads `installed.json` and logs package names, required versions, - installed versions, and compliance status. - - Args: - configs (dict): Configuration dictionary. - - Returns: - None: Prints the installed package details. - """ installed_filepath = installed_configfile(configs) # Fetch dynamically @@ -543,19 +407,6 @@ def packages_installed(configs: dict) -> None: ## ----------------------------------------------------------------------------- def restore_packages(file_path: str, configs: dict) -> None: - """ - Restores all previously backed-up Python packages by reading - the specified file and installing the packages listed in it. - - This function should be executed after upgrading Python to ensure that - the same packages are available in the new Python environment. - - Args: - file_path (str): The file path to the package list generated by `pip freeze`. - - Raises: - subprocess.CalledProcessError: If the package installation fails. - """ try: subprocess.run( @@ -577,19 +428,6 @@ def restore_packages(file_path: str, configs: dict) -> None: ## ----------------------------------------------------------------------------- def review_packages(configs: dict) -> list: - """ - Reviews installed package versions and returns an updated package status list. - - This function checks all installed dependencies, determines their status - (installed, outdated, missing), and returns the structured package data. - It also updates `installed.json` with the latest package states. - - Args: - configs (dict): Configuration dictionary. - - Returns: - list: A list of reviewed package data including installation status. - """ installed_filepath = installed_configfile(configs) @@ -634,3 +472,13 @@ def review_packages(configs: dict) -> list: ) return installed_data # Return the structured package list + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/requirements/lib/policy_utils.py b/packages/requirements/lib/policy_utils.py index 00c0c9a..3f406f9 100644 --- a/packages/requirements/lib/policy_utils.py +++ b/packages/requirements/lib/policy_utils.py @@ -3,59 +3,32 @@ # File: ./packages/requirements/lib/policy_utils.py # Version: 0.1.0 -""" -# Environment and Policy Management Utilities - -## Overview - This module provides functions for managing package policies and evaluating dependency - installation requirements within the dependency management system. It ensures that packages - are installed, upgraded, or downgraded based on predefined policies while maintaining compliance - with system constraints. - -## Features - - **Policy-Based Dependency Evaluation:** Determines whether a package should be installed, upgraded, downgraded, or skipped. - - **Automated Compliance Checking:** Compares installed versions against target and latest versions. - - **Dynamic Policy Enforcement:** Adapts installation actions based on policies such as `"latest"` or `"restricted"`. - - **Structured Logging:** Provides detailed debugging and compliance logs for better traceability. - - **Integration with Installed Package Records:** Updates `installed.json` dynamically. - -## Usage -This module is invoked by the dependency management workflow to analyze package states and -apply policy-driven installation decisions. - -## Dependencies - - `subprocess`: For executing system commands. - - `json`: For handling structured package configurations. - - `platform`: For system detection. - - `importlib.metadata`: For retrieving installed package versions. - - `pathlib`: For managing configuration file paths. - - `log_utils`: Custom logging module for structured output. - - `package_utils`: Provides package management functions such as retrieving `installed.json`. - - `version_utils`: Handles installed and latest package version retrieval. - -## Notes - - This module ensures a **structured decision-making** process for package installations. - - It dynamically adapts to the system's constraints, ensuring **safe package management**. -""" - +# Standard library imports - Core system and OS interaction modules import sys import subprocess import shutil +# Standard library imports - Utility modules import json import argparse import platform import logging +# Standard library imports - Import system import importlib.metadata +# Standard library imports - Function tools from functools import lru_cache +# Standard library imports - Date and time handling from datetime import datetime, timezone -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -66,6 +39,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from lib import system_variables as environment from packages.appflow_tracer.lib import log_utils @@ -77,48 +53,6 @@ ## ----------------------------------------------------------------------------- def policy_management(configs: dict) -> list: - """ - Evaluate package installation policies and update dependency statuses. - - This function analyzes each package in the dependency list, comparing its installed - version against the target and latest available versions. Based on the specified - policy, it determines whether the package should be installed, upgraded, downgraded, - or skipped. - - ## Args: - - `configs` (`dict`): The configuration dictionary containing dependency policies. - - ## Returns: - - `list`: The updated list of dependencies with policy-based statuses. - - ## Policy Decision Logic: - 1. **Missing Package (`status = "installing"`)** - - If the package is not installed, it is marked for installation. - - Installs either the `"latest"` or `"target"` version based on policy. - - 2. **Outdated Package (`status = "outdated" | "upgrading"`)** - - If installed version < target version: - - `"latest"` policy → Upgrade to latest available version. - - `"restricted"` policy → Keep outdated but log warning. - - 3. **Target Version Matched (`status = "matched"`)** - - If installed version == target version: - - `"latest"` policy → Check if a newer version exists; mark as `"outdated"`. - - Otherwise, mark as `"matched"` (no action needed). - - 4. **Upgraded Version Installed (`status = "downgraded" | "upgraded"`)** - - If installed version > target version: - - `"restricted"` policy → Downgrade to target version. - - `"latest"` policy → Keep upgraded. - - ## Logging: - - Each package's evaluation is logged, showing its target, installed, and latest versions. - - Policy enforcement decisions are logged with detailed status messages. - - ## Notes: - - This function modifies `configs["requirements"]` and updates `installed.json`. - - Ensures structured compliance before initiating installation processes. - """ dependencies = configs["requirements"] # Use already-loaded requirements installed_filepath = package_utils.installed_configfile(configs) # Fetch dynamically @@ -219,3 +153,13 @@ def policy_management(configs: dict) -> list: ) return dependencies # Explicitly return the modified requirements list + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/packages/requirements/lib/version_utils.py b/packages/requirements/lib/version_utils.py index 15e1232..93689f4 100644 --- a/packages/requirements/lib/version_utils.py +++ b/packages/requirements/lib/version_utils.py @@ -3,56 +3,32 @@ # File: ./packages/requirements/lib/version_utils.py # Version: 0.1.0 -""" -# Version Management Utilities for Dependency Handling - -## Overview - This module provides utilities for retrieving and managing package versions across - various package managers. It supports version detection for Python packages installed - via Pip, Homebrew, APT, DNF, and Windows Package Manager (Microsoft Store). - -## Features - - **Retrieve Installed Package Versions:** Determines the currently installed version of a package. - - **Check Latest Available Versions:** Queries the latest available package versions from the appropriate source. - - **Multi-Platform Support:** Detects package versions across macOS (Homebrew), Linux (APT/DNF), and Windows (Microsoft Store). - - **Optimized Performance:** Uses caching and structured queries to minimize redundant operations. - - **Logging & Debugging:** Provides detailed debug logs for package evaluations. - -## Usage - This module is used internally by the dependency management system to dynamically - assess package versions before applying installation policies. - -## Dependencies - - `subprocess`: For executing package manager commands. - - `json`: For parsing structured package data. - - `importlib.metadata`: For retrieving installed Python package versions. - - `pathlib`: For managing system paths. - - `log_utils`: Custom logging module for structured output. - - `brew_utils`: Handles Homebrew-specific package version retrieval. - -## Notes - - This module prioritizes Pip-based queries before falling back to system-level package managers. - - It ensures **structured decision-making** when evaluating package versions. -""" - +# Standard library imports - Core system and OS interaction modules import sys import subprocess import shutil +# Standard library imports - Utility modules import json import argparse import platform import logging +# Standard library imports - Import system import importlib.metadata +# Standard library imports - Function tools from functools import lru_cache +# Standard library imports - Date and time handling from datetime import datetime, timezone -from typing import Optional, Union +# Standard library imports - File system-related module from pathlib import Path +# Standard library imports - Type hinting (kept in a separate group) +from typing import Optional, Union + # Define base directories LIB_DIR = Path(__file__).resolve().parent.parent.parent / "lib" if str(LIB_DIR) not in sys.path: @@ -63,6 +39,9 @@ # for path in sys.path: # print(f' - {path}') +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from lib import system_variables as environment from packages.appflow_tracer.lib import log_utils @@ -71,26 +50,6 @@ # ------------------------------------------------------ def latest_version(package: str, configs: dict) -> Optional[str]: - """ - Fetch the latest available version of a package using the appropriate package manager. - - This function determines the latest available version of a package by querying: - 1. **Pip** (default for Python packages). - 2. **Homebrew** (if Python is managed via Brew on macOS). - 3. **APT/DNF** (if applicable on Linux). - 4. **Windows Package Manager** (Microsoft Store). - - ## Args: - - `package` (`str`): The package name to check. - - `configs` (`dict`): Configuration dictionary used for logging and environment detection. - - ## Returns: - - `Optional[str]`: The latest available version as a string if found, otherwise `None`. - - ## Notes: - - Prioritizes Pip as it provides the most up-to-date package information. - - Uses `match` statements to route requests to the correct package manager. - """ env_info = configs.get("environment", {}) install_method = env_info.get("INSTALL_METHOD") @@ -114,22 +73,6 @@ def latest_version(package: str, configs: dict) -> Optional[str]: ## ----------------------------------------------------------------------------- def linux_version(package: str) -> Optional[str]: - """ - Retrieve the installed version of a package via APT (Debian-based) or DNF (Fedora). - - This function attempts to determine the installed version using: - - `dpkg -s ` for APT (Debian-based systems). - - `rpm -q ` for DNF (Fedora-based systems). - - ## Args: - - `package` (`str`): The package name to check. - - ## Returns: - - `Optional[str]`: The installed version if found, otherwise `None`. - - ## Notes: - - If `dpkg` is unavailable, it falls back to `rpm`. - """ try: result = subprocess.run( @@ -158,22 +101,6 @@ def linux_version(package: str) -> Optional[str]: ## ----------------------------------------------------------------------------- def linux_latest_version(package: str) -> Optional[str]: - """ - Retrieve the latest available version of a package via APT or DNF. - - This function checks: - - `apt-cache madison ` for APT (Debian-based systems). - - `dnf list available ` for DNF (Fedora-based systems). - - ## Args: - - `package` (`str`): The package name to check. - - ## Returns: - - `Optional[str]`: The latest available version if found, otherwise `None`. - - ## Notes: - - If `apt-cache` is unavailable, it falls back to `dnf`. - """ try: result = subprocess.run( @@ -202,21 +129,6 @@ def linux_latest_version(package: str) -> Optional[str]: # ------------------------------------------------------ def windows_version(package: str) -> Optional[str]: - """ - Retrieve the installed version of a package via Microsoft Store. - - This function runs a PowerShell command to check the installed version of - a package using `Get-AppxPackage`. - - ## Args: - - `package` (`str`): The package name to check. - - ## Returns: - - `Optional[str]`: The installed version if found, otherwise `None`. - - ## Notes: - - Uses PowerShell commands, which require administrator privileges. - """ try: result = subprocess.run( @@ -226,28 +138,13 @@ def windows_version(package: str) -> Optional[str]: check=True ) version = result.stdout.strip() - return version if version else None # ✅ Return None if no output is found + return version if version else None # Return None if no output is found except subprocess.CalledProcessError: - return None # ✅ If the command fails, the package is missing + return None # If the command fails, the package is missing ## ----------------------------------------------------------------------------- def windows_latest_version(package: str) -> Optional[str]: - """ - Retrieve the latest available version of a package via Microsoft Store. - - This function runs a PowerShell command to check the latest available version - of a package using `Find-Package`. - - ## Args: - - `package` (`str`): The package name to check. - - ## Returns: - - `Optional[str]`: The latest available version if found, otherwise `None`. - - ## Notes: - - Requires PowerShell execution privileges. - """ try: result = subprocess.run( @@ -263,27 +160,6 @@ def windows_latest_version(package: str) -> Optional[str]: ## ----------------------------------------------------------------------------- def installed_version(package: str, configs: dict) -> Optional[str]: - """ - Retrieve the installed version of a package. - - This function checks for an installed package version using the following priority order: - 1. **Pip (`pip list --format=json`)** - Best for detecting all installed packages. - 2. **Pip (`importlib.metadata.version()`)** - Fallback for retrieving individual package metadata. - 3. **Homebrew (`brew list --versions`)** - If applicable on macOS. - 4. **APT/DNF (`dpkg -s` or `rpm -q`)** - If applicable on Linux. - 5. **Windows Package Manager (`powershell Get-AppxPackage`)** - If applicable on Windows. - - ## Args: - - `package` (`str`): The package name to check. - - `configs` (`dict`): Configuration dictionary containing system environment details. - - ## Returns: - - `Optional[str]`: The installed package version if found, otherwise `None`. - - ## Notes: - - Uses structured logging to track package version retrieval. - - Ensures compatibility with externally managed Python environments. - """ env = configs.get("environment", {}) install_method = env.get("INSTALL_METHOD") @@ -383,21 +259,6 @@ def installed_version(package: str, configs: dict) -> Optional[str]: ## ----------------------------------------------------------------------------- def pip_latest_version(package: str) -> Optional[str]: - """ - Retrieve the latest available version of a package via Pip. - - This function executes `pip index versions ` to fetch a list of available - versions and extracts the latest one. - - ## Args: - - `package` (`str`): The package name to check. - - ## Returns: - - `Optional[str]`: The latest available version as a string if found, otherwise `None`. - - ## Notes: - - Requires internet access to fetch version information from PyPI. - """ try: result = subprocess.run( @@ -409,6 +270,16 @@ def pip_latest_version(package: str) -> Optional[str]: for line in result.stdout.splitlines(): if "Available versions:" in line: versions = line.split(":")[1].strip().split(", ") - return versions[0] if versions and versions[0] != "None" else None # ✅ Ensure `NoneType` is returned properly + return versions[0] if versions and versions[0] != "None" else None # Ensure `NoneType` is returned properly except subprocess.CalledProcessError: return None + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +def main() -> None: + pass + +if __name__ == "__main__": + main() diff --git a/run.json b/run.json index bf2e1b5..a69bad4 100644 --- a/run.json +++ b/run.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:45.863523+00:00", - "updated": "2025-03-10T01:18:09.143812+00:00" + "updated": "2025-03-10T06:15:17.961788+00:00" } } \ No newline at end of file diff --git a/tests/appflow_tracer/tracing/file_utils/test_file_utils.json b/tests/appflow_tracer/tracing/file_utils/test_file_utils.json index d7a56e4..6883c23 100644 --- a/tests/appflow_tracer/tracing/file_utils/test_file_utils.json +++ b/tests/appflow_tracer/tracing/file_utils/test_file_utils.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:48.438358+00:00", - "updated": "2025-03-10T01:17:18.914499+00:00" + "updated": "2025-03-10T06:15:06.726157+00:00" } } \ No newline at end of file diff --git a/tests/appflow_tracer/tracing/log_utils/test_log_utils.json b/tests/appflow_tracer/tracing/log_utils/test_log_utils.json index b9472cb..296fca8 100644 --- a/tests/appflow_tracer/tracing/log_utils/test_log_utils.json +++ b/tests/appflow_tracer/tracing/log_utils/test_log_utils.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:46.987976+00:00", - "updated": "2025-03-10T01:17:20.180796+00:00" + "updated": "2025-03-10T06:15:05.116581+00:00" } } \ No newline at end of file diff --git a/tests/appflow_tracer/tracing/serialize_utils/test_serialize_utils.json b/tests/appflow_tracer/tracing/serialize_utils/test_serialize_utils.json index 15a3550..9390a28 100644 --- a/tests/appflow_tracer/tracing/serialize_utils/test_serialize_utils.json +++ b/tests/appflow_tracer/tracing/serialize_utils/test_serialize_utils.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:47.451887+00:00", - "updated": "2025-03-10T01:17:21.557886+00:00" + "updated": "2025-03-10T06:15:05.629136+00:00" } } \ No newline at end of file diff --git a/tests/appflow_tracer/tracing/test_tracing.json b/tests/appflow_tracer/tracing/test_tracing.json index 537c096..1d5e63f 100644 --- a/tests/appflow_tracer/tracing/test_tracing.json +++ b/tests/appflow_tracer/tracing/test_tracing.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:46.492417+00:00", - "updated": "2025-03-10T01:17:30.096435+00:00" + "updated": "2025-03-10T06:15:04.585544+00:00" } } \ No newline at end of file diff --git a/tests/appflow_tracer/tracing/trace_utils/test_trace_utils.json b/tests/appflow_tracer/tracing/trace_utils/test_trace_utils.json index 4e0ec2b..f13afb5 100644 --- a/tests/appflow_tracer/tracing/trace_utils/test_trace_utils.json +++ b/tests/appflow_tracer/tracing/trace_utils/test_trace_utils.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:47.896763+00:00", - "updated": "2025-03-10T01:17:23.965686+00:00" + "updated": "2025-03-10T06:15:06.133617+00:00" } } \ No newline at end of file