python-code-validator 0.1.2__py3-none-any.whl → 0.1.3__py3-none-any.whl

code_validator/__init__.py

@@ -1,17 +1,47 @@
 """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.
-
-Key components exposed by this package include:
-    - StaticValidator: The main orchestrator for running the validation process.
-    - AppConfig: A dataclass for configuring the validator's behavior.
-    - ExitCode: An Enum defining exit codes for CLI operations.
-    - Custom Exceptions: For fine-grained error handling during validation.
+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
+from .config import AppConfig, ExitCode, LogLevel
 from .core import StaticValidator
 from .exceptions import RuleParsingError, ValidationFailedError
 
@@ -19,7 +49,9 @@ __all__ = [
     "StaticValidator",
     "AppConfig",
     "ExitCode",
+    "LogLevel",
     "ValidationFailedError",
     "RuleParsingError",
 ]
-__version__ = "0.1.2"
+
+__version__ = "0.1.3"

code_validator/__main__.py

@@ -1,8 +1,17 @@
-"""Enables running the validator as a module.
+"""Enables running the validator as a package.
 
 This file allows the package to be executed directly from the command line
-using `python -m code_validator`. It serves as the main entry point
-that invokes the command-line interface logic.
+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

code_validator/cli.py

@@ -2,7 +2,11 @@
 
 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.
+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
@@ -19,8 +23,13 @@ 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:
-        An instance of argparse.ArgumentParser with all arguments defined.
+        argparse.ArgumentParser: A fully configured parser instance ready to
+            process command-line arguments.
     """
     parser = argparse.ArgumentParser(
         prog="validate-code",
@@ -32,7 +41,7 @@ def setup_arg_parser() -> argparse.ArgumentParser:
         "-l",
         "--log-level",
         type=LogLevel,
-        choices=LogLevel,
+        choices=list(LogLevel),
         default=LogLevel.WARNING,
         help="Set the logging level (default: WARNING).",
     )
@@ -45,14 +54,20 @@ def setup_arg_parser() -> argparse.ArgumentParser:
 def run_from_cli() -> None:
     """Runs the full application lifecycle from the command line.
 
-    This function parses arguments, initializes logging and configuration,
-    runs the validator, and handles all top-level exceptions, exiting with an
-    appropriate exit code.
+    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()
 
-    # 1. Setup environment
     logger = setup_logging(args.log_level)
     console = Console(logger, is_silent=args.silent)
     config = AppConfig(
@@ -63,7 +78,6 @@ def run_from_cli() -> None:
         stop_on_first_fail=args.stop_on_first_fail,
     )
 
-    # 2. Run main logic with robust error handling
     try:
         console.print(f"Starting validation for: {config.solution_path}", level=LogLevel.INFO)
         validator = StaticValidator(config, console)

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
 
 

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

code_validator/components/factories.py

@@ -1,9 +1,10 @@
 """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

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

code_validator/config.py

@@ -34,7 +34,15 @@ class LogLevel(StrEnum):
 
 @dataclass(frozen=True)
 class AppConfig:
-    """Stores the main application configuration from CLI arguments."""
+    """Stores the main application configuration from CLI arguments.
+
+    Attributes:
+        solution_path: The file path to the Python solution to be validated.
+        rules_path: The file path to the JSON rules file.
+        log_level: The minimum logging level for console output.
+        is_silent: If True, suppresses all non-log output to stdout.
+        stop_on_first_fail: If True, halts validation after the first failed rule.
+    """
 
     solution_path: Path
     rules_path: Path
@@ -45,7 +53,18 @@ class AppConfig:
 
 @dataclass(frozen=True)
 class SelectorConfig:
-    """Represents the configuration for a Selector component from a JSON rule."""
+    """Represents the configuration for a Selector component from a JSON rule.
+
+    This dataclass captures all possible keys within the "selector" block
+    of a JSON validation rule.
+
+    Attributes:
+        type: The type of the selector to be used (e.g., "function_def").
+        name: A generic name parameter used by many selectors (e.g., the name
+            of a function, class, or module).
+        node_type: The AST node type name for the `ast_node` selector.
+        in_scope: The scope in which to apply the selector.
+    """
 
     type: str
     name: str | None = None
@@ -55,7 +74,21 @@ class SelectorConfig:
 
 @dataclass(frozen=True)
 class ConstraintConfig:
