openroles 0.1.0__py3-none-any.whl

openroles/__init__.py

@@ -0,0 +1,84 @@
+"""openroles: every open role, straight from the employer's own applicant tracking system.
+
+    >>> import openroles
+    >>> openroles.detect("https://jobs.lever.co/acme")
+    [Board(ats='lever', token='acme')]
+    >>> jobs = openroles.fetch("greenhouse:acme", query="data analyst", location="London")
+
+Greenhouse, Lever, Ashby and Workday, read from the same public JSON their own
+careers pages use: no key, no account, no scraping service, and nothing but the
+Python standard library.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+import datetime as _dt
+from typing import Callable, Iterable, List, Optional, Union
+
+from .models import ATS, Board, BoardError, Job, RobotsDisallowed
+
+__all__ = ["ATS", "Board", "BoardError", "Job", "RobotsDisallowed", "__version__",
+           "detect", "fetch"]
+
+
+def detect(target: str) -> List[Board]:
+    """The job boards behind a board URL, "ats:token", a careers page or a company name."""
+    from .discover import detect as _detect
+    return _detect(target)
+
+
+def _boards(target: Union[str, Board]) -> List[Board]:
+    if isinstance(target, Board):
+        return [target]
+    found = detect(target)
+    if not found:
+        raise BoardError(f"no Greenhouse, Lever, Ashby or Workday board found for {target!r}")
+    return found
+
+
+def _matches(job: Job, query: Optional[str], location: Optional[str],
+             remote: Optional[bool], since: Optional[_dt.date]) -> bool:
+    if query and not all(w in job.title.lower() for w in query.lower().split()):
+        return False
+    if location:
+        where = " ".join([job.location] + job.locations).lower()
+        if location.lower() not in where:
+            return False
+    if remote is not None and bool(job.remote) != remote:
+        return False
+    if since and job.posted and job.posted < since.isoformat():
+        return False
+    return True
+
+
+def fetch(target: Union[str, Board], query: Optional[str] = None,
+          location: Optional[str] = None, remote: Optional[bool] = None,
+          since_days: Optional[int] = None, limit: Optional[int] = None,
+          details: Union[None, bool, Callable[[Job], bool]] = None,
+          country: str = "", workday_queries: Optional[Iterable[str]] = None) -> List[Job]:
+    """Open roles from one employer's board (or every board `detect` finds for a name).
+
+    query       words that must all appear in the title (Workday also searches with it)
+    location    text that must appear in a location ("London", "Remote")
+    remote      True for remote roles only, False for on-site and hybrid only
+    since_days  posted within this many days (roles with no date are kept)
+    limit       at most this many roles, newest first
+    details     Workday only: fetch each posting's page for its description (one
+                request each). Defaults to True when `query` narrows the board.
+    country     Workday only: narrow the board to one country by name ("Canada")
+    """
+    from .providers import READERS
+    since = (_dt.date.today() - _dt.timedelta(days=since_days)) if since_days else None
+    jobs: List[Job] = []
+    for board in _boards(target):
+        reader = READERS[board.ats]
+        if board.ats == "workday":
+            queries = list(workday_queries) if workday_queries else (query or None)
+            got = reader.fetch(board.token, query=queries, country=country,
+                               details=bool(query) if details is None else details)
+        else:
+            got = reader.fetch(board.token)
+        jobs.extend(j for j in got if _matches(j, query, location, remote, since))
+    jobs.sort(key=lambda j: j.posted or "", reverse=True)
+    return jobs[:limit] if limit else jobs

openroles/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

openroles/_http.py

@@ -0,0 +1,130 @@
+"""The one place openroles talks to the network.
+
+Polite by construction: at most PER_HOST requests in flight to any one host, a timeout
+on every call, an honest User-Agent, and robots.txt read once per host per process.
+"""
+from __future__ import annotations
+
+import http.client
+import json
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Optional, Tuple
+
+from . import __version__
+from .robots import allowed, is_robots_body
+
+USER_AGENT = f"openroles/{__version__} (+https://github.com/aranculleton/openroles)"
+TIMEOUT = 20
+PER_HOST = 2
+RETRY_PAUSE = 2.0
+
+_SLOTS: dict = {}
+_SLOTS_LOCK = threading.Lock()
+
+
+def _slot(host: str) -> threading.BoundedSemaphore:
+    with _SLOTS_LOCK:
+        return _SLOTS.setdefault(host.lower(), threading.BoundedSemaphore(PER_HOST))
+
+
+def request(url: str, payload: Optional[dict] = None,
+            accept: str = "application/json") -> Tuple[Optional[object], Optional[str]]:
+    """(parsed JSON, None) or (None, why). A GET, or a JSON POST when `payload` is given."""
+    raw, err = request_raw(url, payload, accept)
+    if err:
+        return None, err
+    try:
+        return json.loads(raw), None
+    except ValueError:
+        return None, "the response was not JSON"
+
+
+def request_raw(url: str, payload: Optional[dict] = None,
+                accept: str = "*/*", limit: int = 100_000_000) -> Tuple[str, Optional[str]]:
+    """(body as text, None) or ("", why)."""
+    headers = {"User-Agent": USER_AGENT, "Accept": accept}
+    data = None
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    host = urllib.parse.urlsplit(url).netloc
+    err = None
+    # One retry, after a pause, for a dropped connection or a gateway error. Never for
+    # 429 or 503: those mean slow down, and the caller decides what that means.
+    for attempt in range(2):
+        if attempt:
+            time.sleep(RETRY_PAUSE)
+        try:
+            req = urllib.request.Request(url, data=data, headers=headers,
+                                         method="POST" if data is not None else "GET")
+            with _slot(host):
+                with urllib.request.urlopen(req, timeout=TIMEOUT) as fh:
+                    return fh.read(limit).decode("utf-8", "replace"), None
+        except urllib.error.HTTPError as e:
+            err = f"HTTP {e.code}"
+            if e.code not in (502, 504):
+                break
+        # HTTPException covers a body cut off mid-read, which is not an OSError.
+        except (urllib.error.URLError, http.client.HTTPException, OSError, ValueError) as e:
+            err = type(e).__name__
+    return "", err
+
+
+# ------------------------------------------------------------------ robots.txt
+
+# Statuses that mean no policy is published. RFC 9309 section 2.3.1.3 reads an
+# unavailable robots.txt as no restriction. A 403 is left out on purpose: on
+# robots.txt it is usually a firewall refusing an unknown client. A 429, a 5xx or
+# no answer means the policy could not be read, which the RFC treats as disallow.
+NO_POLICY = {401, 404, 410}
+AGENTS = ("*", "openroles")
+
+_ROBOTS: dict = {}
+_ROBOTS_LOCK = threading.Lock()
+
+
+def robots_txt(host: str) -> Tuple[int, str]:
+    """(HTTP status, body) for https://<host>/robots.txt, fetched once per process.
+
+    Status 0 means no answer at all.
+    """
+    key = host.lower()
+    with _ROBOTS_LOCK:
+        if key in _ROBOTS:
+            return _ROBOTS[key]
+    req = urllib.request.Request(f"https://{key}/robots.txt",
+                                 headers={"User-Agent": USER_AGENT,
+                                          "Accept": "text/plain,*/*"})
+    try:
+        with _slot(key):
+            with urllib.request.urlopen(req, timeout=TIMEOUT) as fh:
+                got = (fh.status, fh.read(512_000).decode("utf-8", "replace"))
+    except urllib.error.HTTPError as e:
+        got = (e.code, "")
+    except (urllib.error.URLError, http.client.HTTPException, OSError, ValueError):
+        got = (0, "")
+    with _ROBOTS_LOCK:
+        _ROBOTS[key] = got
+    return got
+
+
+def robots_allows(host: str, paths) -> Tuple[bool, str]:
+    """(may these paths be read, why), from the host's robots.txt."""
+    status, body = robots_txt(host)
+    if status == 200:
+        if not is_robots_body(body):
+            return False, ("robots.txt answered 200 with something that is not a robots "
+                           "file, so permission is unconfirmed")
+        for path in paths:
+            for agent in AGENTS:
+                if not allowed(body, agent, path):
+                    return False, f"robots.txt on {host} disallows {path}"
+        return True, "robots.txt allows it"
+    if status in NO_POLICY:
+        return True, f"no robots.txt (HTTP {status}), which RFC 9309 reads as no restriction"
+    seen = f"HTTP {status}" if status else "no answer"
+    return False, f"robots.txt on {host} could not be read ({seen}), so permission is unconfirmed"

