diff --git a/.coverage b/.coverage new file mode 100644 index 0000000..37f3983 Binary files /dev/null and b/.coverage differ diff --git a/.gitignore b/.gitignore index 7c6ca7b..ae05772 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,13 @@ .DS_Store -## .legacy -## *--legacy.* +.legacy +*--legacy.* .outputs .project -## .prototypes -## *--prototype.* +.prototypes +*--prototype.* logs/ !logs/.gitkeep # Keeps the logs directory in Git but ignores its content @@ -56,9 +56,9 @@ pip-delete-this-directory.txt ## htmlcov/ .tox/ .nox/ -.coverage -## .coverage.* +# .coverage +.coverage.* .cache nosetests.xml @@ -75,7 +75,7 @@ cover/ # Django stuff: -## *.log +# *.log local_settings.py db.sqlite3 diff --git a/.pydocs/__init__.py b/.pydocs/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/.pydocs/pydoc.run.py b/.pydocs/pydoc.run.py index cf1ec0c..36575f7 100644 --- a/.pydocs/pydoc.run.py +++ b/.pydocs/pydoc.run.py @@ -1,6 +1,8 @@ #!/usr/bin/env python3 # Python File: ./lib/run.py + +__module__ = "run" __version__ = "0.1.0" # Documentation version # Module-level documentation diff --git a/docs/coverage/lib/system_variables.coverage b/docs/coverage/lib/system_variables.coverage index df06058..b39bdf6 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 22 22 0 0 0% +lib/system_variables.py 26 26 2 0 0% ----------------------------------------------------------- -TOTAL 22 22 0 0 0% +TOTAL 26 26 2 0 0% diff --git a/docs/coverage/lib/timezone_localoffset.coverage b/docs/coverage/lib/timezone_localoffset.coverage index 968aaef..bca4e16 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 42 42 4 0 0% +lib/timezone_localoffset.py 44 44 4 0 0% --------------------------------------------------------------- -TOTAL 42 42 4 0 0% +TOTAL 44 44 4 0 0% diff --git a/docs/coverage/packages/__init__.coverage b/docs/coverage/packages/__init__.coverage index e3905dc..81ac087 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 6 6 0 0 0% +packages/__init__.py 8 8 0 0 0% -------------------------------------------------------- -TOTAL 6 6 0 0 0% +TOTAL 8 8 0 0 0% diff --git a/docs/pydoc/lib/pkgconfig_loader.pydoc b/docs/pydoc/lib/pkgconfig_loader.pydoc index 7e57aa9..218bc8f 100644 --- a/docs/pydoc/lib/pkgconfig_loader.pydoc +++ b/docs/pydoc/lib/pkgconfig_loader.pydoc @@ -75,6 +75,9 @@ FUNCTIONS - Otherwise, the logs directory from the configuration is used. main() -> None + Function: main() -> None + Description: + Placeholder function for module execution. package_configs(overrides: Optional[dict] = None) -> dict Function: package_configs(overrides: Optional[dict] = None) -> dict @@ -162,7 +165,7 @@ DATA project_logs = PosixPath('/logs... project_packages = PosixPath('/... project_root = PosixPath('') - timestamp = '20250309231457' + timestamp = '20250310091339' VERSION 0.1.0 diff --git a/docs/pydoc/lib/system_variables.pydoc b/docs/pydoc/lib/system_variables.pydoc index 1c69d3d..6625d3a 100644 --- a/docs/pydoc/lib/system_variables.pydoc +++ b/docs/pydoc/lib/system_variables.pydoc @@ -49,6 +49,9 @@ DESCRIPTION - 0: Execution completed successfully. - 1: Error encountered during variable initialization. +FUNCTIONS + main() -> None + DATA category = namespace(calls=namespace(id='CALL', color='\x1b...'), rese... default_indent = 4 diff --git a/docs/pydoc/lib/timezone_localoffset.pydoc b/docs/pydoc/lib/timezone_localoffset.pydoc index 8f13b33..3958f5f 100644 --- a/docs/pydoc/lib/timezone_localoffset.pydoc +++ b/docs/pydoc/lib/timezone_localoffset.pydoc @@ -3,12 +3,104 @@ Help on module lib.timezone_localoffset in lib: NAME - lib.timezone_localoffset - # File: ./lib/timezone_localoffset.py + lib.timezone_localoffset - File Path: ./lib/timezone_localoffset.py + +DESCRIPTION + Description: + The timezone_localoffset.py module retrieves and calculates the local time zone and its offset from UTC. + It ensures accurate timekeeping and synchronization within the framework. + + Core Features: + - **Time Zone Detection**: Determines the local time zone using `pytz`. + - **UTC Offset Calculation**: Computes the difference between local time and UTC. + - **Command-Line Execution**: Provides CLI debugging for time zone information. + + Usage: + Retrieving Local Time Zone and Offset: + from lib.timezone_localoffset import get_local_offset + offset = get_local_offset(debug=True) + + Running as a CLI tool: + ```bash + python timezone_localoffset.py --debug + ``` + + Dependencies: + - sys - Handles system error logging. + - pytz - Provides accurate time zone calculations. + - datetime - Retrieves current timestamps. + - argparse - Parses command-line arguments. + + Global Behavior: + - Fetches local time zone details dynamically. + - Computes the UTC offset in hours. + - Supports CLI execution with optional debug output. + + CLI Integration: + This module supports command-line execution to retrieve and display time zone details. + + Example Execution: + ```bash + python timezone_localoffset.py --debug + ``` + + Expected Behavior: + - Successfully retrieves and prints the local time zone and offset. + - Displays additional debug information when enabled. + - Logs errors and exits with status `1` if time zone retrieval fails. + + Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered during time zone retrieval. FUNCTIONS get_local_offset(debug: bool = False) -> float + Function: get_local_offset(debug: bool = False) -> float + Description: + Retrieves and calculates the local time zone offset from UTC. + + Parameters: + - debug (bool, optional): Enables additional debugging output. Defaults to False. + + Returns: + - float: The UTC offset of the local time zone in hours. + + Workflow: + 1. Detects the system's local time zone using `pytz`. + 2. Retrieves the current local time and UTC time. + 3. Computes the time offset in hours. + 4. Prints formatted output for debugging if `debug` is enabled. + + Notes: + - The default time zone is set to `"America/Creston"`, but it should be dynamically + determined for broader applicability. + - If an error occurs, it is printed to `stderr`, and the function exits with a failure code. + + Error Handling: + - Logs errors if time zone retrieval or UTC offset calculation fails. main(debug: bool = False) -> None + Function: main(debug: bool = False) -> None + Description: + Main entry point for processing time zone offset calculations. + + Parameters: + - debug (bool, optional): Enables additional debugging output. Defaults to False. + + Returns: + - None: This function does not return a value; it handles execution flow. + + Workflow: + 1. Calls `get_local_offset()` with the `debug` flag. + 2. Captures and logs any errors. + 3. Exits with a non-zero status code if an error occurs. + + Notes: + - The function can be triggered via the command-line interface (CLI). + - Debug mode prints additional details about the local time zone. + + Error Handling: + - If an error occurs during time zone retrieval, the script exits with status `1`. DATA LocalOffset = None diff --git a/docs/pydoc/run.pydoc b/docs/pydoc/run.pydoc index 2984b51..79bb30b 100644 --- a/docs/pydoc/run.pydoc +++ b/docs/pydoc/run.pydoc @@ -117,7 +117,6 @@ FUNCTIONS DATA LIB_DIR = PosixPath('/lib') - __module_name__ = 'run' VERSION 0.1.0 diff --git a/docs/pydoc/scripts/__init__.pydoc b/docs/pydoc/scripts/__init__.pydoc index 2d38f83..1929582 100644 --- a/docs/pydoc/scripts/__init__.pydoc +++ b/docs/pydoc/scripts/__init__.pydoc @@ -3,7 +3,38 @@ Help on module scripts.__init__ in scripts: NAME - scripts.__init__ - # File: ./scripts/__init__.py + scripts.__init__ - File Path: scripts/__init__.py + +DESCRIPTION + Description: + Scripts Package Initialization + + This module ensures that the `scripts/` directory is recognized as a Python package. + It provides a structured framework for organizing standalone scripts while maintaining + explicit import control. + + Core Features: + - **Package Initialization**: Enables `scripts/` to function as a Python package. + - **Modular Script Management**: Ensures standalone scripts can be structured and executed efficiently. + - **Explicit Import Control**: Prevents unintended execution by requiring explicit script imports. + - **Future Expansion**: Can be extended to initialize common utilities if needed. + + Usage: + Scripts within `scripts/` should be explicitly imported when needed: + from scripts import some_script + some_script.execute() + + Important Notes: + - This file **does not** automatically import submodules to prevent unnecessary execution. + - Individual scripts must be explicitly imported as required to maintain modularity. + + Dependencies: + - None (This module is solely responsible for initialization) + + Example: + To execute a standalone script within `scripts/`: + from scripts import example_script + example_script.run() VERSION 0.1.0 diff --git a/docs/pydoc/scripts/testing.pydoc b/docs/pydoc/scripts/testing.pydoc index 6926594..a508e0f 100644 --- a/docs/pydoc/scripts/testing.pydoc +++ b/docs/pydoc/scripts/testing.pydoc @@ -3,58 +3,59 @@ Help on module scripts.testing in scripts: NAME - scripts.testing - File Path: ./scripts/testing.py + scripts.testing - File Path: scripts/testing.py DESCRIPTION Description: + Standalone Testing Script for Framework Logging - Standalone Testing Script for Framework Logging - - This script serves as a test module to verify logging and tracing capabilities. - It initializes structured logging via `packages.appflow_tracer.tracing`, - prints configuration details, and runs a simple test output. + This script serves as a test module to verify logging and tracing capabilities. + It initializes structured logging via `packages.appflow_tracer.tracing`, + prints configuration details, and runs a simple test output. Features: - - - Configures logging using `tracing.setup_logging()`. - - Prints the loaded logging configuration in JSON format. - - Serves as a standalone script that can be run independently. + - Configures logging using `tracing.setup_logging()`. + - Prints the loaded logging configuration in JSON format. + - Serves as a standalone script that can be run independently. Expected Behavior: - - - The script prints the structured logging configuration. - - Demonstrates logging setup and verification for debugging purposes. - - Can be used as a simple test script for logging functionality. + - The script prints the structured logging configuration. + - Demonstrates logging setup and verification for debugging purposes. + - Can be used as a simple test script for logging functionality. Dependencies: - - - `packages.appflow_tracer.tracing` (for structured logging) - - `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup) + - `packages.appflow_tracer.tracing` (for structured logging) + - `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup) Usage: + To execute the test: + python scripts/testing.py - To execute the test: - > python scripts/testing.py + Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to logging setup errors or missing configurations. FUNCTIONS main() -> None - Execute a standalone test to verify the structured logging system. + Function: main() -> None - This function: - - Configures logging using `tracing.setup_logging()`. - - Prints the loaded logging configuration in JSON format. - - Displays a test output message. + Description: + Execute a standalone test to verify the structured logging system. + + Parameters: + - None + + Returns: + - None: Executes logging setup and test message output. - Expected Behavior: - - The script prints structured logging configuration details. - - Demonstrates the integration of logging setup in a simple, standalone script. + Behavior: + - Configures logging using `tracing.setup_logging()`. + - Prints the loaded logging configuration in JSON format. + - Displays a test output message. Raises: Exception: If an error occurs during logging setup. - Returns: - None - Example: >>> python scripts/testing.py CONFIGS: { @@ -65,6 +66,9 @@ FUNCTIONS DATA PROJECT_ROOT = PosixPath('') +VERSION + 0.1.0 + FILE /scripts/testing.py diff --git a/docs/pydoc/tests/mocks/__init__.pydoc b/docs/pydoc/tests/mocks/__init__.pydoc new file mode 100644 index 0000000..c739552 --- /dev/null +++ b/docs/pydoc/tests/mocks/__init__.pydoc @@ -0,0 +1,17 @@ +### Documentation for tests/mocks/__init__.py + +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. +Help on module tests.mocks.__init__ in tests.mocks: + +NAME + tests.mocks.__init__ - # File: ./scripts/__init__.py + +VERSION + 0.1.0 + +FILE + /tests/mocks/__init__.py + + + diff --git a/docs/pydoc/tests/mocks/config_loader.pydoc b/docs/pydoc/tests/mocks/config_loader.pydoc index 1ee3392..5c8de1c 100644 --- a/docs/pydoc/tests/mocks/config_loader.pydoc +++ b/docs/pydoc/tests/mocks/config_loader.pydoc @@ -1,16 +1,102 @@ ### Documentation for tests/mocks/config_loader.py +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. Help on module tests.mocks.config_loader in tests.mocks: NAME - tests.mocks.config_loader - # File: ./tests/mocks/config_loader.py + tests.mocks.config_loader - File Path: tests/mocks/config_loader.py + +DESCRIPTION + Description: + Mock Configuration Loader for Test Environments + + This module provides structured mock configuration files for testing purposes. It ensures + that test cases operate with predictable configuration data by loading predefined JSON files + (`mock_requirements.json` and `mock_installed.json`). + + Core Features: + - Loads `mock_requirements.json` for testing dependency policies. + - Loads `mock_installed.json` for simulating installed packages. + - Ensures missing configuration fields are automatically populated. + - Prevents test failures due to missing or incomplete configuration files. + + Expected Behavior: + - If `mock_requirements.json` or `mock_installed.json` is missing, a default structure is used. + - Test cases can rely on consistent configuration values. + - Returns structured dictionaries with all required configuration fields. + + Dependencies: + - json (for reading and writing structured data) + - pathlib (for managing file paths) + + Usage: + ```python + from tests.mocks.config_loader import load_mock_requirements, load_mock_installed + + requirements = load_mock_requirements() + installed = load_mock_installed() + ``` FUNCTIONS load_mock_installed() -> dict - Load and return the contents of `mock_installed.json`, ensuring missing fields are populated. + Function: load_mock_installed() + + Description: + Loads and returns the contents of `mock_installed.json`, ensuring + that all required fields are present. If the file is missing, a default + base configuration is returned. + + Parameters: + - None + + Returns: + - dict: A structured dictionary representing the mock installed package configuration. + + Behavior: + - If `mock_installed.json` exists, its contents are loaded. + - If the file is missing, a predefined base configuration is used. + - Ensures all required keys are present in the loaded data. + + Example: + ```python + installed = load_mock_installed() + print(installed["packages"]["installation"]["configs"]) + ``` + + Notes: + - Used for testing dependency installations and package state validation. + - Guarantees test cases receive structured data. load_mock_requirements() -> dict - Load and return the contents of `mock_requirements.json`, ensuring missing fields are populated. + Function: load_mock_requirements() + + Description: + Loads and returns the contents of `mock_requirements.json`, ensuring + that all required fields are present. If the file is missing, a default + base configuration is returned. + + Parameters: + - None + + Returns: + - dict: A structured dictionary representing the mock requirements configuration. + + Behavior: + - If `mock_requirements.json` exists, its contents are loaded. + - If the file is missing, a predefined base configuration is used. + - Ensures all required keys are present in the loaded data. + + Example: + ```python + config = load_mock_requirements() + print(config["logging"]["enable"]) # True + ``` + + Notes: + - Prevents test failures due to missing configuration files. + - Populates default values for missing fields. + + main() -> None DATA BASE_INSTALLED_CONFIG = {'colors': {}, 'environment': {'BREW_AVAILABLE... @@ -18,7 +104,7 @@ DATA MOCKS_DIR = PosixPath('/tests/m... VERSION - 0.1.1 + 0.1.0 FILE /tests/mocks/config_loader.py diff --git a/docs/pydoc/tests/requirements/dependencies/package_utils/test_package_utils.pydoc b/docs/pydoc/tests/requirements/dependencies/package_utils/test_package_utils.pydoc index d0eb5b1..0d7f3b4 100644 --- a/docs/pydoc/tests/requirements/dependencies/package_utils/test_package_utils.pydoc +++ b/docs/pydoc/tests/requirements/dependencies/package_utils/test_package_utils.pydoc @@ -1,5 +1,6 @@ ### Documentation for tests/requirements/dependencies/package_utils/test_package_utils.py +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. Help on module tests.requirements.dependencies.package_utils.test_package_utils in tests.requirements.dependencies.package_utils: NAME diff --git a/docs/pydoc/tests/requirements/dependencies/policy_utils/test_policy_utils.pydoc b/docs/pydoc/tests/requirements/dependencies/policy_utils/test_policy_utils.pydoc index d2d143c..5c49b66 100644 --- a/docs/pydoc/tests/requirements/dependencies/policy_utils/test_policy_utils.pydoc +++ b/docs/pydoc/tests/requirements/dependencies/policy_utils/test_policy_utils.pydoc @@ -1,5 +1,6 @@ ### Documentation for tests/requirements/dependencies/policy_utils/test_policy_utils.py +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. Help on module tests.requirements.dependencies.policy_utils.test_policy_utils in tests.requirements.dependencies.policy_utils: NAME diff --git a/docs/pydoc/tests/requirements/dependencies/test_dependencies.pydoc b/docs/pydoc/tests/requirements/dependencies/test_dependencies.pydoc index 4a1957c..e6b4e14 100644 --- a/docs/pydoc/tests/requirements/dependencies/test_dependencies.pydoc +++ b/docs/pydoc/tests/requirements/dependencies/test_dependencies.pydoc @@ -1,5 +1,6 @@ ### Documentation for tests/requirements/dependencies/test_dependencies.py +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. Help on module tests.requirements.dependencies.test_dependencies in tests.requirements.dependencies: NAME @@ -65,11 +66,9 @@ FUNCTIONS DATA ANY = ROOT_DIR = PosixPath('') - __module_name__ = 'dependencies' - __package_name__ = 'requirements' VERSION - 0.1.1 + 0.1.0 FILE /tests/requirements/dependencies/test_dependencies.py diff --git a/docs/pydoc/tests/requirements/dependencies/version_utils/test_version_utils.pydoc b/docs/pydoc/tests/requirements/dependencies/version_utils/test_version_utils.pydoc index 2a77c2f..17fd0a4 100644 --- a/docs/pydoc/tests/requirements/dependencies/version_utils/test_version_utils.pydoc +++ b/docs/pydoc/tests/requirements/dependencies/version_utils/test_version_utils.pydoc @@ -1,5 +1,6 @@ ### Documentation for tests/requirements/dependencies/version_utils/test_version_utils.py +⚠️ No .pydoc file found at /tests/mocks/.pydocs/pydoc.__init__.py. Help on module tests.requirements.dependencies.version_utils.test_version_utils in tests.requirements.dependencies.version_utils: NAME diff --git a/lib/pkgconfig_loader.py b/lib/pkgconfig_loader.py index 0e496cb..51a39cb 100755 --- a/lib/pkgconfig_loader.py +++ b/lib/pkgconfig_loader.py @@ -244,13 +244,13 @@ def setup_configs( return config +def main() -> None: + pass + # 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__": config = setup_configs() diff --git a/lib/system_variables.py b/lib/system_variables.py index 9378a32..423abc8 100755 --- a/lib/system_variables.py +++ b/lib/system_variables.py @@ -60,3 +60,9 @@ # 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/lib/timezone_localoffset.py b/lib/timezone_localoffset.py index 7b3a972..81ef060 100755 --- a/lib/timezone_localoffset.py +++ b/lib/timezone_localoffset.py @@ -64,6 +64,10 @@ def main( print(f'Error processing time zone: {e}', file=sys.stderr) sys.exit( 1 ) +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + if __name__ == "__main__": # Command-line argument parsing for debug and verbose diff --git a/packages/.pydocs/pydoc.__init__.py b/packages/.pydocs/pydoc.__init__.py index 36e8f3f..588ff64 100644 --- a/packages/.pydocs/pydoc.__init__.py +++ b/packages/.pydocs/pydoc.__init__.py @@ -1,6 +1,10 @@ #!/usr/bin/env python3 # Python File: ./packages/__init__.py + +__package__ = "packages" +__module__ = "__init__" + __version__ = "0.1.0" # Documentation version MODULE_DOCSTRING = """ diff --git a/packages/__init__.py b/packages/__init__.py index c87f3ba..39035f3 100755 --- a/packages/__init__.py +++ b/packages/__init__.py @@ -1,7 +1,11 @@ #!/usr/bin/env python3 # File: ./packages/__init__.py -__version__ = "0.1.0" ## Package version + +__package__ = "packages" +__module__ = "__init__" + +__version__ = "0.1.0" # Modules version # Standard library imports - Core system module import sys diff --git a/packages/appflow_tracer/tracing.json b/packages/appflow_tracer/tracing.json index 84f3c57..11fc6cf 100644 --- a/packages/appflow_tracer/tracing.json +++ b/packages/appflow_tracer/tracing.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:12:33.522502+00:00", - "updated": "2025-03-05T16:57:20.687380+00:00" + "updated": "2025-03-10T16:14:32.453782+00:00" } } \ No newline at end of file diff --git a/packages/requirements/dependencies.json b/packages/requirements/dependencies.json index 607411d..e6e9c24 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-10T06:15:08.872914+00:00" + "updated": "2025-03-10T16:26:01.418203+00:00" } } \ No newline at end of file diff --git a/run.json b/run.json index a69bad4..6c00ffb 100644 --- a/run.json +++ b/run.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:10:45.863523+00:00", - "updated": "2025-03-10T06:15:17.961788+00:00" + "updated": "2025-03-10T16:14:17.831964+00:00" } } \ No newline at end of file diff --git a/run.py b/run.py index 6134369..014ed3b 100755 --- a/run.py +++ b/run.py @@ -2,19 +2,25 @@ # File: ./run.py -__module_name__ = "run" -__version__ = "0.1.0" ## Package version +__module__ = "run" +__version__ = "0.1.0" # Module version +# Standard library imports - Core system and OS interaction modules +import os +import sys +import subprocess + +# Standard library imports - Utility modules import argparse import json import logging -import os import pydoc import re -import subprocess -import sys + +# Standard library imports - File system-related module from pathlib import Path +# Third-party library imports - Testing and coverage tools import coverage import pytest @@ -31,6 +37,7 @@ ## Setup logging configuration # logging.basicConfig(level=logging.INFO) +# Ensure the current directory is added to sys.path sys.path.insert(0, str(Path(__file__).resolve().parent)) from lib import pydoc_generator as pydoc_engine @@ -38,9 +45,6 @@ from packages.appflow_tracer import tracing from packages.appflow_tracer.lib import log_utils -# Load documentation dynamically -from lib.pydoc_loader import load_pydocs - def collect_files( target_dir: str, extensions: list[str], @@ -174,12 +178,8 @@ def main(): if coverage_files: if Path(".coverage").exists() and Path(".coverage").stat().st_size > 0: subprocess.run( - [ - "python", - "-m", - "coverage", - "combine" - ], check=True + ["python", "-m", "coverage", "combine"], + check=True ) log_utils.log_message( f'Generating Coverage Report ...', @@ -190,14 +190,7 @@ def main(): htmlcov_dir = Path("docs") / "htmlcov" htmlcov_dir.mkdir(parents=True, exist_ok=True) subprocess.run( - [ - "python", - "-m", - "coverage", - "html", - "-d", - str(htmlcov_dir) - ], + ["python", "-m", "coverage", "html", "-d", str(htmlcov_dir)], check=True ) # log_utils.log_message( @@ -259,16 +252,14 @@ def main(): # configs=CONFIGS # ) -# # Load documentation dynamically and apply module, function and objects docstrings -# MODULE_DOCSTRING, FUNCTION_DOCSTRINGS, VARIABLE_DOCSTRINGS = load_pydocs(__file__, sys.modules[__name__]) -# __doc__ = MODULE_DOCSTRING +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs load_pydocs(__file__, sys.modules[__name__]) if __name__ == "__main__": + main() # print(f'Module Docstring:\n{__doc__}') # # print(f'parse_arguments.__doc__:\n{parse_arguments.__doc__}') # print(f'collect_files.__doc__:\n{collect_files.__doc__}') - - main() diff --git a/scripts/.pydocs/pydoc.__init__.py b/scripts/.pydocs/pydoc.__init__.py new file mode 100644 index 0000000..32fd307 --- /dev/null +++ b/scripts/.pydocs/pydoc.__init__.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 + +# Python File: ./scripts/__init__.py + +__package__ = "scripts" +__module__ = "__init__" + +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: scripts/__init__.py + +Description: + Scripts Package Initialization + + This module ensures that the `scripts/` directory is recognized as a Python package. + It provides a structured framework for organizing standalone scripts while maintaining + explicit import control. + +Core Features: + - **Package Initialization**: Enables `scripts/` to function as a Python package. + - **Modular Script Management**: Ensures standalone scripts can be structured and executed efficiently. + - **Explicit Import Control**: Prevents unintended execution by requiring explicit script imports. + - **Future Expansion**: Can be extended to initialize common utilities if needed. + +Usage: + Scripts within `scripts/` should be explicitly imported when needed: + from scripts import some_script + some_script.execute() + +Important Notes: + - This file **does not** automatically import submodules to prevent unnecessary execution. + - Individual scripts must be explicitly imported as required to maintain modularity. + +Dependencies: + - None (This module is solely responsible for initialization) + +Example: + To execute a standalone script within `scripts/`: + from scripts import example_script + example_script.run() +""" + +FUNCTION_DOCSTRINGS = {} + +VARIABLE_DOCSTRINGS = {} diff --git a/scripts/.pydocs/pydoc.testing.py b/scripts/.pydocs/pydoc.testing.py new file mode 100644 index 0000000..eaaeb6a --- /dev/null +++ b/scripts/.pydocs/pydoc.testing.py @@ -0,0 +1,97 @@ +#!/usr/bin/env python3 + +# Python File: ./scripts/testing.py + +__package__ = "scripts" +__module__ = "testing" + +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: scripts/testing.py + +Description: + Standalone Testing Script for Framework Logging + + This script serves as a test module to verify logging and tracing capabilities. + It initializes structured logging via `packages.appflow_tracer.tracing`, + prints configuration details, and runs a simple test output. + +Features: + - Configures logging using `tracing.setup_logging()`. + - Prints the loaded logging configuration in JSON format. + - Serves as a standalone script that can be run independently. + +Expected Behavior: + - The script prints the structured logging configuration. + - Demonstrates logging setup and verification for debugging purposes. + - Can be used as a simple test script for logging functionality. + +Dependencies: + - `packages.appflow_tracer.tracing` (for structured logging) + - `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup) + +Usage: + To execute the test: + python scripts/testing.py + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to logging setup errors or missing configurations. +""" + +FUNCTION_DOCSTRINGS = { + "main": """ + Function: main() -> None + + Description: + Execute a standalone test to verify the structured logging system. + + Parameters: + - None + + Returns: + - None: Executes logging setup and test message output. + + Behavior: + - Configures logging using `tracing.setup_logging()`. + - Prints the loaded logging configuration in JSON format. + - Displays a test output message. + + Raises: + Exception: If an error occurs during logging setup. + + Example: + >>> python scripts/testing.py + CONFIGS: { + "logging": { ... } + } + I am a stand-alone script minding my own business. + """ +} + +VARIABLE_DOCSTRINGS = { + "PROJECT_ROOT": """ + - Description: The root directory of the project, dynamically resolved. + - Type: Path + - Usage: Ensures the project's root directory is included in sys.path for imports. + """, + + "CONFIGS": """ + - Description: The global configuration dictionary containing logging and tracing settings. + - Type: dict + - Usage: Stores logging setup details, event configurations, and structured logging parameters. + """, + + "LOGGING": """ + - Description: Stores logging-related configuration settings. + - Type: dict + - Usage: Used for managing structured logging settings dynamically. + """, + + "logger": """ + - Description: The logging instance used for structured log messages. + - Type: logging.Logger + - Usage: Provides logging capabilities for debugging and structured event logging. + """ +} diff --git a/scripts/__init__.py b/scripts/__init__.py index f7e629e..5cd15a1 100755 --- a/scripts/__init__.py +++ b/scripts/__init__.py @@ -1,39 +1,21 @@ #!/usr/bin/env python3 # File: ./scripts/__init__.py -__version__ = "0.1.0" ## Package version -""" -File Path: ./scripts/__init__.py +__package__ = "scripts" +__module__ = "__init__" -Description: - Scripts Package Initialization +__version__ = "0.1.0" # Modules version - This file marks the `scripts/` directory as a valid Python package. It ensures - that standalone scripts within the framework can be properly imported and executed. +# Standard library imports - Core system module +import sys -Core Features: - - **Package Initialization**: Enables `scripts/` to be recognized as a Python package. - - **Modular Script Management**: Allows standalone scripts to be structured and executed efficiently. - - **Future Expansion**: Can be extended to initialize common utilities if needed. +# Standard library imports - File system-related module +from pathlib import Path -Usage: - Scripts within `scripts/` should be explicitly imported when needed: - ```python - from scripts import some_script - some_script.execute() - ``` +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) -Important: - - This file **does not** automatically import submodules to prevent unnecessary execution. - - Individual scripts must be explicitly imported as required. - -Dependencies: - - None (This module solely serves as an initialization file) - -Example: - ```python - from scripts import example_script - example_script.run() - ``` -""" +# 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/scripts/testing.json b/scripts/testing.json index fd1cb7f..d6653fc 100644 --- a/scripts/testing.json +++ b/scripts/testing.json @@ -36,6 +36,6 @@ }, "stats": { "created": "2025-03-03T18:13:42.599715+00:00", - "updated": "2025-03-05T16:57:39.183979+00:00" + "updated": "2025-03-10T16:14:15.369207+00:00" } } \ No newline at end of file diff --git a/scripts/testing.py b/scripts/testing.py index 429c9ec..90a63fd 100755 --- a/scripts/testing.py +++ b/scripts/testing.py @@ -1,49 +1,29 @@ #!/usr/bin/env python3 -""" -File Path: ./scripts/testing.py +# File: ./tests/mocks/config_loader.py -Description: +__package__ = "scripts" +__module__ = "testing" -Standalone Testing Script for Framework Logging - -This script serves as a test module to verify logging and tracing capabilities. -It initializes structured logging via `packages.appflow_tracer.tracing`, -prints configuration details, and runs a simple test output. - -Features: - -- Configures logging using `tracing.setup_logging()`. -- Prints the loaded logging configuration in JSON format. -- Serves as a standalone script that can be run independently. - -Expected Behavior: - -- The script prints the structured logging configuration. -- Demonstrates logging setup and verification for debugging purposes. -- Can be used as a simple test script for logging functionality. - -Dependencies: - -- `packages.appflow_tracer.tracing` (for structured logging) -- `sys`, `json`, `logging`, `pathlib` (for system interaction and logging setup) - -Usage: - -To execute the test: -> python scripts/testing.py -""" +__version__ = "0.1.0" # Module version +# Standard library imports - Core system module import sys + +# Standard library imports - Utility modules import json import logging +# Standard library imports - File system-related module from pathlib import Path # Add the project root to sys.path PROJECT_ROOT = Path(__file__).resolve().parent.parent sys.path.insert(0, str(PROJECT_ROOT)) +# 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 @@ -53,31 +33,6 @@ ) def main() -> None: - """ - Execute a standalone test to verify the structured logging system. - - This function: - - Configures logging using `tracing.setup_logging()`. - - Prints the loaded logging configuration in JSON format. - - Displays a test output message. - - Expected Behavior: - - The script prints structured logging configuration details. - - Demonstrates the integration of logging setup in a simple, standalone script. - - Raises: - Exception: If an error occurs during logging setup. - - Returns: - None - - Example: - >>> python scripts/testing.py - CONFIGS: { - "logging": { ... } - } - I am a stand-alone script minding my own business. - """ global LOGGING, CONFIGS, logger # Ensure CONFIGS is globally accessible @@ -90,5 +45,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/test-pydoc.shell b/test-pydoc.shell index 298d9b1..59d48ea 100644 --- a/test-pydoc.shell +++ b/test-pydoc.shell @@ -1,8 +1,15 @@ #!/usr/bin/env bash -# while true; do rm .coverage.*; rm -rf ./logs/*; pytest -xsv tests/ && sleep 60 && clear; done; -# while true; do rm -rf ./docs; python run.py --pydoc --coverage && sleep 60 && ctree ./docs && clear; done; -# while true; do python -m packages.requirements.dependencies && sleep 60 && clear; done; +# pytest -xvs tests/test_run.py ; +# while true; do rm .coverage.*; rm -rf ./logs/*; pytest -xsv tests/ && sleep 300 && clear; done; +# while true; do rm -rf ./docs; python run.py --pydoc --coverage && sleep 300 && ctree ./docs && clear; done; +# while true; do python -m scripts.testing && sleep 300 && clear; done; +# while true; do python -m packages.requirements.dependencies && sleep 300 && clear; done; +# while true; do python -m packages.appflow_tracer && sleep 300 && clear; done; +# while true; do python -m packages.appflow_tracer.tracing && sleep 300 && clear; done; +# bash ./test-pydoc.shell ; + +## Library modules: python -m pydoc lib.__init__ | bat - ; @@ -18,26 +25,50 @@ python -m pydoc lib.system_params | bat - ; python -m pydoc lib.system_variables | bat - ; python -m pydoc lib.timezone_localoffset | bat - ; +## Packages modules: + python -m pydoc packages.__init__ | bat - ; +## Packages AppFlow-Tracer: + python -m pydoc packages.appflow_tracer.__init__ | bat - ; python -m pydoc packages.appflow_tracer.__main__ | bat - ; +## Packages AppFlow-Tracer - Tracing module: + python -m pydoc packages.appflow_tracer.tracing | bat - ; +## Packages AppFlow-Tracer - Sub-Modules Library: + python -m pydoc packages.appflow_tracer.lib.__init__ | bat - ; python -m pydoc packages.appflow_tracer.lib.file_utils | bat - ; python -m pydoc packages.appflow_tracer.lib.log_utils | bat - ; python -m pydoc packages.appflow_tracer.lib.serialize_utils | bat - ; python -m pydoc packages.appflow_tracer.lib.trace_utils | bat - ; +## Packages Requirements: + python -m pydoc packages.requirements.__init__ | bat - ; python -m pydoc packages.requirements.__main__ | bat - ; +## Packages Requirements - Dependencies module: + python -m pydoc packages.requirements.dependencies | bat - ; +## Packages Requirements - Sub-Modules Library: + python -m pydoc packages.requirements.lib.__init__ | bat - ; python -m pydoc packages.requirements.lib.brew_utils | bat - ; python -m pydoc packages.requirements.lib.package_utils | bat - ; python -m pydoc packages.requirements.lib.policy_utils | bat - ; python -m pydoc packages.requirements.lib.version_utils | bat - ; + +## Packages Framework: + +python -m pydoc run | bat - ; +python -m pydoc tests.conftest | bat - ; +python -m pydoc tests.mocks.config_loader | bat - ; + +## PyTesting Framework: + +python -m pydoc tests.test_run | bat - ; diff --git a/tests/.pydocs/pydoc.conftest.py b/tests/.pydocs/pydoc.conftest.py new file mode 100644 index 0000000..b2c4b28 --- /dev/null +++ b/tests/.pydocs/pydoc.conftest.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 + +# Python File: ./tests/conftest.py + +__package__ = "tests" +__module__ = "conftest" + +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: tests/conftest.py + +Description: + PyTest Configuration Module for the Testing Framework + + This module provides shared test configurations, fixtures, and base configurations + for testing various components of the system. It ensures consistency in test execution + and provides reusable mock configurations. + +Core Features: + - Centralized Test Configuration: Establishes a standardized setup for PyTest execution. + - Dynamic Package Configuration: Generates base configurations dynamically per module. + - Mock Data Loading: Provides preconfigured test environments using `mock_requirements.json` + and `mock_installed.json`. + - Path Management: Ensures that project directories are properly included in `sys.path`. + +Usage: + This module is automatically loaded by PyTest when running tests within the `tests/` directory. + +Dependencies: + - pytest (for defining test fixtures) + - pathlib (for handling file paths) + - sys (for managing system path imports) + - mocks.config_loader (for loading mock configurations) + +Example: + ```python + def test_example(requirements_config): + assert "logging" in requirements_config + ``` + +Exit Codes: + - 0: Execution completed successfully. + - 1: Error encountered in fixture loading or configuration processing. +""" + +FUNCTION_DOCSTRINGS = { + "get_base_config": """ + Function: get_base_config(package_name: str, module_name: str) -> dict + + Description: + Generates a base configuration dynamically based on the given package and module names. + + Parameters: + - package_name (str): The name of the package under test (e.g., "requirements"). + - module_name (str): The name of the module under test (e.g., "package_utils"). + + Returns: + - dict: A base configuration dictionary containing logging, tracing, events, stats, + package installation settings, and environment details. + + Example: + base_config = get_base_config("requirements", "package_utils") + print(base_config["logging"]["package_name"]) # Output: "requirements" + """, + + "requirements_config": """ + Function: requirements_config(request) -> dict + + Description: + PyTest fixture for loading policy-based package configurations from `mock_requirements.json`. + Ensures all required fields exist before returning the configuration. + + Parameters: + - request (FixtureRequest): PyTest's request object to fetch module-specific attributes. + + Returns: + - dict: A dictionary containing policy-based package configurations. + + Expected Behavior: + - Loads configurations dynamically and merges them with default settings. + - Converts package installation paths to `Path` objects. + + Example: + def test_config(requirements_config): + assert "logging" in requirements_config + """, + + "installed_config": """ + Function: installed_config(request) -> dict + + Description: + PyTest fixture for loading installed package configurations from `mock_installed.json`. + Ensures alignment between `dependencies` (installed.json) and `requirements` (CONFIGS). + + Parameters: + - request (FixtureRequest): PyTest's request object to fetch module-specific attributes. + + Returns: + - dict: A dictionary containing installed package configurations. + + Expected Behavior: + - Loads configurations dynamically and merges them with base settings. + - Ensures `dependencies` field is populated correctly. + - Converts package installation paths to `Path` objects. + + Example: + def test_installed(installed_config): + assert "dependencies" in installed_config + """ +} + +VARIABLE_DOCSTRINGS = { + "ROOT_DIR": """ + - Description: Root directory of the project, used to manage system path imports. + - Type: Path + - Usage: Ensures that test modules can access the required package directories. + """, + + "MODULE_DOCSTRING": """ + - Description: Contains the module-level documentation for `conftest.py`. + - Type: str + - Usage: Defines module description, features, usage, and dependencies. + """ +} diff --git a/tests/.pydocs/pydoc.test_run.py b/tests/.pydocs/pydoc.test_run.py new file mode 100644 index 0000000..b007cb8 --- /dev/null +++ b/tests/.pydocs/pydoc.test_run.py @@ -0,0 +1,246 @@ +#!/usr/bin/env python3 + +# Python File: ./tests/test_run.py + +__package__ = "tests" +__module__ = "test_run" + +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: tests/test_run.py + +Description: + PyTest Module for Validating Execution of run.py + + This module ensures that run.py correctly handles: + - Command-line argument parsing. + - File collection for Python scripts. + - Execution of pydoc and coverage reporting. + - Structured logging of execution steps. + +Test Coverage: + 1. Argument Parsing (parse_arguments) + - Ensures correct CLI flag interpretation. + - Confirms SystemExit is raised for --help. + + 2. File Collection (collect_files) + - Verifies Python files are properly discovered. + + 3. Execution & Coverage (main) + - Validates handling of --pydoc and --coverage flags. + - Mocks subprocesses and file interactions. + +Mocking Strategy: + - subprocess.run() → Prevents actual system calls. + - log_utils.log_message() → Ensures structured logging messages. + - collect_files() → Controls file collection behavior. + +Expected Behavior: + - run.py correctly processes command-line arguments. + - Backup, restore, and migration options execute correctly. + - Logging captures all major execution steps. + +Exit Codes: + - 0: Execution completed successfully. + - 1: Failure due to invalid arguments or execution errors. +""" + +FUNCTION_DOCSTRINGS = { + "serialize_configs": """ + Function: serialize_configs(configs) + + Description: + Converts configuration data into a JSON-serializable format by ensuring + that all PosixPath objects are converted to strings. + + Parameters: + - configs (dict): The configuration dictionary containing paths. + + Returns: + - dict: A JSON-serializable dictionary. + + Notes: + - Required to ensure compatibility when serializing configuration data + for logging or debugging purposes. + """, + + "test_parse_arguments": """ + Function: test_parse_arguments(args, expected_attr, expected_value) + + Description: + Tests the argument parsing functionality of parse_arguments, ensuring that + CLI flags are correctly interpreted. + + Parameters: + - args (list[str]): List of CLI arguments to simulate. + - expected_attr (str): The expected attribute in the parsed result. + - expected_value (Any): The expected value of the parsed attribute. + + Returns: + - None: Assertions validate expected behavior. + + Expected Behavior: + - CLI arguments are parsed correctly. + - SystemExit is NOT raised unless explicitly required. + """, + + "test_collect_files": """ + Function: test_collect_files(mock_project_structure) + + Description: + Validates that collect_files() correctly discovers Python files within a project structure. + + Parameters: + - mock_project_structure (tuple): A mocked directory containing Python files. + + Returns: + - None: Assertions verify file discovery. + + Expected Behavior: + - The function correctly identifies .py files. + - Returns an absolute path list of discovered files. + """, + + "test_main_pydoc": """ + Function: test_main_pydoc(mock_subprocess, mock_create_pydocs, monkeypatch, tmp_path) + + Description: + Ensures that main() correctly triggers --pydoc generation. + + Parameters: + - mock_subprocess (Mock): Mocks subprocess.run(). + - mock_create_pydocs (Mock): Mocks create_pydocs() execution. + - monkeypatch (pytest.MonkeyPatch): Modifies system behavior for testing. + - tmp_path (Path): Temporary directory for test files. + + Returns: + - None: Assertions verify expected execution behavior. + + Expected Behavior: + - --pydoc triggers PyDoc generation. + - Calls create_pydocs() with correct parameters. + """, + + "test_main_coverage": """ + Function: test_main_coverage(mock_generate_report, mock_check_output, mock_subprocess, monkeypatch, tmp_path) + + Description: + Ensures that main() correctly triggers --coverage reporting when --pydoc --coverage is used. + + Parameters: + - mock_generate_report (Mock): Mocks generate_report() execution. + - mock_check_output (Mock): Simulates subprocess.check_output(). + - mock_subprocess (Mock): Mocks subprocess.run() calls. + - monkeypatch (pytest.MonkeyPatch): Modifies system behavior. + - tmp_path (Path): Temporary directory for test artifacts. + + Returns: + - None: Assertions verify expected execution. + + Expected Behavior: + - --pydoc triggers PyDoc generation. + - --coverage ensures coverage data is included. + - generate_report() is executed successfully. + """, + + "mock_project_structure": """ + Function: mock_project_structure() + + Description: + A pytest fixture that simulates a project directory structure containing Python files. + + Parameters: + - None + + Returns: + - tuple: A tuple containing the base directory and a mock Python file. + + Expected Behavior: + - The fixture correctly sets up a directory with mock Python files. + - Used in testing collect_files(). + """, + + "test_main_backup": """ + Function: test_main_backup(requirements_config) + + Description: + Ensures that main() correctly handles backup operations. + + Parameters: + - requirements_config (dict): Configuration dictionary for package dependencies. + + Returns: + - None: Assertions validate correct execution. + + Expected Behavior: + - Backup process is triggered. + - backup_packages() is called with correct arguments. + """, + + "test_main_restore": """ + Function: test_main_restore(requirements_config) + + Description: + Ensures that main() correctly handles restore operations. + + Parameters: + - requirements_config (dict): Configuration dictionary for package dependencies. + + Returns: + - None: Assertions validate correct execution. + + Expected Behavior: + - Restore process is triggered. + - restore_packages() is called with correct arguments. + """, + + "test_main_migration": """ + Function: test_main_migration(requirements_config) + + Description: + Ensures that main() correctly handles migration operations. + + Parameters: + - requirements_config (dict): Configuration dictionary for package dependencies. + + Returns: + - None: Assertions validate correct execution. + + Expected Behavior: + - Migration process is triggered. + - migrate_packages() is called with correct arguments. + """ +} + +VARIABLE_DOCSTRINGS = { + "ROOT_DIR": """ + - Description: The root directory of the project, dynamically resolved. + - Type: Path + - Usage: Ensures the project's root directory is included in sys.path. + """, + + "test_args": """ + - Description: The simulated command-line arguments for testing. + - Type: list[str] + - Usage: Used to mock CLI argument parsing for unit tests. + """, + + "mock_project_structure": """ + - Description: A fixture that simulates a project directory with Python files. + - Type: pytest.fixture + - Usage: Ensures collect_files() function behaves as expected in tests. + """, + + "mock_file": """ + - Description: A temporary Python file used for testing pydoc generation. + - Type: Path + - Usage: Ensures PyDoc generation functions correctly in a controlled test environment. + """, + + "coverage_report": """ + - Description: A temporary file storing coverage report data. + - Type: Path + - Usage: Used to validate that coverage data is correctly written and read. + """ +} 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 6883c23..6d165bc 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-10T06:15:06.726157+00:00" + "updated": "2025-03-10T16:13:48.200523+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 296fca8..cf4aa5c 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-10T06:15:05.116581+00:00" + "updated": "2025-03-10T16:13:46.631931+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 9390a28..9ae76b1 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-10T06:15:05.629136+00:00" + "updated": "2025-03-10T16:13:47.132592+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 1d5e63f..bb71b2a 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-10T06:15:04.585544+00:00" + "updated": "2025-03-10T16:13:46.107850+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 f13afb5..7c65b2d 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-10T06:15:06.133617+00:00" + "updated": "2025-03-10T16:13:47.620074+00:00" } } \ No newline at end of file diff --git a/tests/conftest.py b/tests/conftest.py index 41f2e04..1e7cf0e 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,11 +1,28 @@ #!/usr/bin/env python3 # File: ./tests/conftest.py -__version__ = "0.1.2" ## Updated Package version -import pytest +__package__ = "tests" +__module__ = "conftest" + +__version__ = "0.1.0" # Updated Package version + +# Standard library imports - Core system module +import sys +# Standard library imports - File system-related module from pathlib import Path + +import pytest + +# Ensure the root project directory is in sys.path +ROOT_DIR = Path(__file__).resolve().parents[1] +if str(ROOT_DIR) not in sys.path: + sys.path.insert(0, str(ROOT_DIR)) + +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + from mocks.config_loader import ( load_mock_requirements, load_mock_installed @@ -96,3 +113,13 @@ def installed_config(request) -> dict: base_config["packages"]["installation"]["configs"] = Path(base_config["packages"]["installation"]["configs"]) return base_config + +def main() -> None: + pass + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +if __name__ == "__main__": + main() diff --git a/tests/mocks/.pydocs/pydoc.config_loader.py b/tests/mocks/.pydocs/pydoc.config_loader.py new file mode 100644 index 0000000..78b1fab --- /dev/null +++ b/tests/mocks/.pydocs/pydoc.config_loader.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 + +# Python File: ./tests/mocks/config_loader.py + +__package__ = "tests.mocks" +__module__ = "config_loader" + +__version__ = "0.1.0" # Documentation version + +MODULE_DOCSTRING = """ +File Path: tests/mocks/config_loader.py + +Description: + Mock Configuration Loader for Test Environments + + This module provides structured mock configuration files for testing purposes. It ensures + that test cases operate with predictable configuration data by loading predefined JSON files + (`mock_requirements.json` and `mock_installed.json`). + +Core Features: + - Loads `mock_requirements.json` for testing dependency policies. + - Loads `mock_installed.json` for simulating installed packages. + - Ensures missing configuration fields are automatically populated. + - Prevents test failures due to missing or incomplete configuration files. + +Expected Behavior: + - If `mock_requirements.json` or `mock_installed.json` is missing, a default structure is used. + - Test cases can rely on consistent configuration values. + - Returns structured dictionaries with all required configuration fields. + +Dependencies: + - json (for reading and writing structured data) + - pathlib (for managing file paths) + +Usage: + ```python + from tests.mocks.config_loader import load_mock_requirements, load_mock_installed + + requirements = load_mock_requirements() + installed = load_mock_installed() + ``` +""" + +FUNCTION_DOCSTRINGS = { + "load_mock_requirements": """ + Function: load_mock_requirements() + + Description: + Loads and returns the contents of `mock_requirements.json`, ensuring + that all required fields are present. If the file is missing, a default + base configuration is returned. + + Parameters: + - None + + Returns: + - dict: A structured dictionary representing the mock requirements configuration. + + Behavior: + - If `mock_requirements.json` exists, its contents are loaded. + - If the file is missing, a predefined base configuration is used. + - Ensures all required keys are present in the loaded data. + + Example: + ```python + config = load_mock_requirements() + print(config["logging"]["enable"]) # True + ``` + + Notes: + - Prevents test failures due to missing configuration files. + - Populates default values for missing fields. + """, + + "load_mock_installed": """ + Function: load_mock_installed() + + Description: + Loads and returns the contents of `mock_installed.json`, ensuring + that all required fields are present. If the file is missing, a default + base configuration is returned. + + Parameters: + - None + + Returns: + - dict: A structured dictionary representing the mock installed package configuration. + + Behavior: + - If `mock_installed.json` exists, its contents are loaded. + - If the file is missing, a predefined base configuration is used. + - Ensures all required keys are present in the loaded data. + + Example: + ```python + installed = load_mock_installed() + print(installed["packages"]["installation"]["configs"]) + ``` + + Notes: + - Used for testing dependency installations and package state validation. + - Guarantees test cases receive structured data. + """ +} + +VARIABLE_DOCSTRINGS = { + "MOCKS_DIR": """ + - Description: Absolute path to the `tests/mocks/` directory. + - Type: Path + - Usage: Used as the base directory for locating mock JSON files. + """, + + "BASE_REQUIREMENTS_CONFIG": """ + - Description: Default structure for `mock_requirements.json` if missing. + - Type: dict + - Usage: Provides baseline settings for logging, tracing, and package installation. + """, + + "BASE_INSTALLED_CONFIG": """ + - Description: Default structure for `mock_installed.json` if missing. + - Type: dict + - Usage: Mirrors `BASE_REQUIREMENTS_CONFIG` but includes package installation details. + """ +} diff --git a/tests/mocks/__init__.py b/tests/mocks/__init__.py new file mode 100644 index 0000000..a94034a --- /dev/null +++ b/tests/mocks/__init__.py @@ -0,0 +1,21 @@ +#!/usr/bin/env python3 + +# File: ./scripts/__init__.py + +__package__ = "tests.mocks" +__module__ = "__init__" + +__version__ = "0.1.0" # Modules 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)) + +# 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/tests/mocks/config_loader.py b/tests/mocks/config_loader.py index a9bc48b..e2d38b0 100644 --- a/tests/mocks/config_loader.py +++ b/tests/mocks/config_loader.py @@ -1,11 +1,22 @@ #!/usr/bin/env python3 # File: ./tests/mocks/config_loader.py -__version__ = "0.1.1" ## Updated Package version +__package__ = "tests.mocks" +__module__ = "config_loader" + +__version__ = "0.1.0" # Module version + +# Standard library imports - Core system module +import sys import json + +# 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)) + MOCKS_DIR = Path(__file__).resolve().parent # `tests/mocks/` # ✅ Base structure for `mock_requirements.json` (policy settings) @@ -44,7 +55,6 @@ # ✅ Base structure for `mock_installed.json` (installed packages) BASE_INSTALLED_CONFIG = { - "colors": BASE_REQUIREMENTS_CONFIG["colors"], "logging": BASE_REQUIREMENTS_CONFIG["logging"], "tracing": BASE_REQUIREMENTS_CONFIG["tracing"], @@ -84,3 +94,13 @@ def load_mock_installed() -> dict: data.setdefault(key, BASE_INSTALLED_CONFIG[key]) return data + +def main() -> None: + pass + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +if __name__ == "__main__": + main() diff --git a/tests/requirements/dependencies/test_dependencies.py b/tests/requirements/dependencies/test_dependencies.py index 8998f65..618e759 100644 --- a/tests/requirements/dependencies/test_dependencies.py +++ b/tests/requirements/dependencies/test_dependencies.py @@ -2,10 +2,10 @@ # File: ./tests/requirements/dependencies/test_dependencies_utils.py -__package_name__ = "requirements" -__module_name__ = "dependencies" +__package__ = "tests.requirements" +__module__ = "dependencies" -__version__ = "0.1.1" ## Updated Test Module version +__version__ = "0.1.0" ## Updated Test Module version """ # PyTest Module: test_dependencies_utils.py diff --git a/tests/test_run.py b/tests/test_run.py index d43c48f..23a402a 100755 --- a/tests/test_run.py +++ b/tests/test_run.py @@ -1,64 +1,45 @@ #!/usr/bin/env python3 # File: ./tests/test_run.py -__version__ = "0.1.2" ## Updated Test Module version -""" -# PyTest Module: test_run.py +__package__ = "tests" +__module__ = "test_run" -## Overview: - This module tests the execution logic of `run.py`, ensuring that: - - Command-line argument parsing works as expected. - - Main execution logic handles different options correctly. - - `pydoc` generation and coverage reporting execute properly. - -## Test Coverage: - 1. **Argument Parsing (`parse_arguments()`)** - - Ensures correct CLI flag interpretation. - - Confirms SystemExit is raised for `--help`. - - 2. **File Collection (`collect_files()`)** - - Verifies Python files are properly discovered. - - 3. **Execution & Coverage (`main()`)** - - Validates correct handling of `--pydoc` and `--coverage` flags. - - Mocks subprocesses and file interactions to isolate tests. - -## Mocking Strategy: - - `subprocess.run()` → Prevents actual system calls. - - `log_utils.log_message()` → Ensures structured logging messages. - - `collect_files()` → Controls file collection behavior. - -## Expected Behavior: - - `run.py` correctly processes command-line arguments. - - Backup, restore, and migration options execute correctly. - - Logging captures all major execution steps. -""" +__version__ = "0.1.0" # PyTest version +# Standard library imports - Core system module import sys -import pytest -import argparse import subprocess +import argparse import json +# Standard library imports - File system-related module +from pathlib import Path + +# Standard library imports - Unit testing and mocking tools from unittest.mock import ( ANY, MagicMock, patch ) -from pathlib import Path + +# Third-party library imports - Testing framework +import pytest # Ensure the root project directory is in sys.path ROOT_DIR = Path(__file__).resolve().parents[1] if str(ROOT_DIR) not in sys.path: sys.path.insert(0, str(ROOT_DIR)) -from packages.appflow_tracer import tracing +# Ensure the current directory is added to sys.path +sys.path.insert(0, str(Path(__file__).resolve().parent)) + import run +from packages.appflow_tracer import tracing -# ✅ Convert PosixPath objects into strings for JSON serialization +# Convert PosixPath objects into strings for JSON serialization def serialize_configs(configs): - """Convert PosixPath objects to strings for JSON serialization.""" + return json.loads(json.dumps(configs, default=lambda o: str(o) if isinstance(o, Path) else o)) # ------------------------------------------------------------------------------ @@ -66,66 +47,45 @@ def serialize_configs(configs): # ------------------------------------------------------------------------------ @pytest.mark.parametrize("args, expected_attr, expected_value", [ - ([], "pydoc", False), # ✅ Default value (no arguments) - (["--pydoc"], "pydoc", True), # ✅ Enable PyDoc generation - (["--coverage"], "coverage", True), # ✅ Enable Coverage Mode - (["--target", "tests/example.py"], "target", "tests/example.py"), # ✅ Specify target file + ([], "pydoc", False), # Default value (no arguments) + (["--pydoc"], "pydoc", True), # Enable PyDoc generation + (["--coverage"], "coverage", True), # Enable Coverage Mode + (["--target", "tests/example.py"], "target", "tests/example.py"), # Specify target file ]) def test_parse_arguments(args, expected_attr, expected_value): - """Ensure `parse_arguments()` correctly handles command-line arguments.""" - test_args = ["run.py"] + args # ✅ Ensure script name is included + + test_args = ["run.py"] + args # Ensure script name is included with patch.object(sys, "argv", test_args), \ - patch("sys.exit") as mock_exit: # ✅ Prevent argparse from exiting + patch("sys.exit") as mock_exit: # Prevent argparse from exiting - parsed_args = run.parse_arguments() # ✅ Call the function + parsed_args = run.parse_arguments() # Call the function - # ✅ Ensure correct argument parsing + # Ensure correct argument parsing assert getattr(parsed_args, expected_attr) == expected_value, \ f"Expected `{expected_attr}={expected_value}`, but got `{getattr(parsed_args, expected_attr, None)}`" - mock_exit.assert_not_called() # ✅ Ensure no forced exit happened + mock_exit.assert_not_called() # Ensure no forced exit happened # ------------------------------------------------------------------------------ # Test: collect_files() # ------------------------------------------------------------------------------ -# @pytest.fixture -# def mock_project_structure(tmp_path): -# """Creates a temporary project structure for testing `collect_files()`.""" -# base_dir = tmp_path / "mock_project" -# base_dir.mkdir(parents=True, exist_ok=True) -# -# mock_file = base_dir / "mock_file.py" -# mock_file.write_text("def mock_function(): pass") # Create a non-empty Python file -# -# return base_dir, mock_file - @pytest.fixture def mock_project_structure(): - """Mocks a project structure with Python files for `collect_files()` test.""" + with patch("pathlib.Path.is_dir", return_value=True), \ patch("pathlib.Path.rglob", return_value=[Path("mock_project/mock_file.py")]), \ patch("pathlib.Path.stat", return_value=MagicMock(st_size=10)): # Simulate non-empty file yield Path("mock_project"), Path("mock_project/mock_file.py") -# def test_collect_files(mock_project_structure): -# """Ensure `collect_files()` correctly identifies Python files.""" -# base_dir, mock_file = mock_project_structure -# files_list = run.collect_files(base_dir, extensions=[".py"]) -# -# expected_files = {str(mock_file)} -# collected_files = {str(file) for file in files_list} -# -# assert collected_files == expected_files, f"Expected {expected_files}, but got {collected_files}" - def test_collect_files(mock_project_structure): - """Ensure `collect_files()` correctly identifies Python files.""" + base_dir, mock_file = mock_project_structure files_list = run.collect_files(base_dir, extensions=[".py"]) - expected_files = {str(mock_file.resolve())} # ✅ Convert to absolute path + expected_files = {str(mock_file.resolve())} # Convert to absolute path collected_files = {str(file) for file in files_list} assert collected_files == expected_files, f"Expected {expected_files}, but got {collected_files}" @@ -181,7 +141,7 @@ def test_collect_files(mock_project_structure): @patch("lib.pydoc_generator.create_pydocs") @patch("subprocess.run") def test_main_pydoc(mock_subprocess, mock_create_pydocs, monkeypatch, tmp_path): - """Ensure `main()` correctly handles `--pydoc` generation.""" + monkeypatch.setattr("sys.argv", ["run.py", "--pydoc"]) mock_file = tmp_path / "mock_file.py" mock_file.write_text("def mock_function(): pass") @@ -200,30 +160,9 @@ def test_main_pydoc(mock_subprocess, mock_create_pydocs, monkeypatch, tmp_path): # Test: main() - Coverage # ------------------------------------------------------------------------------ -# @patch("subprocess.run") -# @patch("coverage.Coverage") -# @patch("lib.pydoc_generator.generate_report") -# def test_main_coverage(mock_generate_report, mock_coverage, mock_subprocess, monkeypatch): -# """Ensure `main()` correctly handles coverage processing.""" -# monkeypatch.setattr("sys.argv", ["run.py", "--coverage"]) -# test_file = Path(__file__).resolve() -# -# mock_cov_instance = mock_coverage.return_value -# mock_cov_instance.start.return_value = None -# mock_cov_instance.stop.return_value = None -# mock_cov_instance.save.return_value = None -# -# with patch("run.collect_files", return_value=[test_file]): -# run.main() -# -# mock_cov_instance.start.assert_called_once() -# mock_cov_instance.stop.assert_called_once() -# mock_cov_instance.save.assert_called_once() -# mock_generate_report.assert_called_once() - @patch("subprocess.run") -@patch("subprocess.check_output", return_value="mock coverage output\n") # ✅ Fix TypeError issue -@patch("lib.pydoc_generator.generate_report") # ✅ Mock PyDoc since coverage is part of it +@patch("subprocess.check_output", return_value="mock coverage output\n") # Fix TypeError issue +@patch("lib.pydoc_generator.generate_report") # Mock PyDoc since coverage is part of it def test_main_coverage( mock_generate_report, mock_check_output, @@ -231,48 +170,51 @@ def test_main_coverage( monkeypatch, tmp_path ): - """ - Ensure `main()` correctly triggers PyDoc with coverage when `--pydoc --coverage` is used. - - **Fixes:** - - ✅ Ensures `generate_report()` is triggered. - - ✅ Confirms subprocess calls related to `coverage` are executed inside `pydoc`. - - ✅ Handles `TypeError` by ensuring `subprocess.check_output()` returns a string. - - ✅ Fixes `FileNotFoundError` by simulating coverage report creation. - - **Expected Behavior:** - - `--pydoc` triggers PyDoc generation. - - `--coverage` ensures that coverage is part of the PyDoc process. - - `generate_report()` is called. - - `subprocess.run(["coverage", "html"])` is executed. - - `docs/coverage/coverage.report` is created and read successfully. - """ - - # ✅ Simulate CLI args: run.py --pydoc --coverage - monkeypatch.setattr("sys.argv", ["run.py", "--pydoc", "--coverage"]) + + # Simulate CLI args: run.py --pydoc --coverage + monkeypatch.setattr( + "sys.argv", + ["run.py", "--pydoc", "--coverage"] + ) test_file = Path(__file__).resolve() - # ✅ Ensure `docs/coverage/coverage.report` exists before it is read + # Ensure `docs/coverage/coverage.report` exists before it is read coverage_report = tmp_path / "coverage.report" coverage_report.write_text("Mock Coverage Report\n") - # ✅ Make `mock_generate_report` simulate file creation + # Make `mock_generate_report` simulate file creation def _generate_mock_report(*args, **kwargs): if "coverage_report" in kwargs: kwargs["coverage_report"].write_text("Generated Coverage Report\n") mock_generate_report.side_effect = _generate_mock_report - # ✅ Mock file collection (should return this test file) + # Mock file collection (should return this test file) with patch("run.collect_files", return_value=[test_file]): run.main() - # ✅ Ensure `generate_report()` was called (since PyDoc handles coverage) + # Ensure `generate_report()` was called (since PyDoc handles coverage) mock_generate_report.assert_called_once() - # ✅ Ensure `coverage combine` and `coverage html` were executed inside PyDoc - mock_subprocess.assert_any_call(["python", "-m", "coverage", "combine"], check=True) - mock_subprocess.assert_any_call(["python", "-m", "coverage", "html", "-d", "docs/htmlcov"], check=True) + # Ensure `coverage combine` and `coverage html` were executed inside PyDoc + mock_subprocess.assert_any_call( + ["python", "-m", "coverage", "combine"], + check=True + ) + mock_subprocess.assert_any_call( + ["python", "-m", "coverage", "html", "-d", "docs/htmlcov"], + check=True + ) - # ✅ Ensure `coverage.report` file was created + # Ensure `coverage.report` file was created assert coverage_report.exists(), "Expected coverage report file to be created but it does not exist." + +def main() -> None: + pass + +# Load documentation dynamically and apply module, function and objects docstrings +from lib.pydoc_loader import load_pydocs +load_pydocs(__file__, sys.modules[__name__]) + +if __name__ == "__main__": + main()