-    """Represents the configuration for a Constraint component from a JSON rule."""
+    """Represents the configuration for a Constraint component from a JSON rule.
+
+    This dataclass captures all possible keys within the "constraint" block
+    of a JSON validation rule.
+
+    Attributes:
+        type: The type of the constraint to be applied (e.g., "is_required").
+        count: The exact number of nodes expected. Used by `is_required`.
+        parent_name: The expected parent class name. Used by `must_inherit_from`.
+        expected_type: The expected Python type name. Used by `must_be_type`.
+        allowed_names: A list of permitted names. Used by `name_must_be_in`.
+        allowed_values: A list of permitted literal values. Used by `value_must_be_in`.
+        names: A list of expected argument names. Used by `must_have_args`.
+        exact_match: A boolean flag for argument matching. Used by `must_have_args`.
+    """
 
     type: str
     count: int | None = None
@@ -69,7 +102,12 @@ class ConstraintConfig:
 
 @dataclass(frozen=True)
 class FullRuleCheck:
-    """Represents the 'check' block within a full validation rule."""
+    """Represents the 'check' block within a full validation rule.
+
+    Attributes:
+        selector: The configuration for the selector component.
+        constraint: The configuration for the constraint component.
+    """
 
     selector: SelectorConfig
     constraint: ConstraintConfig
@@ -77,7 +115,14 @@ class FullRuleCheck:
 
 @dataclass(frozen=True)
 class ShortRuleConfig:
-    """Represents a 'short' (pre-defined) validation rule from JSON."""
+    """Represents a 'short' (pre-defined) validation rule from JSON.
+
+    Attributes:
+        rule_id: The unique integer identifier for the rule.
+        type: The string identifier for the short rule (e.g., "check_syntax").
+        message: The error message to display if the rule fails.
+        params: A dictionary of optional parameters for the rule.
+    """
 
     rule_id: int
     type: str
@@ -87,7 +132,14 @@ class ShortRuleConfig:
 
 @dataclass(frozen=True)
 class FullRuleConfig:
-    """Represents a 'full' (custom) validation rule with selector and constraint."""
+    """Represents a 'full' (custom) validation rule with a selector and constraint.
+
+    Attributes:
+        rule_id: The unique integer identifier for the rule.
+        message: The error message to display if the rule fails.
+        check: An object containing the selector and constraint configurations.
+        is_critical: If True, validation halts if this rule fails.
+    """
 
     rule_id: int
     message: str

code_validator/core.py

@@ -1,3 +1,44 @@
+"""The core engine of the Python Code Validator.
+
+This module contains the main orchestrator class, `StaticValidator`, which is
+responsible for managing the entire validation lifecycle. It loads the source
+code and a set of JSON rules, then uses a factory-based component system to
+execute each rule and report the results.
+
+The core is designed to be decoupled from the specific implementations of rules,
+selectors, and constraints, allowing for high extensibility.
+
+Example:
+    To run a validation, you would typically use the CLI, but the core can also
+    be used programmatically:
+
+    .. code-block:: python
+
+        from code_validator import StaticValidator, AppConfig, LogLevel
+        from code_validator.output import Console, setup_logging
+        from pathlib import Path
+        import logging
+
+        logger = logging.getLogger(__name__)
+        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
+        )
+
+        validator = StaticValidator(config, console)
+        is_valid = validator.run()
+
+        if is_valid:
+            print("Validation Passed!")
+        else:
+            print(f"Validation Failed. Errors in: {validator.failed_rules_id}")
+
+"""
+
 import ast
 import json
 
@@ -10,25 +51,50 @@ from .output import Console
 
 
 class StaticValidator:
-    """Orchestrates the static validation process."""
+    """Orchestrates the static validation process.
+
+    This class is the main entry point for running a validation session. It
+    manages loading of source files and rules, parsing the code into an AST,
+    and iterating through the rules to execute them.
+
+    Attributes:
+        _config (AppConfig): The application configuration object.
+        _console (Console): The handler for all logging and stdout printing.
+        _rule_factory (RuleFactory): The factory responsible for creating rule objects.
+        _source_code (str): The raw text content of the Python file being validated.
+        _ast_tree (ast.Module | None): The Abstract Syntax Tree of the source code.
+        _rules (list[Rule]): A list of initialized, executable rule objects.
+        _failed_rules (list[int]): A list of rule IDs that failed during the run.
+    """
 
     def __init__(self, config: AppConfig, console: Console):
