docs: полная документация всех API классов

Добавлены подробные 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 Все методы задокументированы на русском с примерами.
2026-03-23 04:27:27 +00:00 · 2026-03-23 04:27:27 +00:00 · bc951cc763
commit bc951cc763
parent 25372e5182
2 changed files with 449 additions and 47 deletions
--- 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}")

 <a id="kwork_api.client.KworkClient.ProjectsAPI.get_worker_orders"></a>

@ -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)}")

 <a id="kwork_api.client.KworkClient.UserAPI"></a>

--- 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)