RuleScan: pass
Python
Python 3.10+ rules: PEP 8 layout and naming, grouped imports, one docstring style, builtin generic type hints, uv or Poetry environments, src layout with editable installs, pytest with parametrize, and idioms like context managers and enums.
Add a trust badge to your README
[](https://waxmark.app/items/python-2/scan)
---
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 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 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. 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.
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` or `pyright`, and catch errors early.
* **All Function Signatures**: Annotate parameters and return types.
* **Variables**: Annotate complex or ambiguous variable types.
* **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 Any, TypeAlias
UserId: TypeAlias = int | str # Python 3.12+: `type UserId = int | str`
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) -> 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 `uv` or `Poetry` for dependency management and environment isolation; both write a lock file and manage `pyproject.toml`.
* **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
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 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 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 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}")
```