-        """Initializes the validator with configuration and an output handler."""
+        """Initializes the StaticValidator.
+
+        Args:
+            config: An `AppConfig` object containing all necessary run
+                configurations, such as file paths and flags.
+            console: A `Console` object for handling all output.
+        """
         self._config = config
         self._console = console
         self._rule_factory = RuleFactory(self._console)
         self._source_code: str = ""
         self._ast_tree: ast.Module | None = None
-        self._validation_rules: list[Rule] = []
+        self._rules: list[Rule] = []
         self._failed_rules: list[int] = []
 
     @property
     def failed_rules_id(self) -> list[int]:
-        """Returns a list of rule IDs that failed during the last run."""
+        """list[int]: A list of rule IDs that failed during the last run."""
         return self._failed_rules
 
     def _load_source_code(self) -> None:
-        """Loads the content of the student's solution file."""
+        """Loads the content of the student's solution file into memory.
+
+        Raises:
+            FileNotFoundError: If the source file specified in the config does not exist.
+            RuleParsingError: If the source file cannot be read for any other reason.
+        """
         self._console.print(f"Reading source file: {self._config.solution_path}")
         try:
             self._source_code = self._config.solution_path.read_text(encoding="utf-8")
@@ -38,25 +104,42 @@ class StaticValidator:
             raise RuleParsingError(f"Cannot read source file: {e}") from e
 
     def _parse_ast_tree(self) -> bool:
-        """Parses the loaded source code into an AST."""
+        """Parses the loaded source code into an AST and enriches it.
+
+        This method attempts to parse the source code. If successful, it calls
+        a helper to add parent references to each node in the tree, which is
+        crucial for many advanced checks. If a `SyntaxError` occurs, it
+        checks if a `check_syntax` rule was defined to provide a custom message.
+
+        Returns:
+            bool: True if parsing was successful, False otherwise.
+        """
         self._console.print("Parsing Abstract Syntax Tree (AST)...")
         try:
             self._ast_tree = ast.parse(self._source_code)
             enrich_ast_with_parents(self._ast_tree)
             return True
         except SyntaxError as e:
-            # Ищем правило check_syntax, чтобы вывести его кастомное сообщение
-            for rule in self._validation_rules:
+            for rule in self._rules:
                 if getattr(rule.config, "type", None) == "check_syntax":
-                    self._console.print(rule.config.message, level="ERROR")
+                    self._console.print(rule.config.message, level=LogLevel.ERROR)
                     self._failed_rules.append(rule.config.rule_id)
                     return False
-            # Если такого правила нет, выводим стандартное сообщение
-            self._console.print(f"Syntax Error found: {e}", level="ERROR")
+            self._console.print(f"Syntax Error found: {e}", level=LogLevel.ERROR)
             return False
 
     def _load_and_parse_rules(self) -> None:
-        """Loads and parses the JSON file with validation rules."""
+        """Loads and parses the JSON file into executable Rule objects.
+
+        This method reads the JSON rules file, validates its basic structure,
+        and then uses the `RuleFactory` to instantiate a list of concrete
+        Rule objects.
+
+        Raises:
+            FileNotFoundError: If the rules file does not exist.
+            RuleParsingError: If the JSON is malformed or a rule configuration
+                is invalid.
+        """
         self._console.print(f"Loading rules from: {self._config.rules_path}")
         try:
             rules_data = json.loads(self._config.rules_path.read_text(encoding="utf-8"))
@@ -64,18 +147,29 @@ class StaticValidator:
             if not isinstance(raw_rules, list):
                 raise RuleParsingError("`validation_rules` key not found or is not a list.")
 
-            self._validation_rules = [self._rule_factory.create(rule) for rule in raw_rules]
-            self._console.print(f"Successfully parsed {len(self._validation_rules)} rules.")
+            self._rules = [self._rule_factory.create(rule) for rule in raw_rules]
+            self._console.print(f"Successfully parsed {len(self._rules)} rules.")
         except json.JSONDecodeError as e:
             raise RuleParsingError(f"Invalid JSON in rules file: {e}") from e
         except FileNotFoundError:
             raise
 
     def run(self) -> bool:
-        """Runs the entire validation process."""
+        """Runs the entire validation process from start to finish.
+
+        This is the main public method of the class. It orchestrates the
+        sequence of loading, parsing, and rule execution.
+
+        Returns:
+            bool: True if all validation rules passed, False otherwise.
+
+        Raises:
+            RuleParsingError: Propagated from loading/parsing steps.
+            FileNotFoundError: Propagated from loading steps.
+        """
         try:
             self._load_source_code()
-            self._load_and_parse_rules()  # Загружаем правила до парсинга AST
+            self._load_and_parse_rules()
 
             if not self._parse_ast_tree():
                 return False
@@ -83,18 +177,17 @@ class StaticValidator:
         except (FileNotFoundError, RuleParsingError):
             raise
 
-        for rule in self._validation_rules:
-            # check_syntax уже обработан в _parse_ast_tree, пропускаем его
+        for rule in self._rules:
             if getattr(rule.config, "type", None) == "check_syntax":
                 continue
 
             self._console.print(f"Executing rule: {rule.config.rule_id}", level=LogLevel.DEBUG)
             is_passed = rule.execute(self._ast_tree, self._source_code)
             if not is_passed:
-                self._console.print(rule.config.message, level="ERROR")
+                self._console.print(rule.config.message, level=LogLevel.ERROR)
                 self._failed_rules.append(rule.config.rule_id)
                 if getattr(rule.config, "is_critical", False) or self._config.stop_on_first_fail:
-                    self._console.print("Critical rule failed. Halting validation.", level="WARNING")
+                    self._console.print("Critical rule failed. Halting validation.", level=LogLevel.WARNING)
                     break
 
         return not self._failed_rules

code_validator/rules_library/basic_rules.py

@@ -1,10 +1,10 @@
-# src/code_validator/rules_library/basic_rules.py
-
 """Contains concrete implementations of executable validation rules.
 
 This module defines the handler classes for both "short" (pre-defined) and
-"full" (custom selector/constraint) rules. Each class implements the `Rule`
-protocol and encapsulates the logic for a specific type of validation check.
+"full" (custom selector/constraint) rules. Each class in this module implements
+the `Rule` protocol from `definitions.py` and encapsulates the logic for a
+specific type of validation check. The `RuleFactory` uses these classes to
+instantiate the correct handler for each rule defined in a JSON file.
 """
 
 import ast
@@ -77,10 +77,10 @@ class CheckLinterRule(Rule):
             True if no PEP8 violations are found, False otherwise.
         """
         if not source_code:
-            self._console.print("Source code is empty, skipping PEP8 check.", level="WARNING")
+            self._console.print("Source code is empty, skipping PEP8 check.", level=LogLevel.WARNING)
             return True
 
-        self._console.print(f"Rule {self.config.rule_id}: Running flake8 linter...", level="DEBUG")
+        self._console.print(f"Rule {self.config.rule_id}: Running flake8 linter...", level=LogLevel.DEBUG)
 
         params = self.config.params
         args = [sys.executable, "-m", "flake8", "-"]
@@ -102,19 +102,21 @@ class CheckLinterRule(Rule):
 
             if process.returncode != 0 and process.stdout:
                 linter_output = process.stdout.strip()
-                self._console.print(f"Flake8 found issues:\n{linter_output}", level="DEBUG")
+                self._console.print(f"Flake8 found issues:\n{linter_output}", level=LogLevel.DEBUG)
                 return False
             elif process.returncode != 0:
-                self._console.print(f"Flake8 exited with code {process.returncode}:\n{process.stderr}", level="ERROR")
+                self._console.print(
+                    f"Flake8 exited with code {process.returncode}:\n{process.stderr}", level=LogLevel.ERROR
+                )
                 return False
 
-            self._console.print("PEP8 check passed.", level="DEBUG")
+            self._console.print("PEP8 check passed.", level=LogLevel.ERROR)
             return True
         except FileNotFoundError:
-            self._console.print("flake8 not found. Is it installed in the venv?", level="CRITICAL")
+            self._console.print("flake8 not found. Is it installed in the venv?", level=LogLevel.CRITICAL)
             return False
         except Exception as e:
-            self._console.print(f"An unexpected error occurred while running flake8: {e}", level="CRITICAL")
+            self._console.print(f"An unexpected error occurred while running flake8: {e}", level=LogLevel.CRITICAL)
             return False
 
 
@@ -157,11 +159,11 @@ class FullRuleHandler(Rule):
             The boolean result of applying the constraint to the selected nodes.
         """
         if not tree:
-            self._console.print("AST not available, skipping rule.", level="WARNING")
+            self._console.print("AST not available, skipping rule.", level=LogLevel.WARNING)
             return True
 
-        self._console.print(f"Applying selector: {self._selector.__class__.__name__}", level="DEBUG")
+        self._console.print(f"Applying selector: {self._selector.__class__.__name__}", level=LogLevel.DEBUG)
         selected_nodes = self._selector.select(tree)
 
-        self._console.print(f"Applying constraint: {self._constraint.__class__.__name__}", level="DEBUG")
+        self._console.print(f"Applying constraint: {self._constraint.__class__.__name__}", level=LogLevel.DEBUG)
         return self._constraint.check(selected_nodes)

code_validator/rules_library/constraint_logic.py

@@ -2,7 +2,11 @@
 
 Each class in this module implements the `Constraint` protocol and encapsulates
 the logic for a specific condition that can be checked against a list of
-AST nodes found by a Selector.
+AST nodes. These classes are instantiated by the `ConstraintFactory` based on
+the "constraint" block in a JSON rule.
+
+The module also includes helper functions for processing AST nodes, which are
+used internally by the constraint classes.
 """
 
 import ast
@@ -66,6 +70,12 @@ class MustInheritFromConstraint(Constraint):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the constraint.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's constraint config.
+                Expects `parent_name` (str) specifying the required parent class.
+        """
         self.parent_name_to_find: str | None = kwargs.get("parent_name")
 
     def check(self, nodes: list[ast.AST]) -> bool:
@@ -105,6 +115,12 @@ class MustBeTypeConstraint(Constraint):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the constraint.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's constraint config.
+                Expects `expected_type` (str) with the name of the required type.
+        """
         self.expected_type_str: str | None = kwargs.get("expected_type")
         self.type_map = {
             "str": str,
@@ -164,6 +180,12 @@ class NameMustBeInConstraint(Constraint):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the constraint.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's constraint config.
+                Expects `allowed_names` (list[str]) containing the valid names.
+        """
         self.allowed_names = set(kwargs.get("allowed_names", []))
 
     @staticmethod
@@ -194,6 +216,12 @@ class ValueMustBeInConstraint(Constraint):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the constraint.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's constraint config.
+                Expects `allowed_values` (list) containing the valid literal values.
+        """
         self.allowed_values = set(kwargs.get("allowed_values", []))
 
     def check(self, nodes: list[ast.AST]) -> bool:
@@ -224,6 +252,13 @@ class MustHaveArgsConstraint(Constraint):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the constraint.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's constraint config.
+                Can accept `count` (int), `names` (list[str]), and
+                `exact_match` (bool).
+        """
         self.expected_count: int | None = kwargs.get("count")
         self.expected_names: list[str] | None = kwargs.get("names")
         self.exact_match: bool = kwargs.get("exact_match", True)

code_validator/rules_library/selector_nodes.py

@@ -3,7 +3,8 @@
 Each class in this module implements the `Selector` protocol and is responsible
 for finding and returning specific types of nodes from an Abstract Syntax Tree.
 They use `ast.walk` to traverse the tree and can be constrained to specific
-scopes using the ScopedSelector base class.
+scopes via the `ScopedSelector` base class, which uses the `scope_handler`.
+These classes are instantiated by the `SelectorFactory`.
 """
 
 import ast
@@ -27,11 +28,11 @@ class ScopedSelector(Selector):
     """
 
     def __init__(self, **kwargs: Any):
-        """Initializes the ScopedSelector.
+        """Initializes the ScopedSelector base class.
 
         Args:
-            **kwargs: Keyword arguments containing the scope configuration.
-                Expects `in_scope` key.
+            **kwargs: Keyword arguments passed from a subclass constructor.
+                It extracts the `in_scope` configuration.
         """
         self.in_scope_config = kwargs.get("in_scope")
 
@@ -67,6 +68,12 @@ class FunctionDefSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the FunctionDefSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `name` (str) and optionally `in_scope` (dict).
+        """
         super().__init__(**kwargs)
         self.name_to_find = kwargs.get("name")
 
