## 📘 Инструкция для генерации Python-кода
### 1. Общие правила
* Используй **Python 3.10+**.
* Соблюдай **четкий, читаемый и однозначный стиль** кодирования.
* **Каждая функция, метод и класс** должны иметь:
* Аннотацию типов (`type hints`)
* Полную и корректную документацию в формате `docstring` (см. раздел 3)
* Внутренние комментарии (`#`), где необходимо
---
### 2. Комментарии
* Комментарии должны быть **точными** и описывать **что делает код**, а не «что мы делаем».
* **Запрещено** использовать местоимения: `делаем`, `возвращаем`, `отправляем`, `переходим` и т.п.
* **Разрешены** только термины: `извлечение`, `выполнение`, `вызов`, `замена`, `проверка`, `отправка`, `Функция выполняет`, `Функция изменяет значение` и т.д.
#### ❌ Пример неправильного комментария:
```python
# Получаем значение параметра
✅ Пример правильного комментария:
# Функция извлекает значение параметра
3. Docstring (формат документации)
Каждая функция/метод/класс должна содержать docstring в следующем формате:
def function(param: str, param1: Optional[str | dict | str] = None) -> dict | None:
"""
Args:
param (str): Описание параметра `param`.
param1 (Optional[str | dict | str], optional): Описание параметра `param1`. По умолчанию `None`.
Returns:
dict | None: Описание возвращаемого значения. Возвращает словарь или `None`.
Raises:
SomeError: Описание ситуации, в которой возникает исключение `SomeError`.
Example:
>>> function('param', 'param1')
{'param': 'param1'}
"""
Все параметры и возвращаемые значения должны быть описаны.
Формулировки должны быть лаконичными, точными и однозначными.
Не допускается пропуск описания параметров/возвращаемых значений/исключений.
4. Аннотация типов
Все переменные, параметры и возвращаемые значения должны быть аннотированы.
Используй синтаксис Python 3.10+: list[int], dict[str, Any], str | None и т.д.
Примеры корректных аннотаций:
✅ Простые типы:
name: str = "John"
count: int = 42
flag: bool = True
✅ Коллекции и сложные типы:
from typing import Any, Optional, Callable, TypeAlias
coordinates: tuple[float, float] = (55.75, 37.61)
metadata: dict[str, Any] = {"debug": True}
UserId: TypeAlias = int
✅ Функции и методы:
def get_user_name(user_id: int) -> str:
"""Возвращает имя пользователя по его идентификатору."""
...
✅ Асинхронные функции:
async def fetch_users() -> AsyncIterator[dict[str, int | str]]:
...
✅ Обобщённые типы:
from typing import TypeVar, Generic
T = TypeVar("T")
class Container(Generic[T]):
def __init__(self, value: T) -> None:
self.value = value
def get(self) -> T:
return self.value
5. Прочее
Используй default_factory в dataclass для изменяемых значений (list, dict).
Для Optional значений указывай T | None (Python 3.10+) или Optional[T].
Для сложных структур — используй TypeAlias.
📌 Подсказка: При генерации кода всегда включай аннотацию типов, docstring, и избегай субъективных формулировок в комментариях. Цель — максимально точная, воспроизводимая и формализованная структура кода.
