Version history: Python

v1

scan: pass2026-08-11 — Ingested from source

Initial version.

v2

currentscan: pass2026-11-02 — Currency pass 2026-11-01: builtin generics and X | None replace typing.List/Dict/Optional; uv added beside Poetry (Pipenv legacy); docstring style is a per-project choice with a Google-style example; test example imports my_package, not src.my_package; missing Any import added; quoted globs so the frontmatter parses; team boilerplate removed.
  ---- description: This guide defines the definitive Python best practices for our team, focusing on readability, maintainability, and modern development standards. Adhere to these rules for consistent, high-quality Python code.
- globs: **/*.py+ description: "Modern Python (3.10+) best practices: PEP 8 layout and naming, import order, docstrings, builtin generic type hints, uv or Poetry environments, src layout packaging, pytest, and common idioms to prefer or avoid."
+ globs: "**/*.py"
+ alwaysApply: false  ---
  # python Best Practices
  - This document outlines the definitive Python best practices for our team. Adherence ensures consistent, readable, and maintainable code across all projects. We prioritize **PEP 8** as the foundation, augmented with modern tooling and patterns.+ This document outlines Python best practices for Python 3.10 and newer. Adherence ensures consistent, readable, and maintainable code across projects. **PEP 8** is the foundation, augmented with modern tooling and patterns.  
  ## 1. Code Layout & Formatting
  
  Always adhere to PEP 8. Use an auto-formatter like `Black` or `Ruff` to enforce consistency.
  
  *   **Indentation**: Use 4 spaces. Never tabs.
  *   **Line Length**: Limit lines to 88 characters. Docstrings and comments should ideally wrap at 72 characters.
  *   **Blank Lines**:
      *   Two blank lines between top-level functions and classes.
      *   One blank line between methods within a class.
      *   One blank line to separate logical sections within functions/methods.
  
  ❌ BAD:
  ```python
  def my_func():
      x = 1
      y = 2
      return x + y
  class MyClass:
      def __init__(self, name):
          self.name = name
      def greet(self):
          print(f"Hello, {self.name}!")
  ```
  
  ✅ GOOD:
  ```python
  def my_function():
      x = 1
      y = 2
  
      # Separate logical steps
      result = x + y
      return result
  
  
  class MyClass:
      def __init__(self, name):
          self.name = name
  
      def greet(self):
          print(f"Hello, {self.name}!")
  ```
  
  ## 2. Imports
  - Organize imports for clarity and to prevent circular dependencies. Use `isort` to automate this.+ Organize imports for clarity and to prevent circular dependencies. Use Ruff's import sorting (`ruff check --select I --fix`) or `isort` to automate this.  
  *   **Grouping**:
      1.  Standard library imports.
      2.  Third-party library imports.
      3.  Local application/project-specific imports.
  *   **Alphabetical Order**: Sort imports alphabetically within each group.
  *   **Absolute Imports**: Prefer absolute imports over relative imports.
  
  ❌ BAD:
  ```python
  import os, sys
  from my_package.sub_module import some_function
  import requests
  from .another_module import another_function
  ```
  
  ✅ GOOD:
  ```python
  import os
  import sys
  
  import requests
  
  from my_package.sub_module import some_function
  from my_package.another_module import another_function
  ```
  
  ## 3. Naming Conventions
  
  Follow PEP 8 naming conventions strictly.
  
  *   **Modules**: `lowercase_with_underscores`
  *   **Packages**: `lowercase_with_underscores`
  *   **Classes**: `CamelCase`
  *   **Functions/Methods**: `lowercase_with_underscores`
  *   **Variables**: `lowercase_with_underscores`
  *   **Constants**: `UPPERCASE_WITH_UNDERSCORES`
  *   **Protected Members**: `_single_leading_underscore` (internal use)
  *   **Private Members**: `__double_leading_underscore` (name mangling, avoid unless necessary for mixins)
  
  ❌ BAD:
  ```python
  class myClass: # Class name not CamelCase
      def Get_Data(self): # Method name not lowercase_with_underscores
          MY_VAR = 10 # Variable name not lowercase_with_underscores
          return MY_VAR
  ```
  
  ✅ GOOD:
  ```python
  class MyClass:
      def get_data(self):
          my_var = 10
          return my_var
  
  GLOBAL_CONSTANT = 100
  ```
  
  ## 4. Docstrings & Comments
  - Document all public modules, classes, and functions using PEP 257 docstring conventions. Use reStructuredText format for Sphinx compatibility.+ Document all public modules, classes, and functions using PEP 257 docstring conventions. Pick one docstring style per project — Google style (shown below), NumPy style, or reStructuredText — and apply it consistently; Sphinx renders all three (Google and NumPy via the `napoleon` extension).  
  *   **Module Docstrings**: Top of the file, after `__future__` imports.
  *   **Class Docstrings**: First line after the class definition.
  *   **Function/Method Docstrings**: First line after the `def` statement.
  *   **Comments**: Use sparingly for *why* code exists, not *what* it does.
  
  ❌ BAD:
  ```python
  def calculate_sum(a, b): # This function adds two numbers
      return a + b
  ```
  
  ✅ GOOD:
  ```python
  def calculate_sum(a: int, b: int) -> int:
      """Calculate the sum of two integers.
  -     :param a: The first integer.
-     :param b: The second integer.
-     :return: The sum of a and b.
-     :raises TypeError: If a or b are not integers.+     Args:
+         a: The first integer.
+         b: The second integer.
+ 
+     Returns:
+         The sum of a and b.
+ 
+     Raises:
+         TypeError: If a or b are not integers.      """
      if not isinstance(a, int) or not isinstance(b, int):
          raise TypeError("Inputs must be integers.")
      return a + b
  ```
  
  ## 5. Type Hints
  - **Always use type hints.** They improve readability, enable static analysis with `mypy`, and catch errors early.+ **Always use type hints.** They improve readability, enable static analysis with `mypy` or `pyright`, and catch errors early.  
  *   **All Function Signatures**: Annotate parameters and return types.
  *   **Variables**: Annotate complex or ambiguous variable types.- *   **`typing` module**: Use `List`, `Dict`, `Optional`, `Union`, `Callable`, `Any`, etc.