@@ -118,6 +125,12 @@ class ImportStatementSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the ImportStatementSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `name` (str) for the module name and optionally `in_scope`.
+        """
         super().__init__(**kwargs)
         self.module_name_to_find = kwargs.get("name")
 
@@ -188,6 +201,12 @@ class AssignmentSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the AssignmentSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `name` (str) for the assignment target and optionally `in_scope`.
+        """
         super().__init__(**kwargs)
         self.target_name_to_find = kwargs.get("name")
 
@@ -221,6 +240,13 @@ class UsageSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the UsageSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `name` (str) for the variable/attribute being used and
+                optionally `in_scope`.
+        """
         super().__init__(**kwargs)
         self.variable_name_to_find = kwargs.get("name")
 
@@ -248,10 +274,30 @@ class LiteralSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the LiteralSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `name` (str) to be "string" or "number" and optionally
+                `in_scope`.
+        """
         super().__init__(**kwargs)
-        self.literal_type = kwargs.get("name")  # 'name' - это наш унифицированный ключ
+        self.literal_type = kwargs.get("name")
 
     def select(self, tree: ast.Module) -> list[ast.AST]:
+        """Finds all ast.Constant nodes that match the type criteria.
+
+        This method traverses the given AST (or a sub-tree defined by `in_scope`)
+        and collects all number or string literals. It contains special logic
+        to intelligently ignore nodes that are likely to be docstrings or parts
+        of f-strings to avoid false positives.
+
+        Args:
+            tree: The root of the AST (the module object) to be searched.
+
+        Returns:
+            A list of `ast.Constant` nodes matching the criteria.
+        """
         search_tree = self._get_search_tree(tree)
         if not search_tree:
             return []
