Что такое стандарт кода в Python?

Что такое стандарт кода в Python?

Стандарт кода (code standard, style guide) — это набор соглашений и правил, определяющих, как писать код на определённом языке. Стандарт кода включает рекомендации по форматированию, именованию переменных, организации кода и структуре проекта. В Python это исторически называется PEP 8.

PEP 8 — главный стандарт Python

PEP (Python Enhancement Proposal) — это документы, описывающие совершенствования Python. PEP 8 — это официальный стиль-гайд для кода Python.

Основные правила PEP 8

1. Отступы (Indentation)

# ПРАВИЛЬНО: 4 пробела
def function():
    if True:
        print("Hello")

# НЕПРАВИЛЬНО: 2 пробела или табы
def function():
  if True:
    print("Hello")

Правило: Используй 4 пробела на каждый уровень отступа (никогда табы).

2. Длина строки (Line Length)

# ПРАВИЛЬНО: строка до 79 символов (для кода), 72 для комментариев
short_variable = some_function(arg1, arg2, arg3)

# НЕПРАВИЛЬНО: строка слишком длинная
very_long_variable_name = some_very_long_function_name(argument1, argument2, argument3, argument4)

# ПРАВИЛЬНО: перенос длинных строк
result = some_function(
    very_long_argument_1,
    very_long_argument_2,
    very_long_argument_3
)

3. Пустые строки (Blank Lines)

# ПРАВИЛЬНО: два пробела между функциями верхнего уровня
def function1():
    pass


def function2():
    pass


class MyClass:
    # Один пробел между методами класса
    def method1(self):
        pass

    def method2(self):
        pass

4. Импорты (Imports)

# ПРАВИЛЬНО: импорты в начале файла, отсортированы
import sys
import os
from typing import List, Dict
from pathlib import Path

import numpy as np  # Сторонние библиотеки отдельно

from myproject import utils  # Локальные импорты

# НЕПРАВИЛЬНО: импорты вразброс
from pathlib import Path
import sys
from typing import List
import os

Порядок импортов:

1. Встроенные модули (sys, os, re)
2. Сторонние библиотеки (numpy, django, requests)
3. Локальные модули (myproject.utils)

5. Именование (Naming Conventions)

# Функции и переменные: snake_case
def calculate_total():
    user_age = 25
    first_name = "John"

# НЕПРАВИЛЬНО
def CalculateTotal():  # camelCase — для классов!
    pass

def calculateTotal():  # camelCase — для Python неправильно
    pass

# Классы: PascalCase
class UserAccount:
    pass

class PaymentProcessor:
    pass

# НЕПРАВИЛЬНО
class user_account:  # snake_case — для классов неправильно
    pass

# Константы: UPPER_CASE
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30
DATABASE_URL = "postgresql://localhost/mydb"

# НЕПРАВИЛЬНО
max_retries = 3  # Константа должна быть в UPPER_CASE

# Приватные переменные: ведущий underscore
class BankAccount:
    def __init__(self):
        self._balance = 0  # Приватная переменная
        self.__secret = None  # Очень приватная (name mangling)

6. Пробелы вокруг операторов (Whitespace)

# ПРАВИЛЬНО: пробелы вокруг операторов
i = i + 1
result = a + b
if x == 5:
    pass

# НЕПРАВИЛЬНО: без пробелов
i=i+1
result=a+b
if x==5:
    pass

# ПРАВИЛЬНО: при присвоении параметров, пробелы только внутри
def function(x=5, y=10):
    pass

# НЕПРАВИЛЬНО
def function(x = 5, y = 10):  # Пробелы неправильные
    pass

7. Комментарии (Comments)

# ПРАВИЛЬНО: комментарий после кода (с двумя пробелами)
x = x + 1  # Увеличиваем счётчик

# Отдельная строка комментария
# Для объяснения сложной логики

# НЕПРАВИЛЬНО: комментарий без пробела после #
x = x + 1 #увеличиваем счётчик

