docs: полная документация моделей и исключений

models.py:
- KworkUser, KworkCategory, Kwork, KworkDetails
- PaginationInfo, CatalogResponse
- Project, ProjectsResponse
- Review, ReviewsResponse
- Notification, NotificationsResponse
- Dialog, AuthResponse
- ErrorDetail, APIErrorResponse
- City, Country, TimeZone
- Feature, Badge
- DataResponse

errors.py:
- KworkError (базовое)
- KworkAuthError
- KworkApiError
- KworkNotFoundError
- KworkRateLimitError
- KworkValidationError
- KworkNetworkError

Все классы задокументированы с описанием атрибутов и примерами.

api_reference.md

@@ -874,7 +874,23 @@ async def get_worker_orders() -> list[Project]
 class UserAPI()
 ```
 
-User API endpoints.
+Пользовательское API.
+
+Предоставляет доступ к данным текущего пользователя:
+- Профиль и информация об аккаунте
+- Отзывы (полученные и оставленные)
+- Избранные кворки
+
+**Example**:
+
+  # Информация о пользователе
+  info = await client.user.get_info()
+  
+  # Мои отзывы
+  reviews = await client.user.get_reviews()
+  
+  # Избранные кворки
+  favorites = await client.user.get_favorite_kworks()
 
 <a id="kwork_api.client.KworkClient.UserAPI.__init__"></a>
 
@@ -892,11 +908,25 @@ def __init__(client: "KworkClient")
 async def get_info() -> dict[str, Any]
 ```
 
-Get current user info.
+Получить информацию о текущем пользователе.
+
+Возвращает основные данные аккаунта:
+- ID, username, email
+- Баланс, рейтинг
+- Статус верификации
+- Настройки профиля
 
 **Returns**:
 
-  User info dict
+  Словарь с информацией о пользователе.
+  Структура зависит от ответа API.
+  
+
+**Example**:
+
+  info = await client.user.get_info()
+- `print(f"User` - {info.get('username')}")
+- `print(f"Balance` - {info.get('balance')} RUB")
 
 <a id="kwork_api.client.KworkClient.UserAPI.get_reviews"></a>
 
@@ -907,17 +937,35 @@ async def get_reviews(user_id: Optional[int] = None,
                       page: int = 1) -> ReviewsResponse
 ```
 
-Get user reviews.
+Получить отзывы пользователя.
+
+Если user_id не указан — возвращает отзывы текущего пользователя.
+Если указан — отзывы другого пользователя по ID.
 
 **Arguments**:
 
-- `user_id` - User ID (None for current user)
-- `page` - Page number
+- `user_id` - ID пользователя. Если None — текущий пользователь.
+- `page` - Номер страницы для пагинации (начиная с 1).
   
 
 **Returns**:
 
-  ReviewsResponse
+  ReviewsResponse содержащий:
+  - reviews: список отзывов на странице
+  - pagination: информация о пагинации
+  - average_rating: средний рейтинг
+  
+
+**Example**:
+
+  # Мои отзывы
+  my_reviews = await client.user.get_reviews()
+  
+  # Отзывы другого пользователя
+  user_reviews = await client.user.get_reviews(user_id=12345)
+  
+  # С пагинацией
+  page2 = await client.user.get_reviews(page=2)
 
 <a id="kwork_api.client.KworkClient.UserAPI.get_favorite_kworks"></a>
 
@@ -927,11 +975,20 @@ Get user reviews.
 async def get_favorite_kworks() -> list[Kwork]
 ```
 
-Get favorite kworks.
+Получить список избранных кворков.
+
+Возвращает все кворки, добавленные пользователем в избранное.
 
 **Returns**:
 
-  List of kworks
+  Список избранных кворков.
+  
+
+**Example**:
+
+  favorites = await client.user.get_favorite_kworks()
+  for kwork in favorites:
+- `print(f"{kwork.title}` - {kwork.price} RUB")
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI"></a>
 
@@ -941,7 +998,25 @@ Get favorite kworks.
 class ReferenceAPI()
 ```
 
-Reference data (cities, countries, etc.) endpoints.
+Справочное API.
+
+Предоставляет доступ к справочным данным Kwork:
+- Города, страны, часовые пояса
+- Доступные функции и дополнения
+- Значки пользователей
+
+Эти данные редко меняются и могут быть закэшированы.
+
+**Example**:
+
+  # Все страны
+  countries = await client.reference.get_countries()
+  
+  # Все города
+  cities = await client.reference.get_cities()
+  
+  # Доступные фичи
+  features = await client.reference.get_features()
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.__init__"></a>
 
@@ -959,7 +1034,17 @@ def __init__(client: "KworkClient")
 async def get_cities() -> list[City]
 ```
 