@@ -295,6 +341,12 @@ class AstNodeSelector(ScopedSelector):
     """
 
     def __init__(self, **kwargs: Any):
+        """Initializes the AstNodeSelector.
+
+        Args:
+            **kwargs: Keyword arguments from the JSON rule's selector config.
+                Expects `node_type` (str or list[str]) and optionally `in_scope`.
+        """
         super().__init__(**kwargs)
         node_type_arg = kwargs.get("node_type")
 

{python_code_validator-0.1.2.dist-info → python_code_validator-0.1.3.dist-info}/METADATA

@@ -1,7 +1,7 @@
 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.1.3
+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
         
@@ -28,22 +28,27 @@ License: MIT License
 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"

python_code_validator-0.1.3.dist-info/RECORD

@@ -0,0 +1,22 @@
+code_validator/__init__.py,sha256=3eCuRsidy-Tc4QASdz7mwRIiGYOumb9uPxY3ob85HBs,1721
+code_validator/__main__.py,sha256=Z41EoJqX03AI11gnku_Iwt6rP8SPUkYuxwN7P51qgLc,600
+code_validator/cli.py,sha256=PtPxlgKdbAAEKDpI1Xk7bZ5CKVYr9efIlOgh45Igjxk,4119
+code_validator/config.py,sha256=qLuGsFPn61RS97clV8zHd43jb9EBIBwBzl1jrSKLD2w,5052
+code_validator/core.py,sha256=n4aP_ohE_9qoX9lqbmPSvMZouxomWxauFiwgjzA1_ys,8003
+code_validator/exceptions.py,sha256=XkiRNQ25FWJkjS2wBaUaKQcEL5WF9tN_HSV3tqJwDcE,1627
+code_validator/output.py,sha256=VRJLGwm6X9i8SnovosNrHu96ueZXz9GIvUQXy4xDtHw,3304
+code_validator/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_validator/components/ast_utils.py,sha256=v0N3F58oxNMg7bUY6-8x0AeoLsxrzrp_bLTGNVr5EMU,1589
+code_validator/components/definitions.py,sha256=9WEXQ_i-S4Vega6HqOdjreZE_1cgJPC7guZodTKtzhc,3208
+code_validator/components/factories.py,sha256=0-U--7pekt-fIvqb_WesWh_ehKCvJ7ROObx5GU-yjGc,10492
+code_validator/components/scope_handler.py,sha256=q4cFK_YzoYvAqPkw9wPPxgPe-aO0kgy6gk0ETWduj-U,2593
+code_validator/rules_library/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_validator/rules_library/basic_rules.py,sha256=VYm6t_En0t6D42vp6vtCr5XV6-M4xuPupX8Hz6-eveI,6858
+code_validator/rules_library/constraint_logic.py,sha256=CRnzMgLR17Ja2d4M3jWBO-xLLPB6Vpk7iusGMoyJ17s,10932
+code_validator/rules_library/selector_nodes.py,sha256=hWzvar1tvnkEFReCFLSw5oTK9HETNmdNVcDD3_57Iyg,14306
+python_code_validator-0.1.3.dist-info/licenses/LICENSE,sha256=Lq69RwIO4Dge7OsjgAamJfYSDq2DWI2yzVYI1VX1s6c,1089
+python_code_validator-0.1.3.dist-info/METADATA,sha256=NlDRdvgugKe3hWC-Z8q1h7_lrqZBJ4Jpd6YbjD3nuVU,12081
+python_code_validator-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python_code_validator-0.1.3.dist-info/entry_points.txt,sha256=pw_HijiZyPxokVJHStTkGCwheTjukDomdk81JyHzv74,66
+python_code_validator-0.1.3.dist-info/top_level.txt,sha256=yowMDfABI5oqgW3hhTdec_7UHGeprkvc2BnqRzNbI5w,15
+python_code_validator-0.1.3.dist-info/RECORD,,

python_code_validator-0.1.2.dist-info/RECORD

@@ -1,22 +0,0 @@
-code_validator/__init__.py,sha256=etZcfEkc_LFR8gqYPeH6hitwZ5-HS2WKSjl6LW9M8PY,961
-code_validator/__main__.py,sha256=c7P8Lz3EuwYRHarTEp_DExMUauod9X42p6aTZkpvi10,330
-code_validator/cli.py,sha256=fLbSP_4ABZGZTH6-L4oAXKVRTW-OVMdpcZgT9F4ibtY,3466
-code_validator/config.py,sha256=kTqD8-SFbtUQ9oif-TylqNFPadTq5JSGBv84cI0R8dY,2657
-code_validator/core.py,sha256=4sPdlunmODfNpDrP9QH2jIrGFVLFlo_r8MAoB4_63vo,4560
-code_validator/exceptions.py,sha256=XkiRNQ25FWJkjS2wBaUaKQcEL5WF9tN_HSV3tqJwDcE,1627
-code_validator/output.py,sha256=VRJLGwm6X9i8SnovosNrHu96ueZXz9GIvUQXy4xDtHw,3304
-code_validator/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-code_validator/components/ast_utils.py,sha256=7DzyKmLekj_qtuZcS8BrcWXqQXVEPPQ_rwh3BmpIk9o,1412
-code_validator/components/definitions.py,sha256=cFbKL7UZYHqWjz2gJCmZ6fU_ZdQ5L_h1tlQBYkxSO7Q,3126
-code_validator/components/factories.py,sha256=qrQotS7lyqIGhoNGRvSNQKy6p9YJKQC7YaPi4eCtpww,10436
-code_validator/components/scope_handler.py,sha256=vb4pCE-4DyxGkRYGeW2JWxP2IiZH3uRRfReo0IBgM5Y,2459
-code_validator/rules_library/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-code_validator/rules_library/basic_rules.py,sha256=0K45Ed8yjy-pXDZpI1Xvgj94zvaFz-PucFRz__X4uRI,6652
-code_validator/rules_library/constraint_logic.py,sha256=X95g0673hoZey3LGCBH6AscbIuHYq_aY9WRKIkJhOnk,9525
-code_validator/rules_library/selector_nodes.py,sha256=JxhUBXS95Dad_60Ut-8XkW2MFM-7bkeRb_yk7vXlNPE,12200
-python_code_validator-0.1.2.dist-info/licenses/LICENSE,sha256=Lq69RwIO4Dge7OsjgAamJfYSDq2DWI2yzVYI1VX1s6c,1089
-python_code_validator-0.1.2.dist-info/METADATA,sha256=lYCstaPpPsj2KDOze-aYZFkr_NDi3Cy8UAgUCJHB2Mo,11829
-python_code_validator-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-python_code_validator-0.1.2.dist-info/entry_points.txt,sha256=pw_HijiZyPxokVJHStTkGCwheTjukDomdk81JyHzv74,66
-python_code_validator-0.1.2.dist-info/top_level.txt,sha256=yowMDfABI5oqgW3hhTdec_7UHGeprkvc2BnqRzNbI5w,15
-python_code_validator-0.1.2.dist-info/RECORD,,