From bc951cc763e27b4cb2a32939a5e7d989f672d879 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 23 Mar 2026 04:27:27 +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=B2=D1=81=D0=B5=D1=85=20API=20=D0=BA=D0=BB?= =?UTF-8?q?=D0=B0=D1=81=D1=81=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Добавлены подробные docstrings для: UserAPI: - get_info(), get_reviews(), get_favorite_kworks() ReferenceAPI: - get_cities(), get_countries(), get_timezones() - get_features(), get_public_features(), get_badges_info() NotificationsAPI: - get_list(), fetch(), get_dialogs(), get_blocked_dialogs() OtherAPI: - get_wants(), get_wants_status(), get_kworks_status() - get_offers(), get_exchange_info(), get_channel() - get_in_app_notification(), get_security_user_data() - is_dialog_allow(), get_viewed_kworks() - get_favorite_categories(), update_settings() - go_offline(), get_actor() API property accessor'ы: - catalog, projects, user, reference, notifications, other Все методы задокументированы на русском с примерами. --- api_reference.md | 28 ++- src/kwork_api/client.py | 468 ++++++++++++++++++++++++++++++++++++---- 2 files changed, 449 insertions(+), 47 deletions(-) diff --git a/api_reference.md b/api_reference.md index e2cce63..66bd70e 100644 --- a/api_reference.md +++ b/api_reference.md @@ -826,11 +826,21 @@ async def get_list(page: int = 1, async def get_payer_orders() -> list[Project] ``` -Get orders where user is customer. +Получить заказы где вы являетесь заказчиком. + +Возвращает все проекты, созданные текущим пользователем, +независимо от их статуса (открыт, в работе, завершён). **Returns**: - List of projects + Список проектов где текущий пользователь — заказчик. + + +**Example**: + + orders = await client.projects.get_payer_orders() + for order in orders: + print(f"Заказ #{order.id}: {order.status}") @@ -840,11 +850,21 @@ Get orders where user is customer. async def get_worker_orders() -> list[Project] ``` -Get orders where user is performer. +Получить заказы где вы являетесь исполнителем. + +Возвращает все проекты, где текущий пользователь +назначен исполнителем. **Returns**: - List of projects + Список проектов где текущий пользователь — исполнитель. + + +**Example**: + + work = await client.projects.get_worker_orders() + active = [p for p in work if p.status == "in_progress"] + print(f"Активных заказов: {len(active)}") diff --git a/src/kwork_api/client.py b/src/kwork_api/client.py index a4bfa88..1e245af 100644 --- a/src/kwork_api/client.py +++ b/src/kwork_api/client.py @@ -582,17 +582,46 @@ class KworkClient: # ========== User Endpoints ========== 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() + """ def __init__(self, client: "KworkClient"): self.client = client async def get_info(self) -> 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") """ return await self.client._request("POST", "/user") @@ -602,14 +631,30 @@ class KworkClient: page: int = 1, ) -> ReviewsResponse: """ - Get user reviews. + Получить отзывы пользователя. + + Если user_id не указан — возвращает отзывы текущего пользователя. + Если указан — отзывы другого пользователя по ID. Args: - 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) """ data = await self.client._request( "POST", @@ -620,10 +665,17 @@ class KworkClient: async def get_favorite_kworks(self) -> 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") """ data = await self.client._request("POST", "/favoriteKworks") return [Kwork.model_validate(k) for k in data.get("kworks", [])] @@ -631,111 +683,360 @@ class KworkClient: # ========== Reference Data Endpoints ========== 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() + """ def __init__(self, client: "KworkClient"): self.client = client async def get_cities(self) -> list[City]: - """Get all cities.""" + """ + Получить список всех городов. + + Returns: + Список всех городов из справочника Kwork. + + Example: + cities = await client.reference.get_cities() + moscow = next(c for c in cities if c.name == "Москва") + """ data = await self.client._request("POST", "/cities") return [City.model_validate(c) for c in data.get("cities", [])] async def get_countries(self) -> list[Country]: - """Get all countries.""" + """ + Получить список всех стран. + + Returns: + Список всех стран с кодами и городами. + + Example: + countries = await client.reference.get_countries() + russia = next(c for c in countries if c.code == "RU") + """ data = await self.client._request("POST", "/countries") return [Country.model_validate(c) for c in data.get("countries", [])] async def get_timezones(self) -> 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) + """ data = await self.client._request("POST", "/timezones") return [TimeZone.model_validate(t) for t in data.get("timezones", [])] async def get_features(self) -> 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") + """ data = await self.client._request("POST", "/getAvailableFeatures") return [Feature.model_validate(f) for f in data.get("features", [])] async def get_public_features(self) -> list[Feature]: - """Get public features.""" + """ + Получить публичные функции. + + Аналогично get_features(), но возвращает только + публично доступные опции. + + Returns: + Список публичных features. + """ data = await self.client._request("POST", "/getPublicFeatures") return [Feature.model_validate(f) for f in data.get("features", [])] async def get_badges_info(self) -> 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}") + """ data = await self.client._request("POST", "/getBadgesInfo") return [Badge.model_validate(b) for b in data.get("badges", [])] # ========== Notifications & Messages ========== 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() + """ def __init__(self, client: "KworkClient"): self.client = client async def get_list(self) -> 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}") + """ data = await self.client._request("POST", "/notifications") return NotificationsResponse.model_validate(data) async def fetch(self) -> 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} новых уведомлений!") + """ data = await self.client._request("POST", "/notificationsFetch") return NotificationsResponse.model_validate(data) async def get_dialogs(self) -> 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}") + """ data = await self.client._request("POST", "/dialogs") return [Dialog.model_validate(d) for d in data.get("dialogs", [])] async def get_blocked_dialogs(self) -> list[Dialog]: - """Get blocked dialogs.""" + """ + Получить список заблокированных диалогов. + + Возвращает диалоги с пользователями, которые были + заблокированы текущим пользователем. + + Returns: + Список заблокированных диалогов. + + Example: + blocked = await client.notifications.get_blocked_dialogs() + print(f"Заблокировано: {len(blocked)} пользователей") + """ data = await self.client._request("POST", "/blockedDialogList") return [Dialog.model_validate(d) for d in data.get("dialogs", [])] # ========== Other Endpoints ========== 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() + """ def __init__(self, client: "KworkClient"): self.client = client async def get_wants(self) -> dict[str, Any]: - """Get user wants.""" + """ + Получить пользовательские предпочтения (wants). + + Wants — это настройки интересов пользователя: + - Предпочитаемые категории + - Ключевые слова для мониторинга + - Фильтры для поиска + + Returns: + Словарь с настройками предпочтений. + + Example: + wants = await client.other.get_wants() + print(wants) + """ return await self.client._request("POST", "/myWants") async def get_wants_status(self) -> dict[str, Any]: - """Get wants status.""" + """ + Получить статус предпочтений. + + Returns: + Статус wants с метаданными. + """ return await self.client._request("POST", "/wantsStatusList") async def get_kworks_status(self) -> dict[str, Any]: - """Get kworks status.""" + """ + Получить статусы кворков пользователя. + + Возвращает информацию о статусах всех кворков + текущего пользователя (активен, на модерации, и т.д.). + + Returns: + Словарь со статусами кворков. + + Example: + status = await client.other.get_kworks_status() + print(status) + """ return await self.client._request("POST", "/kworksStatusList") async def get_offers(self) -> dict[str, Any]: - """Get offers.""" + """ + Получить персональные предложения. + + Returns: + Список персональных предложений от Kwork. + """ return await self.client._request("POST", "/offers") async def get_exchange_info(self) -> dict[str, Any]: - """Get exchange info.""" + """ + Получить информацию об обмене валюты. + + Returns: + Информация о курсах валют и обмене. + """ return await self.client._request("POST", "/exchangeInfo") async def get_channel(self) -> dict[str, Any]: - """Get channel info.""" + """ + Получить информацию о канале пользователя. + + Returns: + Данные канала (если есть). + """ return await self.client._request("POST", "/getChannel") async def get_in_app_notification(self) -> dict[str, Any]: - """Get in-app notification.""" + """ + Получить внутриприложенное уведомление. + + Returns: + Данные in-app уведомления. + """ return await self.client._request("POST", "/getInAppNotification") async def get_security_user_data(self) -> dict[str, Any]: - """Get security user data.""" + """ + Получить данные безопасности пользователя. + + Returns: + Информация о безопасности аккаунта. + """ return await self.client._request("POST", "/getSecurityUserData") async def is_dialog_allow(self, user_id: int) -> bool: - """Check if dialog is allowed.""" + """ + Проверить возможность начала диалога с пользователем. + + Args: + user_id: ID пользователя для проверки. + + Returns: + True если диалог разрешён, False иначе. + + Example: + allowed = await client.other.is_dialog_allow(12345) + if allowed: + print("Можно написать сообщение") + """ data = await self.client._request( "POST", "/isDialogAllow", @@ -744,55 +1045,136 @@ class KworkClient: return data.get("allowed", False) async def get_viewed_kworks(self) -> list[Kwork]: - """Get viewed kworks.""" + """ + Получить просмотренные кворки. + + Возвращает список кворков, которые пользователь + просматривал ранее. + + Returns: + Список просмотренных кворков. + + Example: + viewed = await client.other.get_viewed_kworks() + print(f"Просмотрено: {len(viewed)} кворков") + """ data = await self.client._request("POST", "/viewedCatalogKworks") return [Kwork.model_validate(k) for k in data.get("kworks", [])] async def get_favorite_categories(self) -> list[int]: - """Get favorite categories.""" + """ + Получить ID избранных категорий. + + Returns: + Список ID категорий, добавленных в избранное. + + Example: + cats = await client.other.get_favorite_categories() + print(f"Избранные категории: {cats}") + """ data = await self.client._request("POST", "/favoriteCategories") return data.get("categories", []) async def update_settings(self, settings: dict[str, Any]) -> dict[str, Any]: - """Update user settings.""" + """ + Обновить настройки пользователя. + + Args: + settings: Словарь с настройками для обновления. + Структура зависит от конкретных настроек. + + Returns: + Ответ API с подтверждением обновления. + + Example: + await client.other.update_settings({ + "email_notifications": True, + "language": "ru" + }) + """ return await self.client._request("POST", "/updateSettings", json=settings) async def go_offline(self) -> dict[str, Any]: - """Set user status to offline.""" + """ + Установить статус пользователя "оффлайн". + + Скрывает онлайн-статус от других пользователей. + + Returns: + Подтверждение изменения статуса. + + Example: + await client.other.go_offline() + """ return await self.client._request("POST", "/offline") async def get_actor(self) -> dict[str, Any]: - """Get actor info.""" + """ + Получить информацию об актёре (текущем пользователе). + + Returns: + Данные актёра/пользователя. + """ return await self.client._request("POST", "/actor") # ========== API Property Accessors ========== @property def catalog(self) -> CatalogAPI: - """Catalog API.""" + """ + API каталога кворков. + + Returns: + CatalogAPI для работы с каталогом. + """ return self.CatalogAPI(self) @property def projects(self) -> ProjectsAPI: - """Projects API.""" + """ + API биржи проектов. + + Returns: + ProjectsAPI для работы с проектами. + """ return self.ProjectsAPI(self) @property def user(self) -> UserAPI: - """User API.""" + """ + Пользовательское API. + + Returns: + UserAPI для работы с профилем. + """ return self.UserAPI(self) @property def reference(self) -> ReferenceAPI: - """Reference data API.""" + """ + Справочное API. + + Returns: + ReferenceAPI для справочных данных. + """ return self.ReferenceAPI(self) @property def notifications(self) -> NotificationsAPI: - """Notifications API.""" + """ + API уведомлений. + + Returns: + NotificationsAPI для уведомлений и сообщений. + """ return self.NotificationsAPI(self) @property def other(self) -> OtherAPI: - """Other endpoints.""" + """ + Прочее API. + + Returns: + OtherAPI для вспомогательных эндпоинтов. + """ return self.OtherAPI(self)