Version history: Python
v1
scan: pass2026-08-11 — Ingested from sourceInitial 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}")- ```+ ```