Files
jobboard/plugins/readers/workable.py
T
WolfandClaude Opus 5.5 c497fe965d Keep a description's headings, bullets and paragraphs, and draw them in the reader
The readers flattened a posting's HTML into one line with strip_html, so
sections and bullets ran together. _shared.html_text gives a line per
paragraph, '• ' before a list item and '## ' before a heading; every
reader's description goes through it, sections read per role get their
own headings, and the reader pane draws the lines as h3, ul and p.
Excerpts leave the marks out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 21:40:12 +02:00

152 lines
6.1 KiB
Python

"""Workable: `workable:<account>`, paged ten roles at a time with a stated
total.
Written from one real board, Hugging Face's, on 2026-09-28, when the first
board with roles was seen; jobhunt-hq did not read Workable.
The list carries no text. The text is read per role by `detail`, `GET
/api/v2/accounts/{slug}/jobs/{shortcode}` (checked 2026-09-30, Hugging Face's
DB4D7C0EC8): the list's fields again, and `description`, `requirements` and
`benefits` as HTML. The list gives the numeric `id` and the `shortcode`; the
role's `source_id` is the number, so the row keeps the `shortcode` for this
request. The API answers 429 to a run of requests; the runner spaces the
reads and stops on one.
"""
from __future__ import annotations
import json
from collections.abc import Callable
from typing import Any
from ._contract import Ask, Fields, Place, Reads
from ._shared import Get, HEADING, Page, Row, add_place, html_text, only, parse_dt, path_slug_ok
NAME = "workable"
LABEL = "Workable"
RANK = 40
PATTERNS = (
r"apply\.workable\.com/(?:api/v\d/accounts/)?([A-Za-z0-9_-]+)",
r"https?://(?!apply\.|www\.)([a-z0-9-]+)\.workable\.com",
)
READS = Reads(
scope="board", listing="paged", page_size=10, text="detail", complete="stated",
places="many",
fields=Fields(posted="trusted", remote="stated", employment="stated"),
robots=("read: apply.workable.com's robots.txt disallows nothing (an empty Disallow), so "
"POST /api/v3/accounts/<slug>/jobs and /api/v2/accounts/<slug>/jobs/<shortcode> "
"are allowed (checked 2026-09-30)"),
)
_API = "apply.workable.com"
# No probe: Workable's API sits behind a rate limit that a run of guesses
# trips, and a Workable site links its board plainly anyway.
def slug_ok(slug: str) -> bool:
return path_slug_ok(slug)
def allowed(slug: str) -> Callable[[str], bool]:
return only(_API)
def careers_url(slug: str) -> str:
return f"https://{_API}/{slug}"
def page(get: Get, slug: str, cursor: Any, ask: Ask = Ask()) -> Page:
"""One POST of the list; the next page is the same POST with
`{"token": nextPage}`, and the last page has no `nextPage`."""
url = f"https://{_API}/api/v3/accounts/{slug}/jobs"
data = json.loads(get(url, method="POST", payload={"token": cursor} if cursor else {}))
return data, data.get("results") or [], data.get("total"), data.get("nextPage") or None
def parse(body: bytes, slug: str) -> list[Row]:
return rows(json.loads(body), slug)
def _places(job: dict[str, Any], remote: bool) -> list[Place]:
"""Every place of a role. `locations`
lists them (city, region, country; `hidden` ones are stated too), and
`location` is the first alone, the fallback for a role that lists none.
A place is remote when the role is."""
found: list[Place] = []
listed = [loc for loc in job.get("locations") or [] if isinstance(loc, dict)]
for loc in listed or [job.get("location") or {}]:
parts: list[str] = []
for part in (loc.get("city"), loc.get("region"), loc.get("country")):
part = str(part or "").strip()
if part and part not in parts:
parts.append(part)
text = ", ".join(parts)
add_place(found, {"text": text, "remote": remote})
return found
def rows(data: dict[str, Any], slug: str) -> list[Row]:
"""One page of POST https://apply.workable.com/api/v3/accounts/{slug}/jobs
-> `{"total": int, "results": [...], "nextPage": token}`, as Hugging
Face's board answered on 2026-09-28. A result carries no URL and no text:
the job page is `https://apply.workable.com/{slug}/j/{shortcode}/`, and
the description is only on the per-job endpoint, which `detail` reads, so
`description` stays empty here. The `shortcode` is kept in the row for it.
`location` is the first place and `locations` all of them; `department`
is a list; `remote` is a flag beside `workplace` (remote, hybrid,
on_site); `type` is the hours or the contract (full, part, ...)."""
out = []
for j in data.get("results") or []:
title = (j.get("title") or "").strip()
shortcode = (j.get("shortcode") or "").strip()
if not title or not shortcode:
continue
workplace = str(j.get("workplace") or "").strip()
remote = bool(j.get("remote")) or workplace == "remote"
places = _places(j, remote)
dept = j.get("department") or ""
if isinstance(dept, list):
dept = ", ".join(d for d in dept if d)
out.append({
"source_id": str(j.get("id") or shortcode),
"shortcode": shortcode,
"title": title,
"places": places,
"location": "; ".join(p["text"] for p in places),
"url": f"https://{_API}/{slug}/j/{shortcode}/",
"posted": parse_dt(j.get("published")),
"department": dept.strip(),
"description": "",
"remote": workplace or j.get("remote"),
"salary_text": "", # Workable's list endpoint states no pay at all
"employment": str(j.get("type") or "").strip() or None,
})
return out
#: The parts of a role's ad that make its description, in reading order.
_PARTS = ("description", "requirements", "benefits")
def detail(get: Get, slug: str, row: Row) -> dict[str, Any]:
"""`/api/v2/accounts/{slug}/jobs/{shortcode}` -> the HTML of
`description`, `requirements` and `benefits`, joined as one text. An
answer with none of the three keys is not a role and raises, so the role
is asked again on a later pull."""
shortcode = str(row.get("shortcode") or "")
if not path_slug_ok(shortcode):
raise ValueError(f"no Workable shortcode in the row: {shortcode!r}")
data = json.loads(get(f"https://{_API}/api/v2/accounts/{slug}/jobs/{shortcode}"))
if not isinstance(data, dict) or not any(k in data for k in _PARTS):
raise ValueError("not a Workable role: no description")
parts = []
for key in _PARTS:
if text := html_text(data.get(key)):
if key != "description":
parts.append(HEADING + key.capitalize())
parts.append(text)
return {"description": "\n".join(parts)}