much-data/kwork-api
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: simplify documentation structure

Browse Source 
- Remove manual API docs (mkdocstrings generates automatically)
- Remove internal docs (ARCHITECTURE, GITEA_PAGES, RELEASE, SEMANTIC_RELEASE)
- Add usage.md with examples
- Simplify index.md
- Update mkdocs.yml (minimal config)
- Remove api_reference.md duplicate
This commit is contained in:
root 2026-03-29 00:56:45 +00:00
parent 43a75ae09b
commit 309556c1a0
12 changed files with 170 additions and 1001 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
docs/ARCHITECTURE.md
View File

@ -1,261 +0,0 @@
# Architecture — kwork-api
## 📐 Обзор
**kwork-api** — асинхронный Python клиент для Kwork.ru API с полной типизацией и документацией.
---
## 🏗️ Архитектура
```
┌─────────────────────────────────────────────────────────┐
│ User Application │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ KworkClient │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Authentication Layer │ │
│ │ - login() / token auth │ │
│ │ - Session management │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ API Groups │ │
│ │ - catalog, projects, user, reference, ... │ │
│ └──────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ HTTP Layer (httpx) │ │
│ │ - HTTP/2 support │ │
│ │ - Timeout handling │ │
│ │ - Error handling │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Kwork.ru API (HTTPS) │
└─────────────────────────────────────────────────────────┘
```
---
## 📁 Структура проекта
```
kwork-api/
├── src/kwork_api/
│ ├── __init__.py # Public API
│ ├── client.py # KworkClient + API groups
│ ├── models.py # Pydantic models
│ └── errors.py # Exception classes
│
├── tests/
│ ├── test_client.py # Client tests
│ ├── test_models.py # Model tests
│ └── test_all_endpoints.py # Endpoint tests
│
├── docs/
│ ├── index.md # Quick start
│ ├── api-reference.md # API docs
│ ├── RELEASE.md # Release guide
│ └── ARCHITECTURE.md # This file
│
├── .github/workflows/
│ └── ci.yml # CI/CD pipeline
│
├── pyproject.toml # Project config
├── uv.lock # Dependencies lock
└── README.md # Main documentation
```
---
## 🔑 Компоненты
### 1. KworkClient
**Ответственность:** Основное взаимодействие с API
**Функции:**
- Аутентификация (login / token)
- Управление сессией
- Делегирование API группам
**API Groups:**
```python
client.catalog # CatalogAPI
client.projects # ProjectsAPI
client.user # UserAPI
client.reference # ReferenceAPI
client.notifications # NotificationsAPI
client.other # OtherAPI
```
---
### 2. Models (Pydantic)
**Ответственность:** Валидация и типизация ответов API
**Категории:**
- **User models:** KworkUser, AuthResponse
- **Kwork models:** Kwork, KworkDetails, KworkCategory
- **Project models:** Project, ProjectsResponse
- **Review models:** Review, ReviewsResponse
- **Notification models:** Notification, Dialog
- **Reference models:** City, Country, TimeZone, Feature, Badge
- **Error models:** ErrorDetail, APIErrorResponse
---
### 3. Errors
**Ответственность:** Обработка ошибок API
**Иерархия:**
```
KworkError (base)
├── KworkAuthError # 401, 403
├── KworkApiError # 4xx, 5xx
│ ├── KworkNotFoundError # 404
│ ├── KworkRateLimitError # 429
│ └── KworkValidationError # 400
└── KworkNetworkError # Network issues
```
---
### 4. HTTP Layer (httpx)
**Ответственность:** HTTP запросы
**Функции:**
- HTTP/2 поддержка
- Таймауты
- Cookies management
- Token authentication
- Error handling
---
## 🔄 Flow: Аутентификация
```
User → KworkClient.login(username, password)
│
▼
POST /signIn (cookies)
│
▼
POST /getWebAuthToken (token)
│
▼
Store token + cookies
│
▼
Return authenticated client
```
---
## 🔄 Flow: API Request
```
User → client.catalog.get_list(page=1)
│
▼
CatalogAPI.get_list()
│
▼
KworkClient._request()
│
▼
httpx.AsyncClient.post()
│
▼
KworkClient._handle_response()
│
▼
CatalogResponse.model_validate()
│
▼
Return typed response
```
---
## 🚀 CI/CD Pipeline
```
Push/Tag → GitHub Actions
│
├── Test Job
│ ├── Install UV + Python
│ ├── Run linters (ruff)
│ ├── Run tests (pytest)
│ └── Upload coverage
│
├── Build Job
│ ├── Build wheel + sdist
│ └── Upload artifacts
│
├── Publish Job (on tag)
│ ├── Download artifacts
│ └── Publish to Gitea Registry
│
└── Docs Job
├── Build MkDocs
└── Upload site
```
---
## 📊 Зависимости
### Runtime
- `httpx[http2]>=0.26.0` — HTTP client
- `pydantic>=2.0.0` — Data validation
- `structlog>=24.0.0` — Logging
### Development
- `pytest>=8.0.0` — Testing
- `pytest-cov>=4.0.0` — Coverage
- `pytest-asyncio>=0.23.0` — Async tests
- `respx>=0.20.0` — HTTP mocking
- `ruff>=0.3.0` — Linting
- `mkdocs + mkdocstrings` — Documentation
---
## 🔒 Безопасность
- **Токены:** Не сохраняются в логах
- **Пароли:** Передаются только при login()
- **Сессии:** Token + cookies хранятся в клиенте
- **HTTPS:** Все запросы через HTTPS
---
## 📈 Производительность
- **Async/Await:** Неблокирующие запросы
- **HTTP/2:** Multiplexing запросов
- **Connection pooling:** Переиспользование соединений
- **Timeouts:** Защита от зависаний
---
## 🧪 Тестирование
- **Unit тесты:** 92% coverage
- **Mock HTTP:** respx для изоляции
- **Async tests:** pytest-asyncio
- **CI:** Автоматический прогон при каждом коммите
---
## 📝 Лицензия
MIT License — свободное использование с указанием авторства.

