Python AI Rules

Comprehensive AI rules and patterns for Python development

Python AI Rules Overview

AI rules for Python development focus on clean code practices, type hints, and Pythonic patterns to generate high-quality, maintainable code. These rules guide AI assistants in understanding and working with Python's unique features and best practices.

Code Style and Structure

Naming Conventions

{
  "python.naming": {
    "classes": "PascalCase",
    "functions": "snake_case",
    "variables": "snake_case",
    "constants": "UPPER_SNAKE_CASE",
    "private": "_leading_underscore",
    "protected": "__double_underscore",
    "modules": "lowercase_with_underscores"
  }
}

Code Organization

{
  "python.organization": {
    "imports": {
      "order": [
        "standard_library",
        "third_party",
        "local_application"
      ],
      "style": "absolute_imports",
      "grouping": "by_type"
    },
    "declarations": {
      "order": [
        "module_docstring",
        "imports",
        "constants",
        "classes",
        "functions",
        "main_execution"
      ]
    }
  }
}

Best Practices

Type Hints

{
  "python.typing": {
    "usage": "type_hints_required",
    "style": {
      "return_types": "explicit",
      "generics": "use_typing_extensions",
      "unions": "use_pipe_syntax",
      "optionals": "use_or_none"
    },
    "validation": {
      "runtime": "use_runtime_checkable",
      "protocols": "prefer_over_abc"
    }
  }
}

Modern Patterns

{
  "python.patterns": {
    "functions": {
      "prefer": "pure_functions",
      "decorators": "use_for_cross_cutting",
      "parameters": {
        "defaults": "immutable_only",
        "args_kwargs": "document_usage"
      }
    },
    "classes": {
      "style": "dataclasses_for_data",
      "inheritance": "composition_over_inheritance",
      "methods": {
        "static": "prefer_module_functions",
        "class": "document_shared_state"
      }
    },
    "async": {
      "prefer": "asyncio",
      "patterns": "async_context_managers",
      "errors": "structured_error_handling"
    }
  }
}

Testing and Quality

{
  "python.testing": {
    "framework": "pytest",
    "patterns": {
      "fixtures": "function_scope_default",
      "parametrize": "use_for_variations",
      "mocking": "use_autospec",
      "assertions": "explicit_message"
    },
    "coverage": {
      "minimum": 80,
      "report": ["term-missing", "html"],
      "exclude": ["__init__.py", "tests/*"]
    }
  }
}

Performance Optimization

{
  "python.performance": {
    "data_structures": {
      "lists": "use_list_comprehension",
      "dicts": "use_dict_comprehension",
      "sets": "prefer_for_lookups"
    },
    "iteration": {
      "prefer": "generators",
      "large_data": "use_itertools",
      "memory": "lazy_evaluation"
    },
    "concurrency": {
      "io_bound": "asyncio",
      "cpu_bound": "multiprocessing",
      "threading": "avoid_for_cpu_work"
    }
  }
}

Example Usage

Here's a practical example demonstrating these rules in action:

from dataclasses import dataclass
from typing import Protocol, runtime_checkable
from abc import ABC
import asyncio
from typing import Optional, List

# Type-safe protocol
@runtime_checkable
class DataService(Protocol):
    async def fetch(self) -> dict:
        ...
    async def update(self, data: dict) -> bool:
        ...

# Data model with type hints
@dataclass
class User:
    id: str
    name: str
    email: str
    active: bool = True

    @property
    def display_name(self) -> str:
        return f"{self.name} <{self.email}>"

# Service implementation with error handling
class UserService:
    def __init__(self, data_service: DataService) -> None:
        self._data_service = data_service
        self._cache: dict[str, User] = {}

    async def get_user(self, user_id: str) -> Optional[User]:
        try:
            if user_id in self._cache:
                return self._cache[user_id]
            
            data = await self._data_service.fetch()
            user = User(**data)
            self._cache[user_id] = user
            return user
        except Exception as e:
            logger.error(f"Error fetching user {user_id}: {e}")
            return None

    @classmethod
    def create_batch(cls, users: List[dict]) -> List[User]:
        return [User(**user_data) for user_data in users]

Development Tools Integration

These rules work well with popular Python development tools:

Mypy for static type checking
Black for code formatting
Pylint/Flake8 for linting
isort for import sorting
pytest for testing

Environment Setup

{
  "python.environment": {
    "version": ">=3.9",
    "virtualenv": {
      "required": true,
      "naming": "project_name-env"
    },
    "dependencies": {
      "management": "poetry",
      "lockfile": "required",
      "updates": "scheduled"
    }
  }
}

Remember to:

Use virtual environments for project isolation
Keep dependencies up to date
Run type checking as part of CI/CD
Maintain comprehensive test coverage
Document public APIs using docstrings

Elixir Cursor Rules

Learn about cursor rules specific to Elixir development.

Microservices Example

Learn how to use cursor rules in a microservices architecture.

Simple Project Example

Learn how to use cursor rules in a simple project context.