=========================
Python Rules
=========================

Python-specific coding standards and best practices for development.

File: `python-rules.mdc`

Purpose
-------

The Python Rules provide language-specific guidelines to ensure consistent, high-quality Python code throughout the project. These rules establish coding standards, documentation requirements, and design patterns that are specific to Python development.

Key Principles
--------------

* **PEP 8 Compliance**: Following standard Python style guidelines
* **Proper Documentation**: Using Google-style docstrings for all code
* **Type Hints**: Leveraging Python's type annotation system
* **Error Handling**: Standardized approaches to exception management
* **Package Structure**: Consistent organization of Python modules

Detailed Contents
-----------------

Code Style
~~~~~~~~~~~~~~~

The Python rules establish coding style requirements:

* 4 spaces for indentation (no tabs)
* 88 character line length (Black formatter compatible)
* snake_case for functions, methods, and variables
* PascalCase for class names
* UPPERCASE for constants
* Docstrings for all public functions, classes, and methods

Import Organization
~~~~~~~~~~~~~~~~~~~~~~~~

Guidelines for organizing imports:

* Standard library imports first
* Third-party imports second
* Local application imports third
* Blank lines between import groups
* Absolute imports preferred over relative imports
* Specific imports (from x import y) when only a few items are needed

Documentation Standards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Requirements for code documentation:

* Google-style docstrings for all functions, classes, and methods
* Type hints for function parameters and return values
* Examples for complex functions
* Clear descriptions of parameters and return values
* Documentation of exceptions raised
* Module-level docstrings explaining purpose and contents

Error Handling
~~~~~~~~~~~~~~~~~~~

Standardized approaches for error handling:

* Using specific exception types (no bare except:)
* Creating custom exception classes for domain-specific errors
* Logging exceptions with context information
* Using context managers for resource cleanup

Class Structure
~~~~~~~~~~~~~~~~~~~~

Guidelines for organizing Python classes:

* Specific order for class methods (class methods, static methods, init, etc.)
* Proper use of dunder methods
* Preference for composition over inheritance
* Use of abstract base classes for shared interfaces
* Property usage for attribute access control

Testing
~~~~~~~~~~~~

Requirements for Python testing:

* Unit tests for all public functions and methods
* pytest as the testing framework
* Test organization mirroring package structure
* Use of fixtures for test setup
* Mocking external dependencies
* High test coverage targets

Asynchronous Code
~~~~~~~~~~~~~~~~~~~~~~

Guidelines for async programming:

* Preference for async/await over callbacks
* asyncio usage for asynchronous operations
* Task management best practices
* Proper exception handling in async code

Project-Specific Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Project-specific Python patterns:

* Naming conventions for different component types
* Dependency injection patterns
* Configuration management
* Database access patterns
* Logging implementation

Rationale
---------

The Python rules serve several essential purposes:

1. **Consistency**: Ensuring a consistent coding style and approach
2. **Quality**: Establishing high standards for Python code
3. **Maintainability**: Making code easier to understand and modify
4. **Efficiency**: Promoting patterns that work well with Python's strengths
5. **Compatibility**: Ensuring code works across different Python environments

By following these Python-specific rules, developers can write code that leverages Python's strengths while avoiding common pitfalls of the language.