211
docs/GITEA_PAGES.md
View File

@ -1,211 +0,0 @@
# Gitea Pages — Хостинг документации
## 📋 Обзор
**Gitea Pages** — аналог GitHub Pages для хостинга статических сайтов напрямую из Gitea.
**URL документации:** `https://git.much-data.ru/claw/kwork-api/`
---
## 🔧 НАСТРОЙКА
### **Шаг 1: Включить Pages в репозитории**
1. Зайди в https://git.much-data.ru/claw/kwork-api
2. **Settings** → **Pages**
3. Включить **Enable Pages**
4. Выбрать источник:
- **Source:** `gh-pages` branch
- **Folder:** `/ (root)`
5. **Save**
---
### **Шаг 2: Настроить Gitea Token**
1. https://git.much-data.ru → Settings → Applications
2. Создать токен с правами:
- `write:repository`
- `write:package`
3. Скопировать токен
4. В репозитории: **Settings** → **Secrets**
5. Добавить секрет: `GITEA_TOKEN` = твой токен
---
### **Шаг 3: Первый деплой**
```bash
cd /root/kwork-api
# Собрать документацию
uv run mkdocs build
# Проверить что site/ создан
ls -la site/
# Закоммитить и запушить
git add .
git commit -m "docs: initial documentation"
git push origin main
# CI/CD автоматически задеплоит на gh-pages
```
---
### **Шаг 4: Проверить**
После успешного CI/CD:
**Документация доступна:**
```
https://git.much-data.ru/claw/kwork-api/
```
Или если включён custom domain:
```
https://kwork-api.much-data.ru/
```
---
## 🔄 АВТОМАТИЧЕСКИЙ ДЕПЛОЙ
**Workflow срабатывает при:**
- ✅ Push в `main` ветку
- ✅ Создании тега релиза
**Что делает:**
1. Собирает MkDocs документацию
2. Пушит в `gh-pages` ветку
3. Gitea Pages автоматически обновляет сайт
---
## 🌐 CUSTOM DOMAIN (опционально)
### **DNS настройка:**
```
# В панели управления доменом much-data.ru
# CNAME запись:
kwork-api CNAME git.much-data.ru
# Или A запись:
kwork-api A 5.188.26.192
```
### **В Gitea Pages:**
1. **Settings** → **Pages**
2. **Custom Domain:** `kwork-api.much-data.ru`
3. **Save**
### **Создать CNAME файл:**
```bash
# В корне проекта (не в site/)
echo "kwork-api.much-data.ru" > static/CNAME
git add static/CNAME
git commit -m "docs: add custom domain"
git push
```
---
## 📊 СТРУКТУРА ВЕТКИ
```
main (исходный код)
├── src/
├── docs/
├── mkdocs.yml
└── .github/workflows/ci.yml
gh-pages (автоматически, только сайт)
├── index.html
├── api-reference/
├── search/
└── ...
```
---
## 🔍 TROUBLESHOOTING
### **Pages не включаются:**
```bash
# Проверить что Gitea версия >= 1.19
# Админ должен включить Pages в настройках сервера
```
### **CI/CD ошибка деплоя:**
```bash
# Проверить токен
# Проверить права токена (write:repository)
# Проверить что gh-pages ветка существует
```
### **404 на странице:**
```bash
# Подождать 1-2 минуты (Gitea обрабатывает)
# Проверить что site/ не пустой
# Проверить workflow логи
```
---
## 📋 ЧЕКЛИСТ
- [ ] Включить Pages в настройках репозитория
- [ ] Создать Gitea Token
- [ ] Добавить токен в Secrets (`GITEA_TOKEN`)
- [ ] Запушить изменения в main
- [ ] Дождаться CI/CD
- [ ] Проверить https://git.much-data.ru/claw/kwork-api/
- [ ] (Опционально) Настроить custom domain
---
## 🎯 АЛЬТЕРНАТИВЫ
Если Gitea Pages не работает:
### **1. Netlify (бесплатно)**
```bash
# Подключить репозиторий
# Build command: uv run mkdocs build
# Publish directory: site/
```
### **2. Vercel (бесплатно)**
```bash
# Аналогично Netlify
# Автоматический деплой из Git
```
### **3. Cloudflare Pages (бесплатно)**
```bash
# Быстрый CDN
# Автоматический HTTPS
```
### **4. Своё сервер (nginx)**
```bash
# Скопировать site/ на сервер
# Настроить nginx на /var/www/kwork-api-docs/
```
---
## 📞 ССЫЛКИ
- [Gitea Pages Documentation](https://docs.gitea.com/usage/pages)
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Gitea Actions](https://docs.gitea.com/usage/actions)

131
docs/RELEASE.md
View File

@ -1,131 +0,0 @@
# Release Guide — kwork-api
## 📋 Стратегия версионирования
Используем **SemVer** (Semantic Versioning): `MAJOR.MINOR.PATCH`
- **MAJOR** — ломающие изменения API
- **MINOR** — новая функциональность (обратно совместимая)
- **PATCH** — багфиксы (обратно совместимые)
---
## 🚀 Процесс релиза
### 1. Подготовка
```bash
# Убедись что все тесты проходят
uv run pytest
# Проверь линтеры
uv run ruff check src/ tests/
# Проверь сборку
uv build
```
### 2. Обновление версии
```bash
# Обновить версию в pyproject.toml
# Например: 0.1.0 → 0.1.1
# Создать тег
git tag -a v0.1.1 -m "Release v0.1.1"
# Отпушить тег
git push origin v0.1.1
```
### 3. Автоматическая публикация
После пуша тега:
1. ✅ Запускается CI/CD pipeline
2. ✅ Прогоняются тесты
3. ✅ Собирается пакет
4. ✅ Публикуется в Gitea Registry
---
## 📦 Gitea Package Registry
**URL:** `https://git.much-data.ru/api/packages/claw/pypi`
**Установка:**
```bash
# Создать .pypirc в домашней директории
cat > ~/.pypirc << EOF
[pypi]
username = claw
password = YOUR_GITEA_TOKEN
[git.much-data.ru]
repository = https://git.much-data.ru/api/packages/claw/pypi
username = claw
password = YOUR_GITEA_TOKEN
EOF
# Установить из Gitea
uv pip install kwork-api --index-url https://git.much-data.ru/api/packages/claw/pypi
```
---
## 🔑 Получение Gitea Token
1. Зайди в https://git.much-data.ru
2. Профиль → Settings → Applications
3. Создать токен с правами `write:package`
4. Сохрани токен в секреты репозитория: `GITEA_TOKEN`
---
## 📊 Changelog
Ведётся в `CHANGELOG.md` по формату [Keep a Changelog](https://keepachangelog.com/).
### Пример:
```markdown
## [0.1.1] - 2026-03-23
### Fixed
- Исправлена ошибка аутентификации при истечении токена
### Changed
- Обновлены зависимости
## [0.1.0] - 2026-03-23
### Added
- Первый релиз
- Базовая функциональность клиента
- Документация 100%
```
---
## ✅ Чеклист перед релизом
- [ ] Все тесты проходят
- [ ] Линтеры без ошибок
- [ ] Документация обновлена
- [ ] CHANGELOG.md обновлён
- [ ] Версия в pyproject.toml обновлена
- [ ] Тег создан и отправлен
- [ ] CI/CD pipeline успешен
- [ ] Пакет опубликован
---
## 🔧 Ручная публикация (если нужно)
```bash
# Собрать
uv build
# Опубликовать
uv publish \
--publish-url https://git.much-data.ru/api/packages/claw/pypi \
--token YOUR_GITEA_TOKEN
```

281
docs/SEMANTIC_RELEASE.md
View File

@ -1,281 +0,0 @@
# Semantic Release — Автоматическое версионирование
## 📋 Обзор
**python-semantic-release** автоматически определяет версию на основе Conventional Commits.
**Как работает:**
```
Commit → Анализ сообщения → Определение типа → Bump версии → Тег → Релиз
```
---
## 🎯 CONVENTIONAL COMMITS
### **Формат коммита:**
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
### **Типы коммитов и влияние на версию:**
| Тип | Влияние | Пример | Версия |
|-----|---------|--------|--------|
| `feat` | **MINOR** | `feat: add new API endpoint` | 0.1.0 → 0.2.0 |
| `fix` | **PATCH** | `fix: handle timeout errors` | 0.1.0 → 0.1.1 |
| `perf` | **PATCH** | `perf: optimize HTTP requests` | 0.1.0 → 0.1.1 |
| `feat` + BREAKING | **MAJOR** | `feat: change auth method` | 0.1.0 → 1.0.0 |
| `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build` | Нет | `docs: update README` | Без изменений |
---
## 📝 ПРИМЕРЫ КОММИТОВ
### **PATCH (багфиксы):**
```bash
git commit -m "fix: handle 404 error in catalog API"
git commit -m "fix(auth): restore session from token correctly"
git commit -m "perf: reduce HTTP connection overhead"
```
### **MINOR (новая функциональность):**
```bash
git commit -m "feat: add batch kwork details endpoint"
git commit -m "feat(projects): add get_payer_orders method"
git commit -m "feat: support HTTP/2 for faster requests"
```
### **MAJOR (ломающие изменения):**
```bash
git commit -m "feat: redesign authentication flow
BREAKING CHANGE: login() now returns KworkClient instead of tuple
Migration:
Before: token, cookies = await login(user, pass)
After: client = await KworkClient.login(user, pass)
"
```
### **Без влияния на версию:**
```bash
git commit -m "docs: add usage examples to README"
git commit -m "test: increase coverage to 95%"
git commit -m "style: fix formatting with ruff"
git commit -m "refactor: simplify error handling"
git commit -m "chore: update dependencies"
git commit -m "ci: add Gitea Actions workflow"
git commit -m "build: configure UV build system"
```
---
## 🔄 WORKFLOW
### **Разработка:**
```bash
# Делай коммиты по Conventional Commits
git commit -m "feat: add new endpoint"
git commit -m "fix: handle edge case"
git commit -m "docs: update documentation"
# Пуш в main
git push origin main
```
### **CI/CD (автоматически):**
```
1. Тесты запускаются
2. Сборка пакета
3. Semantic Release анализирует коммиты
4. Определяет тип версии (MAJOR/MINOR/PATCH)
5. Обновляет версию в pyproject.toml и __init__.py
6. Создаёт Git тег
7. Генерирует CHANGELOG
8. Создаёт релиз в Gitea
9. Публикует пакет в Gitea Registry
```
### **Результат:**
```
✅ v0.1.1 создан
✅ CHANGELOG.md обновлён
✅ Пакет опубликован
✅ Релиз в Gitea создан
```
---
## 🔧 РУЧНОЕ УПРАВЛЕНИЕ
### **Проверить следующую версию:**
```bash
cd /root/kwork-api
uv run semantic-release version --print
```
### **Сгенерировать CHANGELOG:**
```bash
uv run semantic-release changelog
```
### **Создать релиз вручную:**
```bash
# Bump версии
uv run semantic-release version --no-push
# Проверить что изменилось
git diff
# Запушить
git push origin main --tags
```
---
## 📊 ПРИМЕР ИСТОРИИ ВЕРСИЙ
```
v0.1.0 (2026-03-23)
- Initial release
- Complete API client
- 100% documentation
v0.1.1 (2026-03-24)
- fix: handle timeout errors
- fix: restore session correctly
v0.2.0 (2026-03-25)
- feat: add batch endpoint
- feat: support HTTP/2
v0.2.1 (2026-03-26)
- perf: optimize requests
v1.0.0 (2026-03-27)
- feat: new authentication
- BREAKING CHANGE: API changed
```
---
## ⚙️ КОНФИГУРАЦИЯ
**Файл:** `pyproject.toml`
```toml
[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
version_variables = ["src/kwork_api/__init__.py:__version__"]
branch = "main"
build_command = "uv build"
commit_parser = "angular"
tag_format = "v{version}"
[tool.semantic_release.commit_parser_options]
minor_tags = ["feat"]
patch_tags = ["fix", "perf"]
breaking_change_tags = ["feat"]
[tool.semantic_release.remote]
type = "gitea"
domain = "https://git.much-data.ru"
owner = "claw"
repo_name = "kwork-api"
```
---
## 🚨 TROUBLESHOOTING
### **Ошибка: "No commits to release"**
```bash
# Значит не было коммитов с типами feat/fix/perf
# Сделай коммит с правильным форматом
git commit -m "feat: add something new"
```
### **Ошибка: "Gitea token invalid"**
```bash
# Проверь токен
# Settings → Applications → Create new token
# Права: write:repository, write:package
# Обнови секрет в Gitea Actions
```
### **Версия не обновляется**
```bash
# Проверь конфигурацию
uv run semantic-release --version
# Проверь что __version__ есть в __init__.py
grep "__version__" src/kwork_api/__init__.py
```
---
## 📋 ЧЕКЛИСТ ПЕРЕД ПУШЕМ
- [ ] Коммиты по Conventional Commits
- [ ] Тесты проходят
- [ ] CHANGELOG обновлён (автоматически)
- [ ] Версия в __init__.py совпадает
- [ ] GITEA_TOKEN настроен в секретах
---
## 🎯 BEST PRACTICES
### **✅ Делай:**
```bash
# Атомарные коммиты
git commit -m "feat: add user endpoint"
git commit -m "fix: handle 404 error"
# Понятные описания
git commit -m "fix: restore session from saved token"
# Scope для больших изменений
git commit -m "feat(auth): add OAuth2 support"
```
### **❌ Не делай:**
```bash
# Слишком общие
git commit -m "fix stuff"
# Несколько изменений в одном
git commit -m "feat: add user endpoint and fix auth and update docs"
# Не по формату
git commit -m "added new feature"
```
---
## 📞 ССЫЛКИ
- [python-semantic-release](https://python-semantic-release.readthedocs.io/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Angular Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)

12
docs/api-reference.md
View File

@ -1,9 +1,9 @@
# API Reference
Complete API documentation for Kwork API client.
Auto-generated API documentation is available below.
## Modules
- [Client](api/client.md) — Main client class and API groups
- [Models](api/models.md) — Pydantic models for API responses
- [Errors](api/errors.md) — Exception classes
::: kwork_api.client.KworkClient
handler: python
options:
show_root_heading: true
show_source: true

3
docs/api/client.md
View File

@ -1,3 +0,0 @@
# Client API
::: kwork_api.client.KworkClient

5
docs/api/errors.md
View File

@ -1,5 +0,0 @@
# Errors
Exception classes for API errors.
::: kwork_api.errors

5
docs/api/models.md
View File

@ -1,5 +0,0 @@
# Models
Pydantic models for API responses.
::: kwork_api.models

0
docs/api_reference.md
View File

108
docs/index.md
View File

@ -1,109 +1,47 @@
# Kwork API — Python Client
# Kwork API
Unofficial Python client for Kwork.ru API.
## Features
- Complete async API client (45+ endpoints)
- Pydantic models for all responses
- Two-step authentication (cookies + web_auth_token)
- Comprehensive error handling
- HTTP/2 support
## Installation
```bash
pip install kwork-api
```
Or with UV:
```bash
uv add kwork-api
# or
pip install kwork-api
```
## Quick Start
### Login with credentials
```python
from kwork_api import KworkClient
# Authenticate
client = await KworkClient.login("username", "password")
# Login with credentials
async with await KworkClient.login("username", "password") as client:
# Get catalog
catalog = await client.catalog.get_list(page=1)
# Get projects
projects = await client.projects.get_list(page=1)
projects = await client.projects.get_list()
# Close when done
await client.close()
# Get user info
user = await client.user.get_info()
```
### Using context manager
## Documentation
```python
async with await KworkClient.login("username", "password") as client:
catalog = await client.catalog.get_list(page=1)
# Client automatically closes
```
- [Usage Guide](usage.md) — Examples and best practices
- [API Reference](api-reference.md) — Complete API documentation
### Save and restore session
## Links
```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}")
```
- [Source Code](https://git.much-data.ru/much-data/kwork-api)
- [Issues](https://git.much-data.ru/much-data/kwork-api/issues)
- [Gitea Packages](https://git.much-data.ru/much-data/kwork-api/packages)

132
docs/usage.md Normal file
View File

@ -0,0 +1,132 @@
# Usage Guide
## Authentication
### Login with credentials
```python
from kwork_api import KworkClient
async with await KworkClient.login("username", "password") as client:
# Your code here
pass
```
### Restore session from token
```python
from kwork_api import KworkClient
# Save token after first login
client = await KworkClient.login("username", "password")
token = client.token # Save this
# Later, restore session
client = KworkClient(token="saved_token")
user = await client.user.get_info()
```
## API Groups
### Catalog API
```python
# Get catalog list
catalog = await client.catalog.get_list(page=1, category_id=1)
# Get kwork details
kwork = await client.catalog.get_details(kwork_id=123)
```
### Projects API (Freelance)
```python
# Get projects list
projects = await client.projects.get_list(page=1)
# Get your orders
my_orders = await client.projects.get_payer_orders()
```
### User API
```python
# Get user info
user = await client.user.get_info()
# Get reviews
reviews = await client.user.get_reviews(user_id=123)
```
### Reference API
```python
# Get cities
cities = await client.reference.get_cities()
# Get countries
countries = await client.reference.get_countries()
# Get categories
categories = await client.reference.get_categories()
```
### Notifications API
```python
# Get notifications
notifications = await client.notifications.get_list()
# Get dialogs
dialogs = await client.notifications.get_dialogs()
```
## Error Handling
```python
from kwork_api import KworkApiError, KworkAuthError
try:
catalog = await client.catalog.get_list()
except KworkAuthError as e:
print(f"Authentication failed: {e}")
except KworkApiError as e:
print(f"API error: {e.status_code} - {e.message}")
```
## Best Practices
### Rate Limiting
Kwork doesn't have official rate limits, but be respectful:
```python
import asyncio
for page in range(1, 11):
catalog = await client.catalog.get_list(page=page)
await asyncio.sleep(0.5) # 500ms delay
```
### Session Management
Always use context manager for automatic cleanup:
```python
async with await KworkClient.login("user", "pass") as client:
# Client automatically closed
pass
```
### Save Token
Save token after first login to avoid repeated authentication:
```python
# First login
client = await KworkClient.login("user", "pass")
save_token(client.token) # Save to secure storage
# Later
client = KworkClient(token=load_token())
```

16
mkdocs.yml
View File

@ -1,9 +1,9 @@
site_name: Kwork API
site_description: Unofficial Python client for Kwork.ru API
site_url: https://github.com/claw/kwork-api
site_url: https://git.much-data.ru/much-data/kwork-api
repo_name: claw/kwork-api
repo_url: https://github.com/claw/kwork-api
repo_name: much-data/kwork-api
repo_url: https://git.much-data.ru/much-data/kwork-api
theme:
name: material
@ -58,7 +58,7 @@ markdown_extensions:
- pymdownx.keys
- pymdownx.magiclink:
repo_url_shorthand: true
user: claw
user: much-data
repo: kwork-api
- pymdownx.mark
- pymdownx.smartsymbols
@ -71,9 +71,5 @@ markdown_extensions:
nav:
- Home: index.md
- API Reference:
- Overview: api-reference.md
- Client: api/client.md
- Models: api/models.md
- Errors: api/errors.md
- Examples: examples.md
- API Reference: api-reference.md
- Usage: usage.md