diff --git a/.gitignore b/.gitignore index 45ddf0a..c70e9ab 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ site/ +api_reference.md diff --git a/api_reference.md b/api_reference.md deleted file mode 100644 index 7f21263..0000000 --- a/api_reference.md +++ /dev/null @@ -1,2561 +0,0 @@ -# Table of Contents - -* [kwork\_api](#kwork_api) - * [KworkClient](#kwork_api.KworkClient) - * [KworkError](#kwork_api.KworkError) - * [KworkAuthError](#kwork_api.KworkAuthError) - * [KworkApiError](#kwork_api.KworkApiError) - * [\_\_version\_\_](#kwork_api.__version__) - * [\_\_all\_\_](#kwork_api.__all__) -* [kwork\_api.client](#kwork_api.client) - * [logging](#kwork_api.client.logging) - * [Any](#kwork_api.client.Any) - * [Optional](#kwork_api.client.Optional) - * [httpx](#kwork_api.client.httpx) - * [HttpUrl](#kwork_api.client.HttpUrl) - * [KworkApiError](#kwork_api.client.KworkApiError) - * [KworkAuthError](#kwork_api.client.KworkAuthError) - * [KworkError](#kwork_api.client.KworkError) - * [KworkNetworkError](#kwork_api.client.KworkNetworkError) - * [KworkNotFoundError](#kwork_api.client.KworkNotFoundError) - * [KworkRateLimitError](#kwork_api.client.KworkRateLimitError) - * [KworkValidationError](#kwork_api.client.KworkValidationError) - * [APIErrorResponse](#kwork_api.client.APIErrorResponse) - * [AuthResponse](#kwork_api.client.AuthResponse) - * [Badge](#kwork_api.client.Badge) - * [CatalogResponse](#kwork_api.client.CatalogResponse) - * [City](#kwork_api.client.City) - * [Country](#kwork_api.client.Country) - * [DataResponse](#kwork_api.client.DataResponse) - * [Dialog](#kwork_api.client.Dialog) - * [Feature](#kwork_api.client.Feature) - * [Kwork](#kwork_api.client.Kwork) - * [KworkDetails](#kwork_api.client.KworkDetails) - * [NotificationsResponse](#kwork_api.client.NotificationsResponse) - * [Project](#kwork_api.client.Project) - * [ProjectsResponse](#kwork_api.client.ProjectsResponse) - * [Review](#kwork_api.client.Review) - * [ReviewsResponse](#kwork_api.client.ReviewsResponse) - * [TimeZone](#kwork_api.client.TimeZone) - * [logger](#kwork_api.client.logger) - * [KworkClient](#kwork_api.client.KworkClient) - * [BASE\_URL](#kwork_api.client.KworkClient.BASE_URL) - * [LOGIN\_URL](#kwork_api.client.KworkClient.LOGIN_URL) - * [TOKEN\_URL](#kwork_api.client.KworkClient.TOKEN_URL) - * [\_\_init\_\_](#kwork_api.client.KworkClient.__init__) - * [login](#kwork_api.client.KworkClient.login) - * [close](#kwork_api.client.KworkClient.close) - * [\_\_aenter\_\_](#kwork_api.client.KworkClient.__aenter__) - * [\_\_aexit\_\_](#kwork_api.client.KworkClient.__aexit__) - * [CatalogAPI](#kwork_api.client.KworkClient.CatalogAPI) - * [ProjectsAPI](#kwork_api.client.KworkClient.ProjectsAPI) - * [UserAPI](#kwork_api.client.KworkClient.UserAPI) - * [ReferenceAPI](#kwork_api.client.KworkClient.ReferenceAPI) - * [NotificationsAPI](#kwork_api.client.KworkClient.NotificationsAPI) - * [OtherAPI](#kwork_api.client.KworkClient.OtherAPI) - * [catalog](#kwork_api.client.KworkClient.catalog) - * [projects](#kwork_api.client.KworkClient.projects) - * [user](#kwork_api.client.KworkClient.user) - * [reference](#kwork_api.client.KworkClient.reference) - * [notifications](#kwork_api.client.KworkClient.notifications) - * [other](#kwork_api.client.KworkClient.other) -* [kwork\_api.models](#kwork_api.models) - * [datetime](#kwork_api.models.datetime) - * [Any](#kwork_api.models.Any) - * [Optional](#kwork_api.models.Optional) - * [BaseModel](#kwork_api.models.BaseModel) - * [Field](#kwork_api.models.Field) - * [KworkUser](#kwork_api.models.KworkUser) - * [id](#kwork_api.models.KworkUser.id) - * [username](#kwork_api.models.KworkUser.username) - * [avatar\_url](#kwork_api.models.KworkUser.avatar_url) - * [is\_online](#kwork_api.models.KworkUser.is_online) - * [rating](#kwork_api.models.KworkUser.rating) - * [KworkCategory](#kwork_api.models.KworkCategory) - * [id](#kwork_api.models.KworkCategory.id) - * [name](#kwork_api.models.KworkCategory.name) - * [slug](#kwork_api.models.KworkCategory.slug) - * [parent\_id](#kwork_api.models.KworkCategory.parent_id) - * [Kwork](#kwork_api.models.Kwork) - * [id](#kwork_api.models.Kwork.id) - * [title](#kwork_api.models.Kwork.title) - * [description](#kwork_api.models.Kwork.description) - * [price](#kwork_api.models.Kwork.price) - * [currency](#kwork_api.models.Kwork.currency) - * [category\_id](#kwork_api.models.Kwork.category_id) - * [seller](#kwork_api.models.Kwork.seller) - * [images](#kwork_api.models.Kwork.images) - * [rating](#kwork_api.models.Kwork.rating) - * [reviews\_count](#kwork_api.models.Kwork.reviews_count) - * [created\_at](#kwork_api.models.Kwork.created_at) - * [updated\_at](#kwork_api.models.Kwork.updated_at) - * [KworkDetails](#kwork_api.models.KworkDetails) - * [full\_description](#kwork_api.models.KworkDetails.full_description) - * [requirements](#kwork_api.models.KworkDetails.requirements) - * [delivery\_time](#kwork_api.models.KworkDetails.delivery_time) - * [revisions](#kwork_api.models.KworkDetails.revisions) - * [features](#kwork_api.models.KworkDetails.features) - * [faq](#kwork_api.models.KworkDetails.faq) - * [PaginationInfo](#kwork_api.models.PaginationInfo) - * [current\_page](#kwork_api.models.PaginationInfo.current_page) - * [total\_pages](#kwork_api.models.PaginationInfo.total_pages) - * [total\_items](#kwork_api.models.PaginationInfo.total_items) - * [items\_per\_page](#kwork_api.models.PaginationInfo.items_per_page) - * [has\_next](#kwork_api.models.PaginationInfo.has_next) - * [has\_prev](#kwork_api.models.PaginationInfo.has_prev) - * [CatalogResponse](#kwork_api.models.CatalogResponse) - * [kworks](#kwork_api.models.CatalogResponse.kworks) - * [pagination](#kwork_api.models.CatalogResponse.pagination) - * [filters](#kwork_api.models.CatalogResponse.filters) - * [sort\_options](#kwork_api.models.CatalogResponse.sort_options) - * [Project](#kwork_api.models.Project) - * [id](#kwork_api.models.Project.id) - * [title](#kwork_api.models.Project.title) - * [description](#kwork_api.models.Project.description) - * [budget](#kwork_api.models.Project.budget) - * [budget\_type](#kwork_api.models.Project.budget_type) - * [category\_id](#kwork_api.models.Project.category_id) - * [customer](#kwork_api.models.Project.customer) - * [status](#kwork_api.models.Project.status) - * [created\_at](#kwork_api.models.Project.created_at) - * [updated\_at](#kwork_api.models.Project.updated_at) - * [bids\_count](#kwork_api.models.Project.bids_count) - * [skills](#kwork_api.models.Project.skills) - * [ProjectsResponse](#kwork_api.models.ProjectsResponse) - * [projects](#kwork_api.models.ProjectsResponse.projects) - * [pagination](#kwork_api.models.ProjectsResponse.pagination) - * [Review](#kwork_api.models.Review) - * [id](#kwork_api.models.Review.id) - * [rating](#kwork_api.models.Review.rating) - * [comment](#kwork_api.models.Review.comment) - * [author](#kwork_api.models.Review.author) - * [kwork\_id](#kwork_api.models.Review.kwork_id) - * [created\_at](#kwork_api.models.Review.created_at) - * [ReviewsResponse](#kwork_api.models.ReviewsResponse) - * [reviews](#kwork_api.models.ReviewsResponse.reviews) - * [pagination](#kwork_api.models.ReviewsResponse.pagination) - * [average\_rating](#kwork_api.models.ReviewsResponse.average_rating) - * [Notification](#kwork_api.models.Notification) - * [id](#kwork_api.models.Notification.id) - * [type](#kwork_api.models.Notification.type) - * [title](#kwork_api.models.Notification.title) - * [message](#kwork_api.models.Notification.message) - * [is\_read](#kwork_api.models.Notification.is_read) - * [created\_at](#kwork_api.models.Notification.created_at) - * [link](#kwork_api.models.Notification.link) - * [NotificationsResponse](#kwork_api.models.NotificationsResponse) - * [notifications](#kwork_api.models.NotificationsResponse.notifications) - * [unread\_count](#kwork_api.models.NotificationsResponse.unread_count) - * [Dialog](#kwork_api.models.Dialog) - * [id](#kwork_api.models.Dialog.id) - * [participant](#kwork_api.models.Dialog.participant) - * [last\_message](#kwork_api.models.Dialog.last_message) - * [unread\_count](#kwork_api.models.Dialog.unread_count) - * [updated\_at](#kwork_api.models.Dialog.updated_at) - * [AuthResponse](#kwork_api.models.AuthResponse) - * [success](#kwork_api.models.AuthResponse.success) - * [user\_id](#kwork_api.models.AuthResponse.user_id) - * [username](#kwork_api.models.AuthResponse.username) - * [web\_auth\_token](#kwork_api.models.AuthResponse.web_auth_token) - * [message](#kwork_api.models.AuthResponse.message) - * [ErrorDetail](#kwork_api.models.ErrorDetail) - * [code](#kwork_api.models.ErrorDetail.code) - * [message](#kwork_api.models.ErrorDetail.message) - * [field](#kwork_api.models.ErrorDetail.field) - * [APIErrorResponse](#kwork_api.models.APIErrorResponse) - * [success](#kwork_api.models.APIErrorResponse.success) - * [errors](#kwork_api.models.APIErrorResponse.errors) - * [message](#kwork_api.models.APIErrorResponse.message) - * [City](#kwork_api.models.City) - * [id](#kwork_api.models.City.id) - * [name](#kwork_api.models.City.name) - * [country\_id](#kwork_api.models.City.country_id) - * [Country](#kwork_api.models.Country) - * [id](#kwork_api.models.Country.id) - * [name](#kwork_api.models.Country.name) - * [code](#kwork_api.models.Country.code) - * [cities](#kwork_api.models.Country.cities) - * [TimeZone](#kwork_api.models.TimeZone) - * [id](#kwork_api.models.TimeZone.id) - * [name](#kwork_api.models.TimeZone.name) - * [offset](#kwork_api.models.TimeZone.offset) - * [Feature](#kwork_api.models.Feature) - * [id](#kwork_api.models.Feature.id) - * [name](#kwork_api.models.Feature.name) - * [description](#kwork_api.models.Feature.description) - * [price](#kwork_api.models.Feature.price) - * [type](#kwork_api.models.Feature.type) - * [Badge](#kwork_api.models.Badge) - * [id](#kwork_api.models.Badge.id) - * [name](#kwork_api.models.Badge.name) - * [description](#kwork_api.models.Badge.description) - * [icon\_url](#kwork_api.models.Badge.icon_url) - * [DataResponse](#kwork_api.models.DataResponse) - * [success](#kwork_api.models.DataResponse.success) - * [data](#kwork_api.models.DataResponse.data) - * [message](#kwork_api.models.DataResponse.message) -* [kwork\_api.errors](#kwork_api.errors) - * [Any](#kwork_api.errors.Any) - * [Optional](#kwork_api.errors.Optional) - * [KworkError](#kwork_api.errors.KworkError) - * [\_\_init\_\_](#kwork_api.errors.KworkError.__init__) - * [\_\_str\_\_](#kwork_api.errors.KworkError.__str__) - * [KworkAuthError](#kwork_api.errors.KworkAuthError) - * [\_\_init\_\_](#kwork_api.errors.KworkAuthError.__init__) - * [\_\_str\_\_](#kwork_api.errors.KworkAuthError.__str__) - * [KworkApiError](#kwork_api.errors.KworkApiError) - * [\_\_init\_\_](#kwork_api.errors.KworkApiError.__init__) - * [\_\_str\_\_](#kwork_api.errors.KworkApiError.__str__) - * [KworkNotFoundError](#kwork_api.errors.KworkNotFoundError) - * [\_\_init\_\_](#kwork_api.errors.KworkNotFoundError.__init__) - * [KworkRateLimitError](#kwork_api.errors.KworkRateLimitError) - * [\_\_init\_\_](#kwork_api.errors.KworkRateLimitError.__init__) - * [KworkValidationError](#kwork_api.errors.KworkValidationError) - * [\_\_init\_\_](#kwork_api.errors.KworkValidationError.__init__) - * [\_\_str\_\_](#kwork_api.errors.KworkValidationError.__str__) - * [KworkNetworkError](#kwork_api.errors.KworkNetworkError) - * [\_\_init\_\_](#kwork_api.errors.KworkNetworkError.__init__) - * [\_\_str\_\_](#kwork_api.errors.KworkNetworkError.__str__) - - - -# Module kwork\_api - -Kwork.ru API Client - -Unofficial Python client for Kwork.ru API. - -**Example**: - - 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") - - # Get catalog - catalog = await client.catalog.get_list(page=1) - - - -## KworkClient - - - -## KworkError - - - -## KworkAuthError - - - -## KworkApiError - - - -#### \_\_version\_\_ - - - -#### \_\_all\_\_ - - - -# Module kwork\_api.client - -Kwork API Client. - -Main client class with authentication and all API endpoints. - - - -## logging - - - -## Any - - - -## Optional - - - -## httpx - - - -## HttpUrl - - - -## KworkApiError - - - -## KworkAuthError - - - -## KworkError - - - -## KworkNetworkError - - - -## KworkNotFoundError - - - -## KworkRateLimitError - - - -## KworkValidationError - - - -## APIErrorResponse - - - -## AuthResponse - - - -## Badge - - - -## CatalogResponse - - - -## City - - - -## Country - - - -## DataResponse - - - -## Dialog - - - -## Feature - - - -## Kwork - - - -## KworkDetails - - - -## NotificationsResponse - - - -## Project - - - -## ProjectsResponse - - - -## Review - - - -## ReviewsResponse - - - -## TimeZone - - - -#### logger - - - -## KworkClient - -```python -class KworkClient() -``` - -Асинхронный клиент для Kwork.ru API. - -Предоставляет доступ ко всем основным эндпоинтам 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) - -# Восстановление сессии по токену -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` для корректного освобождения ресурсов. - - - -#### BASE\_URL - - - -#### LOGIN\_URL - - - -#### TOKEN\_URL - - - -#### KworkClient.\_\_init\_\_ - -```python -def __init__(token: Optional[str] = None, - cookies: Optional[dict[str, str]] = None, - timeout: float = 30.0, - base_url: Optional[str] = None) -``` - -Инициализация клиента. - -Создаёт неаутентифицированный клиент или восстанавливает сессию -по ранее полученному токену. - -**Arguments**: - -- `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. - - - -#### KworkClient.login - -```python -@classmethod -async def login(cls, - username: str, - password: str, - timeout: float = 30.0) -> "KworkClient" -``` - -Аутентификация по логину и паролю. - -Выполняет двухэтапный процесс аутентификации Kwork: -1. POST /signIn — проверка учётных данных, получение session cookies -2. POST /getWebAuthToken — обмен cookies на web_auth_token - -Полученный токен и cookies сохраняются в клиенте для последующих запросов. - -**Arguments**: - -- `username` - Логин или email аккаунта Kwork. -- `password` - Пароль аккаунта Kwork. -- `timeout` - Таймаут запросов в секундах. Применяется к каждому этапу. - - -**Returns**: - - Полностью аутентифицированный экземпляр KworkClient, - готовый к работе с API. - - -**Raises**: - -- `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(). - - - -#### KworkClient.close - -```python -async def close() -> None -``` - -Close HTTP client. - - - -#### KworkClient.\_\_aenter\_\_ - -```python -async def __aenter__() -> "KworkClient" -``` - - - -#### KworkClient.\_\_aexit\_\_ - -```python -async def __aexit__(*args: Any) -> None -``` - - - -## CatalogAPI - -```python -class CatalogAPI() -``` - -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) - - - -#### CatalogAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### CatalogAPI.get\_list - -```python -async def get_list(page: int = 1, - category_id: Optional[int] = None, - sort: str = "recommend") -> CatalogResponse -``` - -Получить список кворков из каталога. - -Основной эндпоинт для поиска и просмотра кворков. -Возвращает пагинированный список с возможностью фильтрации. - -**Arguments**: - -- `page` - Номер страницы для пагинации (начиная с 1). -- `category_id` - ID категории для фильтрации. - Если None — все категории. -- `sort` - Опция сортировки. Варианты: - - "recommend" — по рекомендации (по умолчанию) - - "price_asc" — по возрастанию цены - - "price_desc" — по убыванию цены - - "rating" — по рейтингу - - "reviews" — по количеству отзывов - - "newest" — по дате создания - - -**Returns**: - - 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) - - - -#### CatalogAPI.get\_details - -```python -async def get_details(kwork_id: int) -> KworkDetails -``` - -Получить полную информацию о кворке. - -Возвращает расширенную информацию о кворке включая: -- Полное описание и требования -- Сроки выполнения и количество правок -- Дополнительные опции (features) -- FAQ от продавца - -**Arguments**: - -- `kwork_id` - Уникальный идентификатор кворка. - - -**Returns**: - - 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}") - - - -#### CatalogAPI.get\_details\_extra - -```python -async def get_details_extra(kwork_id: int) -> dict[str, Any] -``` - -Получить дополнительные детали кворка. - -Возвращает расширенную информацию, которая не включена -в основной ответ get_details(). Может содержать: -- Дополнительные изображения -- Видео обзоры -- Детали пакетов услуг -- Статистику продаж - -**Arguments**: - -- `kwork_id` - Уникальный идентификатор кворка. - - -**Returns**: - - Словарь с дополнительными данными. Структура зависит - от конкретного кворка и не гарантируется стабильной. - - -**Notes**: - - Этот эндпоинт возвращает "сырые" данные без валидации. - Структура ответа может измениться без предупреждения. - - - -## ProjectsAPI - -```python -class ProjectsAPI() -``` - -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() - - - -#### ProjectsAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### ProjectsAPI.get\_list - -```python -async def get_list(page: int = 1, - category_id: Optional[int] = None) -> ProjectsResponse -``` - -Получить список проектов с биржи. - -Основной эндпоинт для просмотра доступных заказов. -Возвращает пагинированный список проектов. - -**Arguments**: - -- `page` - Номер страницы (начиная с 1). -- `category_id` - ID категории для фильтрации. - Если None — все категории. - - -**Returns**: - - 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 - ) - - - -#### ProjectsAPI.get\_payer\_orders - -```python -async def get_payer_orders() -> list[Project] -``` - -Получить заказы где вы являетесь заказчиком. - -Возвращает все проекты, созданные текущим пользователем, -независимо от их статуса (открыт, в работе, завершён). - -**Returns**: - - Список проектов где текущий пользователь — заказчик. - - -**Example**: - - orders = await client.projects.get_payer_orders() - for order in orders: - print(f"Заказ #{order.id}: {order.status}") - - - -#### ProjectsAPI.get\_worker\_orders - -```python -async def get_worker_orders() -> list[Project] -``` - -Получить заказы где вы являетесь исполнителем. - -Возвращает все проекты, где текущий пользователь -назначен исполнителем. - -**Returns**: - - Список проектов где текущий пользователь — исполнитель. - - -**Example**: - - work = await client.projects.get_worker_orders() - active = [p for p in work if p.status == "in_progress"] - print(f"Активных заказов: {len(active)}") - - - -## UserAPI - -```python -class UserAPI() -``` - -Пользовательское API. - -Предоставляет доступ к данным текущего пользователя: -- Профиль и информация об аккаунте -- Отзывы (полученные и оставленные) -- Избранные кворки - -**Example**: - - # Информация о пользователе - info = await client.user.get_info() - - # Мои отзывы - reviews = await client.user.get_reviews() - - # Избранные кворки - favorites = await client.user.get_favorite_kworks() - - - -#### UserAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### UserAPI.get\_info - -```python -async def get_info() -> dict[str, Any] -``` - -Получить информацию о текущем пользователе. - -Возвращает основные данные аккаунта: -- ID, username, email -- Баланс, рейтинг -- Статус верификации -- Настройки профиля - -**Returns**: - - Словарь с информацией о пользователе. - Структура зависит от ответа API. - - -**Example**: - - info = await client.user.get_info() -- `print(f"User` - {info.get('username')}") -- `print(f"Balance` - {info.get('balance')} RUB") - - - -#### UserAPI.get\_reviews - -```python -async def get_reviews(user_id: Optional[int] = None, - page: int = 1) -> ReviewsResponse -``` - -Получить отзывы пользователя. - -Если user_id не указан — возвращает отзывы текущего пользователя. -Если указан — отзывы другого пользователя по ID. - -**Arguments**: - -- `user_id` - ID пользователя. Если None — текущий пользователь. -- `page` - Номер страницы для пагинации (начиная с 1). - - -**Returns**: - - 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) - - - -#### UserAPI.get\_favorite\_kworks - -```python -async def get_favorite_kworks() -> list[Kwork] -``` - -Получить список избранных кворков. - -Возвращает все кворки, добавленные пользователем в избранное. - -**Returns**: - - Список избранных кворков. - - -**Example**: - - favorites = await client.user.get_favorite_kworks() - for kwork in favorites: -- `print(f"{kwork.title}` - {kwork.price} RUB") - - - -## ReferenceAPI - -```python -class ReferenceAPI() -``` - -Справочное API. - -Предоставляет доступ к справочным данным Kwork: -- Города, страны, часовые пояса -- Доступные функции и дополнения -- Значки пользователей - -Эти данные редко меняются и могут быть закэшированы. - -**Example**: - - # Все страны - countries = await client.reference.get_countries() - - # Все города - cities = await client.reference.get_cities() - - # Доступные фичи - features = await client.reference.get_features() - - - -#### ReferenceAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### ReferenceAPI.get\_cities - -```python -async def get_cities() -> list[City] -``` - -Получить список всех городов. - -**Returns**: - - Список всех городов из справочника Kwork. - - -**Example**: - - cities = await client.reference.get_cities() - moscow = next(c for c in cities if c.name == "Москва") - - - -#### ReferenceAPI.get\_countries - -```python -async def get_countries() -> list[Country] -``` - -Получить список всех стран. - -**Returns**: - - Список всех стран с кодами и городами. - - -**Example**: - - countries = await client.reference.get_countries() - russia = next(c for c in countries if c.code == "RU") - - - -#### ReferenceAPI.get\_timezones - -```python -async def get_timezones() -> list[TimeZone] -``` - -Получить список всех часовых поясов. - -**Returns**: - - Список часовых поясов с названиями и смещениями. - - -**Example**: - - timezones = await client.reference.get_timezones() - msks = next(tz for tz in timezones if "Moscow" in tz.name) - - - -#### ReferenceAPI.get\_features - -```python -async def get_features() -> list[Feature] -``` - -Получить доступные дополнительные функции (features). - -Features — это платные дополнения к кворкам: -- Увеличенные сроки -- Дополнительные правки -- Приоритетная поддержка -- и т.д. - -**Returns**: - - Список доступных features с названиями и ценами. - - -**Example**: - - features = await client.reference.get_features() - for f in features: -- `print(f"{f.name}` - {f.price} RUB") - - - -#### ReferenceAPI.get\_public\_features - -```python -async def get_public_features() -> list[Feature] -``` - -Получить публичные функции. - -Аналогично get_features(), но возвращает только -публично доступные опции. - -**Returns**: - - Список публичных features. - - - -#### ReferenceAPI.get\_badges\_info - -```python -async def get_badges_info() -> list[Badge] -``` - -Получить информацию о значках пользователей. - -Значки (badges) отображают достижения и статусы: -- "Профессионал" -- "Быстрый ответ" -- "Надёжный продавец" -- и т.д. - -**Returns**: - - Список значков с описаниями и иконками. - - -**Example**: - - badges = await client.reference.get_badges_info() - for badge in badges: -- `print(f"{badge.name}` - {badge.description}") - - - -## NotificationsAPI - -```python -class NotificationsAPI() -``` - -API уведомлений и сообщений. - -Предоставляет доступ к системе уведомлений Kwork: -- Список уведомлений -- Получение новых уведомлений -- Диалоги с пользователями -- Заблокированные диалоги - -**Example**: - - # Все уведомления - notifications = await client.notifications.get_list() - - # Новые уведомления - new = await client.notifications.fetch() - - # Диалоги - dialogs = await client.notifications.get_dialogs() - - - -#### NotificationsAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### NotificationsAPI.get\_list - -```python -async def get_list() -> NotificationsResponse -``` - -Получить список всех уведомлений. - -Возвращает все уведомления пользователя с информацией -о прочтении. - -**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}") - - - -#### NotificationsAPI.fetch - -```python -async def fetch() -> NotificationsResponse -``` - -Получить новые уведомления. - -Отличается от get_list() тем, что возвращает только -уведомления, появившиеся с момента последнего запроса. -Также может обновлять счётчик непрочитанных. - -**Returns**: - - NotificationsResponse с новыми уведомлениями. - - -**Example**: - - new_notifs = await client.notifications.fetch() - if new_notifs.unread_count > 0: - print(f"У вас {new_notifs.unread_count} новых уведомлений!") - - - -#### NotificationsAPI.get\_dialogs - -```python -async def get_dialogs() -> list[Dialog] -``` - -Получить список диалогов (чатов). - -Возвращает все активные диалоги пользователя с другими -пользователями Kwork. - -**Returns**: - - Список диалогов с последней перепиской. - - -**Example**: - - dialogs = await client.notifications.get_dialogs() - for d in dialogs: - print(f"С {d.participant.username}: {d.last_message}") - - - -#### NotificationsAPI.get\_blocked\_dialogs - -```python -async def get_blocked_dialogs() -> list[Dialog] -``` - -Получить список заблокированных диалогов. - -Возвращает диалоги с пользователями, которые были -заблокированы текущим пользователем. - -**Returns**: - - Список заблокированных диалогов. - - -**Example**: - - blocked = await client.notifications.get_blocked_dialogs() -- `print(f"Заблокировано` - {len(blocked)} пользователей") - - - -## OtherAPI - -```python -class OtherAPI() -``` - -Прочее API. - -Вспомогательные эндпоинты которые не вошли в другие категории: -- Пользовательские настройки и предпочтения (wants) -- Статусы кворков и заказов -- Персональные предложения (offers) -- Настройки профиля -- Статус онлайн/оффлайн - -**Example**: - - # Пользовательские предпочтения - wants = await client.other.get_wants() - - # Статус кворков - status = await client.other.get_kworks_status() - - # Установить статус оффлайн - await client.other.go_offline() - - - -#### OtherAPI.\_\_init\_\_ - -```python -def __init__(client: "KworkClient") -``` - - - -#### OtherAPI.get\_wants - -```python -async def get_wants() -> dict[str, Any] -``` - -Получить пользовательские предпочтения (wants). - -Wants — это настройки интересов пользователя: -- Предпочитаемые категории -- Ключевые слова для мониторинга -- Фильтры для поиска - -**Returns**: - - Словарь с настройками предпочтений. - - -**Example**: - - wants = await client.other.get_wants() - print(wants) - - - -#### OtherAPI.get\_wants\_status - -```python -async def get_wants_status() -> dict[str, Any] -``` - -Получить статус предпочтений. - -**Returns**: - - Статус wants с метаданными. - - - -#### OtherAPI.get\_kworks\_status - -```python -async def get_kworks_status() -> dict[str, Any] -``` - -Получить статусы кворков пользователя. - -Возвращает информацию о статусах всех кворков -текущего пользователя (активен, на модерации, и т.д.). - -**Returns**: - - Словарь со статусами кворков. - - -**Example**: - - status = await client.other.get_kworks_status() - print(status) - - - -#### OtherAPI.get\_offers - -```python -async def get_offers() -> dict[str, Any] -``` - -Получить персональные предложения. - -**Returns**: - - Список персональных предложений от Kwork. - - - -#### OtherAPI.get\_exchange\_info - -```python -async def get_exchange_info() -> dict[str, Any] -``` - -Получить информацию об обмене валюты. - -**Returns**: - - Информация о курсах валют и обмене. - - - -#### OtherAPI.get\_channel - -```python -async def get_channel() -> dict[str, Any] -``` - -Получить информацию о канале пользователя. - -**Returns**: - - Данные канала (если есть). - - - -#### OtherAPI.get\_in\_app\_notification - -```python -async def get_in_app_notification() -> dict[str, Any] -``` - -Получить внутриприложенное уведомление. - -**Returns**: - - Данные in-app уведомления. - - - -#### OtherAPI.get\_security\_user\_data - -```python -async def get_security_user_data() -> dict[str, Any] -``` - -Получить данные безопасности пользователя. - -**Returns**: - - Информация о безопасности аккаунта. - - - -#### OtherAPI.is\_dialog\_allow - -```python -async def is_dialog_allow(user_id: int) -> bool -``` - -Проверить возможность начала диалога с пользователем. - -**Arguments**: - -- `user_id` - ID пользователя для проверки. - - -**Returns**: - - True если диалог разрешён, False иначе. - - -**Example**: - - allowed = await client.other.is_dialog_allow(12345) - if allowed: - print("Можно написать сообщение") - - - -#### OtherAPI.get\_viewed\_kworks - -```python -async def get_viewed_kworks() -> list[Kwork] -``` - -Получить просмотренные кворки. - -Возвращает список кворков, которые пользователь -просматривал ранее. - -**Returns**: - - Список просмотренных кворков. - - -**Example**: - - viewed = await client.other.get_viewed_kworks() -- `print(f"Просмотрено` - {len(viewed)} кворков") - - - -#### OtherAPI.get\_favorite\_categories - -```python -async def get_favorite_categories() -> list[int] -``` - -Получить ID избранных категорий. - -**Returns**: - - Список ID категорий, добавленных в избранное. - - -**Example**: - - cats = await client.other.get_favorite_categories() - print(f"Избранные категории: {cats}") - - - -#### OtherAPI.update\_settings - -```python -async def update_settings(settings: dict[str, Any]) -> dict[str, Any] -``` - -Обновить настройки пользователя. - -**Arguments**: - -- `settings` - Словарь с настройками для обновления. - Структура зависит от конкретных настроек. - - -**Returns**: - - Ответ API с подтверждением обновления. - - -**Example**: - - await client.other.update_settings({ -- `"email_notifications"` - True, -- `"language"` - "ru" - }) - - - -#### OtherAPI.go\_offline - -```python -async def go_offline() -> dict[str, Any] -``` - -Установить статус пользователя "оффлайн". - -Скрывает онлайн-статус от других пользователей. - -**Returns**: - - Подтверждение изменения статуса. - - -**Example**: - - await client.other.go_offline() - - - -#### OtherAPI.get\_actor - -```python -async def get_actor() -> dict[str, Any] -``` - -Получить информацию об актёре (текущем пользователе). - -**Returns**: - - Данные актёра/пользователя. - - - -#### KworkClient.catalog - -```python -@property -def catalog() -> CatalogAPI -``` - -API каталога кворков. - -**Returns**: - - CatalogAPI для работы с каталогом. - - - -#### KworkClient.projects - -```python -@property -def projects() -> ProjectsAPI -``` - -API биржи проектов. - -**Returns**: - - ProjectsAPI для работы с проектами. - - - -#### KworkClient.user - -```python -@property -def user() -> UserAPI -``` - -Пользовательское API. - -**Returns**: - - UserAPI для работы с профилем. - - - -#### KworkClient.reference - -```python -@property -def reference() -> ReferenceAPI -``` - -Справочное API. - -**Returns**: - - ReferenceAPI для справочных данных. - - - -#### KworkClient.notifications - -```python -@property -def notifications() -> NotificationsAPI -``` - -API уведомлений. - -**Returns**: - - NotificationsAPI для уведомлений и сообщений. - - - -#### KworkClient.other - -```python -@property -def other() -> OtherAPI -``` - -Прочее API. - -**Returns**: - - OtherAPI для вспомогательных эндпоинтов. - - - -# Module kwork\_api.models - -Pydantic models for Kwork API responses. - -All models follow the structure found in the HAR dump analysis. - - - -## datetime - - - -## Any - - - -## Optional - - - -## BaseModel - - - -## Field - - - -## KworkUser - -```python -class KworkUser(BaseModel) -``` - -User information. - - - -#### id - - - -#### username - - - -#### avatar\_url - - - -#### is\_online - - - -#### rating - - - -## KworkCategory - -```python -class KworkCategory(BaseModel) -``` - -Category information. - - - -#### id - - - -#### name - - - -#### slug - - - -#### parent\_id - - - -## Kwork - -```python -class Kwork(BaseModel) -``` - -Kwork (service) information. - - - -#### id - - - -#### title - - - -#### description - - - -#### price - - - -#### currency - - - -#### category\_id - - - -#### seller - - - -#### images - - - -#### rating - - - -#### reviews\_count - - - -#### created\_at - - - -#### updated\_at - - - -## KworkDetails - -```python -class KworkDetails(Kwork) -``` - -Extended kwork details. - - - -#### full\_description - - - -#### requirements - - - -#### delivery\_time - -in days - - - -#### revisions - - - -#### features - - - -#### faq - - - -## PaginationInfo - -```python -class PaginationInfo(BaseModel) -``` - -Pagination metadata. - - - -#### current\_page - - - -#### total\_pages - - - -#### total\_items - - - -#### items\_per\_page - - - -#### has\_next - - - -#### has\_prev - - - -## CatalogResponse - -```python -class CatalogResponse(BaseModel) -``` - -Catalog response with kworks and pagination. - - - -#### kworks - - - -#### pagination - - - -#### filters - - - -#### sort\_options - - - -## Project - -```python -class Project(BaseModel) -``` - -Project (freelance order) information. - - - -#### id - - - -#### title - - - -#### description - - - -#### budget - - - -#### budget\_type - -fixed, hourly - - - -#### category\_id - - - -#### customer - - - -#### status - -open, in_progress, completed, cancelled - - - -#### created\_at - - - -#### updated\_at - - - -#### bids\_count - - - -#### skills - - - -## ProjectsResponse - -```python -class ProjectsResponse(BaseModel) -``` - -Projects list response. - - - -#### projects - - - -#### pagination - - - -## Review - -```python -class Review(BaseModel) -``` - -Review information. - - - -#### id - - - -#### rating - - - -#### comment - - - -#### author - - - -#### kwork\_id - - - -#### created\_at - - - -## ReviewsResponse - -```python -class ReviewsResponse(BaseModel) -``` - -Reviews list response. - - - -#### reviews - - - -#### pagination - - - -#### average\_rating - - - -## Notification - -```python -class Notification(BaseModel) -``` - -Notification information. - - - -#### id - - - -#### type - -message, order, system, etc. - - - -#### title - - - -#### message - - - -#### is\_read - - - -#### created\_at - - - -#### link - - - -## NotificationsResponse - -```python -class NotificationsResponse(BaseModel) -``` - -Notifications list response. - - - -#### notifications - - - -#### unread\_count - - - -## Dialog - -```python -class Dialog(BaseModel) -``` - -Dialog (chat) information. - - - -#### id - - - -#### participant - - - -#### last\_message - - - -#### unread\_count - - - -#### updated\_at - - - -## AuthResponse - -```python -class AuthResponse(BaseModel) -``` - -Authentication response. - - - -#### success - - - -#### user\_id - - - -#### username - - - -#### web\_auth\_token - - - -#### message - - - -## ErrorDetail - -```python -class ErrorDetail(BaseModel) -``` - -Error detail from API. - - - -#### code - - - -#### message - - - -#### field - - - -## APIErrorResponse - -```python -class APIErrorResponse(BaseModel) -``` - -Standard API error response. - - - -#### success - - - -#### errors - - - -#### message - - - -## City - -```python -class City(BaseModel) -``` - -City information. - - - -#### id - - - -#### name - - - -#### country\_id - - - -## Country - -```python -class Country(BaseModel) -``` - -Country information. - - - -#### id - - - -#### name - - - -#### code - - - -#### cities - - - -## TimeZone - -```python -class TimeZone(BaseModel) -``` - -Timezone information. - - - -#### id - - - -#### name - - - -#### offset - -e.g., "+03:00" - - - -## Feature - -```python -class Feature(BaseModel) -``` - -Feature/addon information. - - - -#### id - - - -#### name - - - -#### description - - - -#### price - - - -#### type - -extra, premium, etc. - - - -## Badge - -```python -class Badge(BaseModel) -``` - -User badge information. - - - -#### id - - - -#### name - - - -#### description - - - -#### icon\_url - - - -## DataResponse - -```python -class DataResponse(BaseModel) -``` - -Generic data response wrapper. - - - -#### success - - - -#### data - - - -#### message - - - -# Module kwork\_api.errors - -Kwork API exceptions. - -All exceptions provide clear error messages for debugging. - - - -## Any - - - -## Optional - - - -## KworkError - -```python -class KworkError(Exception) -``` - -Base exception for all Kwork API errors. - - - -#### KworkError.\_\_init\_\_ - -```python -def __init__(message: str, response: Optional[Any] = None) -``` - - - -#### KworkError.\_\_str\_\_ - -```python -def __str__() -> str -``` - - - -## KworkAuthError - -```python -class KworkAuthError(KworkError) -``` - -Authentication/authorization error. - - - -#### KworkAuthError.\_\_init\_\_ - -```python -def __init__(message: str = "Authentication failed", - response: Optional[Any] = None) -``` - - - -#### KworkAuthError.\_\_str\_\_ - -```python -def __str__() -> str -``` - - - -## KworkApiError - -```python -class KworkApiError(KworkError) -``` - -API request error (4xx, 5xx). - - - -#### KworkApiError.\_\_init\_\_ - -```python -def __init__(message: str, - status_code: Optional[int] = None, - response: Optional[Any] = None) -``` - - - -#### KworkApiError.\_\_str\_\_ - -```python -def __str__() -> str -``` - - - -## KworkNotFoundError - -```python -class KworkNotFoundError(KworkApiError) -``` - -Resource not found (404). - - - -#### KworkNotFoundError.\_\_init\_\_ - -```python -def __init__(resource: str, response: Optional[Any] = None) -``` - - - -## KworkRateLimitError - -```python -class KworkRateLimitError(KworkApiError) -``` - -Rate limit exceeded (429). - - - -#### KworkRateLimitError.\_\_init\_\_ - -```python -def __init__(message: str = "Rate limit exceeded", - response: Optional[Any] = None) -``` - - - -## KworkValidationError - -```python -class KworkValidationError(KworkApiError) -``` - -Validation error (400). - - - -#### KworkValidationError.\_\_init\_\_ - -```python -def __init__(message: str = "Validation failed", - fields: Optional[dict[str, list[str]]] = None, - response: Optional[Any] = None) -``` - - - -#### KworkValidationError.\_\_str\_\_ - -```python -def __str__() -> str -``` - - - -## KworkNetworkError - -```python -class KworkNetworkError(KworkError) -``` - -Network/connection error. - - - -#### KworkNetworkError.\_\_init\_\_ - -```python -def __init__(message: str = "Network error", response: Optional[Any] = None) -``` - - - -#### KworkNetworkError.\_\_str\_\_ - -```python -def __str__() -> str -``` -