-Get all cities.
+Получить список всех городов.
+
+**Returns**:
+
+  Список всех городов из справочника Kwork.
+  
+
+**Example**:
+
+  cities = await client.reference.get_cities()
+  moscow = next(c for c in cities if c.name == "Москва")
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.get_countries"></a>
 
@@ -969,7 +1054,17 @@ Get all cities.
 async def get_countries() -> list[Country]
 ```
 
-Get all countries.
+Получить список всех стран.
+
+**Returns**:
+
+  Список всех стран с кодами и городами.
+  
+
+**Example**:
+
+  countries = await client.reference.get_countries()
+  russia = next(c for c in countries if c.code == "RU")
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.get_timezones"></a>
 
@@ -979,7 +1074,17 @@ Get all countries.
 async def get_timezones() -> list[TimeZone]
 ```
 
-Get all timezones.
+Получить список всех часовых поясов.
+
+**Returns**:
+
+  Список часовых поясов с названиями и смещениями.
+  
+
+**Example**:
+
+  timezones = await client.reference.get_timezones()
+  msks = next(tz for tz in timezones if "Moscow" in tz.name)
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.get_features"></a>
 
@@ -989,7 +1094,24 @@ Get all timezones.
 async def get_features() -> list[Feature]
 ```
 
-Get available features.
+Получить доступные дополнительные функции (features).
+
+Features — это платные дополнения к кворкам:
+- Увеличенные сроки
+- Дополнительные правки
+- Приоритетная поддержка
+- и т.д.
+
+**Returns**:
+
+  Список доступных features с названиями и ценами.
+  
+
+**Example**:
+
+  features = await client.reference.get_features()
+  for f in features:
+- `print(f"{f.name}` - {f.price} RUB")
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.get_public_features"></a>
 
@@ -999,7 +1121,14 @@ Get available features.
 async def get_public_features() -> list[Feature]
 ```
 
-Get public features.
+Получить публичные функции.
+
+Аналогично get_features(), но возвращает только
+публично доступные опции.
+
+**Returns**:
+
+  Список публичных features.
 
 <a id="kwork_api.client.KworkClient.ReferenceAPI.get_badges_info"></a>
 
@@ -1009,7 +1138,24 @@ Get public features.
 async def get_badges_info() -> list[Badge]
 ```
 
-Get badges info.
+Получить информацию о значках пользователей.
+
+Значки (badges) отображают достижения и статусы:
+- "Профессионал"
+- "Быстрый ответ"
+- "Надёжный продавец"
+- и т.д.
+
+**Returns**:
+
+  Список значков с описаниями и иконками.
+  
+
+**Example**:
+
+  badges = await client.reference.get_badges_info()
+  for badge in badges:
+- `print(f"{badge.name}` - {badge.description}")
 
 <a id="kwork_api.client.KworkClient.NotificationsAPI"></a>
 
@@ -1019,7 +1165,24 @@ Get badges info.
 class NotificationsAPI()
 ```
 
-Notifications and messages endpoints.
+API уведомлений и сообщений.
+
+Предоставляет доступ к системе уведомлений Kwork:
+- Список уведомлений
+- Получение новых уведомлений
+- Диалоги с пользователями
+- Заблокированные диалоги
+
+**Example**:
+
+  # Все уведомления
+  notifications = await client.notifications.get_list()
+  
+  # Новые уведомления
+  new = await client.notifications.fetch()
+  
+  # Диалоги
+  dialogs = await client.notifications.get_dialogs()
 
 <a id="kwork_api.client.KworkClient.NotificationsAPI.__init__"></a>
 
@@ -1037,7 +1200,26 @@ def __init__(client: "KworkClient")
 async def get_list() -> NotificationsResponse
 ```
 
-Get notifications list.
+Получить список всех уведомлений.
+
+Возвращает все уведомления пользователя с информацией
+о прочтении.
+
+**Returns**:
+
+  NotificationsResponse содержащий:
+  - notifications: список уведомлений
+  - unread_count: количество непрочитанных
+  
+
+**Example**:
+
+  notifs = await client.notifications.get_list()
+- `print(f"Непрочитанных` - {notifs.unread_count}")
+  
+  for n in notifs.notifications:
+  if not n.is_read:
+- `print(f"Новое` - {n.title}")
 
 <a id="kwork_api.client.KworkClient.NotificationsAPI.fetch"></a>
 
