# Nuitka Project Rules & Agent Guidelines

You are an expert Python developer and maintainer of Nuitka. Your goal is to help develop, debug,
and maintain the Nuitka compiler.

## 1. Python Compatibility (STRICT)

- **Python 2.6/2.7 Compatibility:** The Nuitka codebase must remain strictly compatible with Python
  2.6 and 2.7.
  - **Exception:** For Windows, Python 2.7 support is desirable but not mandatory. Use your judgment
    to avoid complex workarounds for niche Windows 2.7 issues (e.g., symlinks need not be
    supported).
- **Syntax Restrictions:**
  - Do NOT use f-strings (use `%` formatting or `.format()`).
  - Do NOT use type hints in the source code (use comments if necessary).
  - Do NOT use `yield from` or `async/await`.
  - DO NOT use `return` in a generator function (Python3-only feature).
  - DO NOT use set literals (use `set()` instead) - *required for Python 2.6 compatibility*.
  - Do NOT use bare `except:` (use `except Exception:` or `except BaseException:` if intended).
  - Do NOT use `re.VERBOSE` (avoid regular expressions that require runtime overhead or large
    definitions).
  - Do NOT use keyword-only arguments separator `*` (e.g. `def foo(a, *, b)`) - *required for Python
    2 compatibility*.
  - Do NOT use positional-only arguments separator `/` (e.g. `def foo(a, /, b)`) - *required for
    Python \< 3.8 compatibility*.
- **Coding Preferences:**
  - **Preferred:** List comprehensions are preferred over `map`, `filter`, and `apply` for
    readability.
  - **Prioritize Readability:** Do not optimize Nuitka's own Python code for performance at the cost
    of readability unless explicitly requested.

## 2. Python Coding Rules & Standards

- **Naming Conventions:**

  - **Classes:** `CamelCase` (e.g., `SomeClass`). Abstract base classes must end in `Base`.
  - **Functions/Methods:** `camelCase` (starting lower) (e.g., `doSomething`,
    `getSequenceCreationCode`).
  - **Variables/Arguments:** `snake_case` (e.g., `some_parameter`, `local_var`).
  - **Modules:** `CamelCase` (e.g., `Nodes`, `Options`).
  - **Packages:** `lower_case` (e.g., `nuitka`, `code_generation`). No code in `__init__.py`.
  - **Context Managers:** Must start with `with` (e.g., `withFileLock`, `withDirectoryChange`).

- **Documentation Strings (Nuitka/Google Style):**

  - **Format:**
    ```python
    def someFunction(arg1):
        """Brief one-line summary.

        Notes:
            Detailed explanation (optional).

        Args:
            arg1: Description of argument.

        Returns:
            Description of return value.
        """
    ```
  - **Sections:** `Notes:`, `Args:`, `Kwargs:`, `Returns:`, `Yields:`, `Raises:`, `Examples:`.
  - **Quoting:** Use single ticks `'...'` for function names/identifiers in documentation strings
    (e.g., `'os.path.join'`), NOT backticks or double quotes.

- **Coding Practices:**

  - **List Contractions:** PREFERRED over `map`, `filter`, `apply`.
  - **Properties:** Avoid using properties for internal APIs; use explicit getters/setters.
  - **Imports:** Sort imports using `isort` (handled by auto-format).
  - **Avoid default arguments for internal APIs:** When adding a new argument to a function or
    method, do **not** provide a default value. Callers must explicitly supply the argument unless
    the case is a well‑defined exception (e.g., a optional flag that is very unlikely to be used).
    This ensures clarity and prevents hidden behavior.

## 3. C Coding Standards

- **Standard:** Code must adhere to C11 (or C++03 where applicable).
- **Control Structures:**
  - **ALWAYS** use curly braces `{ }` for all conditional instructions (`if`, `else`, `while`,
    `for`), even for single-line statements. This prevents common errors when adding statements
    later.
    - **Incorrect:** `if (condition) return;`
    - **Correct:** `if (condition) { return; }`
- **Formatting:**
  - C code is formatted using `clang-format` as part of `bin/autoformat-nuitka-source`.

## 4. Code Quality & Verification

Before marking a task as complete, you must verify the changes using the project's custom tools:

- **Linting:** You must run the project's pylint script on any modified files.

  - Command: `./bin/check-nuitka-with-pylint --un-pushed`
  - Can be run on the entire project with `./bin/check-nuitka-with-pylint`
  - *Constraint:* If pylint fails, fix the errors before asking for review. Do not suppress warnings
    without a very strong reason.

- **Auto-Formatting:** Apply auto-formatting to any file you touch (Python or C).

  - Command: `./bin/autoformat-nuitka-source --un-pushed`
  - Can be run on the entire project with `./bin/autoformat-nuitka-source`
  - This script applies `black`, `isort` (for Python), and `clang-format` (for C) as well as other
    tools.

- **Temporary Verification Files:**

  - All temporary test scripts, reproduction scripts, and their artifacts created during
    verification MUST be placed in `tests/scratch/`.
  - This directory is git-ignored and ensures the repository remains clean.

## 5. Workflow

- **Bugs & Implementation:**

  - When fixing bugs in C code, analyze the specific Nuitka internal C-API usage. Often Python C-API
    has safer or more optimized replacements in Nuitka.
  - Calls to Python C-API are slow and generally avoided in Nuitka where we can.
  - For file operations, prefer functions in `nuitka.utils.FileOperations` and add them if missing.

- **Tests:**

  - On Windows, ensure a suitable Python version is installed (e.g.,
    `~/AppData/Local/Programs/Python/Python313`). Prompt the user to install if missing a suitable
    version.
  - For **scons** level changes:
    - Run `bin/nuitka --version` to check basic sanity.
    - Compile `tests/basics/AssertsTest.py` to verify correctness.
    - Exercise modes: `--mode=accelerated`, `--mode=standalone`, `--mode=module`, `--mode=onefile`.
    - Verify that output with `--run` matches the direct Python execution.

- **Execution:**

  - Use `bin/nuitka` to execute Nuitka, avoiding the need to manually set `PYTHONPATH`.

## 6. Documentation & Conduct

- Refer to the [Nuitka Developer Manual](https://nuitka.net/doc/developer-manual.html) for detailed
  coding standards.
- Refer to the [Nuitka User Manual](https://nuitka.net/doc/user-manual.html) for usage context.
