python-code-validator 0.1.2__tar.gz → 0.2.1__tar.gz

{python_code_validator-0.1.2/src/python_code_validator.egg-info → python_code_validator-0.2.1}/PKG-INFO

@@ -1,49 +1,32 @@
 Metadata-Version: 2.4
 Name: python-code-validator
-Version: 0.1.2
-Summary: A flexible framework for static validation of Python code based on JSON rules.
+Version: 0.2.1
+Summary: A flexible, AST-based framework for static validation of Python code using declarative JSON rules.
 Author-email: Qu1nel <covach.qn@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 Ivan Kovach
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/Qu1nel/PythonCodeValidator
 Project-URL: Documentation, https://pythoncodevalidator.readthedocs.io/en/latest/
 Project-URL: Bug Tracker, https://github.com/Qu1nel/PythonCodeValidator/issues
-Keywords: validation,linter,static analysis,testing,education
-Classifier: Development Status :: 3 - Alpha
+Keywords: validation,linter,static analysis,testing,education,ast
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Education
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: flake8>=7.0.0
 Provides-Extra: dev
 Requires-Dist: ruff>=0.4.0; extra == "dev"
-Requires-Dist: flake8>=7.0.0; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
-Requires-Dist: coverage>=7.5.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.5.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0.0; extra == "docs"
 Requires-Dist: furo; extra == "docs"