@@ -1047,7 +1229,22 @@ Get notifications list.
 async def fetch() -> NotificationsResponse
 ```
 
-Fetch new notifications.
+Получить новые уведомления.
+
+Отличается от get_list() тем, что возвращает только
+уведомления, появившиеся с момента последнего запроса.
+Также может обновлять счётчик непрочитанных.
+
+**Returns**:
+
+  NotificationsResponse с новыми уведомлениями.
+  
+
+**Example**:
+
+  new_notifs = await client.notifications.fetch()
+  if new_notifs.unread_count > 0:
+  print(f"У вас {new_notifs.unread_count} новых уведомлений!")
 
 <a id="kwork_api.client.KworkClient.NotificationsAPI.get_dialogs"></a>
 
@@ -1057,7 +1254,21 @@ Fetch new notifications.
 async def get_dialogs() -> list[Dialog]
 ```
 
-Get dialogs list.
+Получить список диалогов (чатов).
+
+Возвращает все активные диалоги пользователя с другими
+пользователями Kwork.
+
+**Returns**:
+
+  Список диалогов с последней перепиской.
+  
+
+**Example**:
+
+  dialogs = await client.notifications.get_dialogs()
+  for d in dialogs:
+  print(f"С {d.participant.username}: {d.last_message}")
 
 <a id="kwork_api.client.KworkClient.NotificationsAPI.get_blocked_dialogs"></a>
 
@@ -1067,7 +1278,20 @@ Get dialogs list.
 async def get_blocked_dialogs() -> list[Dialog]
 ```
 
-Get blocked dialogs.
+Получить список заблокированных диалогов.
+
+Возвращает диалоги с пользователями, которые были
+заблокированы текущим пользователем.
+
+**Returns**:
+
+  Список заблокированных диалогов.
+  
+
+**Example**:
+
+  blocked = await client.notifications.get_blocked_dialogs()
+- `print(f"Заблокировано` - {len(blocked)} пользователей")
 
 <a id="kwork_api.client.KworkClient.OtherAPI"></a>
 
@@ -1077,7 +1301,25 @@ Get blocked dialogs.
 class OtherAPI()
 ```
 
-Other API endpoints.
+Прочее API.
+
+Вспомогательные эндпоинты которые не вошли в другие категории:
+- Пользовательские настройки и предпочтения (wants)
+- Статусы кворков и заказов
+- Персональные предложения (offers)
+- Настройки профиля
+- Статус онлайн/оффлайн
+
+**Example**:
+
+  # Пользовательские предпочтения
+  wants = await client.other.get_wants()
+  
+  # Статус кворков
+  status = await client.other.get_kworks_status()
+  
+  # Установить статус оффлайн
+  await client.other.go_offline()
 
 <a id="kwork_api.client.KworkClient.OtherAPI.__init__"></a>
 
@@ -1095,7 +1337,22 @@ def __init__(client: "KworkClient")
 async def get_wants() -> dict[str, Any]
 ```
 
-Get user wants.
+Получить пользовательские предпочтения (wants).
+
+Wants — это настройки интересов пользователя:
+- Предпочитаемые категории
+- Ключевые слова для мониторинга
+- Фильтры для поиска
+
+**Returns**:
+
+  Словарь с настройками предпочтений.
+  
+
+**Example**:
+
+  wants = await client.other.get_wants()
+  print(wants)
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_wants_status"></a>
 
@@ -1105,7 +1362,11 @@ Get user wants.
 async def get_wants_status() -> dict[str, Any]
 ```
 
-Get wants status.
+Получить статус предпочтений.
+
+**Returns**:
+
+  Статус wants с метаданными.
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_kworks_status"></a>
 
@@ -1115,7 +1376,20 @@ Get wants status.
 async def get_kworks_status() -> dict[str, Any]
 ```
 
-Get kworks status.
+Получить статусы кворков пользователя.
+
+Возвращает информацию о статусах всех кворков
+текущего пользователя (активен, на модерации, и т.д.).
+
+**Returns**:
+
+  Словарь со статусами кворков.
+  
+
+**Example**:
+
+  status = await client.other.get_kworks_status()
+  print(status)
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_offers"></a>
 
@@ -1125,7 +1399,11 @@ Get kworks status.
 async def get_offers() -> dict[str, Any]
 ```
 
-Get offers.
+Получить персональные предложения.
+
+**Returns**:
+
+  Список персональных предложений от Kwork.
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_exchange_info"></a>
 
@@ -1135,7 +1413,11 @@ Get offers.
 async def get_exchange_info() -> dict[str, Any]
 ```
 
-Get exchange info.
+Получить информацию об обмене валюты.
+
+**Returns**:
+
+  Информация о курсах валют и обмене.
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_channel"></a>
 
