python.yaml

# Python Code Review Guidelines
# Comprehensive rules for Python code quality, security, and best practices

name: Python Code Review Guidelines
description: Guidelines for reviewing Python code covering security, performance, best practices, and async patterns
globs:
  - "**/*.py"

areas:
  - name: security
    description: Security-related rules to prevent vulnerabilities
    rules:
      - name: avoid-eval-exec
        description: Never use eval() or exec() with untrusted input. These functions execute arbitrary code and are a major security risk. Use ast.literal_eval() for safe evaluation of literals, or implement a proper parser.
        severity: high
        
      - name: avoid-pickle-untrusted
        description: Never unpickle data from untrusted sources. pickle.loads() can execute arbitrary code during deserialization. Use JSON, MessagePack, or other safe serialization formats for untrusted data.
        severity: high
        
      - name: prevent-sql-injection
        description: Always use parameterized queries instead of string formatting for SQL. Never use f-strings, format(), or % formatting with user input in SQL queries. Use ORM methods or cursor.execute() with parameters.
        severity: high
        
      - name: prevent-command-injection
        description: Avoid os.system(), subprocess with shell=True, or similar functions with user input. Use subprocess.run() with a list of arguments and shell=False. Validate and sanitize all inputs.
        severity: high
        
      - name: prevent-ssrf
        description: Validate and whitelist URLs before making HTTP requests. Never directly use user input to construct request URLs. Check for private IP ranges, localhost, and internal hostnames.
        severity: high
        
      - name: avoid-hardcoded-secrets
        description: Never hardcode passwords, API keys, tokens, or other secrets in source code. Use environment variables, secret management services, or configuration files excluded from version control.
        severity: high
        
      - name: secure-file-operations
        description: Validate file paths to prevent path traversal attacks. Use os.path.realpath() to resolve paths and verify they stay within expected directories. Never trust user input for file paths.
        severity: high

  - name: performance
    description: Performance optimization rules
    rules:
      - name: use-generators-for-large-data
        description: Use generators instead of lists for large datasets to reduce memory usage. Replace [x for x in large_iterable] with (x for x in large_iterable) when you don't need random access or len().
        severity: medium
        
      - name: prefer-list-comprehensions
        description: Use list comprehensions instead of map/filter with lambda for better readability and often better performance. However, prefer generators for large datasets.
        severity: low
        
      - name: avoid-global-imports-in-functions
        description: Import modules at the top of the file, not inside functions. Repeated imports inside frequently called functions add overhead. Exception exists for optional dependencies or circular import resolution.
        severity: medium
        
      - name: efficient-string-concatenation
        description: Use join() for concatenating many strings instead of + in loops. String concatenation with + creates new objects each time, while join() is O(n). Use f-strings for simple formatting.
        severity: medium
        
      - name: use-builtin-functions
        description: Prefer built-in functions like sum(), min(), max(), any(), all() over manual loops. Built-in functions are implemented in C and significantly faster.
        severity: low
        
      - name: avoid-unnecessary-copies
        description: Be mindful of operations that create unnecessary copies of data structures. Use slicing sparingly on large lists, prefer itertools for combining iterables, and consider memory_view for large binary data.
        severity: medium

  - name: best_practices
    description: Python best practices and idioms
    rules:
      - name: use-type-hints
        description: Add type hints to function signatures and class attributes. Type hints improve code readability, enable better IDE support, and allow static type checking with mypy or pyright.
        severity: medium
        
      - name: use-context-managers
        description: Use context managers (with statement) for resource management. Always use with for file operations, database connections, locks, and any resource that needs cleanup.
        severity: medium
        
      - name: specific-exception-handling
        description: Catch specific exceptions instead of bare except or except Exception. Bare except catches SystemExit and KeyboardInterrupt. Log or handle exceptions appropriately, don't silently pass.
        severity: medium

      - name: avoid-mutable-default-args
        description: Never use mutable objects (lists, dicts, sets) as default argument values. They are shared across all calls and lead to subtle bugs. Use None as default and create the mutable object inside the function.
        severity: high

      - name: use-dataclasses-or-pydantic
        description: Use dataclasses or Pydantic models instead of plain dicts for structured data. They provide type safety, validation, and better IDE support. Use frozen=True for immutable data.
        severity: low

      - name: proper-dunder-methods
        description: Implement dunder methods correctly. __eq__ should return NotImplemented for unknown types. __hash__ must be implemented if __eq__ is. __repr__ should return a string that can recreate the object.
        severity: medium

      - name: use-pathlib
        description: Prefer pathlib.Path over os.path for file path operations. pathlib provides a more intuitive, object-oriented API and handles cross-platform path separators automatically.
        severity: low

      - name: avoid-star-imports
        description: Never use from module import *. It pollutes the namespace, makes code harder to understand, and can cause subtle bugs when modules are updated. Import specific names or use the module prefix.
        severity: medium

  - name: async
    description: Async/await patterns and common pitfalls
    rules:
      - name: no-blocking-in-async
        description: Never call blocking I/O functions (time.sleep, requests.get, file I/O) in async functions. Use asyncio.sleep(), aiohttp, aiofiles, or run blocking code in executor with loop.run_in_executor().
        severity: high

      - name: proper-async-context-managers
        description: Use async with for async context managers. Regular with statements don't await __aenter__ and __aexit__. Use aiofiles for file operations, async database connections, etc.
        severity: medium

      - name: avoid-asyncio-run-in-async
        description: Never call asyncio.run() from within an async function or when an event loop is already running. Use await directly or asyncio.create_task() for concurrent execution.
        severity: high

      - name: handle-async-exceptions
        description: Handle exceptions in async tasks properly. Unhandled exceptions in fire-and-forget tasks are silently ignored. Use asyncio.create_task() and store references, or use exception handlers.
        severity: medium

      - name: use-async-generators-correctly
        description: Use async for when iterating over async generators. Remember that async generators need async cleanup - use async with contextlib.aclosing() or properly await aclose().
        severity: medium

      - name: avoid-sync-primitives-in-async
        description: Don't use threading locks, queues, or other sync primitives in async code. Use asyncio.Lock, asyncio.Queue, asyncio.Semaphore, etc. Mixing sync and async primitives causes deadlocks.
        severity: high