- *   **`TypeAlias`**: For complex type signatures.+ *   **Builtin generics**: Use `list[str]`, `dict[str, int]`, `tuple[int, ...]` and `X | None` instead of `typing.List`, `Dict`, `Tuple`, `Optional`, `Union` (deprecated aliases since Python 3.9/3.10).
+ *   **`typing` module**: Still needed for `Any`, `TypeAlias`, `Protocol`, `TypedDict`, `Literal`; use `collections.abc` for `Callable`, `Iterable`, `Sequence`.
+ *   **Type aliases**: `TypeAlias` (3.10+) or the `type X = ...` statement (3.12+) for complex signatures.  
  ❌ BAD:
  ```python
  def process_data(data):
      # ...
      return len(data)
  
  def get_user(user_id):
      # ...
      return {"id": user_id, "name": "Test"}
  ```
  
  ✅ GOOD:
  ```python- from typing import Dict, Any, List, Optional, Union, TypeAlias+ from typing import Any, TypeAlias  - UserId: TypeAlias = Union[int, str]+ UserId: TypeAlias = int | str  # Python 3.12+: `type UserId = int | str`  - def process_data(data: List[str]) -> int:+ def process_data(data: list[str]) -> int:      """Processes a list of strings and returns its length."""
      return len(data)
  - def get_user(user_id: UserId) -> Optional[Dict[str, Any]]:+ def get_user(user_id: UserId) -> dict[str, Any] | None:      """Retrieves user data by ID."""
      if user_id == 1:
          return {"id": 1, "name": "Alice"}
      return None
  ```
  
  ## 6. Virtual Environments
  - **Mandatory for all projects.** Use `Poetry` or `Pipenv` for dependency management and environment isolation.+ **Mandatory for all projects.** Use `uv` or `Poetry` for dependency management and environment isolation; both write a lock file and manage `pyproject.toml`.  - *   **Poetry**: Recommended for new projects due to superior dependency resolution and packaging features.