@@ -1145,7 +1427,11 @@ Get exchange info.
 async def get_channel() -> dict[str, Any]
 ```
 
-Get channel info.
+Получить информацию о канале пользователя.
+
+**Returns**:
+
+  Данные канала (если есть).
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_in_app_notification"></a>
 
@@ -1155,7 +1441,11 @@ Get channel info.
 async def get_in_app_notification() -> dict[str, Any]
 ```
 
-Get in-app notification.
+Получить внутриприложенное уведомление.
+
+**Returns**:
+
+  Данные in-app уведомления.
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_security_user_data"></a>
 
@@ -1165,7 +1455,11 @@ Get in-app notification.
 async def get_security_user_data() -> dict[str, Any]
 ```
 
-Get security user data.
+Получить данные безопасности пользователя.
+
+**Returns**:
+
+  Информация о безопасности аккаунта.
 
 <a id="kwork_api.client.KworkClient.OtherAPI.is_dialog_allow"></a>
 
@@ -1175,7 +1469,23 @@ Get security user data.
 async def is_dialog_allow(user_id: int) -> bool
 ```
 
-Check if dialog is allowed.
+Проверить возможность начала диалога с пользователем.
+
+**Arguments**:
+
+- `user_id` - ID пользователя для проверки.
+  
+
+**Returns**:
+
+  True если диалог разрешён, False иначе.
+  
+
+**Example**:
+
+  allowed = await client.other.is_dialog_allow(12345)
+  if allowed:
+  print("Можно написать сообщение")
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_viewed_kworks"></a>
 
@@ -1185,7 +1495,20 @@ Check if dialog is allowed.
 async def get_viewed_kworks() -> list[Kwork]
 ```
 
-Get viewed kworks.
+Получить просмотренные кворки.
+
+Возвращает список кворков, которые пользователь
+просматривал ранее.
+
+**Returns**:
+
+  Список просмотренных кворков.
+  
+
+**Example**:
+
+  viewed = await client.other.get_viewed_kworks()
+- `print(f"Просмотрено` - {len(viewed)} кворков")
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_favorite_categories"></a>
 
@@ -1195,7 +1518,17 @@ Get viewed kworks.
 async def get_favorite_categories() -> list[int]
 ```
 
-Get favorite categories.
+Получить ID избранных категорий.
+
+**Returns**:
+
+  Список ID категорий, добавленных в избранное.
+  
+
+**Example**:
+
+  cats = await client.other.get_favorite_categories()
+  print(f"Избранные категории: {cats}")
 
 <a id="kwork_api.client.KworkClient.OtherAPI.update_settings"></a>
 
@@ -1205,7 +1538,25 @@ Get favorite categories.
 async def update_settings(settings: dict[str, Any]) -> dict[str, Any]
 ```
 
-Update user settings.
+Обновить настройки пользователя.
+
+**Arguments**:
+
+- `settings` - Словарь с настройками для обновления.
+  Структура зависит от конкретных настроек.
+  
+
+**Returns**:
+
+  Ответ API с подтверждением обновления.
+  
+
+**Example**:
+
+  await client.other.update_settings({
+- `"email_notifications"` - True,
+- `"language"` - "ru"
+  })
 
 <a id="kwork_api.client.KworkClient.OtherAPI.go_offline"></a>
 
@@ -1215,7 +1566,18 @@ Update user settings.
 async def go_offline() -> dict[str, Any]
 ```
 
-Set user status to offline.
+Установить статус пользователя "оффлайн".
+
+Скрывает онлайн-статус от других пользователей.
+
+**Returns**:
+
+  Подтверждение изменения статуса.
+  
+
+**Example**:
+
+  await client.other.go_offline()
 
 <a id="kwork_api.client.KworkClient.OtherAPI.get_actor"></a>
 
@@ -1225,7 +1587,11 @@ Set user status to offline.
 async def get_actor() -> dict[str, Any]
 ```
 
-Get actor info.
+Получить информацию об актёре (текущем пользователе).
+
+**Returns**:
+
+  Данные актёра/пользователя.
 
 <a id="kwork_api.client.KworkClient.catalog"></a>
 
@@ -1236,7 +1602,11 @@ Get actor info.
 def catalog() -> CatalogAPI
 ```
 
-Catalog API.
+API каталога кворков.
+
+**Returns**:
+
+  CatalogAPI для работы с каталогом.
 
 <a id="kwork_api.client.KworkClient.projects"></a>
 
@@ -1247,7 +1617,11 @@ Catalog API.
 def projects() -> ProjectsAPI
 ```
 
