From 857d5a95c575141ed797c6c4f0bdf44ac6255746 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 23 Mar 2026 04:28:44 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BF=D0=BE=D0=BB=D0=BD=D0=B0=D1=8F=20?= =?UTF-8?q?=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D0=B5=D0=B9=20?= =?UTF-8?q?=D0=B8=20=D0=B8=D1=81=D0=BA=D0=BB=D1=8E=D1=87=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 474 ++++++++++++++++++++++++++++++++++++---- src/kwork_api/errors.py | 120 +++++++++- src/kwork_api/models.py | 266 +++++++++++++++++++--- 3 files changed, 779 insertions(+), 81 deletions(-) diff --git a/api_reference.md b/api_reference.md index 66bd70e..7f21263 100644 --- a/api_reference.md +++ b/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() @@ -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") @@ -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) @@ -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") @@ -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() @@ -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 == "Москва") @@ -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") @@ -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) @@ -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") @@ -999,7 +1121,14 @@ Get available features. async def get_public_features() -> list[Feature] ``` -Get public features. +Получить публичные функции. + +Аналогично get_features(), но возвращает только +публично доступные опции. + +**Returns**: + + Список публичных features. @@ -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}") @@ -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() @@ -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}") @@ -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} новых уведомлений!") @@ -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}") @@ -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)} пользователей") @@ -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() @@ -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) @@ -1105,7 +1362,11 @@ Get user wants. async def get_wants_status() -> dict[str, Any] ``` -Get wants status. +Получить статус предпочтений. + +**Returns**: + + Статус wants с метаданными. @@ -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) @@ -1125,7 +1399,11 @@ Get kworks status. async def get_offers() -> dict[str, Any] ``` -Get offers. +Получить персональные предложения. + +**Returns**: + + Список персональных предложений от Kwork. @@ -1135,7 +1413,11 @@ Get offers. async def get_exchange_info() -> dict[str, Any] ``` -Get exchange info. +Получить информацию об обмене валюты. + +**Returns**: + + Информация о курсах валют и обмене. @@ -1145,7 +1427,11 @@ Get exchange info. async def get_channel() -> dict[str, Any] ``` -Get channel info. +Получить информацию о канале пользователя. + +**Returns**: + + Данные канала (если есть). @@ -1155,7 +1441,11 @@ Get channel info. async def get_in_app_notification() -> dict[str, Any] ``` -Get in-app notification. +Получить внутриприложенное уведомление. + +**Returns**: + + Данные in-app уведомления. @@ -1165,7 +1455,11 @@ Get in-app notification. async def get_security_user_data() -> dict[str, Any] ``` -Get security user data. +Получить данные безопасности пользователя. + +**Returns**: + + Информация о безопасности аккаунта. @@ -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("Можно написать сообщение") @@ -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)} кворков") @@ -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}") @@ -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" + }) @@ -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() @@ -1225,7 +1587,11 @@ Set user status to offline. async def get_actor() -> dict[str, Any] ``` -Get actor info. +Получить информацию об актёре (текущем пользователе). + +**Returns**: + + Данные актёра/пользователя. @@ -1236,7 +1602,11 @@ Get actor info. def catalog() -> CatalogAPI ``` -Catalog API. +API каталога кворков. + +**Returns**: + + CatalogAPI для работы с каталогом. @@ -1247,7 +1617,11 @@ Catalog API. def projects() -> ProjectsAPI ``` -Projects API. +API биржи проектов. + +**Returns**: + + ProjectsAPI для работы с проектами. @@ -1258,7 +1632,11 @@ Projects API. def user() -> UserAPI ``` -User API. +Пользовательское API. + +**Returns**: + + UserAPI для работы с профилем. @@ -1269,7 +1647,11 @@ User API. def reference() -> ReferenceAPI ``` -Reference data API. +Справочное API. + +**Returns**: + + ReferenceAPI для справочных данных. @@ -1280,7 +1662,11 @@ Reference data API. def notifications() -> NotificationsAPI ``` -Notifications API. +API уведомлений. + +**Returns**: + + NotificationsAPI для уведомлений и сообщений. @@ -1291,7 +1677,11 @@ Notifications API. def other() -> OtherAPI ``` -Other endpoints. +Прочее API. + +**Returns**: + + OtherAPI для вспомогательных эндпоинтов. diff --git a/src/kwork_api/errors.py b/src/kwork_api/errors.py index 28e4e0a..b4e9831 100644 --- a/src/kwork_api/errors.py +++ b/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) diff --git a/src/kwork_api/models.py b/src/kwork_api/models.py index 1344fe3..6e45aad 100644 --- a/src/kwork_api/models.py +++ b/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