@@ -282,7 +265,7 @@ Validation failed.
   **[Read the Docs](https://[your-project].readthedocs.io)**.
 - **Developer's Guide**: For a deep dive into the architecture, see the
   **[How It Works guide](./docs/how_it_works/index.md)**.
-- **Interactive AI-Powered Docs**: *(Coming Soon)* An interactive documentation experience.
+- **Interactive AI-Powered Docs**: **[DeepWiki](https://deepwiki.com/Qu1nel/PythonCodeValidator)**.
 
 ## 🤝 Contributing
 

{python_code_validator-0.1.2 → python_code_validator-0.2.1}/README.md

@@ -229,7 +229,7 @@ Validation failed.
   **[Read the Docs](https://[your-project].readthedocs.io)**.
 - **Developer's Guide**: For a deep dive into the architecture, see the
   **[How It Works guide](./docs/how_it_works/index.md)**.
-- **Interactive AI-Powered Docs**: *(Coming Soon)* An interactive documentation experience.
+- **Interactive AI-Powered Docs**: **[DeepWiki](https://deepwiki.com/Qu1nel/PythonCodeValidator)**.
 
 ## 🤝 Contributing
 
@@ -253,4 +253,4 @@ Email: **[covach.qn@gmail.com](mailto:covach.qn@gmail.com)** Telegram: **[@qnlln
 
 <br/>
 
-<p align="right"><a href="./LICENSE">MIT</a> © <a href="https://github.com/Qu1nel/">Ivan Kovach</a></p>
+<p align="right"><a href="./LICENSE">MIT</a> © <a href="https://github.com/Qu1nel/">Ivan Kovach</a></p>

python_code_validator-0.2.1/pyproject.toml

@@ -0,0 +1,120 @@
+# ==============================================================================
+#  Build System Configuration (PEP 517/518)
+# ==============================================================================
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+# ==============================================================================
+#  Project Metadata (PEP 621)
+# ==============================================================================
+[project]
+name = "python-code-validator"
+version = "0.2.1"
+description = "A flexible, AST-based framework for static validation of Python code using declarative JSON rules."
+keywords = ["validation", "linter", "static analysis", "testing", "education", "ast"]
+authors = [{ name = "Qu1nel", email = "covach.qn@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.11"
+license-files = ["LICEN[CS]E*"]
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Education",
+]
+
+dependencies = [
+    "flake8>=7.0.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/Qu1nel/PythonCodeValidator"
+"Documentation" = "https://pythoncodevalidator.readthedocs.io/en/latest/"
+"Bug Tracker" = "https://github.com/Qu1nel/PythonCodeValidator/issues"
+
+
+[project.scripts]
+validate-code = "code_validator.cli:run_from_cli"
+
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.4.0",
+    "build",
+    "twine",
+    "coverage[toml]>=7.5.0",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "furo",
+    "myst-parser",
+    "sphinx-design",
+]
+
+# ==============================================================================
+#  Tool Configuration
+# ==============================================================================
+
+[tool.ruff]
+line-length = 120
+exclude = [
+    ".venv",
+    "build",
+    "dist",
+    "src/python_code_validator.egg-info",
+    "tests/fixtures",
+]
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle errors
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "I", # isort
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "D", # pydocstyle
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "D100", # Missing docstring in public module
+    "D101", # Missing docstring in public class
+    "D102", # Missing docstring in public method
+    "D103", # Missing docstring in public function
+    "D104", # Missing docstring in public package
+    "D107", # Missing docstring in __init__
+]
+"src/code_validator/components/__init__.py" = ["D104"]
+"src/code_validator/rules_library/__init__.py" = ["D104"]
+"src/code_validator/components/factories.py" = ["D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["code_validator", "tests"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.coverage.run]
+omit = [
+    "src/code_validator/__main__.py",
+    "src/code_validator/cli.py",
+    "tests/*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true

python_code_validator-0.2.1/src/code_validator/__init__.py

@@ -0,0 +1,57 @@
+"""A flexible framework for static validation of Python code.
+
+This package provides a comprehensive toolkit for statically analyzing Python
+source code based on a declarative set of rules defined in a JSON format. It
+allows for checking syntax, style, structure, and constraints without
+executing the code.
+
+The primary entry point for using this package programmatically is the
+`StaticValidator` class.
+
+Example:
+    A minimal example of using the validator as a library.
+
+    .. code-block:: python
+
+        from code_validator import StaticValidator, AppConfig, LogLevel
+        from code_validator.output import Console, setup_logging
+        from pathlib import Path
+
+        # Basic setup
+        logger = setup_logging(LogLevel.INFO)
+        console = Console(logger)
+        config = AppConfig(
+            solution_path=Path("path/to/solution.py"),
+            rules_path=Path("path/to/rules.json"),
+            log_level=LogLevel.INFO,
+            is_silent=False,
+            stop_on_first_fail=False
+        )
+
+        # Run validation
+        validator = StaticValidator(config, console)
+        is_valid = validator.run()
+
+        if is_valid:
+            print("Validation Passed!")
+
+Attributes:
+    __version__ (str): The current version of the package.
+    __all__ (list[str]): The list of public objects exposed by the package.
+
+"""
+
+from .config import AppConfig, ExitCode, LogLevel
+from .core import StaticValidator
+from .exceptions import RuleParsingError, ValidationFailedError
+
+__all__ = [
+    "StaticValidator",
+    "AppConfig",
+    "ExitCode",
+    "LogLevel",
+    "ValidationFailedError",
+    "RuleParsingError",
+]
+
+__version__ = "0.2.1"

python_code_validator-0.2.1/src/code_validator/__main__.py

@@ -0,0 +1,20 @@
+"""Enables running the validator as a package.
+
+This file allows the package to be executed directly from the command line
+using the ``-m`` flag with Python (e.g., ``python -m code_validator``). It
+serves as the primary entry point that finds and invokes the command-line
+interface logic defined in the `cli` module.
+
+Example:
+    You can run the validator package like this from the project root:
+
+    .. code-block:: bash
+
+        python -m code_validator path/to/solution.py path/to/rules.json
+
+"""
+
+from .cli import run_from_cli
+
+if __name__ == "__main__":
+    run_from_cli()

python_code_validator-0.2.1/src/code_validator/cli.py

@@ -0,0 +1,112 @@
+"""Defines the command-line interface for the code validator.
+
+This module is responsible for parsing command-line arguments, setting up the
+application configuration, and orchestrating the main validation workflow. It acts
+as the primary entry point for user interaction when the tool is called from
+the terminal.
+
+The main function, `run_from_cli`, handles the entire application lifecycle,
+including robust top-level error handling to ensure meaningful exit codes.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import AppConfig, ExitCode, LogLevel
+from .core import StaticValidator
+from .exceptions import CodeValidatorError
+from .output import Console, setup_logging
+
+
+def setup_arg_parser() -> argparse.ArgumentParser:
+    """Creates and configures the argument parser for the CLI.
+
+    This function defines all positional and optional arguments that the
+    `validate-code` command accepts, including their types, help messages,
+    and default values.
+
+    Returns:
+        argparse.ArgumentParser: A fully configured parser instance ready to
+            process command-line arguments.
+    """
+    parser = argparse.ArgumentParser(
+        prog="validate-code",
+        description="Validates a Python source file against a set of JSON rules.",
+    )
+
+    parser.add_argument("solution_path", type=Path, help="Path to the Python solution file to validate.")
+    parser.add_argument("rules_path", type=Path, help="Path to the JSON file with validation rules.")
+
+    parser.add_argument(
+        "--log",
+        type=LogLevel,
+        default=LogLevel.ERROR,
+        help=("Set the logging level for stderr (TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: ERROR."),
+    )
+    parser.add_argument(
+        "--quiet", action="store_true", help="Suppress all stdout output (validation errors and final verdict)."
+    )
+    parser.add_argument("--no-verdict", action="store_true", help="Suppress stdout output verdict, show failed rules.")
+    parser.add_argument("--stop-on-first-fail", action="store_true", help="Stop after the first failed rule.")
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def run_from_cli() -> None:
+    """Runs the full application lifecycle from the command line.
+
+    This is the main entry point for the `validate-code` script. It performs
+    the following steps:
+    1. Parses command-line arguments.
+    2. Initializes the logger, console, and configuration.
+    3. Instantiates and runs the `StaticValidator`.
+    4. Handles all top-level exceptions and exits with an appropriate status code.
+
+    Raises:
+        SystemExit: This function will always terminate the process with an
+            exit code defined in the `ExitCode` enum.
+    """
+    parser = setup_arg_parser()
+    args = parser.parse_args()
+
+    logger = setup_logging(args.log)
+    console = Console(logger, is_quiet=args.quiet, show_verdict=not args.no_verdict)
+    console.print(f"Level of logging: {args.log}", level=LogLevel.DEBUG)
+    config = AppConfig(
+        solution_path=args.solution_path,
+        rules_path=args.rules_path,
+        log_level=args.log,
+        is_quiet=args.quiet,
+        stop_on_first_fail=args.stop_on_first_fail,
+    )
+    console.print(f"Config is: {config}", level=LogLevel.TRACE)
+
+    try:
+        console.print(f"Starting validation for: {config.solution_path}", level=LogLevel.INFO)
+        validator = StaticValidator(config, console)
+
+        console.print("Start of validation..", level=LogLevel.TRACE)
+        is_valid = validator.run()
+        console.print(f"End of validation with result: {is_valid = }", level=LogLevel.TRACE)
+
+        if is_valid:
+            console.print("Validation successful.", level=LogLevel.INFO, is_verdict=True)
+            sys.exit(ExitCode.SUCCESS)
+        else:
+            console.print("Validation failed.", level=LogLevel.INFO, is_verdict=True)
+            sys.exit(ExitCode.VALIDATION_FAILED)
+
+    except CodeValidatorError as e:
+        console.print("Error: Internal Error of validator!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for CodeValidatorError: {e}")
+        sys.exit(ExitCode.VALIDATION_FAILED)
+    except FileNotFoundError as e:
+        console.print(f"Error: File not found - {e.filename}!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for FileNotFoundError: {e}")
+        sys.exit(ExitCode.FILE_NOT_FOUND)
+    except Exception as e:
+        console.print(f"An unexpected error occurred: {e.__class__.__name__}!", level=LogLevel.CRITICAL)
+        logger.exception(f"Traceback for unexpected error: {e}")
+        sys.exit(ExitCode.UNEXPECTED_ERROR)

{python_code_validator-0.1.2 → python_code_validator-0.2.1}/src/code_validator/components/ast_utils.py

@@ -1,4 +1,9 @@
-"""Provides utility functions for working with Python's Abstract Syntax Trees (AST)."""
+"""Provides utility functions for working with Python's Abstract Syntax Trees (AST).
+
+This module contains helper functions that perform common operations on AST nodes,
+such as enriching the tree with parent references. These utilities are used by
+various components of the validator to simplify complex tree analysis.
+"""
 
 import ast
 
@@ -15,7 +20,6 @@ def enrich_ast_with_parents(tree: ast.Module) -> None:
     """
     for node in ast.walk(tree):
         for child in ast.iter_child_nodes(node):
-            # Dynamically add a reference to the parent node.
             child.parent = node
 
 

{python_code_validator-0.1.2 → python_code_validator-0.2.1}/src/code_validator/components/definitions.py

@@ -1,10 +1,11 @@
-"""Defines the core component interfaces using Protocols.
+"""Defines the core component interfaces for the validator using Protocols.
 
 This module establishes the fundamental "contracts" for the main architectural
-components of the validator: Rules, Selectors, and Constraints. By using
-Protocols, we ensure that any class conforming to these interfaces can be used
-interchangeably by the system's factories and core engine, enabling a flexible
-and decoupled plugin-style architecture.
+components: Rules, Selectors, and Constraints. By using `typing.Protocol`, we
+ensure that any class conforming to these interfaces can be used interchangeably
+by the system's factories and core engine. This enables a flexible and
+decoupled plugin-style architecture, where new components can be added without
+modifying the core logic.
 """
 
 import ast

{python_code_validator-0.1.2 → python_code_validator-0.2.1}/src/code_validator/components/factories.py

@@ -1,17 +1,18 @@
 """Contains factories for creating rule, selector, and constraint objects.
 
 This module implements the Factory Method design pattern to decouple the core
-validator engine from the concrete implementation of rules. Factories are
-responsible for parsing raw dictionary configurations from JSON and instantiating
-the appropriate handler classes.
+validator engine from the concrete implementations of its components. Factories
+are responsible for parsing raw dictionary configurations from the main JSON
+rules file and instantiating the appropriate handler classes from the
+`rules_library`.
 """
 
 import dataclasses
 from typing import Any, Type, TypeVar
 
-from ..config import ConstraintConfig, FullRuleCheck, FullRuleConfig, SelectorConfig, ShortRuleConfig
+from ..config import ConstraintConfig, FullRuleCheck, FullRuleConfig, LogLevel, SelectorConfig, ShortRuleConfig
 from ..exceptions import RuleParsingError
-from ..output import Console
+from ..output import Console, log_initialization
 from ..rules_library.basic_rules import CheckLinterRule, CheckSyntaxRule, FullRuleHandler
 from ..rules_library.constraint_logic import (
     IsForbiddenConstraint,
@@ -70,6 +71,7 @@ class RuleFactory:
         _constraint_factory (ConstraintFactory): A factory for creating constraint objects.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
     def __init__(self, console: Console):
         """Initializes the RuleFactory.
 
@@ -100,8 +102,10 @@ class RuleFactory:
                 required keys, or specifies an unknown type.
         """
         rule_id = rule_config.get("rule_id")
+        self._console.print(f"Start parsing rule ({rule_id}):\n{rule_config}", level=LogLevel.TRACE)
         try:
             if "type" in rule_config:
+                self._console.print(f"Rule {rule_id} is shorted rule - {rule_config['type']}", level=LogLevel.DEBUG)
                 config = _create_dataclass_from_dict(ShortRuleConfig, rule_config)
                 return self._create_short_rule(config)
 
@@ -109,20 +113,31 @@ class RuleFactory:
                 raw_selector_cfg = rule_config["check"]["selector"]
                 raw_constraint_cfg = rule_config["check"]["constraint"]
 
-                selector = self._selector_factory.create(raw_selector_cfg)
-                constraint = self._constraint_factory.create(raw_constraint_cfg)
-
                 selector_cfg = _create_dataclass_from_dict(SelectorConfig, raw_selector_cfg)
                 constraint_cfg = _create_dataclass_from_dict(ConstraintConfig, raw_constraint_cfg)
+
+                selector = self._selector_factory.create(selector_cfg)
+                constraint = self._constraint_factory.create(constraint_cfg)
+
+                self._console.print(
+                    f"Rule {rule_id} is general rule with: selector - "
+                    f"{selector_cfg.type}, constraint - {raw_constraint_cfg['type']}",
+                    level=LogLevel.DEBUG,
+                )
+
                 check_cfg = FullRuleCheck(selector=selector_cfg, constraint=constraint_cfg)
+                self._console.print(f"Create FullRuleCheck: {check_cfg}", level=LogLevel.TRACE)
+
                 config = FullRuleConfig(
                     rule_id=rule_config["rule_id"],
                     message=rule_config["message"],
                     check=check_cfg,
                     is_critical=rule_config.get("is_critical", False),
                 )
+                self._console.print(f"Create FullRuleConfig: {config}", level=LogLevel.TRACE)
                 return FullRuleHandler(config, selector, constraint, self._console)
             else:
+                self._console.print(f"Invalid syntax of rule: {rule_id}", level=LogLevel.WARNING)
                 raise RuleParsingError("Rule must contain 'type' or 'check' key.", rule_id)
         except (TypeError, KeyError, RuleParsingError) as e:
             raise RuleParsingError(f"Invalid config for rule '{rule_id}': {e}", rule_id) from e
@@ -164,21 +179,23 @@ class SelectorFactory:
     any state.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
+    def __init__(self) -> None:
+        pass
+
     @staticmethod
-    def create(selector_config: dict[str, Any]) -> Selector:
+    def create(config: SelectorConfig) -> Selector:
         """Creates a specific selector instance based on its type.
 
         This method uses the 'type' field from the selector configuration
         to determine which concrete Selector class to instantiate.
 
         Args:
-            selector_config: The 'selector' block from a JSON rule.
+            config: The 'selector' block from a JSON rule.
 
         Returns:
             An instance of a class that conforms to the Selector protocol.
         """
-        config = _create_dataclass_from_dict(SelectorConfig, selector_config)
-
         match config.type:
             case "function_def":
                 return FunctionDefSelector(name=config.name, in_scope_config=config.in_scope)
@@ -209,21 +226,23 @@ class ConstraintFactory:
     to a list of AST nodes. This class uses a static `create` method.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
+    def __init__(self) -> None:
+        pass
+
     @staticmethod
-    def create(constraint_config: dict[str, Any]) -> Constraint:
+    def create(config: ConstraintConfig) -> Constraint:
         """Creates a specific constraint instance based on its type.
 
         This method uses the 'type' field from the constraint configuration
         to determine which concrete Constraint class to instantiate.
 
         Args:
-            constraint_config: The 'constraint' block from a JSON rule.
+            config: The 'constraint' block from a JSON rule.
 
         Returns:
             An instance of a class that conforms to the Constraint protocol.
         """
-        config = _create_dataclass_from_dict(ConstraintConfig, constraint_config)
-
         match config.type:
             case "is_required":
                 return IsRequiredConstraint(count=config.count)

{python_code_validator-0.1.2 → python_code_validator-0.2.1}/src/code_validator/components/scope_handler.py

@@ -1,8 +1,10 @@
 """Provides functionality to find and isolate specific scopes within an AST.
 
-This module contains helper functions that are used by ScopedSelectors to narrow
-down their search area from the entire module to a specific function, class,
-or method, based on the `in_scope` configuration from a JSON rule.
+This module contains a key helper function, `find_scope_node`, which is used
+by `ScopedSelector` instances. Its purpose is to traverse the AST and return
+a specific subtree (e.g., a function body or class body) based on the
+`in_scope` configuration from a JSON rule. This allows rules to be applied
+with high precision to specific parts of the source code.
 """
 
 import ast