# ПРАВИЛЬНО: docstring для функций
def calculate_factorial(n: int) -> int:
    """Calculate factorial of n.
    
    Args:
        n: Non-negative integer
    
    Returns:
        Factorial of n
    
    Raises:
        ValueError: If n is negative
    """
    if n < 0:
        raise ValueError("n must be non-negative")
    return 1 if n <= 1 else n * calculate_factorial(n - 1)

8. Типизация (Type Hints)

# ПРАВИЛЬНО: типизация делает код понятнее
from typing import List, Dict, Optional

def process_users(users: List[Dict[str, str]]) -> int:
    """Process users and return count."""
    return len(users)

def find_user_by_email(email: str) -> Optional[Dict]:
    """Find user or return None."""
    # ...
    return None

# Классы тоже типизируем
class UserService:
    def __init__(self, db_connection: DatabaseConnection) -> None:
        self.db = db_connection
    
    def get_user(self, user_id: int) -> Optional[User]:
        # ...
        pass

Инструменты для проверки стандарта

1. Flake8

# Установка
pip install flake8

# Проверка файла
flake8 myfile.py

# Проверка всего проекта
flake8 .

# Проверка с выбранными правилами
flake8 --select E,W .

2. Black (автоформатирование)

# Установка
pip install black

# Форматирование файла
black myfile.py

# Форматирование всего проекта
black .

# Проверка без изменений
black --check .

3. Pylint (более строгая проверка)

pip install pylint

# Проверка файла
pylint myfile.py

# Вывод детального отчёта
pylint myfile.py --output-format=json

4. isort (сортировка импортов)

pip install isort

# Сортировка импортов
isort myfile.py

# Проверка без изменений
isort --check-only myfile.py

Конфигурация проекта

.flake8

[flake8]
max-line-length = 100
extend-ignore = E203, W503
exclude = .git, __pycache__, venv

pyproject.toml

[tool.black]
line-length = 100
target-version = ['py39']
exclude = '''
    (
        /(
            \.git
            | \.venv
            | __pycache__
        )
    )
'''

[tool.isort]
profile = "black"
line_length = 100

Практический пример: хороший код

"""User service module.

Provides functionality for user management and authentication.
"""

from typing import Dict, List, Optional
from datetime import datetime, UTC
from enum import Enum

from sqlalchemy.orm import Session

from myapp.domain.user import User
from myapp.infrastructure.password import hash_password, verify_password


class UserRole(Enum):
    """User roles."""
    ADMIN = "admin"
    USER = "user"
    GUEST = "guest"


MAX_PASSWORD_LENGTH = 128
MIN_PASSWORD_LENGTH = 8


class UserService:
    """Service for managing users."""

    def __init__(self, db: Session) -> None:
        """Initialize user service.
        
        Args:
            db: Database session
        """
        self.db = db

    def create_user(
        self,
        email: str,
        password: str,
        role: UserRole = UserRole.USER
    ) -> User:
        """Create new user.
        
        Args:
            email: User email
            password: User password
            role: User role (default: USER)
        
        Returns:
            Created user object
        
        Raises:
            ValueError: If password is invalid
        """
        if not self._is_valid_password(password):
            raise ValueError(
                f"Password must be {MIN_PASSWORD_LENGTH}-"
                f"{MAX_PASSWORD_LENGTH} characters"
            )
        
        hashed_password = hash_password(password)
        user = User(
            email=email,
            password=hashed_password,
            role=role,
            created_at=datetime.now(UTC)
        )
        
        self.db.add(user)
        self.db.commit()
        return user

    @staticmethod
    def _is_valid_password(password: str) -> bool:
        """Check if password meets requirements."""
        return (
            MIN_PASSWORD_LENGTH <= len(password) <= MAX_PASSWORD_LENGTH
        )

Почему стандарты важны

1. Читаемость — одинаковый стиль делает код понятнее
2. Сотрудничество — команда быстро разбирается в чужом коде
3. Поддержка — проще находить и исправлять баги
4. Качество — инструменты помогают выявить проблемы
5. Профессионализм — хороший код — признак опыта

Вывод: Стандарт кода Python (PEP 8) — это не просто рекомендация, это основа профессионального Python разработки. Использование инструментов (Black, Flake8, isort) автоматизирует проверку и форматирование, позволяя сосредоточиться на логике приложения, а не на форматировании.