-Projects API.
+API биржи проектов.
+
+**Returns**:
+
+  ProjectsAPI для работы с проектами.
 
 <a id="kwork_api.client.KworkClient.user"></a>
 
@@ -1258,7 +1632,11 @@ Projects API.
 def user() -> UserAPI
 ```
 
-User API.
+Пользовательское API.
+
+**Returns**:
+
+  UserAPI для работы с профилем.
 
 <a id="kwork_api.client.KworkClient.reference"></a>
 
@@ -1269,7 +1647,11 @@ User API.
 def reference() -> ReferenceAPI
 ```
 
-Reference data API.
+Справочное API.
+
+**Returns**:
+
+  ReferenceAPI для справочных данных.
 
 <a id="kwork_api.client.KworkClient.notifications"></a>
 
@@ -1280,7 +1662,11 @@ Reference data API.
 def notifications() -> NotificationsAPI
 ```
 
-Notifications API.
+API уведомлений.
+
+**Returns**:
+
+  NotificationsAPI для уведомлений и сообщений.
 
 <a id="kwork_api.client.KworkClient.other"></a>
 
@@ -1291,7 +1677,11 @@ Notifications API.
 def other() -> OtherAPI
 ```
 
-Other endpoints.
+Прочее API.
+
+**Returns**:
+
+  OtherAPI для вспомогательных эндпоинтов.
 
 <a id="kwork_api.models"></a>
 

src/kwork_api/errors.py

@@ -1,14 +1,37 @@
 """
-Kwork API exceptions.
+Исключения Kwork API.
 
-All exceptions provide clear error messages for debugging.
+Все исключения предоставляют понятные сообщения для отладки.
+Иерархия исключений:
+
+    KworkError (базовое)
+    ├── KworkAuthError (ошибки аутентификации)
+    ├── KworkApiError (HTTP ошибки API)
+    │   ├── KworkNotFoundError (404)
+    │   ├── KworkRateLimitError (429)
+    │   └── KworkValidationError (400)
+    └── KworkNetworkError (ошибки сети)
 """
 
 from typing import Any, Optional
 
 
 class KworkError(Exception):
-    """Base exception for all Kwork API errors."""
+    """
+    Базовое исключение для всех ошибок Kwork API.
+    
+    Все остальные исключения наследуются от этого класса.
+    
+    Attributes:
+        message: Сообщение об ошибке.
+        response: Оригинальный HTTP response (если есть).
+    
+    Example:
+        try:
+            await client.catalog.get_list()
+        except KworkError as e:
+            print(f"Ошибка: {e.message}")
+    """
     
     def __init__(self, message: str, response: Optional[Any] = None):
         self.message = message
@@ -20,7 +43,20 @@ class KworkError(Exception):
 
 
 class KworkAuthError(KworkError):
-    """Authentication/authorization error."""
+    """
+    Ошибка аутентификации/авторизации.
+    
+    Возникает при:
+    - Неверном логине или пароле
+    - Истёкшем или невалидном токене
+    - Отсутствии прав доступа (403)
+    
+    Example:
+        try:
+            client = await KworkClient.login("user", "wrong_password")
+        except KworkAuthError:
+            print("Неверные учётные данные")
+    """
     
     def __init__(self, message: str = "Authentication failed", response: Optional[Any] = None):
         super().__init__(message, response)
@@ -30,7 +66,20 @@ class KworkAuthError(KworkError):
 
 
 class KworkApiError(KworkError):
