hh-api

Name	hh-api JSON
Version	0.1.4 JSON
	download
home_page	None
Summary	Async Python client for the HeadHunter (hh.ru) API with token refresh and typing.
upload_time	2025-08-14 12:47:49
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	MIT
keywords	api async headhunter hh hr httpx jobs
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # hh-api

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/hh-api)](https://pypi.org/project/hh-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Современная асинхронная Python-библиотека для работы с API HeadHunter (hh.ru) с автоматическим управлением OAuth2-токенами и поддержкой multi-tenant архитектуры.

## 🎯 Ключевые особенности

- 🚀 **Полностью асинхронная** на базе `httpx` и `asyncio`
- 🔐 **Умное управление OAuth2-токенами** с автоматическим обновлением
- 🏢 **Multi-tenant поддержка** для работы с несколькими пользователями
- 💾 **Гибкие хранилища токенов**: память, JSON-файлы, Redis, база данных, переменные окружения
- 🔄 **Автоматические повторные попытки** при сетевых ошибках
- 🎭 **Полная типизация** для лучшей поддержки IDE
- 🛡️ **Безопасность**: защита от race conditions при обновлении токенов

## 📦 Установка

```bash
pip install hh-api
```


## 📚 API Reference

### HHClient

| Метод | Описание |
|-------|----------|
| `search_vacancies(**params)` | Поиск вакансий |
| `get_vacancy(vacancy_id)` | Получить детали вакансии |
| `get_resume(resume_id)` | Получить информацию о резюме |
| `search_similar_vacancies(resume_id, **params)` | Найти похожие вакансии |
| `apply_to_vacancy(resume_id, vacancy_id, message)` | Откликнуться на вакансию |
| `get_dictionaries()` | Получить справочники HH |

### TokenManager

| Метод | Описание |
|-------|----------|
| `authorization_url(subject, state?)` | Сгенерировать URL для авторизации |
| `exchange_code(subject, code)` | Обменять код на токены |
| `ensure_access(subject)` | Получить действующий access token |
| `refresh(subject, refresh_token?)` | Обновить токены |


## 🤝 Вклад в проект

Приветствуются pull requests! Для больших изменений сначала откройте issue для обсуждения.

1. Fork репозитория
2. Создайте ветку для фичи (`git checkout -b feature/AmazingFeature`)
3. Commit изменения (`git commit -m 'Add some AmazingFeature'`)
4. Push в ветку (`git push origin feature/AmazingFeature`)
5. Откройте Pull Request

## 📄 Лицензия

Этот проект лицензирован под MIT License - см. файл [LICENSE](LICENSE) для деталей.

## 🙏 Благодарности

- [HeadHunter API](https://github.com/hhru/api) за отличную документацию
- [httpx](https://www.python-httpx.org/) за прекрасный асинхронный HTTP-клиент
- Всем контрибьюторам проекта

## 📧 Контакты

iNetsmol - [@inetsmol](https://github.com/inetsmol) - inetsmol@gmail.com

Ссылка на проект: [https://github.com/inetsmol/hh-api](https://github.com/inetsmol/hh-api)
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "hh-api",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "api, async, headhunter, hh, hr, httpx, jobs",
    "author": null,
    "author_email": "iNetsmol <inetsmol@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/41/25/6a2b7a422e17dffd8d241fbf6166382e8f8810d69dee43f474a9549a3bed/hh_api-0.1.4.tar.gz",
    "platform": null,
    "description": "# hh-api\n\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/hh-api)](https://pypi.org/project/hh-api/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\u0421\u043e\u0432\u0440\u0435\u043c\u0435\u043d\u043d\u0430\u044f \u0430\u0441\u0438\u043d\u0445\u0440\u043e\u043d\u043d\u0430\u044f Python-\u0431\u0438\u0431\u043b\u0438\u043e\u0442\u0435\u043a\u0430 \u0434\u043b\u044f \u0440\u0430\u0431\u043e\u0442\u044b \u0441 API HeadHunter (hh.ru) \u0441 \u0430\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u0435\u0441\u043a\u0438\u043c \u0443\u043f\u0440\u0430\u0432\u043b\u0435\u043d\u0438\u0435\u043c OAuth2-\u0442\u043e\u043a\u0435\u043d\u0430\u043c\u0438 \u0438 \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u043e\u0439 multi-tenant \u0430\u0440\u0445\u0438\u0442\u0435\u043a\u0442\u0443\u0440\u044b.\n\n## \ud83c\udfaf \u041a\u043b\u044e\u0447\u0435\u0432\u044b\u0435 \u043e\u0441\u043e\u0431\u0435\u043d\u043d\u043e\u0441\u0442\u0438\n\n- \ud83d\ude80 **\u041f\u043e\u043b\u043d\u043e\u0441\u0442\u044c\u044e \u0430\u0441\u0438\u043d\u0445\u0440\u043e\u043d\u043d\u0430\u044f** \u043d\u0430 \u0431\u0430\u0437\u0435 `httpx` \u0438 `asyncio`\n- \ud83d\udd10 **\u0423\u043c\u043d\u043e\u0435 \u0443\u043f\u0440\u0430\u0432\u043b\u0435\u043d\u0438\u0435 OAuth2-\u0442\u043e\u043a\u0435\u043d\u0430\u043c\u0438** \u0441 \u0430\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u0435\u0441\u043a\u0438\u043c \u043e\u0431\u043d\u043e\u0432\u043b\u0435\u043d\u0438\u0435\u043c\n- \ud83c\udfe2 **Multi-tenant \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0430** \u0434\u043b\u044f \u0440\u0430\u0431\u043e\u0442\u044b \u0441 \u043d\u0435\u0441\u043a\u043e\u043b\u044c\u043a\u0438\u043c\u0438 \u043f\u043e\u043b\u044c\u0437\u043e\u0432\u0430\u0442\u0435\u043b\u044f\u043c\u0438\n- \ud83d\udcbe **\u0413\u0438\u0431\u043a\u0438\u0435 \u0445\u0440\u0430\u043d\u0438\u043b\u0438\u0449\u0430 \u0442\u043e\u043a\u0435\u043d\u043e\u0432**: \u043f\u0430\u043c\u044f\u0442\u044c, JSON-\u0444\u0430\u0439\u043b\u044b, Redis, \u0431\u0430\u0437\u0430 \u0434\u0430\u043d\u043d\u044b\u0445, \u043f\u0435\u0440\u0435\u043c\u0435\u043d\u043d\u044b\u0435 \u043e\u043a\u0440\u0443\u0436\u0435\u043d\u0438\u044f\n- \ud83d\udd04 **\u0410\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u0435\u0441\u043a\u0438\u0435 \u043f\u043e\u0432\u0442\u043e\u0440\u043d\u044b\u0435 \u043f\u043e\u043f\u044b\u0442\u043a\u0438** \u043f\u0440\u0438 \u0441\u0435\u0442\u0435\u0432\u044b\u0445 \u043e\u0448\u0438\u0431\u043a\u0430\u0445\n- \ud83c\udfad **\u041f\u043e\u043b\u043d\u0430\u044f \u0442\u0438\u043f\u0438\u0437\u0430\u0446\u0438\u044f** \u0434\u043b\u044f \u043b\u0443\u0447\u0448\u0435\u0439 \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u043a\u0438 IDE\n- \ud83d\udee1\ufe0f **\u0411\u0435\u0437\u043e\u043f\u0430\u0441\u043d\u043e\u0441\u0442\u044c**: \u0437\u0430\u0449\u0438\u0442\u0430 \u043e\u0442 race conditions \u043f\u0440\u0438 \u043e\u0431\u043d\u043e\u0432\u043b\u0435\u043d\u0438\u0438 \u0442\u043e\u043a\u0435\u043d\u043e\u0432\n\n## \ud83d\udce6 \u0423\u0441\u0442\u0430\u043d\u043e\u0432\u043a\u0430\n\n```bash\npip install hh-api\n```\n\n\n## \ud83d\udcda API Reference\n\n### HHClient\n\n| \u041c\u0435\u0442\u043e\u0434 | \u041e\u043f\u0438\u0441\u0430\u043d\u0438\u0435 |\n|-------|----------|\n| `search_vacancies(**params)` | \u041f\u043e\u0438\u0441\u043a \u0432\u0430\u043a\u0430\u043d\u0441\u0438\u0439 |\n| `get_vacancy(vacancy_id)` | \u041f\u043e\u043b\u0443\u0447\u0438\u0442\u044c \u0434\u0435\u0442\u0430\u043b\u0438 \u0432\u0430\u043a\u0430\u043d\u0441\u0438\u0438 |\n| `get_resume(resume_id)` | \u041f\u043e\u043b\u0443\u0447\u0438\u0442\u044c \u0438\u043d\u0444\u043e\u0440\u043c\u0430\u0446\u0438\u044e \u043e \u0440\u0435\u0437\u044e\u043c\u0435 |\n| `search_similar_vacancies(resume_id, **params)` | \u041d\u0430\u0439\u0442\u0438 \u043f\u043e\u0445\u043e\u0436\u0438\u0435 \u0432\u0430\u043a\u0430\u043d\u0441\u0438\u0438 |\n| `apply_to_vacancy(resume_id, vacancy_id, message)` | \u041e\u0442\u043a\u043b\u0438\u043a\u043d\u0443\u0442\u044c\u0441\u044f \u043d\u0430 \u0432\u0430\u043a\u0430\u043d\u0441\u0438\u044e |\n| `get_dictionaries()` | \u041f\u043e\u043b\u0443\u0447\u0438\u0442\u044c \u0441\u043f\u0440\u0430\u0432\u043e\u0447\u043d\u0438\u043a\u0438 HH |\n\n### TokenManager\n\n| \u041c\u0435\u0442\u043e\u0434 | \u041e\u043f\u0438\u0441\u0430\u043d\u0438\u0435 |\n|-------|----------|\n| `authorization_url(subject, state?)` | \u0421\u0433\u0435\u043d\u0435\u0440\u0438\u0440\u043e\u0432\u0430\u0442\u044c URL \u0434\u043b\u044f \u0430\u0432\u0442\u043e\u0440\u0438\u0437\u0430\u0446\u0438\u0438 |\n| `exchange_code(subject, code)` | \u041e\u0431\u043c\u0435\u043d\u044f\u0442\u044c \u043a\u043e\u0434 \u043d\u0430 \u0442\u043e\u043a\u0435\u043d\u044b |\n| `ensure_access(subject)` | \u041f\u043e\u043b\u0443\u0447\u0438\u0442\u044c \u0434\u0435\u0439\u0441\u0442\u0432\u0443\u044e\u0449\u0438\u0439 access token |\n| `refresh(subject, refresh_token?)` | \u041e\u0431\u043d\u043e\u0432\u0438\u0442\u044c \u0442\u043e\u043a\u0435\u043d\u044b |\n\n\n## \ud83e\udd1d \u0412\u043a\u043b\u0430\u0434 \u0432 \u043f\u0440\u043e\u0435\u043a\u0442\n\n\u041f\u0440\u0438\u0432\u0435\u0442\u0441\u0442\u0432\u0443\u044e\u0442\u0441\u044f pull requests! \u0414\u043b\u044f \u0431\u043e\u043b\u044c\u0448\u0438\u0445 \u0438\u0437\u043c\u0435\u043d\u0435\u043d\u0438\u0439 \u0441\u043d\u0430\u0447\u0430\u043b\u0430 \u043e\u0442\u043a\u0440\u043e\u0439\u0442\u0435 issue \u0434\u043b\u044f \u043e\u0431\u0441\u0443\u0436\u0434\u0435\u043d\u0438\u044f.\n\n1. Fork \u0440\u0435\u043f\u043e\u0437\u0438\u0442\u043e\u0440\u0438\u044f\n2. \u0421\u043e\u0437\u0434\u0430\u0439\u0442\u0435 \u0432\u0435\u0442\u043a\u0443 \u0434\u043b\u044f \u0444\u0438\u0447\u0438 (`git checkout -b feature/AmazingFeature`)\n3. Commit \u0438\u0437\u043c\u0435\u043d\u0435\u043d\u0438\u044f (`git commit -m 'Add some AmazingFeature'`)\n4. Push \u0432 \u0432\u0435\u0442\u043a\u0443 (`git push origin feature/AmazingFeature`)\n5. \u041e\u0442\u043a\u0440\u043e\u0439\u0442\u0435 Pull Request\n\n## \ud83d\udcc4 \u041b\u0438\u0446\u0435\u043d\u0437\u0438\u044f\n\n\u042d\u0442\u043e\u0442 \u043f\u0440\u043e\u0435\u043a\u0442 \u043b\u0438\u0446\u0435\u043d\u0437\u0438\u0440\u043e\u0432\u0430\u043d \u043f\u043e\u0434 MIT License - \u0441\u043c. \u0444\u0430\u0439\u043b [LICENSE](LICENSE) \u0434\u043b\u044f \u0434\u0435\u0442\u0430\u043b\u0435\u0439.\n\n## \ud83d\ude4f \u0411\u043b\u0430\u0433\u043e\u0434\u0430\u0440\u043d\u043e\u0441\u0442\u0438\n\n- [HeadHunter API](https://github.com/hhru/api) \u0437\u0430 \u043e\u0442\u043b\u0438\u0447\u043d\u0443\u044e \u0434\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u0430\u0446\u0438\u044e\n- [httpx](https://www.python-httpx.org/) \u0437\u0430 \u043f\u0440\u0435\u043a\u0440\u0430\u0441\u043d\u044b\u0439 \u0430\u0441\u0438\u043d\u0445\u0440\u043e\u043d\u043d\u044b\u0439 HTTP-\u043a\u043b\u0438\u0435\u043d\u0442\n- \u0412\u0441\u0435\u043c \u043a\u043e\u043d\u0442\u0440\u0438\u0431\u044c\u044e\u0442\u043e\u0440\u0430\u043c \u043f\u0440\u043e\u0435\u043a\u0442\u0430\n\n## \ud83d\udce7 \u041a\u043e\u043d\u0442\u0430\u043a\u0442\u044b\n\niNetsmol - [@inetsmol](https://github.com/inetsmol) - inetsmol@gmail.com\n\n\u0421\u0441\u044b\u043b\u043a\u0430 \u043d\u0430 \u043f\u0440\u043e\u0435\u043a\u0442: [https://github.com/inetsmol/hh-api](https://github.com/inetsmol/hh-api)",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Async Python client for the HeadHunter (hh.ru) API with token refresh and typing.",
    "version": "0.1.4",
    "project_urls": {
        "Homepage": "https://github.com/inetsmol/hh-api",
        "Issues": "https://github.com/inetsmol/hh-api/issues"
    },
    "split_keywords": [
        "api",
        " async",
        " headhunter",
        " hh",
        " hr",
        " httpx",
        " jobs"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b50ec1a3d631c528fb0beb4d7961b36133b577e0001d92eac413df3af1416357",
                "md5": "a1cf276948e3cd4da2f0e32604d37422",
                "sha256": "3bee7bfc05ca5ddd9207e75e0892adcb9b4403944a22cf2254e1cdd1594466c8"
            },
            "downloads": -1,
            "filename": "hh_api-0.1.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "a1cf276948e3cd4da2f0e32604d37422",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 19045,
            "upload_time": "2025-08-14T12:47:48",
            "upload_time_iso_8601": "2025-08-14T12:47:48.305479Z",
            "url": "https://files.pythonhosted.org/packages/b5/0e/c1a3d631c528fb0beb4d7961b36133b577e0001d92eac413df3af1416357/hh_api-0.1.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "41256a2b7a422e17dffd8d241fbf6166382e8f8810d69dee43f474a9549a3bed",
                "md5": "68b909111ca4f0962d481d37e146f003",
                "sha256": "1470625d405c7e84749e702a447ec883f7d50c3ec77fdd86de708e5dc5bceace"
            },
            "downloads": -1,
            "filename": "hh_api-0.1.4.tar.gz",
            "has_sig": false,
            "md5_digest": "68b909111ca4f0962d481d37e146f003",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 31424,
            "upload_time": "2025-08-14T12:47:49",
            "upload_time_iso_8601": "2025-08-14T12:47:49.764799Z",
            "url": "https://files.pythonhosted.org/packages/41/25/6a2b7a422e17dffd8d241fbf6166382e8f8810d69dee43f474a9549a3bed/hh_api-0.1.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-14 12:47:49",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "inetsmol",
    "github_project": "hh-api",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "hh-api"
}