much-data/kwork-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a5a1ec5970
kwork-api/docs/api_reference.md
root a5a1ec5970 docs: полная миграция на pydoc-markdown (убран MkDocs) 
- Удалён mkdocs.yml и вся сгенерированная site/ директория
- pydoc-markdown.yml теперь использует markdown renderer напрямую
- Скрипт gen_docs.py генерирует docs/api_reference.md без MkDocs
- Обновлён pre-commit hook для использования pydoc-markdown
- Убраны зависимости MkDocs из конфигурации

Теперь документация генерируется только через pydoc-markdown.
2026-03-23 04:19:09 +00:00

39 KiB
Raw Blame History

Table of Contents

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

class KworkClient()

Kwork.ru API client.

Usage: # Login with credentials client = await KworkClient.login("username", "password")

# Or restore from token
client = KworkClient(token="your_web_auth_token")

# Make requests
catalog = await client.catalog.get_list(page=1)

BASE_URL

LOGIN_URL

TOKEN_URL

KworkClient.__init__

def __init__(token: Optional[str] = None,
             cookies: Optional[dict[str, str]] = None,
             timeout: float = 30.0,
             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)

KworkClient.login

@classmethod
async def login(cls,
                username: str,
                password: str,
                timeout: float = 30.0) -> "KworkClient"

Login with username and password.

Arguments:

  • username - Kwork username or email
  • password - Kwork password
  • timeout - Request timeout

Returns:

Authenticated KworkClient instance

Raises:

  • KworkAuthError - If login fails

KworkClient.close

async def close() -> None

Close HTTP client.

KworkClient.__aenter__

async def __aenter__() -> "KworkClient"

KworkClient.__aexit__

async def __aexit__(*args: Any) -> None

CatalogAPI

class CatalogAPI()

Catalog/Kworks API endpoints.

CatalogAPI.__init__

def __init__(client: "KworkClient")

CatalogAPI.get_list

async def get_list(page: int = 1,
                   category_id: Optional[int] = None,
                   sort: str = "recommend") -> CatalogResponse

Get kworks catalog.

Arguments:

  • page - Page number
  • category_id - Category filter
  • sort - Sort option (recommend, price_asc, price_desc, etc.)

Returns:

CatalogResponse with kworks and pagination

CatalogAPI.get_details

async def get_details(kwork_id: int) -> KworkDetails

Get kwork details.

Arguments:

  • kwork_id - Kwork ID

Returns:

KworkDetails with full information

CatalogAPI.get_details_extra

async def get_details_extra(kwork_id: int) -> dict[str, Any]

Get additional kwork details.

Arguments:

  • kwork_id - Kwork ID

Returns:

Extra details dict

ProjectsAPI

class ProjectsAPI()

Projects (freelance orders) API endpoints.

ProjectsAPI.__init__

def __init__(client: "KworkClient")

ProjectsAPI.get_list

async def get_list(page: int = 1,
                   category_id: Optional[int] = None) -> ProjectsResponse

Get projects list.

Arguments:

  • page - Page number
  • category_id - Category filter

Returns:

ProjectsResponse with projects and pagination

ProjectsAPI.get_payer_orders

async def get_payer_orders() -> list[Project]

Get orders where user is customer.

Returns:

List of projects

ProjectsAPI.get_worker_orders

async def get_worker_orders() -> list[Project]

Get orders where user is performer.

Returns:

List of projects

UserAPI

class UserAPI()

User API endpoints.

UserAPI.__init__

def __init__(client: "KworkClient")

UserAPI.get_info

async def get_info() -> dict[str, Any]

Get current user info.

Returns:

User info dict

UserAPI.get_reviews

async def get_reviews(user_id: Optional[int] = None,
                      page: int = 1) -> ReviewsResponse

Get user reviews.

Arguments:

  • user_id - User ID (None for current user)
  • page - Page number

Returns:

ReviewsResponse

UserAPI.get_favorite_kworks

async def get_favorite_kworks() -> list[Kwork]

Get favorite kworks.

Returns:

List of kworks

ReferenceAPI

class ReferenceAPI()

Reference data (cities, countries, etc.) endpoints.

ReferenceAPI.__init__

def __init__(client: "KworkClient")

ReferenceAPI.get_cities

async def get_cities() -> list[City]

Get all cities.

ReferenceAPI.get_countries

async def get_countries() -> list[Country]

Get all countries.

ReferenceAPI.get_timezones

async def get_timezones() -> list[TimeZone]

Get all timezones.

ReferenceAPI.get_features

async def get_features() -> list[Feature]

Get available features.

ReferenceAPI.get_public_features

async def get_public_features() -> list[Feature]

Get public features.

ReferenceAPI.get_badges_info

async def get_badges_info() -> list[Badge]

Get badges info.

NotificationsAPI

class NotificationsAPI()

Notifications and messages endpoints.

NotificationsAPI.__init__

def __init__(client: "KworkClient")

NotificationsAPI.get_list

async def get_list() -> NotificationsResponse

Get notifications list.

NotificationsAPI.fetch

async def fetch() -> NotificationsResponse

Fetch new notifications.

NotificationsAPI.get_dialogs

async def get_dialogs() -> list[Dialog]

Get dialogs list.

NotificationsAPI.get_blocked_dialogs

async def get_blocked_dialogs() -> list[Dialog]

Get blocked dialogs.

OtherAPI

class OtherAPI()

Other API endpoints.

OtherAPI.__init__

def __init__(client: "KworkClient")

OtherAPI.get_wants

async def get_wants() -> dict[str, Any]

Get user wants.

OtherAPI.get_wants_status

async def get_wants_status() -> dict[str, Any]

Get wants status.

