python-code-validator 0.1.1__tar.gz → 0.1.3__tar.gz

{python_code_validator-0.1.1/src/python_code_validator.egg-info → python_code_validator-0.1.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-code-validator
-Version: 0.1.1
-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
         
@@ -26,23 +26,29 @@ License: MIT License
         SOFTWARE.
         
 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"
@@ -78,9 +84,9 @@ Dynamic: license-file
   <h4>
     <a href="#-quick-usage-example">Usage Examples</a>
     <span>·</span>
-    <a href="https://[your-project].readthedocs.io">Full Documentation</a>
+    <a href="https://pythoncodevalidator.readthedocs.io/en/latest/">Full Documentation</a>
     <span>·</span>
-    <a href="#">AI documentation</a>
+    <a href="https://deepwiki.com/Qu1nel/PythonCodeValidator">AI documentation</a>
     <span>·</span>
     <a href="https://github.com/Qu1nel/PythonCodeValidator/blob/main/docs/how_it_works/index.md">Developer's Guide</a>
     <span>·</span>
@@ -280,7 +286,7 @@ Validation failed.
 - **Full User Guide & JSON Specification**: Our complete documentation is hosted on
   **[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)**.
+  **[How It Works guide](./docs/how_it_works/index.md)**.
 - **Interactive AI-Powered Docs**: *(Coming Soon)* An interactive documentation experience.
 
 ## 🤝 Contributing

{python_code_validator-0.1.1 → python_code_validator-0.1.3}/README.md

@@ -26,9 +26,9 @@
   <h4>
     <a href="#-quick-usage-example">Usage Examples</a>
     <span>·</span>
-    <a href="https://[your-project].readthedocs.io">Full Documentation</a>
+    <a href="https://pythoncodevalidator.readthedocs.io/en/latest/">Full Documentation</a>
     <span>·</span>
-    <a href="#">AI documentation</a>
+    <a href="https://deepwiki.com/Qu1nel/PythonCodeValidator">AI documentation</a>
     <span>·</span>
     <a href="https://github.com/Qu1nel/PythonCodeValidator/blob/main/docs/how_it_works/index.md">Developer's Guide</a>
     <span>·</span>
@@ -228,7 +228,7 @@ Validation failed.
 - **Full User Guide & JSON Specification**: Our complete documentation is hosted on
   **[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)**.
+  **[How It Works guide](./docs/how_it_works/index.md)**.
 - **Interactive AI-Powered Docs**: *(Coming Soon)* An interactive documentation experience.
 
 ## 🤝 Contributing

python_code_validator-0.1.3/pyproject.toml

@@ -0,0 +1,119 @@
+# ==============================================================================
+#  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.1.3"
+authors = [{ name = "Qu1nel", email = "covach.qn@gmail.com" }]
+description = "A flexible, AST-based framework for static validation of Python code using declarative JSON rules."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+keywords = ["validation", "linter", "static analysis", "testing", "education", "ast"]
+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",
+    "License :: OSI Approved :: MIT License",
+    "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"]
+
+
+[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.1.3/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.1.3"

python_code_validator-0.1.3/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.1.1 → python_code_validator-0.1.3}/src/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)

{python_code_validator-0.1.1 → python_code_validator-0.1.3}/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.1 → python_code_validator-0.1.3}/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.1 → python_code_validator-0.1.3}/src/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

{python_code_validator-0.1.1 → python_code_validator-0.1.3}/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

python_code_validator-0.1.3/src/code_validator/config.py

@@ -0,0 +1,151 @@
+"""Defines all data structures and configuration models for the validator.
+
+This module contains Enum classes for standardized codes and several frozen
+dataclasses that represent the structured configuration loaded from JSON files
+and command-line arguments. These models ensure type safety and provide a
+clear "shape" for the application's data.
+"""
+
+from dataclasses import dataclass, field
+from enum import IntEnum, StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ExitCode(IntEnum):
+    """Defines standardized exit codes for the command-line application."""
+
+    SUCCESS = 0
+    VALIDATION_FAILED = 1
+    FILE_NOT_FOUND = 2
+    JSON_ERROR = 3
+    UNEXPECTED_ERROR = 10
+
+
+class LogLevel(StrEnum):
+    """Defines the supported logging levels for the application."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """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
+    log_level: LogLevel
+    is_silent: bool
+    stop_on_first_fail: bool
+
+
+@dataclass(frozen=True)
+class SelectorConfig:
+    """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
+    node_type: str | list[str] | None = None
+    in_scope: str | dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class ConstraintConfig:
+    """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
+    parent_name: str | None = None
+    expected_type: str | None = None
+    allowed_names: list[str] | None = None
+    allowed_values: list[Any] | None = None
+    names: list[str] | None = None
+    exact_match: bool | None = None
+
+
+@dataclass(frozen=True)
+class FullRuleCheck:
+    """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
+
+
+@dataclass(frozen=True)
+class ShortRuleConfig:
+    """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
+    message: str
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class FullRuleConfig:
+    """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
+    check: FullRuleCheck
+    is_critical: bool = False
+
+
+# A type alias representing any possible rule configuration object.
+ValidationRuleConfig = ShortRuleConfig | FullRuleConfig