Table of Contents

• About The Project
• The Power of Combinatorics
• Key Features
• Getting Started
  • Installation
• Usage Examples
  • Example 1: Simple Check
  • Example 2: Advanced Check
• Documentation
• Contributing
• License
• Contact

📖 About The Project

Python Code Validator is an engine designed for educational platforms and automated testing systems. It solves a key problem: how to verify that a student's code meets specific structural and stylistic requirements before running resource-intensive dynamic tests.

Instead of writing complex Python scripts for each new validation rule, you can define them declaratively in a simple, powerful JSON format. This allows teachers and curriculum developers to easily create and adapt validation scenarios without deep programming knowledge. The framework analyzes the code's Abstract Syntax Tree (AST), providing a deep and reliable way to enforce best practices.

📈 The Power of Combinatorics

The framework's power lies in its combinatorial architecture. It is built on a small set of primitive "bricks": Selectors ($S$) that define what to find in the code, and Constraints ($C$) that define what condition to check.

The number of unique validation rules ($R$) is not a sum, but a product of these components. A single rule can be represented as:

$$R_{\text{single}} = S \times C$$

With approximately $10$ types of selectors and $10$ types of constraints, this already provides ~$100$ unique checks. However, the true flexibility comes from logical composition, allowing for a near-infinite number of validation scenarios:

$$R_{\text{total}} \approx S \times \sum_{k=1}^{|C|} \binom{|C|}{k} = S \times (2^{|C|} - 1)$$

This design provides thousands of potential validation scenarios out-of-the-box, offering extreme flexibility with minimal complexity.

✨ Key Features

• Declarative JSON Rules: Define validation logic in a human-readable format.
• Powerful Static Analysis:
  • ✅ Check syntax and PEP8 compliance (flake8).
  • ✅ Enforce or forbid specific import statements.
  • ✅ Verify class structure, inheritance, and function signatures.
  • ✅ Forbid "magic numbers" or specific function calls like eval.
• Precise Scoping: Apply rules globally, or narrowly to a specific function, class, or method.
• Extensible Architecture: Easily add new, custom checks by creating new Selector or Constraint components.

🚀 Getting Started

Installation

1. For Users (from PyPI):

Install the package with one command. This will make the validate-code command-line tool available.

pip install python-code-validator

2. For Users (from source):

If you want to install directly from the repository:

git clone https://github.com/Qu1nel/PythonCodeValidator.git
cd PythonCodeValidator
pip install .

3. For Developers:

To set up a full development environment, see the Contributing Guidelines.

⚡ Quick Usage Example

The validator is a command-line tool named validate-code.

Example 1: Simple Check

Let's check if a required function exists.

solution_simple.py:

# This file is missing the 'solve' function
def main():
    print("Hello")

rules_simple.json:

{
  "validation_rules": [
    {
      "rule_id": 1,
      "message": "Required function 'solve' is missing.",
      "check": {
        "selector": {
          "type": "function_def",
          "name": "solve"
        },
        "constraint": {
          "type": "is_required"
        }
      }
    }
  ]
}

Running the validator:

$ validate-code solution_simple.py rules_simple.json
Starting validation for: solution_simple.py
Required function 'solve' is missing.
Validation failed.

Example 2: Advanced Check

Let's enforce a complex rule: "In our game class, the update method must not contain any print statements."

game.py:

import arcade


class MyGame(arcade.Window):
    def update(self, delta_time):
        print("Debugging player position...")  # Forbidden call
        self.player.x += 1

rules_advanced.json:

{
  "validation_rules": [
    {
      "rule_id": 101,
      "message": "Do not use 'print' inside the 'update' method.",
      "check": {
        "selector": {
          "type": "function_call",
          "name": "print",
          "in_scope": {
            "class": "MyGame",
            "method": "update"
          }
        },
        "constraint": {
          "type": "is_forbidden"
        }
      }
    }
  ]
}

Running the validator:

$ validate-code game.py rules_advanced.json
Starting validation for: game.py
Do not use 'print' inside the 'update' method.
Validation failed.

📚 Documentation

• Full User Guide & JSON Specification: Our complete documentation is hosted on Read the Docs.
• Developer's Guide: For a deep dive into the architecture, see the How It Works guide.
• Interactive AI-Powered Docs: DeepWiki.

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please read our Contributing Guidelines to get started. This project adheres to the Code of Conduct.

📜 License

Distributed under the MIT License. See LICENSE for more information.

Contact

Developed by Ivan Kovach (@Qu1nel).

Email: covach.qn@gmail.com Telegram: @qnllnq

MIT © Ivan Kovach