openroles/cli.py

@@ -0,0 +1,86 @@
+"""openroles on the command line.
+
+    openroles <company, careers URL, board URL or ats:token> [filters]
+    openroles detect <company or URL>
+    openroles mcp                      # serve the tools to an MCP client over stdio
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from typing import List, Optional
+
+from . import BoardError, Job, __version__, detect, fetch
+
+
+def _table(jobs: List[Job]) -> str:
+    if not jobs:
+        return "no open roles matched"
+    rows = [(j.posted or "-", j.title, j.location or "-", j.url) for j in jobs]
+    w0 = max(len(r[0]) for r in rows)
+    w1 = min(60, max(len(r[1]) for r in rows))
+    w2 = min(40, max(len(r[2]) for r in rows))
+    out = [f"{r[0]:<{w0}}  {r[1][:w1]:<{w1}}  {r[2][:w2]:<{w2}}  {r[3]}" for r in rows]
+    return "\n".join(out) + f"\n\n{len(jobs)} open role(s)"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "mcp":
+        from .mcp import serve
+        return serve()
+    if argv and argv[0] == "detect":
+        ap = argparse.ArgumentParser(prog="openroles detect",
+                                     description="Find the job boards behind a company or URL.")
+        ap.add_argument("target")
+        a = ap.parse_args(argv[1:])
+        boards = detect(a.target)
+        for b in boards:
+            print(b)
+        if not boards:
+            print(f"no Greenhouse, Lever, Ashby or Workday board found for {a.target!r}",
+                  file=sys.stderr)
+        return 0 if boards else 1
+
+    ap = argparse.ArgumentParser(
+        prog="openroles",
+        description="Every open role, straight from the employer's own ATS "
+                    "(Greenhouse, Lever, Ashby, Workday).",
+        epilog="Also: `openroles detect <target>` and `openroles mcp`.")
+    ap.add_argument("target", help="a company name, a careers or board URL, or ats:token")
+    ap.add_argument("-q", "--query", help="words that must all appear in the title")
+    ap.add_argument("-l", "--location", help="text that must appear in a location")
+    ap.add_argument("--remote", action="store_true", help="remote roles only")
+    ap.add_argument("--since", type=int, metavar="DAYS", help="posted within DAYS days")
+    ap.add_argument("-n", "--limit", type=int, help="at most N roles, newest first")
+    ap.add_argument("--country", default="", help="Workday: narrow to one country by name")
+    ap.add_argument("--details", action="store_true",
+                    help="Workday: fetch every posting's description (one request each)")
+    ap.add_argument("--json", action="store_true", help="JSON array (the default when piped)")
+    ap.add_argument("--jsonl", action="store_true", help="one JSON object per line")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    ap.add_argument("--version", action="version", version=f"openroles {__version__}")
+    a = ap.parse_args(argv)
+    logging.basicConfig(level=logging.INFO if a.verbose else logging.WARNING,
+                        format="%(name)s: %(message)s")
+    try:
+        jobs = fetch(a.target, query=a.query, location=a.location,
+                     remote=True if a.remote else None, since_days=a.since, limit=a.limit,
+                     details=True if a.details else None, country=a.country)
+    except BoardError as e:
+        print(f"openroles: {e}", file=sys.stderr)
+        return 1
+    if a.jsonl:
+        for j in jobs:
+            print(json.dumps(j.to_dict(), ensure_ascii=False))
+    elif a.json or not sys.stdout.isatty():
+        print(json.dumps([j.to_dict() for j in jobs], ensure_ascii=False, indent=2))
+    else:
+        print(_table(jobs))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openroles/discover.py

@@ -0,0 +1,101 @@
+"""Which ATS an employer's jobs live on, from a URL, a careers page or a company name."""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+from urllib.parse import parse_qs, urlsplit
+
+from . import _http
+from .models import ATS, Board
+from .providers import ashby, greenhouse, lever, workday
+
+_SLUG = r"([A-Za-z0-9][A-Za-z0-9_.-]*)"
+PATTERNS = [
+    ("greenhouse", re.compile(r"(?:job-boards|boards)(?:\.eu)?\.greenhouse\.io/embed/job_board(?:/js)?\?for=" + _SLUG, re.I)),
+    ("greenhouse", re.compile(r"boards-api\.greenhouse\.io/v1/boards/" + _SLUG, re.I)),
+    ("greenhouse", re.compile(r"(?:job-boards|boards)(?:\.eu)?\.greenhouse\.io/(?!embed\b)" + _SLUG, re.I)),
+    ("lever", re.compile(r"jobs(?:\.eu)?\.lever\.co/" + _SLUG, re.I)),
+    ("lever", re.compile(r"api(?:\.eu)?\.lever\.co/v0/postings/" + _SLUG, re.I)),
+    ("ashby", re.compile(r"jobs\.ashbyhq\.com/" + _SLUG, re.I)),
+    ("ashby", re.compile(r"api\.ashbyhq\.com/posting-api/job-board/" + _SLUG, re.I)),
+]
+_NOT_A_BOARD = {"embed", "js", "v1", "api", "static", "assets", "favicon.ico", "robots.txt"}
+
+
+def parse(text: str) -> Optional[Board]:
+    """A Board from "ats:token" or from any board URL. None when it names no board."""
+    text = (text or "").strip()
+    head, sep, tail = text.partition(":")
+    if sep and head.lower() in ATS and not tail.startswith("//"):
+        token = tail.strip()
+        if head.lower() == "workday":
+            token = workday.token_from(token) or token
+        return Board(head.lower(), token) if token else None
+    wd = workday.token_from(text)
+    if wd:
+        return Board("workday", wd)
+    if "greenhouse.io" in text and "for=" in text:
+        q = parse_qs(urlsplit(text if "//" in text else "https://" + text).query)
+        if q.get("for"):
+            return Board("greenhouse", q["for"][0])
+    for ats, rx in PATTERNS:
+        m = rx.search(text)
+        if m and m.group(1).lower() not in _NOT_A_BOARD:
+            return Board(ats, m.group(1).rstrip("."))
+    return None
+
+
+def in_page(url: str) -> List[Board]:
+    """Every board a careers page links to or embeds, if its robots.txt allows reading it."""
+    parts = urlsplit(url if "//" in url else "https://" + url)
+    path = parts.path or "/"
+    ok, _why = _http.robots_allows(parts.netloc, [path])
+    if not ok:
+        return []
+    body, err = _http.request_raw(parts.geturl(), accept="text/html,*/*", limit=3_000_000)
+    if err:
+        return []
+    found = []
+    for m in re.finditer(r"https?://[^\s\"'<>)]+", body):
+        board = parse(m.group(0))
+        if board and board not in found:
+            found.append(board)
+    return found
+
+
+def slugs(company: str) -> List[str]:
+    """The board names an employer is likely to use: "Acme Data Ltd" -> acmedata, acme-data, acme."""
+    words = re.findall(r"[a-z0-9]+", company.lower().replace("&", " and "))
+    suffixes = {"inc", "ltd", "llc", "plc", "limited", "corp", "corporation", "co", "group",
+                "gmbh", "ag", "sa", "bv", "the"}
+    core = [w for w in words if w not in suffixes] or words
+    out = ["".join(core), "-".join(core), core[0] if core else ""]
+    return [s for s in dict.fromkeys(out) if s]
+
+
+def guess(company: str) -> List[Board]:
+    """Boards found by trying the employer's likely board names on Greenhouse, Lever and Ashby.
+
+    Workday cannot be guessed from a name (its address needs a tenant, a data centre
+    and a site name): give its careers URL instead.
+    """
+    found = []
+    for slug in slugs(company):
+        for ats, reader in (("greenhouse", greenhouse), ("lever", lever), ("ashby", ashby)):
+            if reader.exists(slug):
+                board = Board(ats, slug)
+                if board not in found:
+                    found.append(board)
+        if found:
+            break
+    return found
+
+
+def detect(target: str) -> List[Board]:
+    """The boards behind a board URL, an "ats:token", a careers page or a company name."""
+    board = parse(target)
+    if board:
+        return [board]
+    if re.match(r"^(https?://|www\.)|^[a-z0-9-]+(\.[a-z0-9-]+)+(/|$)", target.strip(), re.I):
+        return in_page(target.strip())
+    return guess(target)