-    """API request error (4xx, 5xx)."""
+    """
+    Ошибка HTTP запроса к API (4xx, 5xx).
+    
+    Базовый класс для HTTP ошибок API. Содержит код статуса.
+    
+    Attributes:
+        status_code: HTTP код ответа (400, 404, 500, etc.)
+    
+    Example:
+        try:
+            await client.catalog.get_details(999999)
+        except KworkApiError as e:
+            print(f"HTTP {e.status_code}: {e.message}")
+    """
     
     def __init__(
         self,
@@ -48,21 +97,60 @@ class KworkApiError(KworkError):
 
 
 class KworkNotFoundError(KworkApiError):
-    """Resource not found (404)."""
+    """
+    Ресурс не найден (404).
+    
+    Возникает при запросе несуществующего кворка,
+    пользователя или другого ресурса.
+    
+    Example:
+        try:
+            await client.catalog.get_details(999999)
+        except KworkNotFoundError:
+            print("Кворк не найден")
+    """
     
     def __init__(self, resource: str, response: Optional[Any] = None):
         super().__init__(f"Resource not found: {resource}", 404, response)
 
 
 class KworkRateLimitError(KworkApiError):
-    """Rate limit exceeded (429)."""
+    """
+    Превышен лимит запросов (429).
+    
+    Возникает при слишком частых запросах к API.
+    Рекомендуется сделать паузу перед повторным запросом.
+    
+    Example:
+        import asyncio
+        
+        try:
+            await client.catalog.get_list()
+        except KworkRateLimitError:
+            await asyncio.sleep(5)  # Пауза 5 секунд
+    """
     
     def __init__(self, message: str = "Rate limit exceeded", response: Optional[Any] = None):
         super().__init__(message, 429, response)
 
 
 class KworkValidationError(KworkApiError):
-    """Validation error (400)."""
+    """
+    Ошибка валидации (400).
+    
+    Возникает при некорректных данных запроса.
+    
+    Attributes:
+        fields: Словарь ошибок по полям {field: [errors]}.
+    
+    Example:
+        try:
+            await client.catalog.get_list(page=-1)
+        except KworkValidationError as e:
+            if e.fields:
+                for field, errors in e.fields.items():
+                    print(f"{field}: {errors[0]}")
+    """
     
     def __init__(
         self,
@@ -81,7 +169,21 @@ class KworkValidationError(KworkApiError):
 
 
 class KworkNetworkError(KworkError):
-    """Network/connection error."""
+    """
+    Ошибка сети/подключения.
+    
+    Возникает при:
+    - Отсутствии соединения
+    - Таймауте запроса
+    - Ошибке DNS
+    - Проблемах с SSL
+    
+    Example:
+        try:
+            await client.catalog.get_list()
+        except KworkNetworkError:
+            print("Проверьте подключение к интернету")
+    """
     
     def __init__(self, message: str = "Network error", response: Optional[Any] = None):
         super().__init__(message, response)

src/kwork_api/models.py

@@ -1,7 +1,8 @@
 """
-Pydantic models for Kwork API responses.
+Pydantic модели для ответов Kwork API.
 
-All models follow the structure found in the HAR dump analysis.
+Все модели соответствуют структуре, найденной при анализе HAR дампа.
+Используются для валидации и типизации ответов API.
 """
 
 from datetime import datetime
@@ -11,7 +12,20 @@ from pydantic import BaseModel, Field
 
 
 class KworkUser(BaseModel):
-    """User information."""
+    """
+    Информация о пользователе Kwork.
+    
+    Attributes:
+        id: Уникальный ID пользователя.
+        username: Имя пользователя (логин).
+        avatar_url: URL аватара или None.
+        is_online: Статус онлайн.
+        rating: Рейтинг пользователя (0-5).
+    
+    Example:
+        user = KworkUser(id=123, username="seller", rating=4.9)
+        print(f"{user.username}: {user.rating} ★")
+    """
     id: int
     username: str
     avatar_url: Optional[str] = None
@@ -20,7 +34,15 @@ class KworkUser(BaseModel):
 
 
 class KworkCategory(BaseModel):
-    """Category information."""
+    """
+    Категория кворков.
+    
+    Attributes:
+        id: Уникальный ID категории.
+        name: Название категории.
+        slug: URL-safe идентификатор.
+        parent_id: ID родительской категории для вложенности.
+    """
     id: int
     name: str
     slug: str
@@ -28,7 +50,25 @@ class KworkCategory(BaseModel):
 
 
 class Kwork(BaseModel):
-    """Kwork (service) information."""
+    """
+    Кворк — услуга на Kwork.
+    
+    Базовая модель кворка с основной информацией.
+    
+    Attributes:
+        id: Уникальный ID кворка.
+        title: Заголовок кворка.
+        description: Краткое описание.
+        price: Цена в рублях.
+        currency: Валюта (по умолчанию RUB).
+        category_id: ID категории.
+        seller: Информация о продавце.
+        images: Список URL изображений.
+        rating: Рейтинг кворка (0-5).
+        reviews_count: Количество отзывов.
+        created_at: Дата создания.
+        updated_at: Дата последнего обновления.
+    """
     id: int
     title: str
     description: Optional[str] = None
@@ -44,17 +84,39 @@ class Kwork(BaseModel):
 
 
 class KworkDetails(Kwork):
-    """Extended kwork details."""
+    """
+    Расширенная информация о кворке.
+    
+    Наследует все поля Kwork плюс дополнительные детали.
+    
+    Attributes:
+        full_description: Полное описание услуги.
+        requirements: Требования к заказчику.
+        delivery_time: Срок выполнения в днях.
+        revisions: Количество бесплатных правок.
+        features: Список дополнительных опций.
+        faq: Список вопросов и ответов.
+    """
     full_description: Optional[str] = None
     requirements: Optional[str] = None
-    delivery_time: Optional[int] = None  # in days
+    delivery_time: Optional[int] = None
     revisions: Optional[int] = None
     features: list[str] = Field(default_factory=list)
     faq: list[dict[str, str]] = Field(default_factory=list)
 
 
 class PaginationInfo(BaseModel):
-    """Pagination metadata."""
+    """
+    Информация о пагинации.
+    
+    Attributes:
+        current_page: Текущая страница (начиная с 1).
+        total_pages: Общее количество страниц.
+        total_items: Общее количество элементов.
+        items_per_page: Элементов на странице.
+        has_next: Есть ли следующая страница.
+        has_prev: Есть ли предыдущая страница.
+    """
     current_page: int = 1
     total_pages: int = 1
     total_items: int = 0
@@ -64,7 +126,15 @@ class PaginationInfo(BaseModel):
 
 
 class CatalogResponse(BaseModel):
-    """Catalog response with kworks and pagination."""
+    """
+    Ответ API каталога кворков.
+    
+    Attributes:
+        kworks: Список кворков на странице.
+        pagination: Информация о пагинации.
+        filters: Доступные фильтры.
+        sort_options: Доступные опции сортировки.
+    """
     kworks: list[Kwork] = Field(default_factory=list)
     pagination: Optional[PaginationInfo] = None
     filters: Optional[dict[str, Any]] = None
@@ -72,15 +142,31 @@ class CatalogResponse(BaseModel):
 
 
 class Project(BaseModel):
-    """Project (freelance order) information."""
+    """
+    Проект (заказ на бирже фриланса).
+    
+    Attributes:
+        id: Уникальный ID проекта.
+        title: Заголовок проекта.
+        description: Описание задачи.
+        budget: Бюджет проекта.
+        budget_type: Тип бюджета: "fixed" (фиксированный) или "hourly" (почасовой).
+        category_id: ID категории.
+        customer: Информация о заказчике.
+        status: Статус проекта: "open", "in_progress", "completed", "cancelled".
+        created_at: Дата создания.
+        updated_at: Дата обновления.
+        bids_count: Количество откликов.
+        skills: Требуемые навыки.
+    """
     id: int
     title: str
     description: Optional[str] = None
     budget: Optional[float] = None
-    budget_type: str = "fixed"  # fixed, hourly
+    budget_type: str = "fixed"
     category_id: Optional[int] = None
     customer: Optional[KworkUser] = None
-    status: str = "open"  # open, in_progress, completed, cancelled
+    status: str = "open"
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
     bids_count: int = 0
@@ -88,13 +174,29 @@ class Project(BaseModel):
 
 
 class ProjectsResponse(BaseModel):
-    """Projects list response."""
+    """
+    Ответ API списка проектов.
+    
+    Attributes:
+        projects: Список проектов.
+        pagination: Информация о пагинации.
+    """
     projects: list[Project] = Field(default_factory=list)
     pagination: Optional[PaginationInfo] = None
 
 
 class Review(BaseModel):
-    """Review information."""
+    """
+    Отзыв о кворке или проекте.
+    
+    Attributes:
+        id: Уникальный ID отзыва.
+        rating: Оценка от 1 до 5.
+        comment: Текст отзыва.
+        author: Автор отзыва.
+        kwork_id: ID кворка (если отзыв о кворке).
+        created_at: Дата создания.
+    """
     id: int
     rating: int = Field(ge=1, le=5)
     comment: Optional[str] = None
@@ -104,16 +206,34 @@ class Review(BaseModel):
 
 
 class ReviewsResponse(BaseModel):
-    """Reviews list response."""
+    """
+    Ответ API списка отзывов.
+    
+    Attributes:
+        reviews: Список отзывов.
+        pagination: Информация о пагинации.
+        average_rating: Средний рейтинг.
+    """
     reviews: list[Review] = Field(default_factory=list)
     pagination: Optional[PaginationInfo] = None
     average_rating: Optional[float] = None
 
 
 class Notification(BaseModel):
-    """Notification information."""
+    """
+    Уведомление пользователя.
+    
+    Attributes:
+        id: Уникальный ID уведомления.
+        type: Тип уведомления: "message", "order", "system", etc.
+        title: Заголовок уведомления.
+        message: Текст уведомления.
+        is_read: Прочитано ли уведомление.
+        created_at: Дата создания.
+        link: Ссылка для перехода (если есть).
+    """
     id: int
-    type: str  # message, order, system, etc.
+    type: str
     title: str
     message: str
     is_read: bool = False
@@ -122,13 +242,28 @@ class Notification(BaseModel):
 
 
 class NotificationsResponse(BaseModel):
-    """Notifications list response."""
+    """
+    Ответ API списка уведомлений.
+    
+    Attributes:
+        notifications: Список уведомлений.
+        unread_count: Количество непрочитанных уведомлений.
+    """
     notifications: list[Notification] = Field(default_factory=list)
     unread_count: int = 0
 
 
 class Dialog(BaseModel):
-    """Dialog (chat) information."""
+    """
+    Диалог (чат) с пользователем.
+    
+    Attributes:
+        id: Уникальный ID диалога.
+        participant: Собеседник.
+        last_message: Текст последнего сообщения.
+        unread_count: Количество непрочитанных сообщений.
+        updated_at: Время последнего сообщения.
+    """
     id: int
     participant: Optional[KworkUser] = None
     last_message: Optional[str] = None
@@ -137,7 +272,16 @@ class Dialog(BaseModel):
 
 
 class AuthResponse(BaseModel):
-    """Authentication response."""
+    """
+    Ответ API аутентификации.
+    
+    Attributes:
+        success: Успешность аутентификации.
+        user_id: ID пользователя.
+        username: Имя пользователя.
+        web_auth_token: Токен для последующих запросов.
+        message: Сообщение (например, об ошибке).
+    """
     success: bool
     user_id: Optional[int] = None
     username: Optional[str] = None
@@ -146,28 +290,57 @@ class AuthResponse(BaseModel):
 
 
 class ErrorDetail(BaseModel):
-    """Error detail from API."""
+    """
+    Детали ошибки API.
+    
+    Attributes:
+        code: Код ошибки.
+        message: Сообщение об ошибке.
+        field: Поле, вызвавшее ошибку (если применимо).
+    """
     code: str
     message: str
     field: Optional[str] = None
 
 
 class APIErrorResponse(BaseModel):
-    """Standard API error response."""
+    """
+    Стандартный ответ API об ошибке.
+    
+    Attributes:
+        success: Всегда False для ошибок.
+        errors: Список деталей ошибок.
+        message: Общее сообщение об ошибке.
+    """
     success: bool = False
     errors: list[ErrorDetail] = Field(default_factory=list)
     message: Optional[str] = None
 
 
 class City(BaseModel):
-    """City information."""
+    """
+    Город из справочника.
+    
+    Attributes:
+        id: Уникальный ID города.
+        name: Название города.
+        country_id: ID страны.
+    """
     id: int
     name: str
     country_id: Optional[int] = None
 
 
 class Country(BaseModel):
-    """Country information."""
+    """
+    Страна из справочника.
+    
+    Attributes:
+        id: Уникальный ID страны.
+        name: Название страны.
+        code: Код страны (ISO).
+        cities: Список городов в стране.
+    """
     id: int
     name: str
     code: Optional[str] = None
@@ -175,23 +348,47 @@ class Country(BaseModel):
 
 
 class TimeZone(BaseModel):
-    """Timezone information."""
+    """
+    Часовой пояс.
+    
+    Attributes:
+        id: Уникальный ID.
+        name: Название пояса.
+        offset: Смещение от UTC (например, "+03:00").
+    """
     id: int
     name: str
-    offset: str  # e.g., "+03:00"
+    offset: str
 
 
 class Feature(BaseModel):
-    """Feature/addon information."""
+    """
+    Дополнительная функция (feature) для кворка.
+    
+    Attributes:
+        id: Уникальный ID функции.
+        name: Название.
+        description: Описание.
+        price: Стоимость в рублях.
+        type: Тип: "extra", "premium", etc.
+    """
     id: int
     name: str
     description: Optional[str] = None
     price: float
-    type: str  # extra, premium, etc.
+    type: str
 
 
 class Badge(BaseModel):
-    """User badge information."""
+    """
+    Значок (достижение) пользователя.
+    
+    Attributes:
+        id: Уникальный ID значка.
+        name: Название значка.
+        description: Описание достижения.
+        icon_url: URL иконки значка.
+    """
     id: int
     name: str
     description: Optional[str] = None
@@ -200,7 +397,16 @@ class Badge(BaseModel):
 
 # Generic response wrapper
 class DataResponse(BaseModel):
-    """Generic data response wrapper."""
+    """
+    Универсальный ответ API с данными.
+    
+    Используется как обёртка для различных ответов API.
+    
+    Attributes:
+        success: Успешность запроса.
+        data: Полезные данные (словарь).
+        message: Дополнительное сообщение.
+    """
     success: bool = True
     data: Optional[dict[str, Any]] = None
     message: Optional[str] = None