From a771a75c49833d157c2666c487f15e0855e53582 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 23 Mar 2026 04:23:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D0=BF=D0=BE=D0=B4=D1=80=D0=BE=D0=B1=D0=BD?= =?UTF-8?q?=D1=8B=D0=B5=20docstrings=20=D0=B4=D0=BB=D1=8F=20KworkClient?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - KworkClient: полное описание класса, аутентификации, примеров - __init__: детальное описание параметров - login(): пошаговое описание процесса аутентификации - CatalogAPI: документация класса и методов get_list, get_details, get_details_extra - ProjectsAPI: документация класса и метода get_list - get_payer_orders/get_worker_orders: описание методов Все docstrings на русском языке с примерами использования. --- api_reference.md | 274 ++++++++++++++++++++++++++++++++----- docs/api-reference.md | 25 ---- docs/api/client.md | 7 - docs/api/errors.md | 23 ---- docs/api/models.md | 23 ---- docs/examples.md | 212 ----------------------------- docs/index.md | 81 ----------- src/kwork_api/client.py | 291 +++++++++++++++++++++++++++++++++------- 8 files changed, 483 insertions(+), 453 deletions(-) delete mode 100644 docs/api-reference.md delete mode 100644 docs/api/client.md delete mode 100644 docs/api/errors.md delete mode 100644 docs/api/models.md delete mode 100644 docs/examples.md delete mode 100644 docs/index.md diff --git a/api_reference.md b/api_reference.md index f8f2aae..e2cce63 100644 --- a/api_reference.md +++ b/api_reference.md @@ -398,17 +398,47 @@ Main client class with authentication and all API endpoints. class KworkClient() ``` -Kwork.ru API client. +Асинхронный клиент для Kwork.ru API. -Usage: - # Login with credentials - client = await KworkClient.login("username", "password") +Предоставляет доступ ко всем основным эндпоинтам Kwork API: +- Каталог кворков и поиск +- Биржа проектов (фриланс заказы) +- Пользовательские данные и отзывы +- Уведомления и сообщения +- Справочные данные (города, страны, категории) - # Or restore from token - client = KworkClient(token="your_web_auth_token") +Аутентификация: +Клиент использует двухэтапную аутентификацию Kwork: +1. POST /signIn — получение session cookies +2. POST /getWebAuthToken — получение web_auth_token - # Make requests - catalog = await client.catalog.get_list(page=1) +Примеры использования: +# Вход по логину/паролю +async with await KworkClient.login("username", "password") as client: +catalog = await client.catalog.get_list(page=1) + +# Восстановление сессии по токену +client = KworkClient(token="saved_web_auth_token") +user_info = await client.user.get_info() + +# Работа с проектами +projects = await client.projects.get_list(page=1) +my_orders = await client.projects.get_payer_orders() + +**Attributes**: + +- `catalog` - Доступ к каталогу кворков +- `projects` - Доступ к бирже проектов +- `user` - Пользовательские эндпоинты +- `reference` - Справочные данные +- `notifications` - Уведомления и сообщения +- `other` - Прочие эндпоинты + + +**Notes**: + + Клиент поддерживает context manager для автоматического закрытия соединения. + Рекомендуется использовать `async with` для корректного освобождения ресурсов. @@ -433,14 +463,37 @@ def __init__(token: Optional[str] = None, base_url: Optional[str] = None) ``` -Initialize client. +Инициализация клиента. + +Создаёт неаутентифицированный клиент или восстанавливает сессию +по ранее полученному токену. **Arguments**: -- `token` - Web auth token (from getWebAuthToken) -- `cookies` - Session cookies (optional, will be set from token) -- `timeout` - Request timeout in seconds -- `base_url` - Custom base URL (for testing) +- `token` - Web auth token, полученный через `getWebAuthToken` или `login()`. + Если указан, автоматически добавляется в cookies. +- `cookies` - Session cookies из предыдущей аутентификации. + Обычно не требуется — устанавливаются автоматически из token. +- `timeout` - Таймаут HTTP запросов в секундах. По умолчанию 30 секунд. +- `base_url` - Кастомный базовый URL. Используется только для тестирования. + + +**Example**: + + # Новый клиент без аутентификации + client = KworkClient() + + # Восстановление сессии + client = KworkClient(token="eyJ0eXAiOiJKV1QiLCJhbGc...") + + # Клиент с кастомным таймаутом + client = KworkClient(timeout=60.0) + + +**Notes**: + + Для полноценной работы API требуется аутентификация. + Используйте `login()` или передайте сохранённый token. @@ -454,23 +507,55 @@ async def login(cls, timeout: float = 30.0) -> "KworkClient" ``` -Login with username and password. +Аутентификация по логину и паролю. + +Выполняет двухэтапный процесс аутентификации Kwork: +1. POST /signIn — проверка учётных данных, получение session cookies +2. POST /getWebAuthToken — обмен cookies на web_auth_token + +Полученный токен и cookies сохраняются в клиенте для последующих запросов. **Arguments**: -- `username` - Kwork username or email -- `password` - Kwork password -- `timeout` - Request timeout +- `username` - Логин или email аккаунта Kwork. +- `password` - Пароль аккаунта Kwork. +- `timeout` - Таймаут запросов в секундах. Применяется к каждому этапу. **Returns**: - Authenticated KworkClient instance + Полностью аутентифицированный экземпляр KworkClient, + готовый к работе с API. **Raises**: -- `KworkAuthError` - If login fails +- `KworkAuthError` - Если логин/пароль неверны или токен не получен. +- `KworkNetworkError` - Если произошла ошибка сети. + + +**Example**: + + # Базовое использование + client = await KworkClient.login("myuser", "mypassword") + + # С кастомным таймаутом + client = await KworkClient.login("user", "pass", timeout=60.0) + + # Сохранение токена для повторного использования + token = client._token + # Позже: client = KworkClient(token=token) + + Security: + Пароль не сохраняется в клиенте. Только token и cookies. + Рекомендуется сохранять token для повторного использования + вместо хранения пароля. + + +**Notes**: + + Токен имеет ограниченное время жизни. При получении 401 ошибки + необходимо выполнить повторный login(). @@ -506,7 +591,23 @@ async def __aexit__(*args: Any) -> None class CatalogAPI() ``` -Catalog/Kworks API endpoints. +API каталога кворков. + +Предоставляет доступ к каталогу услуг Kwork: +- Поиск и фильтрация кворков +- Получение детальной информации +- Категории и сортировка + +**Example**: + + # Получить первую страницу каталога + catalog = await client.catalog.get_list(page=1) + + # Фильтрация по категории + catalog = await client.catalog.get_list(category_id=5) + + # Детали конкретного кворка + details = await client.catalog.get_details(kwork_id=12345) @@ -526,18 +627,48 @@ async def get_list(page: int = 1, sort: str = "recommend") -> CatalogResponse ``` -Get kworks catalog. +Получить список кворков из каталога. + +Основной эндпоинт для поиска и просмотра кворков. +Возвращает пагинированный список с возможностью фильтрации. **Arguments**: -- `page` - Page number -- `category_id` - Category filter -- `sort` - Sort option (recommend, price_asc, price_desc, etc.) +- `page` - Номер страницы для пагинации (начиная с 1). +- `category_id` - ID категории для фильтрации. + Если None — все категории. +- `sort` - Опция сортировки. Варианты: + - "recommend" — по рекомендации (по умолчанию) + - "price_asc" — по возрастанию цены + - "price_desc" — по убыванию цены + - "rating" — по рейтингу + - "reviews" — по количеству отзывов + - "newest" — по дате создания **Returns**: - CatalogResponse with kworks and pagination + CatalogResponse содержащий: + - kworks: список кворков на странице + - pagination: информация о пагинации + - filters: доступные фильтры + - sort_options: доступные опции сортировки + + +**Example**: + + # Первая страница, сортировка по цене + response = await client.catalog.get_list( + page=1, + sort="price_asc" + ) + + for kwork in response.kworks: +- `print(f"{kwork.title}` - {kwork.price} RUB") + + # Пагинация + if response.pagination and response.pagination.has_next: + next_page = await client.catalog.get_list(page=2) @@ -547,16 +678,36 @@ Get kworks catalog. async def get_details(kwork_id: int) -> KworkDetails ``` -Get kwork details. +Получить полную информацию о кворке. + +Возвращает расширенную информацию о кворке включая: +- Полное описание и требования +- Сроки выполнения и количество правок +- Дополнительные опции (features) +- FAQ от продавца **Arguments**: -- `kwork_id` - Kwork ID +- `kwork_id` - Уникальный идентификатор кворка. **Returns**: - KworkDetails with full information + KworkDetails с полной информацией о кворке. + + +**Raises**: + +- `KworkNotFoundError` - Если кворк с таким ID не найден. + + +**Example**: + + details = await client.catalog.get_details(12345) +- `print(f"Название` - {details.title}") +- `print(f"Цена` - {details.price} {details.currency}") +- `print(f"Срок` - {details.delivery_time} дней") +- `print(f"Правки` - {details.revisions}") @@ -566,16 +717,30 @@ Get kwork details. async def get_details_extra(kwork_id: int) -> dict[str, Any] ``` -Get additional kwork details. +Получить дополнительные детали кворка. + +Возвращает расширенную информацию, которая не включена +в основной ответ get_details(). Может содержать: +- Дополнительные изображения +- Видео обзоры +- Детали пакетов услуг +- Статистику продаж **Arguments**: -- `kwork_id` - Kwork ID +- `kwork_id` - Уникальный идентификатор кворка. **Returns**: - Extra details dict + Словарь с дополнительными данными. Структура зависит + от конкретного кворка и не гарантируется стабильной. + + +**Notes**: + + Этот эндпоинт возвращает "сырые" данные без валидации. + Структура ответа может измениться без предупреждения. @@ -585,7 +750,23 @@ Get additional kwork details. class ProjectsAPI() ``` -Projects (freelance orders) API endpoints. +API биржи проектов (фриланс заказы). + +Предоставляет доступ к заказам на фриланс: +- Просмотр открытых проектов +- Заказы где вы заказчик (payer) +- Заказы где вы исполнитель (worker) + +**Example**: + + # Новые проекты + projects = await client.projects.get_list(page=1) + + # Мои заказы как заказчика + my_orders = await client.projects.get_payer_orders() + + # Мои заказы как исполнителя + my_work = await client.projects.get_worker_orders() @@ -604,17 +785,38 @@ async def get_list(page: int = 1, category_id: Optional[int] = None) -> ProjectsResponse ``` -Get projects list. +Получить список проектов с биржи. + +Основной эндпоинт для просмотра доступных заказов. +Возвращает пагинированный список проектов. **Arguments**: -- `page` - Page number -- `category_id` - Category filter +- `page` - Номер страницы (начиная с 1). +- `category_id` - ID категории для фильтрации. + Если None — все категории. **Returns**: - ProjectsResponse with projects and pagination + ProjectsResponse содержащий: + - projects: список проектов на странице + - pagination: информация о пагинации + + +**Example**: + + # Все новые проекты + response = await client.projects.get_list(page=1) + + for project in response.projects: +- `print(f"{project.title}` - {project.budget} {project.budget_type}") + + # Только категория "Разработка" + dev_projects = await client.projects.get_list( + page=1, + category_id=5 + ) diff --git a/docs/api-reference.md b/docs/api-reference.md deleted file mode 100644 index 89642a1..0000000 --- a/docs/api-reference.md +++ /dev/null @@ -1,25 +0,0 @@ -# API Reference - -Auto-generated API documentation using mkdocstrings. - -## Client - -::: kwork_api.client.KworkClient - -## Models - -::: kwork_api.models.Kwork - -::: kwork_api.models.KworkDetails - -::: kwork_api.models.Project - -::: kwork_api.models.CatalogResponse - -## Errors - -::: kwork_api.errors.KworkError - -::: kwork_api.errors.KworkAuthError - -::: kwork_api.errors.KworkApiError diff --git a/docs/api/client.md b/docs/api/client.md deleted file mode 100644 index 7cf4af9..0000000 --- a/docs/api/client.md +++ /dev/null @@ -1,7 +0,0 @@ -# Client API - -::: kwork_api.client.KworkClient - options: - show_root_heading: true - show_source: true - merge_init_into_class: true diff --git a/docs/api/errors.md b/docs/api/errors.md deleted file mode 100644 index a12e5f5..0000000 --- a/docs/api/errors.md +++ /dev/null @@ -1,23 +0,0 @@ -# Errors - -Exception classes for error handling. - -## KworkError - -::: kwork_api.errors.KworkError - -## KworkAuthError - -::: kwork_api.errors.KworkAuthError - -## KworkApiError - -::: kwork_api.errors.KworkApiError - -## KworkNotFoundError - -::: kwork_api.errors.KworkNotFoundError - -## KworkRateLimitError - -::: kwork_api.errors.KworkRateLimitError diff --git a/docs/api/models.md b/docs/api/models.md deleted file mode 100644 index 99cebfb..0000000 --- a/docs/api/models.md +++ /dev/null @@ -1,23 +0,0 @@ -# Models - -Pydantic models used in API responses. - -## Kwork - -::: kwork_api.models.Kwork - -## KworkDetails - -::: kwork_api.models.KworkDetails - -## Project - -::: kwork_api.models.Project - -## CatalogResponse - -::: kwork_api.models.CatalogResponse - -## PaginationInfo - -::: kwork_api.models.PaginationInfo diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 3d0b311..0000000 --- a/docs/examples.md +++ /dev/null @@ -1,212 +0,0 @@ -# Usage Examples - -## Catalog - -### Get Catalog List - -```python -from kwork_api import KworkClient - -async with KworkClient(token="token") as client: - catalog = await client.catalog.get_list(page=1, category_id=5) - - for kwork in catalog.kworks: - print(f"{kwork.title}: {kwork.price} RUB") - - # Pagination - if catalog.pagination: - print(f"Page {catalog.pagination.current_page} of {catalog.pagination.total_pages}") -``` - -### Get Kwork Details - -```python -details = await client.catalog.get_details(kwork_id=123) - -print(f"Title: {details.title}") -print(f"Price: {details.price}") -print(f"Description: {details.full_description}") -print(f"Delivery: {details.delivery_time} days") -``` - -## Projects - -### Get Projects List - -```python -projects = await client.projects.get_list(page=1) - -for project in projects.projects: - print(f"{project.title} - {project.budget} RUB") -``` - -### Get Customer Orders - -```python -orders = await client.projects.get_payer_orders() - -for order in orders: - print(f"Order #{order.id}: {order.status}") -``` - -### Get Performer Orders - -```python -orders = await client.projects.get_worker_orders() - -for order in orders: - print(f"Work #{order.id}: {order.status}") -``` - -## User - -### Get User Info - -```python -user_info = await client.user.get_info() -print(f"Username: {user_info.get('username')}") -``` - -### Get Reviews - -```python -reviews = await client.user.get_reviews(page=1) - -for review in reviews.reviews: - print(f"Rating: {review.rating}/5 - {review.comment}") -``` - -### Get Favorite Kworks - -```python -favorites = await client.user.get_favorite_kworks() - -for kwork in favorites: - print(f"Favorite: {kwork.title}") -``` - -## Reference Data - -### Get Cities - -```python -cities = await client.reference.get_cities() - -for city in cities: - print(f"{city.id}: {city.name}") -``` - -### Get Countries - -```python -countries = await client.reference.get_countries() - -for country in countries: - print(f"{country.id}: {country.name}") -``` - -### Get Timezones - -```python -timezones = await client.reference.get_timezones() - -for tz in timezones: - print(f"{tz.id}: {tz.name} ({tz.offset})") -``` - -## Notifications - -### Get Notifications - -```python -notifications = await client.notifications.get_list() - -for notif in notifications.notifications: - print(f"{notif.title}: {notif.message}") - -print(f"Unread: {notifications.unread_count}") -``` - -### Fetch New Notifications - -```python -new_notifications = await client.notifications.fetch() -print(f"New: {len(new_notifications.notifications)}") -``` - -### Get Dialogs - -```python -dialogs = await client.notifications.get_dialogs() - -for dialog in dialogs: - print(f"Dialog with {dialog.participant.username}: {dialog.last_message}") -``` - -## Error Handling - -```python -from kwork_api import KworkAuthError, KworkApiError, KworkNotFoundError - -try: - catalog = await client.catalog.get_list() -except KworkAuthError as e: - print(f"Authentication failed: {e}") -except KworkNotFoundError as e: - print(f"Resource not found: {e}") -except KworkApiError as e: - print(f"API error [{e.status_code}]: {e.message}") -except Exception as e: - print(f"Unexpected error: {e}") -``` - -## Rate Limiting - -```python -import asyncio - -async def fetch_all_pages(): - all_kworks = [] - - for page in range(1, 10): - try: - catalog = await client.catalog.get_list(page=page) - all_kworks.extend(catalog.kworks) - - if not catalog.pagination or not catalog.pagination.has_next: - break - - # Delay to avoid rate limiting - await asyncio.sleep(1) - - except KworkRateLimitError: - print("Rate limited, waiting...") - await asyncio.sleep(5) - - return all_kworks -``` - -## Pagination Helper - -```python -async def fetch_all_catalog(): - """Fetch all kworks from catalog with pagination.""" - all_kworks = [] - page = 1 - - while True: - catalog = await client.catalog.get_list(page=page) - all_kworks.extend(catalog.kworks) - - if not catalog.pagination or not catalog.pagination.has_next: - break - - page += 1 - await asyncio.sleep(0.5) # Rate limiting - - return all_kworks -``` - ---- - -*More examples in the API Reference.* diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 9a3a421..0000000 --- a/docs/index.md +++ /dev/null @@ -1,81 +0,0 @@ -# Kwork API Documentation - -Unofficial Python client for Kwork.ru API. - -## Quick Start - -### Installation - -```bash -pip install kwork-api -``` - -### Authentication - -```python -from kwork_api import KworkClient - -# Login with credentials -client = await KworkClient.login("username", "password") - -# Or restore from token -client = KworkClient(token="your_web_auth_token") -``` - -### Basic Usage - -```python -async with KworkClient(token="token") as client: - # Get catalog - catalog = await client.catalog.get_list(page=1) - - # Get kwork details - details = await client.catalog.get_details(kwork_id=123) - - # Get projects - projects = await client.projects.get_list() -``` - -## Documentation Sections - -- **[API Reference](api-reference.md)** — All endpoints and methods -- **[Models](api-reference.md#models)** — Pydantic models -- **[Errors](api-reference.md#errors)** — Exception classes -- **[Examples](examples.md)** — Usage examples - -## Features - -- ✅ Full API coverage (45 endpoints) -- ✅ Async/await support -- ✅ Pydantic models for type safety -- ✅ Clear error handling -- ✅ Session management - -## Rate Limiting - -Rate limiting is **not** implemented in the library. Handle it in your code: - -```python -import asyncio - -for page in range(1, 10): - catalog = await client.catalog.get_list(page=page) - await asyncio.sleep(1) # 1 second delay -``` - -## Error Handling - -```python -from kwork_api import KworkAuthError, KworkApiError - -try: - catalog = await client.catalog.get_list() -except KworkAuthError as e: - print(f"Auth failed: {e}") -except KworkApiError as e: - print(f"API error [{e.status_code}]: {e.message}") -``` - ---- - -*Documentation auto-generated from source code.* diff --git a/src/kwork_api/client.py b/src/kwork_api/client.py index 37496e0..a4bfa88 100644 --- a/src/kwork_api/client.py +++ b/src/kwork_api/client.py @@ -44,17 +44,44 @@ logger = logging.getLogger(__name__) class KworkClient: """ - Kwork.ru API client. + Асинхронный клиент для Kwork.ru API. - Usage: - # Login with credentials - client = await KworkClient.login("username", "password") + Предоставляет доступ ко всем основным эндпоинтам Kwork API: + - Каталог кворков и поиск + - Биржа проектов (фриланс заказы) + - Пользовательские данные и отзывы + - Уведомления и сообщения + - Справочные данные (города, страны, категории) + + Аутентификация: + Клиент использует двухэтапную аутентификацию Kwork: + 1. POST /signIn — получение session cookies + 2. POST /getWebAuthToken — получение web_auth_token + + Примеры использования: + # Вход по логину/паролю + async with await KworkClient.login("username", "password") as client: + catalog = await client.catalog.get_list(page=1) - # Or restore from token - client = KworkClient(token="your_web_auth_token") + # Восстановление сессии по токену + client = KworkClient(token="saved_web_auth_token") + user_info = await client.user.get_info() - # Make requests - catalog = await client.catalog.get_list(page=1) + # Работа с проектами + projects = await client.projects.get_list(page=1) + my_orders = await client.projects.get_payer_orders() + + Attributes: + catalog: Доступ к каталогу кворков + projects: Доступ к бирже проектов + user: Пользовательские эндпоинты + reference: Справочные данные + notifications: Уведомления и сообщения + other: Прочие эндпоинты + + Note: + Клиент поддерживает context manager для автоматического закрытия соединения. + Рекомендуется использовать `async with` для корректного освобождения ресурсов. """ BASE_URL = "https://api.kwork.ru" @@ -69,13 +96,32 @@ class KworkClient: base_url: Optional[str] = None, ): """ - Initialize client. + Инициализация клиента. + + Создаёт неаутентифицированный клиент или восстанавливает сессию + по ранее полученному токену. Args: - token: Web auth token (from getWebAuthToken) - cookies: Session cookies (optional, will be set from token) - timeout: Request timeout in seconds - base_url: Custom base URL (for testing) + token: Web auth token, полученный через `getWebAuthToken` или `login()`. + Если указан, автоматически добавляется в cookies. + cookies: Session cookies из предыдущей аутентификации. + Обычно не требуется — устанавливаются автоматически из token. + timeout: Таймаут HTTP запросов в секундах. По умолчанию 30 секунд. + base_url: Кастомный базовый URL. Используется только для тестирования. + + Example: + # Новый клиент без аутентификации + client = KworkClient() + + # Восстановление сессии + client = KworkClient(token="eyJ0eXAiOiJKV1QiLCJhbGc...") + + # Клиент с кастомным таймаутом + client = KworkClient(timeout=60.0) + + Note: + Для полноценной работы API требуется аутентификация. + Используйте `login()` или передайте сохранённый token. """ self.base_url = base_url or self.BASE_URL self.timeout = timeout @@ -93,18 +139,46 @@ class KworkClient: timeout: float = 30.0, ) -> "KworkClient": """ - Login with username and password. + Аутентификация по логину и паролю. + + Выполняет двухэтапный процесс аутентификации Kwork: + 1. POST /signIn — проверка учётных данных, получение session cookies + 2. POST /getWebAuthToken — обмен cookies на web_auth_token + + Полученный токен и cookies сохраняются в клиенте для последующих запросов. Args: - username: Kwork username or email - password: Kwork password - timeout: Request timeout - + username: Логин или email аккаунта Kwork. + password: Пароль аккаунта Kwork. + timeout: Таймаут запросов в секундах. Применяется к каждому этапу. + Returns: - Authenticated KworkClient instance - + Полностью аутентифицированный экземпляр KworkClient, + готовый к работе с API. + Raises: - KworkAuthError: If login fails + KworkAuthError: Если логин/пароль неверны или токен не получен. + KworkNetworkError: Если произошла ошибка сети. + + Example: + # Базовое использование + client = await KworkClient.login("myuser", "mypassword") + + # С кастомным таймаутом + client = await KworkClient.login("user", "pass", timeout=60.0) + + # Сохранение токена для повторного использования + token = client._token + # Позже: client = KworkClient(token=token) + + Security: + Пароль не сохраняется в клиенте. Только token и cookies. + Рекомендуется сохранять token для повторного использования + вместо хранения пароля. + + Note: + Токен имеет ограниченное время жизни. При получении 401 ошибки + необходимо выполнить повторный login(). """ client = cls(timeout=timeout) @@ -261,7 +335,24 @@ class KworkClient: # ========== Catalog Endpoints ========== class CatalogAPI: - """Catalog/Kworks API endpoints.""" + """ + API каталога кворков. + + Предоставляет доступ к каталогу услуг Kwork: + - Поиск и фильтрация кворков + - Получение детальной информации + - Категории и сортировка + + Example: + # Получить первую страницу каталога + catalog = await client.catalog.get_list(page=1) + + # Фильтрация по категории + catalog = await client.catalog.get_list(category_id=5) + + # Детали конкретного кворка + details = await client.catalog.get_details(kwork_id=12345) + """ def __init__(self, client: "KworkClient"): self.client = client @@ -273,15 +364,43 @@ class KworkClient: sort: str = "recommend", ) -> CatalogResponse: """ - Get kworks catalog. + Получить список кворков из каталога. + + Основной эндпоинт для поиска и просмотра кворков. + Возвращает пагинированный список с возможностью фильтрации. Args: - page: Page number - category_id: Category filter - sort: Sort option (recommend, price_asc, price_desc, etc.) - + page: Номер страницы для пагинации (начиная с 1). + category_id: ID категории для фильтрации. + Если None — все категории. + sort: Опция сортировки. Варианты: + - "recommend" — по рекомендации (по умолчанию) + - "price_asc" — по возрастанию цены + - "price_desc" — по убыванию цены + - "rating" — по рейтингу + - "reviews" — по количеству отзывов + - "newest" — по дате создания + Returns: - CatalogResponse with kworks and pagination + CatalogResponse содержащий: + - kworks: список кворков на странице + - pagination: информация о пагинации + - filters: доступные фильтры + - sort_options: доступные опции сортировки + + Example: + # Первая страница, сортировка по цене + response = await client.catalog.get_list( + page=1, + sort="price_asc" + ) + + for kwork in response.kworks: + print(f"{kwork.title}: {kwork.price} RUB") + + # Пагинация + if response.pagination and response.pagination.has_next: + next_page = await client.catalog.get_list(page=2) """ data = await self.client._request( "POST", @@ -296,13 +415,29 @@ class KworkClient: async def get_details(self, kwork_id: int) -> KworkDetails: """ - Get kwork details. + Получить полную информацию о кворке. + + Возвращает расширенную информацию о кворке включая: + - Полное описание и требования + - Сроки выполнения и количество правок + - Дополнительные опции (features) + - FAQ от продавца Args: - kwork_id: Kwork ID - + kwork_id: Уникальный идентификатор кворка. + Returns: - KworkDetails with full information + KworkDetails с полной информацией о кворке. + + Raises: + KworkNotFoundError: Если кворк с таким ID не найден. + + Example: + details = await client.catalog.get_details(12345) + print(f"Название: {details.title}") + print(f"Цена: {details.price} {details.currency}") + print(f"Срок: {details.delivery_time} дней") + print(f"Правки: {details.revisions}") """ data = await self.client._request( "POST", @@ -313,13 +448,25 @@ class KworkClient: async def get_details_extra(self, kwork_id: int) -> dict[str, Any]: """ - Get additional kwork details. + Получить дополнительные детали кворка. + + Возвращает расширенную информацию, которая не включена + в основной ответ get_details(). Может содержать: + - Дополнительные изображения + - Видео обзоры + - Детали пакетов услуг + - Статистику продаж Args: - kwork_id: Kwork ID - + kwork_id: Уникальный идентификатор кворка. + Returns: - Extra details dict + Словарь с дополнительными данными. Структура зависит + от конкретного кворка и не гарантируется стабильной. + + Note: + Этот эндпоинт возвращает "сырые" данные без валидации. + Структура ответа может измениться без предупреждения. """ return await self.client._request( "POST", @@ -330,7 +477,24 @@ class KworkClient: # ========== Projects Endpoints ========== class ProjectsAPI: - """Projects (freelance orders) API endpoints.""" + """ + API биржи проектов (фриланс заказы). + + Предоставляет доступ к заказам на фриланс: + - Просмотр открытых проектов + - Заказы где вы заказчик (payer) + - Заказы где вы исполнитель (worker) + + Example: + # Новые проекты + projects = await client.projects.get_list(page=1) + + # Мои заказы как заказчика + my_orders = await client.projects.get_payer_orders() + + # Мои заказы как исполнителя + my_work = await client.projects.get_worker_orders() + """ def __init__(self, client: "KworkClient"): self.client = client @@ -341,14 +505,33 @@ class KworkClient: category_id: Optional[int] = None, ) -> ProjectsResponse: """ - Get projects list. + Получить список проектов с биржи. + + Основной эндпоинт для просмотра доступных заказов. + Возвращает пагинированный список проектов. Args: - page: Page number - category_id: Category filter - + page: Номер страницы (начиная с 1). + category_id: ID категории для фильтрации. + Если None — все категории. + Returns: - ProjectsResponse with projects and pagination + ProjectsResponse содержащий: + - projects: список проектов на странице + - pagination: информация о пагинации + + Example: + # Все новые проекты + response = await client.projects.get_list(page=1) + + for project in response.projects: + print(f"{project.title}: {project.budget} {project.budget_type}") + + # Только категория "Разработка" + dev_projects = await client.projects.get_list( + page=1, + category_id=5 + ) """ data = await self.client._request( "POST", @@ -362,20 +545,36 @@ class KworkClient: async def get_payer_orders(self) -> 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}") """ data = await self.client._request("POST", "/payerOrders") return [Project.model_validate(p) for p in data.get("orders", [])] async def get_worker_orders(self) -> 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)}") """ data = await self.client._request("POST", "/workerOrders") return [Project.model_validate(p) for p in data.get("orders", [])]