Files
jobboard/plugins/readers/pinpoint.py
T
WolfandClaude Opus 5.5 73dec9028e Rename plugins/atshosts to plugins/readers
Every import, test and live doc follows the new path; behaviour is unchanged.
tests/test_atshosts.py becomes tests/test_readers.py. plan-readers.md and
review-ingest.md keep the old name, since they describe the state before.

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

150 lines
6.0 KiB
Python

"""Pinpoint: `pinpoint:<subdomain>` for acme.pinpointhq.com, the whole board
in one JSON answer. There is no probe: an unknown subdomain's answer was not
checked, and a board is found by the link a career site carries.
Written from Xeneta's board on 2026-09-29 (two roles); jobhunt-hq did not read
Pinpoint. Unverified: whether a large board pages `/postings.json` (the answer
has a `data` list and no paging keys, so every board is read as complete
here), and the spelling of `compensation_frequency`, since no board read so far
shows its pay (`compensation_visible` was false on both roles). A board shared
by several brands (inMusic's, with Native Instruments on it) is read whole;
there is no filter on `job.division`.
There is no posted date in the listing, only in each posting's page as JSON-LD,
so `posted` stays None rather than costing a request a role for it.
"""
from __future__ import annotations
import html
import json
from collections.abc import Callable
from typing import Any
from desk.sources import strip_html
from ._shared import Row, is_web_url, label_slug_ok, num, only, pay_line, yearly_amount
NAME = "pinpoint"
LABEL = "Pinpoint"
PATTERNS = (r"https?://([a-z0-9-]+)\.pinpointhq\.com",)
#: `workplace_type` -> `store._remote`'s words. Anything else says nothing.
_REMOTE = {"onsite": "onsite", "on_site": "onsite", "hybrid": "hybrid", "remote": "remote"}
#: `compensation_frequency` -> the multiplier that makes a figure yearly. The
#: spellings are a guess, since no board read so far states pay; a frequency
#: not listed leaves the yearly columns empty, and `salary_text` still says it.
_YEARLY = {"annually": 1, "annual": 1, "yearly": 1, "year": 1, "monthly": 12, "month": 12}
#: `compensation_frequency` -> the word `salary_text` says after "per".
_PERIOD = {"annually": "year", "annual": "year", "yearly": "year", "monthly": "month",
"weekly": "week", "daily": "day", "hourly": "hour"}
#: The sections of a posting's text, in the order the page shows them: the
#: description, then these fields, each with its own heading in `<field>_header`.
_SECTIONS = ("key_responsibilities", "skills_knowledge_expertise", "benefits")
def host(slug: str) -> str:
return f"{slug.lower()}.pinpointhq.com"
def slug_ok(slug: str) -> bool:
return label_slug_ok(slug)
def allowed(slug: str) -> Callable[[str], bool]:
return only(host(slug))
def careers_url(slug: str) -> str:
return f"https://{host(slug)}/"
def robots_page(slug: str) -> str:
return careers_url(slug)
def feed_url(slug: str) -> str:
return f"https://{host(slug)}/postings.json"
def _plain(markup: Any) -> str:
"""HTML as one line of plain text: the tags out, the entities read (Pinpoint
writes `&amp;` and `&nbsp;`), the whitespace, non-breaking included, collapsed."""
return " ".join(html.unescape(strip_html(str(markup or ""))).split())
def _text(j: dict[str, Any]) -> str:
"""The description and the sections after it, each section under its own
heading, as plain text with a blank line between them."""
parts = [_plain(j.get("description"))]
for field in _SECTIONS:
body = _plain(j.get(field))
if body:
heading = str(j.get(f"{field}_header") or "").strip()
parts.append(f"{heading}: {body}" if heading else body)
return "\n\n".join(p for p in parts if p)
def _place(location: dict[str, Any]) -> str:
"""The place's name, then its `province` where that says more. Pinpoint
fills `province` with a region or a country as the company typed it, so it
is kept only when it differs from the name."""
parts: list[str] = []
for part in (location.get("name") or location.get("city"), location.get("province")):
part = str(part or "").strip()
if part and part.lower() not in (p.lower() for p in parts):
parts.append(part)
return ", ".join(parts)
def _pay(j: dict[str, Any]) -> tuple[int | None, int | None, str, str]:
"""`(salary_min, salary_max, currency, salary_text)` of a posting whose
pay is shown (`compensation_visible`); the free-text `compensation` is the
line when the bounds are not given."""
if not j.get("compensation_visible"):
return None, None, "", ""
lo, hi = num(j.get("compensation_minimum")), num(j.get("compensation_maximum"))
frequency = str(j.get("compensation_frequency") or "").strip().lower()
period = _PERIOD.get(frequency, frequency)
text = pay_line(lo, hi, j.get("compensation_currency"), period)
text = text or str(j.get("compensation") or "").strip()
low, high, code = yearly_amount(lo, hi, j.get("compensation_currency"), frequency, _YEARLY)
return low, high, code, text
def parse(body: bytes, slug: str) -> list[Row]:
"""`{slug}.pinpointhq.com/postings.json` -> `{"data": [...]}`. A posting has
`id`, `title`, `url`, `location` (`name`, `city`, `province`),
`workplace_type`, `job` (`requisition_id`, `department`, `division`), the
HTML `description` and its sections, and the `compensation_*` fields."""
data = json.loads(body)
if not isinstance(data, dict) or not isinstance(data.get("data"), list):
raise ValueError("not a Pinpoint listing: no data list")
out = []
for j in data["data"]:
title = (j.get("title") or "").strip()
url = (j.get("url") or "").strip()
source_id = str(j.get("id") or "")
if not title or not source_id or not is_web_url(url):
continue
job = j.get("job") or {}
low, high, currency, salary_text = _pay(j)
out.append({
"source_id": source_id,
"title": title,
"location": _place(j.get("location") or {}),
"url": url,
"posted": None, # only the posting's own page has a date
"department": str((job.get("department") or {}).get("name") or "").strip(),
"description": _text(j),
"remote": _REMOTE.get(str(j.get("workplace_type") or "").strip().lower()),
"salary_text": salary_text,
"salary_min": low,
"salary_max": high,
"currency": currency,
})
return out