# 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}")
```