0975b68334
Initial release: - Complete async API client (45+ endpoints) - Pydantic models for all responses - Two-step authentication - Comprehensive error handling - 92% test coverage - Gitea Actions CI/CD - Semantic release configured
110 lines
2.3 KiB
Markdown
110 lines
2.3 KiB
Markdown
# Kwork API — Python Client
|
|
|
|
Unofficial Python client for Kwork.ru API.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install kwork-api
|
|
```
|
|
|
|
Or with UV:
|
|
|
|
```bash
|
|
uv add kwork-api
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Login with credentials
|
|
|
|
```python
|
|
from kwork_api import KworkClient
|
|
|
|
# Authenticate
|
|
client = await KworkClient.login("username", "password")
|
|
|
|
# Get catalog
|
|
catalog = await client.catalog.get_list(page=1)
|
|
|
|
# Get projects
|
|
projects = await client.projects.get_list(page=1)
|
|
|
|
# Close when done
|
|
await client.close()
|
|
```
|
|
|
|
### Using context manager
|
|
|
|
```python
|
|
async with await KworkClient.login("username", "password") as client:
|
|
catalog = await client.catalog.get_list(page=1)
|
|
# Client automatically closes
|
|
```
|
|
|
|
### Save and restore session
|
|
|
|
```python
|
|
# Save credentials after login
|
|
client = await KworkClient.login("username", "password")
|
|
|
|
# Option 1: Save token only
|
|
token = client.token
|
|
|
|
# Option 2: Save full credentials (token + cookies)
|
|
creds = client.credentials
|
|
import json
|
|
with open("session.json", "w") as f:
|
|
json.dump(creds, f)
|
|
|
|
# Later, restore session
|
|
client = KworkClient(token=token)
|
|
# or
|
|
client = KworkClient(**creds)
|
|
|
|
user_info = await client.user.get_info()
|
|
```
|
|
|
|
## API Overview
|
|
|
|
### Catalog API
|
|
|
|
- `client.catalog.get_list()` — Get kworks catalog
|
|
- `client.catalog.get_details(kwork_id)` — Get kwork details
|
|
|
|
### Projects API
|
|
|
|
- `client.projects.get_list()` — Get freelance projects
|
|
- `client.projects.get_payer_orders()` — Your orders as customer
|
|
- `client.projects.get_worker_orders()` — Your orders as performer
|
|
|
|
### User API
|
|
|
|
- `client.user.get_info()` — Get user profile
|
|
- `client.user.get_reviews()` — Get user reviews
|
|
- `client.user.get_favorite_kworks()` — Get favorite kworks
|
|
|
|
### Settings & Preferences
|
|
|
|
- `client.get_wants()` — User preferences
|
|
- `client.get_kworks_status()` — Kworks status
|
|
- `client.update_settings()` — Update settings
|
|
- `client.go_offline()` — Set offline status
|
|
|
|
See [API Reference](api-reference.md) for full documentation.
|
|
|
|
## Error Handling
|
|
|
|
```python
|
|
from kwork_api import KworkError, KworkAuthError, KworkApiError
|
|
|
|
try:
|
|
await client.catalog.get_list()
|
|
except KworkAuthError:
|
|
print("Invalid credentials")
|
|
except KworkApiError as e:
|
|
print(f"API error: {e.status_code}")
|
|
except KworkError as e:
|
|
print(f"General error: {e.message}")
|
|
```
|