From 309556c1a0f01e8f1bd9a26a091af60d77e323ff Mon Sep 17 00:00:00 2001 From: root Date: Sun, 29 Mar 2026 00:56:45 +0000 Subject: [PATCH] docs: simplify documentation structure - 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 --- docs/ARCHITECTURE.md | 261 ------------------------------------ docs/GITEA_PAGES.md | 211 ----------------------------- docs/RELEASE.md | 131 ------------------ docs/SEMANTIC_RELEASE.md | 281 --------------------------------------- docs/api-reference.md | 12 +- docs/api/client.md | 3 - docs/api/errors.md | 5 - docs/api/models.md | 5 - docs/api_reference.md | 0 docs/index.md | 114 ++++------------ docs/usage.md | 132 ++++++++++++++++++ mkdocs.yml | 16 +-- 12 files changed, 170 insertions(+), 1001 deletions(-) delete mode 100644 docs/ARCHITECTURE.md delete mode 100644 docs/GITEA_PAGES.md delete mode 100644 docs/RELEASE.md delete mode 100644 docs/SEMANTIC_RELEASE.md delete mode 100644 docs/api/client.md delete mode 100644 docs/api/errors.md delete mode 100644 docs/api/models.md delete mode 100644 docs/api_reference.md create mode 100644 docs/usage.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 8455754..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -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 — свободное использование с указанием авторства. diff --git a/docs/GITEA_PAGES.md b/docs/GITEA_PAGES.md deleted file mode 100644 index cab360a..0000000 --- a/docs/GITEA_PAGES.md +++ /dev/null @@ -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) diff --git a/docs/RELEASE.md b/docs/RELEASE.md deleted file mode 100644 index e5ea9c1..0000000 --- a/docs/RELEASE.md +++ /dev/null @@ -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 -``` diff --git a/docs/SEMANTIC_RELEASE.md b/docs/SEMANTIC_RELEASE.md deleted file mode 100644 index 6768c88..0000000 --- a/docs/SEMANTIC_RELEASE.md +++ /dev/null @@ -1,281 +0,0 @@ -# Semantic Release — Автоматическое версионирование - -## 📋 Обзор - -**python-semantic-release** автоматически определяет версию на основе Conventional Commits. - -**Как работает:** -``` -Commit → Анализ сообщения → Определение типа → Bump версии → Тег → Релиз -``` - ---- - -## 🎯 CONVENTIONAL COMMITS - -### **Формат коммита:** - -``` -(): - -[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) diff --git a/docs/api-reference.md b/docs/api-reference.md index 8aaf2d9..d779d73 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -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 diff --git a/docs/api/client.md b/docs/api/client.md deleted file mode 100644 index bee123c..0000000 --- a/docs/api/client.md +++ /dev/null @@ -1,3 +0,0 @@ -# Client API - -::: kwork_api.client.KworkClient diff --git a/docs/api/errors.md b/docs/api/errors.md deleted file mode 100644 index eef1951..0000000 --- a/docs/api/errors.md +++ /dev/null @@ -1,5 +0,0 @@ -# Errors - -Exception classes for API errors. - -::: kwork_api.errors diff --git a/docs/api/models.md b/docs/api/models.md deleted file mode 100644 index 44fa61f..0000000 --- a/docs/api/models.md +++ /dev/null @@ -1,5 +0,0 @@ -# Models - -Pydantic models for API responses. - -::: kwork_api.models diff --git a/docs/api_reference.md b/docs/api_reference.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/index.md b/docs/index.md index 15f2c89..ff1cfe8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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") - -# 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 +# Login with credentials async with await KworkClient.login("username", "password") as client: + # Get catalog catalog = await client.catalog.get_list(page=1) - # Client automatically closes + + # Get projects + projects = await client.projects.get_list() + + # Get user info + user = await client.user.get_info() ``` -### Save and restore session +## Documentation -```python -# Save credentials after login -client = await KworkClient.login("username", "password") +- [Usage Guide](usage.md) — Examples and best practices +- [API Reference](api-reference.md) — Complete API documentation -# Option 1: Save token only -token = client.token +## Links -# 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) diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..11ee203 --- /dev/null +++ b/docs/usage.md @@ -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()) +``` diff --git a/mkdocs.yml b/mkdocs.yml index ec3c29d..58e9c94 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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