Files
jobboard/plugins/readers/lever.py
T

157 lines
6.0 KiB
Python

"""Lever: `lever:<site>`, or `lever:eu/<site>` for a board on Lever's EU
instance, the whole board in one JSON answer.
Lever runs two instances that share nothing but the API: `api.lever.co` and
`api.eu.lever.co`, with the pages on `jobs.lever.co` and `jobs.eu.lever.co`.
A site exists on one of them only (TomTom and Prima answer 404 on the other,
2026-09-29), and the same name on both would be two companies, so the region
is part of the slug. It is a prefix a plain site name cannot carry, since a
Lever site name has no slash, which leaves every `lever:<site>` target as it
was.
The field map is ported from `openings.go` in
[jobhunt-hq](https://github.com/rembrandtreyes/jobhunt-hq) (MIT).
"""
from __future__ import annotations
import json
import logging
from collections.abc import Callable
from typing import Any
from ._contract import Ask, Fields, Place, Reads, Row
from ._shared import add_place, html_text, num, only, parse_dt, path_slug_ok, pay_line, place, yearly_amount
log = logging.getLogger(__name__)
READS = Reads(
scope="board", listing="whole", text="listing", complete="whole",
places="many",
fields=Fields(pay="figures", posted="trusted", remote="stated", country="stated",
employment="stated"),
robots=("read: robots.txt of api.lever.co and api.eu.lever.co allows /, so "
"/v0/postings/<site>, with crawl-delay 1, one request a board (checked 2026-09-30)"),
)
NAME = "lever"
LABEL = "Lever"
RANK = 20
#: Two groups on the EU hosts, `eu` and the site, which discovery joins into
#: the slug `eu/<site>`.
PATTERNS = (
r"jobs\.lever\.co/([A-Za-z0-9_-]+)",
r"api\.lever\.co/v0/postings/([A-Za-z0-9_-]+)",
r"jobs\.(eu)\.lever\.co/([A-Za-z0-9_-]+)",
r"api\.(eu)\.lever\.co/v0/postings/([A-Za-z0-9_-]+)",
)
#: The region prefixes a slug may carry, to the infix of both host names.
_REGIONS = {"eu": "eu."}
def _split(slug: str) -> tuple[str, str]:
"""`(host infix, site)`: `("eu.", "tomtom")` for `eu/tomtom`, `("", "acme")`
for `acme`."""
region, sep, site = slug.partition("/")
return (_REGIONS.get(region, "?"), site) if sep else ("", slug)
def slug_ok(slug: str) -> bool:
infix, site = _split(slug)
return infix != "?" and path_slug_ok(site)
def allowed(slug: str) -> Callable[[str], bool]:
return only(f"api.{_split(slug)[0]}lever.co")
def careers_url(slug: str) -> str:
infix, site = _split(slug)
return f"https://jobs.{infix}lever.co/{site}"
def feed_url(slug: str, ask: Ask) -> str:
infix, site = _split(slug)
return f"https://api.{infix}lever.co/v0/postings/{site}?mode=json"
def probe_url(slug: str) -> str:
infix, site = _split(slug)
return f"https://api.{infix}lever.co/v0/postings/{site}?limit=1&mode=json"
def probe_slugs(guess: str) -> tuple[str, ...]:
"""A name is tried on both instances, the US one first, since a site that
names neither leaves no other way to tell which one it is on."""
return (guess, *(f"{region}/{guess}" for region in _REGIONS))
def _salary_text(salary_range: dict[str, Any]) -> str:
"""One line from `salaryRange`, whatever its `interval` — including an
hourly or daily one, which `yearly_amount` drops from the columns.
Lever's interval is "per-<period>-<kind>" ("per-year-salary",
"per-hour-wage"); the middle word is the period."""
interval = str(salary_range.get("interval") or "")
parts = interval.split("-")
period = parts[1] if len(parts) >= 3 else ""
return pay_line(num(salary_range.get("min")), num(salary_range.get("max")),
salary_range.get("currency"), period)
def _places(categories: dict[str, Any]) -> list[Place]:
"""`categories.allLocations` (every place of the role, the first being
`location`), or `location` alone when the list is missing."""
names = [categories.get("location"), *(categories.get("allLocations") or [])]
out: list[Place] = []
for name in names:
text = str(name or "").strip()
add_place(out, place(text))
return out
def parse(body: bytes, slug: str) -> list[Row]:
"""The board's postings, a JSON list. Any other answer (an error
document sent with a 200) raises, so the read fails and closes nothing
rather than reading as a board with no roles."""
data = json.loads(body)
if not isinstance(data, list):
raise ValueError(f"Lever's answer is a JSON {type(data).__name__}, "
"not a list of postings")
rows = []
for j in data:
title = (j.get("text") or "").strip()
url = (j.get("hostedUrl") or "").strip()
categories = j.get("categories") or {}
description = j.get("description") or j.get("descriptionPlain") or ""
salary_range = j.get("salaryRange") or {}
salary_min, salary_max, currency = yearly_amount(
salary_range.get("min"), salary_range.get("max"), salary_range.get("currency"),
salary_range.get("interval"), {"per-year-salary": 1, "per-month-salary": 12})
places = _places(categories)
row: Row = {
"source_id": str(j.get("id") or ""),
"title": title,
"places": places,
"location": "; ".join(p["text"] for p in places),
"url": url,
"posted": parse_dt(j.get("createdAt")),
"department": (categories.get("department") or categories.get("team") or "").strip(),
"description": html_text(description),
"remote": (j.get("workplaceType") or "").strip() or None,
"salary_text": _salary_text(salary_range),
"salary_min": salary_min,
"salary_max": salary_max,
"currency": currency,
}
# `country` is one code, for a role at one place; over several it would
# gate the others by the first's country.
country = str(j.get("country") or "").strip()
if len(places) == 1 and country:
row["country"] = country
if employment := str(categories.get("commitment") or "").strip():
row["employment"] = employment
rows.append(row)
return rows