Files
jobboard/plugins/readers/pinpoint.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

149 lines
6.2 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 json
from collections.abc import Callable
from typing import Any
from ._contract import Ask, Fields, Reads
from ._shared import HEADING, Row, html_text, is_web_url, label_slug_ok, num, only, pay_line, yearly_amount
NAME = "pinpoint"
LABEL = "Pinpoint"
PATTERNS = (r"https?://([a-z0-9-]+)\.pinpointhq\.com",)
READS = Reads(
scope="board", listing="whole", text="listing", complete="whole", places="one",
fields=Fields(pay="figures", remote="stated", employment="stated"),
robots="read: robots.txt allows / (checked 2026-09-29)",
)
#: `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 feed_url(slug: str, ask: Ask = Ask()) -> str:
return f"https://{host(slug)}/postings.json"
def _text(j: dict[str, Any]) -> str:
"""The description and the sections after it, each section under its own
heading, as `html_text` lines."""
parts = [html_text(j.get("description"))]
for field in _SECTIONS:
body = html_text(j.get(field))
if body:
if heading := " ".join(str(j.get(f"{field}_header") or "").split()):
parts.append(HEADING + heading)
parts.append(body)
return "\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)
workplace = str(j.get("workplace_type") or "").strip()
place = _place(j.get("location") or {})
out.append({
"source_id": source_id,
"title": title,
"places": [{"text": place, "remote": {"remote": True, "onsite": False,
"on_site": False, "hybrid": False}.get(workplace.lower())}]
if place else [],
"location": place,
"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": workplace or None,
"employment": str(j.get("employment_type") or "").strip() or None,
"salary_text": salary_text,
"salary_min": low,
"salary_max": high,
"currency": currency,
})
return out