OtherAPI.get_kworks_status

async def get_kworks_status() -> dict[str, Any]

Get kworks status.

OtherAPI.get_offers

async def get_offers() -> dict[str, Any]

Get offers.

OtherAPI.get_exchange_info

async def get_exchange_info() -> dict[str, Any]

Get exchange info.

OtherAPI.get_channel

async def get_channel() -> dict[str, Any]

Get channel info.

OtherAPI.get_in_app_notification

async def get_in_app_notification() -> dict[str, Any]

Get in-app notification.

OtherAPI.get_security_user_data

async def get_security_user_data() -> dict[str, Any]

Get security user data.

OtherAPI.is_dialog_allow

async def is_dialog_allow(user_id: int) -> bool

Check if dialog is allowed.

OtherAPI.get_viewed_kworks

async def get_viewed_kworks() -> list[Kwork]

Get viewed kworks.

OtherAPI.get_favorite_categories

async def get_favorite_categories() -> list[int]

Get favorite categories.

OtherAPI.update_settings

async def update_settings(settings: dict[str, Any]) -> dict[str, Any]

Update user settings.

OtherAPI.go_offline

async def go_offline() -> dict[str, Any]

Set user status to offline.

OtherAPI.get_actor

async def get_actor() -> dict[str, Any]

Get actor info.

KworkClient.catalog

@property
def catalog() -> CatalogAPI

Catalog API.

KworkClient.projects

@property
def projects() -> ProjectsAPI

Projects API.

KworkClient.user

@property
def user() -> UserAPI

User API.

KworkClient.reference

@property
def reference() -> ReferenceAPI

Reference data API.

KworkClient.notifications

@property
def notifications() -> NotificationsAPI

Notifications API.

KworkClient.other

@property
def other() -> OtherAPI

Other endpoints.

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

class KworkUser(BaseModel)

User information.

id

username

avatar_url

is_online

rating

KworkCategory

class KworkCategory(BaseModel)

Category information.

id

name

slug

parent_id

Kwork

class Kwork(BaseModel)

Kwork (service) information.

id

title

description

price

currency

category_id

seller

images

rating

reviews_count

created_at

updated_at

KworkDetails

class KworkDetails(Kwork)

Extended kwork details.

full_description

requirements

delivery_time

in days

revisions

features

faq

PaginationInfo

class PaginationInfo(BaseModel)

Pagination metadata.

current_page

total_pages

total_items

items_per_page

has_next

has_prev

CatalogResponse

class CatalogResponse(BaseModel)

Catalog response with kworks and pagination.

kworks

pagination

filters

sort_options

Project

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

class ProjectsResponse(BaseModel)

Projects list response.

projects

pagination

Review

class Review(BaseModel)

Review information.

id

rating

comment

author

kwork_id

created_at

ReviewsResponse

class ReviewsResponse(BaseModel)

Reviews list response.

reviews

pagination

average_rating

Notification

class Notification(BaseModel)

Notification information.

id

type

message, order, system, etc.

title

message

is_read

created_at

link

NotificationsResponse

class NotificationsResponse(BaseModel)

Notifications list response.

notifications

unread_count

Dialog

class Dialog(BaseModel)

Dialog (chat) information.

id

participant

last_message

unread_count

updated_at

AuthResponse

class AuthResponse(BaseModel)

Authentication response.

success

user_id

username

web_auth_token

message

ErrorDetail

class ErrorDetail(BaseModel)

Error detail from API.

code

message

field

APIErrorResponse

class APIErrorResponse(BaseModel)

Standard API error response.

success

errors

message

City

class City(BaseModel)

City information.

id

name

country_id

Country

class Country(BaseModel)

Country information.

id

name

code

cities

TimeZone

class TimeZone(BaseModel)

Timezone information.

id

name

offset

e.g., "+03:00"

Feature

class Feature(BaseModel)

Feature/addon information.

id

name

description

price

type

extra, premium, etc.

Badge

class Badge(BaseModel)

User badge information.

id

name

description

icon_url

DataResponse

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

class KworkError(Exception)

Base exception for all Kwork API errors.

KworkError.__init__

def __init__(message: str, response: Optional[Any] = None)

KworkError.__str__

def __str__() -> str

KworkAuthError

class KworkAuthError(KworkError)

Authentication/authorization error.

KworkAuthError.__init__

def __init__(message: str = "Authentication failed",
             response: Optional[Any] = None)

KworkAuthError.__str__

def __str__() -> str

KworkApiError

class KworkApiError(KworkError)

API request error (4xx, 5xx).

KworkApiError.__init__

def __init__(message: str,
             status_code: Optional[int] = None,
             response: Optional[Any] = None)

KworkApiError.__str__

def __str__() -> str

KworkNotFoundError

class KworkNotFoundError(KworkApiError)

Resource not found (404).

KworkNotFoundError.__init__

def __init__(resource: str, response: Optional[Any] = None)

KworkRateLimitError

class KworkRateLimitError(KworkApiError)

Rate limit exceeded (429).

KworkRateLimitError.__init__

def __init__(message: str = "Rate limit exceeded",
             response: Optional[Any] = None)

KworkValidationError

class KworkValidationError(KworkApiError)

Validation error (400).

KworkValidationError.__init__

def __init__(message: str = "Validation failed",
             fields: Optional[dict[str, list[str]]] = None,
             response: Optional[Any] = None)

KworkValidationError.__str__

def __str__() -> str

KworkNetworkError

class KworkNetworkError(KworkError)

Network/connection error.

KworkNetworkError.__init__

def __init__(message: str = "Network error", response: Optional[Any] = None)

KworkNetworkError.__str__

def __str__() -> str