hh-api-client 0.1.6

Synchronous, typed HeadHunter (hh.uz / hh.ru) API client with safe token handling and Django integration.

hh-api-client

Synchronous, typed HeadHunter (hh.uz / hh.ru) API client with safe token handling and first‑class Django support.

Short overview (EN)

• Lightweight client on top of requests (no async, no heavy deps).
• Works with both raw OAuth2 access tokens and pluggable token providers.
• Designed to integrate cleanly with Django models like OrganizationHHAccount.
• Helpful high‑level methods for vacancies, resumes, negotiations, and employer metadata.

Кратко по‑русски (RU)
hh-api-client — это простой синхронный Python‑клиент для HeadHunter (hh.uz / hh.ru) на базе requests,
который безопасно работает с OAuth2‑токенами и легко встраивается в Django‑проекты.

Qisqacha tavsif (UZ)
hh-api-client — bu HeadHunter (hh.uz / hh.ru) bilan ishlash uchun requests asosida yozilgan oddiy va ishonchli Python kliеnti.
Django loyihalaringizda HH hisoblari va tokenlarini boshqarish uchun qulay.

Requirements

• Python 3.9+
• requests>=2.31.0 (installed automatically with pip install hh-api-client)
• Optional: django>=3.2 if you want to use the Django integration pattern

Installation

pip install hh-api-client

From a Git repository (for example, the main GitHub repo):

pip install git+https://github.com/your-username/hh-api-client.git

For local development:

pip install -e .

Quick start

from hh_api_client import HHAPIClient

client = HHAPIClient(access_token="YOUR_HH_ACCESS_TOKEN")

employer = client.get_employer_info()
print(employer["id"], employer["name"])

With a token provider (recommended)

You can pass any object that implements:

• get_valid_access_token() -> str
• refresh_access_token() -> str

This matches your existing OrganizationHHAccount pattern.

from hh_api_client import HHAPIClient

client = HHAPIClient(organization_hh_account=my_hh_account_instance)

# Example: create vacancy
vacancy_data = {
    "name": "Python Developer",
    "description": "<p>We are looking for a Python developer...</p>",
    "area": {"id": "2759"},  # e.g. Tashkent
    "employment": {"id": "full"},
    "schedule": {"id": "fullDay"},
}

response = client.create_vacancy(vacancy_data)
print(response["id"])

Django integration example

Assuming you have a model like OrganizationHHAccount with methods:

• get_valid_access_token()
• refresh_access_token()

and you store it per organization:

from hh_api_client import HHAPIClient
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    return HHAPIClient(organization_hh_account=hh_account)

Configuring base URL (hh.uz vs hh.ru)

By default this client uses the Uzbekistan API base URL https://api.hh.uz because that is a common production setup.

If you need to change it (for example to https://api.hh.ru), use HHAPIClientConfig:

from django.conf import settings
from hh_api_client import HHAPIClient, HHAPIClientConfig
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    config = HHAPIClientConfig(base_url=getattr(settings, "HH_API_BASE_URL", "https://api.hh.uz"))
    return HHAPIClient(organization_hh_account=hh_account, config=config)

You can wire it to your existing settings:

# settings/base.py
HH_CLIENT_ID = env.str("HH_CLIENT_ID", default="")
HH_CLIENT_SECRET = env.str("HH_CLIENT_SECRET", default="")
HH_REDIRECT_URI = env.str("HH_REDIRECT_URI", default="")
HH_API_BASE_URL = "https://api.hh.uz"  # or api.hh.ru
HH_OAUTH_BASE_URL = "https://hh.uz"

Then your existing usage in signal handlers and DRF views can stay almost the same, just update the import:

from hh_api_client import HHAPIClient

Safety and error handling

• No secrets (tokens) are ever logged.
• Network errors raise requests.RequestException.
• API-level errors raise hh_api_client.HHAPIError with a sanitized message.
• Automatic token refresh is attempted once on 401 responses when a token provider is used.

Endpoints covered

High-level helpers currently implemented:

• get_user_info()
• get_employer_info()
• get_managers()
• get_default_manager_id()
• get_employer_services()
• get_publication_status()
• test_connection()

Vacancies:

• create_vacancy()
• update_vacancy()
• archive_vacancy()
• publish_vacancy()
• extend_vacancy()
• get_vacancy()
• get_vacancies()

Resumes:

• search_resumes()
• get_resume()

Negotiations:

• get_negotiations()
• get_vacancy_candidates()

Releasing (for maintainers)

This project is configured to publish using GitHub Actions and PyPI's OpenID Connect (OIDC) publisher.

• A GitHub Actions workflow lives at .github/workflows/workflow.yml.
• When you push a tag like v0.1.0 to the hh-api-client repository on GitHub, the workflow:
  • Builds the package with python -m build.
  • Publishes the distributions to TestPyPI (environment testpypi).
  • Then publishes the same build to PyPI (environment pypi).

To cut a new release:

1. Bump the version in pyproject.toml.

2. Commit and push to main.

3. Create and push a tag, e.g.:

   git tag v0.1.2
   git push origin v0.1.2
   

4. Wait for the GitHub Actions workflow to complete; the new version will appear on both TestPyPI and PyPI (assuming both publishers are configured).