- *   **Pipenv**: Acceptable for existing projects already using it.
- *   **Never commit `venv/` directories.**+ *   **uv**: Recommended for new projects — fast, standards-based (PEP 621/735 `pyproject.toml`, `uv.lock`), and it also installs Python versions.
+ *   **Poetry**: Equally acceptable; mature packaging and publishing workflow.
+ *   **Pipenv**: Only for existing projects already using it.
+ *   **Never commit `.venv/` or `venv/` directories.**  
  ❌ BAD:
  ```bash
  # Installing directly into global Python environment
  pip install requests black
  ```
  
  ✅ GOOD:
  ```bash+ # Using uv
+ uv init my_project
+ cd my_project
+ uv add requests
+ uv add --dev black
+ uv run python my_script.py
+   # Using Poetry
  poetry new my_project
  cd my_project- poetry add requests black --group dev+ poetry add requests
+ poetry add --group dev black  poetry run python my_script.py
  
  # Using Pipenv
  mkdir my_project && cd my_project
  pipenv install requests
  pipenv install black --dev
  pipenv run python my_script.py
  ```
  
  ## 7. Packaging
  
  Structure projects for easy distribution and installation.
  - *   **`src/` Layout**: Place all package code inside a `src/` directory.+ *   **`src/` Layout**: Place all package code inside a `src/` directory and install the project in editable mode (`uv sync` / `pip install -e .`); import it as `my_package`, never as `src.my_package`.  *   **`pyproject.toml`**: Use this for project metadata and build configuration (PEP 621).
  *   **`README.md`**: Comprehensive project description.
  *   **`LICENSE`**: Clearly state the project's license.
  
  ❌ BAD:
  ```
  my_project/
  ├── my_module.py
  ├── setup.py # Old style
  └── requirements.txt
  ```
  
  ✅ GOOD:
  ```
  my_project/
  ├── src/
  │   └── my_package/
  │       ├── __init__.py
  │       └── main.py
  ├── pyproject.toml
  ├── README.md
  ├── LICENSE
  └── tests/
      └── test_main.py
  ```
  
  ## 8. Testing Approaches
  
  **Automated testing is non-negotiable.** Use `pytest` for all tests.
  
  *   **`pytest`**: The standard test runner.
  *   **Coverage**: Integrate `pytest-cov` to ensure adequate test coverage. Aim for >90%.
  *   **Fixtures**: Use `pytest` fixtures for setup and teardown.
  *   **Parametrization**: Use `pytest.mark.parametrize` for testing multiple inputs.
  *   **Mocks**: Use `unittest.mock` (or `pytest-mock`) for isolating units under test.
  *   **Test-Driven Development (TDD)**: Strongly encouraged. Write tests before code.
  
  ❌ BAD:
  ```python
  # No tests, or using unittest.TestCase directly without pytest
  def add(a, b):
      return a + b
  
  # Manual testing
  print(add(1, 2))
  ```
  
  ✅ GOOD:
  ```python
  # src/my_package/math.py
  def add(a: int, b: int) -> int:
      return a + b
  
  # tests/test_math.py
  import pytest- from src.my_package.math import add+ from my_package.math import add  # the installed package, not a path through src/  
  @pytest.mark.parametrize("a, b, expected", [
      (1, 2, 3),
      (0, 0, 0),
      (-1, 1, 0),
  ])
  def test_add(a: int, b: int, expected: int):
      assert add(a, b) == expected
  
  def test_add_raises_type_error():
      with pytest.raises(TypeError):
          add("1", 2) # type: ignore
  ```
  
  ## 9. Common Patterns & Anti-patterns
  
  *   **Context Managers**: Use `with` statements for resource management.
  
      ❌ BAD:
      ```python
      f = open("file.txt", "r")
      data = f.read()
      f.close() # Easy to forget or miss on error
      ```
  
      ✅ GOOD:
      ```python
      with open("file.txt", "r") as f:
          data = f.read()
      # File is automatically closed
      ```
  
  *   **List Comprehensions/Generator Expressions**: For concise data transformations.
  
      ❌ BAD:
      ```python
      squares = []
      for i in range(10):
          squares.append(i * i)
      ```
  
      ✅ GOOD:
      ```python
      squares = [i * i for i in range(10)]
      ```
  
  *   **F-strings**: Prefer `f-strings` for string formatting.
  
      ❌ BAD:
      ```python
      name = "Alice"
      age = 30
      print("Hello, %s. You are %d years old." % (name, age))
      print("Hello, {}. You are {} years old.".format(name, age))
      ```
  
      ✅ GOOD:
      ```python
      name = "Alice"
      age = 30
      print(f"Hello, {name}. You are {age} years old.")
      ```
      *   **Caveat**: Avoid complex expressions or function calls inside f-strings. Assign to a variable first.
  
  *   **Enums**: Use `enum.Enum` for symbolic constants.
  
      ❌ BAD:
      ```python
      STATUS_PENDING = "pending"
      STATUS_COMPLETED = "completed"
      ```
  
      ✅ GOOD:
      ```python
      from enum import Enum
  
      class Status(Enum):
          PENDING = "pending"
          COMPLETED = "completed"
  
      current_status = Status.PENDING
      ```
  
  *   **Avoid Mutable Default Arguments**: This is a common pitfall.
  
      ❌ BAD:
      ```python
      def add_item(item, item_list=[]): # item_list is created once
          item_list.append(item)
          return item_list
  
      print(add_item(1)) # [1]
      print(add_item(2)) # [1, 2] - unexpected!
      ```
  
      ✅ GOOD:
      ```python-     from typing import List, Optional+     from typing import Any  -     def add_item(item: Any, item_list: Optional[List[Any]] = None) -> List[Any]:+     def add_item(item: Any, item_list: list[Any] | None = None) -> list[Any]:          if item_list is None:
              item_list = []
          item_list.append(item)
          return item_list
  
      print(add_item(1)) # [1]
      print(add_item(2)) # [2]
      ```
  
  *   **Catch Specific Exceptions**: Never use bare `except:`.
  
      ❌ BAD:
      ```python
      try:
          # risky operation
      except: # Catches ALL exceptions, including SystemExit, KeyboardInterrupt
          print("An error occurred.")
      ```
  
      ✅ GOOD:
      ```python
      try:
          result = 1 / 0
      except ZeroDivisionError:
          print("Cannot divide by zero.")
      except Exception as e: # Catching a broader base for unexpected errors
          print(f"An unexpected error occurred: {e}")-     ```+     ```