openroles/mcp.py

@@ -0,0 +1,145 @@
+"""A Model Context Protocol server over stdio, with no dependencies.
+
+    openroles mcp
+
+Add it to an MCP client (Claude Code, Claude Desktop, Cursor and others) as a stdio
+server whose command is `openroles` with the argument `mcp`, or `uvx openroles mcp`.
+It offers two tools: find_job_board and list_open_roles.
+
+The protocol is JSON-RPC 2.0, one message per line on stdin and stdout. Only what a
+tools server needs is implemented: initialize, ping, tools/list and tools/call.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+from . import BoardError, __version__, detect, fetch
+
+PROTOCOL_VERSIONS = ("2025-06-18", "2025-03-26", "2024-11-05")
+DESCRIPTION_CHARS = 4000
+
+TOOLS = [
+    {
+        "name": "find_job_board",
+        "description": ("Find which applicant tracking system (Greenhouse, Lever, Ashby or "
+                        "Workday) an employer posts its jobs on. Give a company name, its "
+                        "careers page URL or a job board URL. Returns boards as ats:token, "
+                        "which list_open_roles accepts."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"target": {"type": "string",
+                                      "description": "company name, careers page URL or board URL"}},
+            "required": ["target"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    },
+    {
+        "name": "list_open_roles",
+        "description": ("List an employer's open roles straight from its own job board, newest "
+                        "first: title, location, remote, posted date, department, pay where "
+                        "posted, and the URL to apply. Filter by title words, location and "
+                        "remote. Descriptions are left out unless asked for, to keep the "
+                        "answer short."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "target": {"type": "string", "description": "ats:token, a board or careers URL, or a company name"},
+                "query": {"type": "string", "description": "words that must all appear in the title"},
+                "location": {"type": "string", "description": "text that must appear in a location, e.g. London or Remote"},
+                "remote_only": {"type": "boolean", "default": False},
+                "since_days": {"type": "integer", "minimum": 1},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 25},
+                "include_descriptions": {"type": "boolean", "default": False},
+                "country": {"type": "string", "description": "Workday only: narrow to one country by name"},
+            },
+            "required": ["target"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    },
+]
+
+
+def _result(payload, is_error: bool = False) -> dict:
+    text = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False)
+    out = {"content": [{"type": "text", "text": text}], "isError": is_error}
+    if not is_error and not isinstance(payload, str):
+        out["structuredContent"] = {"result": payload}
+    return out
+
+
+def call_tool(name: str, args: dict) -> dict:
+    try:
+        if name == "find_job_board":
+            boards = detect(str(args.get("target") or ""))
+            return _result([str(b) for b in boards] if boards else
+                           "no Greenhouse, Lever, Ashby or Workday board found")
+        if name == "list_open_roles":
+            jobs = fetch(str(args.get("target") or ""), query=args.get("query") or None,
+                         location=args.get("location") or None,
+                         remote=True if args.get("remote_only") else None,
+                         since_days=args.get("since_days"),
+                         limit=int(args.get("limit") or 25),
+                         details=bool(args.get("include_descriptions")) or None,
+                         country=str(args.get("country") or ""))
+            rows = []
+            for j in jobs:
+                d = j.to_dict()
+                if args.get("include_descriptions"):
+                    d["description"] = (d.get("description") or "")[:DESCRIPTION_CHARS] or None
+                else:
+                    d.pop("description", None)
+                rows.append(d)
+            return _result(rows)
+        return _result(f"unknown tool {name!r}", is_error=True)
+    except BoardError as e:
+        return _result(str(e), is_error=True)
+    except Exception as e:  # noqa: BLE001  a tool error, never a dead server
+        return _result(f"{type(e).__name__}: {e}", is_error=True)
+
+
+def handle(msg: dict) -> Optional[dict]:
+    """The response to one JSON-RPC message, or None for a notification."""
+    method, mid = msg.get("method"), msg.get("id")
+    if mid is None:
+        return None
+    if method == "initialize":
+        asked = (msg.get("params") or {}).get("protocolVersion")
+        result = {
+            "protocolVersion": asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "openroles", "version": __version__},
+            "instructions": ("Use find_job_board to locate an employer's board, then "
+                             "list_open_roles to read its open roles."),
+        }
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+    elif method == "tools/call":
+        params = msg.get("params") or {}
+        result = call_tool(str(params.get("name")), params.get("arguments") or {})
+    else:
+        return {"jsonrpc": "2.0", "id": mid,
+                "error": {"code": -32601, "message": f"method not found: {method}"}}
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def serve(stdin=None, stdout=None) -> int:
+    stdin, stdout = stdin or sys.stdin, stdout or sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            reply = {"jsonrpc": "2.0", "id": None,
+                     "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = handle(msg) if isinstance(msg, dict) else None
+        if reply is not None:
+            stdout.write(json.dumps(reply, ensure_ascii=False) + "\n")
+            stdout.flush()
+    return 0

openroles/models.py

@@ -0,0 +1,80 @@
+"""What openroles returns: one shape for every applicant tracking system."""
+from __future__ import annotations
+
+import html
+import re
+from dataclasses import asdict, dataclass, field
+from typing import List, Optional
+
+ATS = ("greenhouse", "lever", "ashby", "workday")
+BODY_CAP = 50_000
+
+
+class BoardError(Exception):
+    """A board could not be read: a wrong token, no answer, or robots.txt says no."""
+
+
+class RobotsDisallowed(BoardError):
+    """The host's robots.txt does not allow this board to be read."""
+
+
+@dataclass(frozen=True)
+class Board:
+    """One employer's job board on one ATS.
+
+    `token` is the board's name on its ATS: `acme` for Greenhouse, Lever and Ashby,
+    and `tenant.wdN/Site` for Workday (from https://tenant.wdN.myworkdayjobs.com/Site).
+    """
+    ats: str
+    token: str
+
+    def __post_init__(self):
+        if self.ats not in ATS:
+            raise ValueError(f"unknown ATS {self.ats!r}; expected one of {', '.join(ATS)}")
+
+    def __str__(self) -> str:
+        return f"{self.ats}:{self.token}"
+
+
+@dataclass
+class Job:
+    """One open role, in the same shape whichever ATS it came from."""
+    id: str
+    ats: str
+    board: str
+    title: str
+    url: str
+    location: str = ""
+    locations: List[str] = field(default_factory=list)
+    remote: Optional[bool] = None
+    posted: str = ""
+    department: str = ""
+    employment_type: str = ""
+    compensation: str = ""
+    deadline: str = ""
+    description: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+_TAG = re.compile(r"<[^>]+>")
+
+
+def html_to_text(content: str) -> str:
+    """Plain text from an ATS's HTML, which some boards entity-encode twice."""
+    s = content or ""
+    for _ in range(3):
+        un = html.unescape(s)
+        if un == s:
+            break
+        s = un
+    s = re.sub(r"<(br|/p|/li|/div|/h\d)[^>]*>", "\n", s, flags=re.I)
+    s = _TAG.sub(" ", s)
+    s = re.sub(r"[ \t]{2,}", " ", re.sub(r"\n{3,}", "\n\n", s))
+    return "\n".join(line.strip() for line in s.splitlines()).strip()[:BODY_CAP]
+
+
+def clean(value) -> str:
+    """One line of text, whitespace collapsed."""
+    return " ".join(str(value or "").split())

openroles/providers/__init__.py

@@ -0,0 +1,6 @@
+"""One reader per applicant tracking system."""
+from . import ashby, greenhouse, lever, workday
+
+READERS = {"greenhouse": greenhouse, "lever": lever, "ashby": ashby, "workday": workday}
+
+__all__ = ["READERS", "ashby", "greenhouse", "lever", "workday"]