pdatum 0.1.0__py3-none-any.whl

pdatum/__init__.py

@@ -0,0 +1,3 @@
+"""pdatum: job postings and the employers behind them, for scripts and agents."""
+
+__version__ = "0.1.0"

pdatum/__main__.py

@@ -0,0 +1,3 @@
+from pdatum.cli import main
+
+main()

pdatum/cli.py

@@ -0,0 +1,521 @@
+"""
+The `pdatum` command.
+
+Built on pkanban's model (typer, rich, `--json` everywhere, errors on stderr),
+with the fixes pkanban needed: Click's Windows expansion of `~` and wildcards
+is off, `--json` and `--api-key` are only taken from where they can be ours
+(never from another option's value, never after `--`), and long text never
+has to pass through a shell.
+
+Streams -- `jobs pull`, `jobs changes`, `employers pull` -- write JSON lines to
+stdout and progress to stderr, in either mode, so they can be piped straight
+into a file or another tool.
+"""
+
+import errno
+import os
+import sys
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from pdatum import __version__, config, timespec
+from pdatum.client import Client, PdatumError
+from pdatum.output import (
+    configure_streams,
+    console,
+    emit,
+    emit_error,
+    line,
+    progress,
+    set_json_output,
+)
+
+app = typer.Typer(
+    help="Job postings and the employers behind them, for scripts and agents. "
+    "Start with: pdatum skill",
+    no_args_is_help=True,
+    add_completion=False,
+)
+jobs_app = typer.Typer(help="Job postings.", no_args_is_help=True)
+employers_app = typer.Typer(help="Employer records, with facts and their sources.", no_args_is_help=True)
+key_app = typer.Typer(help="Store or forget your API key.", no_args_is_help=True)
+app.add_typer(jobs_app, name="jobs")
+app.add_typer(employers_app, name="employers")
+app.add_typer(key_app, name="key")
+
+
+def _version(value: bool):
+    if value:
+        emit({"version": __version__}, lambda: console.print(f"pdatum {__version__}"))
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    json_out: bool = typer.Option(
+        False, "--json", help="Print results as JSON. Or set PDATUM_OUTPUT=json."
+    ),
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", "-k", help="Use this key for this command only."
+    ),
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version, is_eager=True, help="Show the version."
+    ),
+):
+    """pdatum"""
+    # main() usually takes these off argv before typer sees them, so they work
+    # after the subcommand too; declaring them here puts them in --help.
+    if json_out:
+        set_json_output(True)
+    if api_key:
+        config.set_runtime_key(api_key)
+
+
+def client(need_key=True):
+    key, _ = config.api_key()
+    if need_key and not key:
+        raise PdatumError(
+            "No API key. Set PDATUM_API_KEY, pass --api-key, or run: pdatum key save <key>",
+            code="missing_key",
+        )
+    return Client(config.base_url(), key)
+
+
+def when(value, name):
+    """A --posted-since style option, parsed, or a usage error that says why."""
+    if value is None:
+        return None
+    try:
+        return timespec.parse(value)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint=name)
+
+
+# -- shared options -------------------------------------------------------------
+
+BRAND = typer.Option(None, "--brand", help="jobwolverine or rxraven. Both if omitted.")
+EMPLOYER = typer.Option(None, "--employer", help="An employer slug (see: pdatum employers list).")
+QUERY = typer.Option(None, "--q", "-q", help="Text in the position or company.")
+LOCATION = typer.Option(None, "--location", help="Text in the location.")
+REMOTE = typer.Option(None, "--remote/--not-remote", help="Only remote jobs, or only not.")
+SINCE = typer.Option(None, "--posted-since", help="2026-09-01, 7d, or epoch seconds.")
+BEFORE = typer.Option(None, "--posted-before", help="2026-09-01, 7d, or epoch seconds.")
+
+
+def job_filters(brand, employer, q, location, remote, posted_since, posted_before):
+    return dict(
+        brand=brand,
+        employer=employer,
+        q=q,
+        location=location,
+        remote=remote,
+        posted_since=when(posted_since, "--posted-since"),
+        posted_before=when(posted_before, "--posted-before"),
+    )
+
+
+def fraction(shown, total):
+    """Coverage first, the way #430 asks: '20 of 1,234'."""
+    return f"{shown:,} of {total:,}" if total is not None else f"{shown:,}"
+
+
+# -- jobs -----------------------------------------------------------------------
+
+
+@jobs_app.command("count")
+def jobs_count(
+    brand: Optional[str] = BRAND, employer: Optional[str] = EMPLOYER,
+    q: Optional[str] = QUERY, location: Optional[str] = LOCATION,
+    remote: Optional[bool] = REMOTE, posted_since: Optional[str] = SINCE,
+    posted_before: Optional[str] = BEFORE,
+):
+    """How many open jobs match. Cheap: size a query before pulling it."""
+    body = client().get(
+        "/jobs/count", **job_filters(brand, employer, q, location, remote, posted_since, posted_before)
+    )
+    emit(body["data"], lambda: console.print(f"{body['data']['count']:,}"))
+
+
+def job_table(jobs):
+    table = Table(show_edge=False, pad_edge=False)
+    for column in ("id", "posted", "company", "position", "location"):
+        table.add_column(column, overflow="fold")
+    for j in jobs:
+        table.add_row(
+            str(j["id"]),
+            timespec.show(j["posted_at"] or j["first_seen_at"])[:10],
+            j["company"] or "", j["position"] or "",
+            (j["location"] or "") + (" (remote)" if j["remote"] else ""),
+        )
+    return table
+
+
+@jobs_app.command("search")
+def jobs_search(
+    brand: Optional[str] = BRAND, employer: Optional[str] = EMPLOYER,
+    q: Optional[str] = QUERY, location: Optional[str] = LOCATION,
+    remote: Optional[bool] = REMOTE, posted_since: Optional[str] = SINCE,
+    posted_before: Optional[str] = BEFORE,
+    limit: int = typer.Option(20, "--limit", "-n", min=1, max=500, help="How many to show."),
+):
+    """The newest open jobs that match: one page. For all of them, use pull."""
+    body = client().get(
+        "/jobs", limit=limit,
+        **job_filters(brand, employer, q, location, remote, posted_since, posted_before),
+    )
+
+    def render():
+        console.print(job_table(body["data"]))
+        more = " -- pdatum jobs pull for all of them" if body["next_cursor"] else ""
+        console.print(f"[dim]{fraction(len(body['data']), body['total'])}{more}[/dim]")
+
+    emit(body, render)
+
+
+@jobs_app.command("get")
+def jobs_get(job_id: int = typer.Argument(..., help="The job's id.")):
+    """One job, open or closed, with its full description."""
+    job = client().get(f"/jobs/{job_id}")["data"]
+
+    def render():
+        state = "open" if job["open"] else "[red]closed[/red]"
+        console.print(f"[bold]{job['position']}[/bold] -- {job['company'] or '?'} ({state})")
+        console.print(
+            f"{job['location'] or 'no location'}{' - remote' if job['remote'] else ''}  |  "
+            f"posted {timespec.show(job['posted_at'])}  |  "
+            f"first seen {timespec.show(job['first_seen_at'])}"
+        )
+        if job["salary_min"] or job["salary_max"]:
+            console.print(f"salary {job['salary_min'] or '?'}-{job['salary_max'] or '?'} "
+                          f"{job['salary_currency']}")
+        console.print(f"apply: {job['application_url']}")
+        console.print()
+        console.print(job["description"], markup=False)
+
+    emit(job, render)
+
+
+def pull_progress(noun):
+    def report(received, total):
+        progress(f"pulled {fraction(received, total)} {noun}")
+    return report
+
+
+@jobs_app.command("pull")
+def jobs_pull(
+    brand: Optional[str] = BRAND, employer: Optional[str] = EMPLOYER,
+    q: Optional[str] = QUERY, location: Optional[str] = LOCATION,
+    remote: Optional[bool] = REMOTE, posted_since: Optional[str] = SINCE,
+    posted_before: Optional[str] = BEFORE,
+    full: bool = typer.Option(False, "--full", help="Whole descriptions, not excerpts."),
+    max_records: Optional[int] = typer.Option(None, "--max", min=1, help="Stop after this many."),
+):
+    """Every open job that matches, as JSON lines on stdout."""
+    filters = job_filters(brand, employer, q, location, remote, posted_since, posted_before)
+    written = 0
+    for job in client().pages(
+        "/jobs", on_page=pull_progress("jobs"),
+        detail="full" if full else "summary", limit=100 if full else 500, **filters,
+    ):
+        line(job)
+        written += 1
+        if max_records and written >= max_records:
+            break
+
+
+@jobs_app.command("changes")
+def jobs_changes(
+    since: str = typer.Option(..., "--since", help="2026-09-01, 7d, or epoch seconds."),
+    brand: Optional[str] = BRAND,
+    full: bool = typer.Option(False, "--full", help="Whole descriptions, not excerpts."),
+):
+    """
+    Every job added, closed or reopened since then, as JSON lines. Upsert by
+    id; closed jobs arrive with "open": false. The last line on stderr says
+    what --since to use next time.
+    """
+    start = when(since, "--since")
+    latest = None
+    for job in client().pages(
+        "/jobs/changes", on_page=pull_progress("changes"),
+        since=start, brand=brand, detail="full" if full else "summary",
+        limit=100 if full else 500,
+    ):
+        line(job)
+        latest = job["changed_at"]
+    # Minus one: times are whole seconds, so re-reading the last second is
+    # what guarantees nothing that landed in it is missed. See the API docs.
+    resume = (latest - 1) if latest is not None else start
+    progress(f"next time: pdatum jobs changes --since {resume}")
+
+
+# -- employers --------------------------------------------------------------------
+
+
+EMPLOYER_Q = typer.Option(None, "--q", "-q", help="Text in the name.")
+DOMAIN = typer.Option(None, "--domain", help="An exact domain, e.g. pfizer.com.")
+EMPLOYER_BRAND = typer.Option(None, "--brand", help="Only employers with open jobs there.")
+
+
+def hiring_word(value):
+    return {True: "yes", False: "no", None: "unknown"}[value]
+
+
+@employers_app.command("list")
+def employers_list(
+    q: Optional[str] = EMPLOYER_Q, domain: Optional[str] = DOMAIN,
+    brand: Optional[str] = EMPLOYER_BRAND,
+    limit: int = typer.Option(50, "--limit", "-n", min=1, max=500),
+):
+    """Employer records: one page. For all of them, use pull."""
+    body = client().get("/employers", q=q, domain=domain, brand=brand, limit=limit)
+
+    def render():
+        table = Table(show_edge=False, pad_edge=False)
+        for column in ("slug", "name", "domain", "open jobs", "hiring"):
+            table.add_column(column, overflow="fold")
+        for e in body["data"]:
+            table.add_row(
+                e["slug"], e["name"], e["domain"] or "",
+                str(sum(e["open_postings"].values())), hiring_word(e["hiring"]),
+            )
+        console.print(table)
+        console.print(f"[dim]{fraction(len(body['data']), body['total'])}[/dim]")
+
+    emit(body, render)
+
+
+@employers_app.command("pull")
+def employers_pull(
+    q: Optional[str] = EMPLOYER_Q, domain: Optional[str] = DOMAIN,
+    brand: Optional[str] = EMPLOYER_BRAND,
+):
+    """Every employer record that matches, as JSON lines on stdout."""
+    for employer in client().pages(
+        "/employers", on_page=pull_progress("employers"),
+        q=q, domain=domain, brand=brand, limit=500,
+    ):
+        line(employer)
+
+
+@employers_app.command("get")
+def employers_get(slug: str = typer.Argument(..., help="The employer's slug.")):
+    """One employer: open jobs per brand, every fact with its source, and history."""
+    e = client().get(f"/employers/{slug}")["data"]
+
+    def render():
+        console.print(f"[bold]{e['name']}[/bold] ({e['slug']})  {e['domain'] or ''}")
+        postings = ", ".join(f"{b} {n}" for b, n in e["open_postings"].items())
+        console.print(f"open jobs: {postings}  |  hiring: {hiring_word(e['hiring'])}")
+        if e["facts"]:
+            table = Table(show_edge=False, pad_edge=False, title="facts")
+            for column in ("key", "value", "source", "observed"):
+                table.add_column(column, overflow="fold")
+            for f in e["facts"]:
+                table.add_row(f["key"], str(f["value"]), f["source"],
+                              timespec.show(f["observed_at"]))
+            console.print(table)
+        else:
+            console.print("[dim]no facts recorded[/dim]")
+
+    emit(e, render)
+
+
+# -- the key, the server, and you ------------------------------------------------
+
+
+@app.command("me")
+def me():
+    """The key you are using, its scopes, and what it has used."""
+    data = client().get("/me")["data"]
+
+    def render():
+        _, source = config.api_key()
+        console.print(f"[bold]{data['name']}[/bold] -- {data['holder']}")
+        console.print(f"key {data['prefix']}... from {source}; scopes: {' '.join(data['scopes'])}")
+        console.print(f"expires {timespec.show(data['expires_at'])}")
+        for period, used in data["usage"].items():
+            console.print(f"{period.replace('_', ' ')}: {used['requests']:,} requests, "
+                          f"{used['records']:,} records")
+
+    emit(data, render)
+
+
+@key_app.command("save")
+def key_save(key: str = typer.Argument(..., help="The key you were issued.")):
+    """Check a key against the server, then save it to the config file."""
+    data = Client(config.base_url(), key).get("/me")["data"]
+    config.save_key(key)
+    emit(
+        {"saved": str(config.config_path()), "key": data},
+        lambda: console.print(
+            f"Saved {data['prefix']}... ({data['name']}) to {config.config_path()}"
+        ),
+    )
+
+
+@key_app.command("clear")
+def key_clear():
+    """Forget the saved key. It still works until it is revoked."""
+    had = config.clear_key()
+    emit({"cleared": had}, lambda: console.print(
+        f"Cleared the key from {config.config_path()}" if had else "No key was saved."
+    ))
+
+
+@app.command("config")
+def cmd_config(
+    url: Optional[str] = typer.Option(None, "--url", help="Point at another server."),
+):
+    """Show, or set, which server this talks to and where the key comes from."""
+    if url:
+        config.set_base_url(url)
+    key, source = config.api_key()
+    data = {
+        "url": config.base_url(),
+        "config": str(config.config_path()),
+        "key": config.display_key(key),
+        "key_from": source,
+    }
+    emit(data, lambda: [console.print(f"{k}: {v}") for k, v in data.items()])
+
+
+SKILL = """\
+pdatum -- job postings and the employers behind them, for agents.
+
+Auth: the key comes from PDATUM_API_KEY. Do not write it into files.
+Check it: pdatum me
+
+Size a query before pulling it (cheap, returns only a number):
+  pdatum jobs count --q "data engineer" --brand jobwolverine --posted-since 30d
+
+Look at a page:
+  pdatum jobs search --q nurse --remote --json
+
+Pull everything that matches, as JSON lines (progress goes to stderr):
+  pdatum jobs pull --q nurse --brand rxraven > jobs.jsonl
+
+One job in full:          pdatum jobs get 48213 --json
+Employers and their facts: pdatum employers list --q pfizer --json
+                           pdatum employers get pfizer --json
+Every fact names its source. hiring is true, false, or null (unknown).
+
+Stay in sync: pdatum jobs changes --since 2026-09-01 > delta.jsonl
+  Upsert each line by id; "open": false means the job closed.
+  The last stderr line gives the --since to use next time.
+
+Times take 2026-09-01, 7d / 12h / 30m, or epoch seconds.
+Every command takes --json; errors go to stderr, exit code non-zero.
+The full API reference: pdatum guide
+"""
+
+
+@app.command("skill")
+def skill():
+    """Short instructions for an AI agent. Save them where your agent reads them."""
+    emit({"skill": SKILL}, lambda: print(SKILL, end=""))
+
+
+@app.command("guide")
+def guide():
+    """The full API reference, fetched from the server so it is never stale."""
+    text = client(need_key=False).text("/docs")
+    emit({"guide": text}, lambda: print(text))
+
+
+# -- entry point ----------------------------------------------------------------
+
+# Options that take no value, so a flag right after one is still ours.
+VALUELESS = frozenset({
+    "--json", "--version", "-V", "--help", "--full", "--remote", "--not-remote",
+})
+
+
+def _is_ours(argv, i):
+    previous = argv[i - 1]
+    return not (previous.startswith("-") and previous not in VALUELESS)
+
+
+def _options_end(argv):
+    return argv.index("--") if "--" in argv else len(argv)
+
+
+def extract_json_flag(argv):
+    """
+    Take --json off argv wherever it can be ours, so it works after the
+    subcommand too. Not when it is another option's value (`--q --json`),
+    and nothing after `--`.
+    """
+    found = False
+    for i in range(_options_end(argv) - 1, 0, -1):
+        if argv[i] == "--json" and _is_ours(argv, i):
+            argv.pop(i)
+            found = True
+    return found
+
+
+def extract_api_key(argv):
+    """Take --api-key KEY / -k KEY / --api-key=KEY off argv, by the same rules."""
+    for i in range(1, _options_end(argv)):
+        token = argv[i]
+        if token.startswith("--api-key=") and _is_ours(argv, i):
+            argv.pop(i)
+            return token.split("=", 1)[1]
+        if token in ("--api-key", "-k") and _is_ours(argv, i):
+            if i + 1 >= len(argv):
+                emit_error(f"{token} needs a value.")
+                raise SystemExit(2)
+            argv.pop(i)
+            return argv.pop(i)
+    return None
+
+
+def main(argv=None):
+    configure_streams()
+    argv = sys.argv if argv is None else argv
+
+    if extract_json_flag(argv):
+        set_json_output(True)
+    key = extract_api_key(argv)
+    if key is not None:
+        config.set_runtime_key(key)
+
+    try:
+        # Click expands ~ and wildcards in every argument on Windows, standing
+        # in for a shell that does not: "~4,100" becomes a home directory and
+        # "*.py" a list of files. Nothing here is a path pattern.
+        app(args=argv[1:], prog_name="pdatum", windows_expand_args=False)
+    except PdatumError as e:
+        extra = {k: v for k, v in (("code", e.code), ("status", e.status)) if v is not None}
+        emit_error(e.message, **extra)
+        raise SystemExit(1)
+    except KeyboardInterrupt:
+        raise SystemExit(130)
+    except OSError as e:
+        if not _reader_left(e):
+            raise
+        # `pdatum jobs pull | head`: the reader left, which is not an error.
+        # Point stdout at nothing, or Python's own flush at exit raises the
+        # same error again and prints it.
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+        except (OSError, ValueError):
+            pass
+        raise SystemExit(0)
+
+
+def _reader_left(error):
+    """
+    Whether an OSError means whoever was reading stdout has gone. POSIX says
+    so with EPIPE; Windows says EINVAL when the pipe's far end is closed.
+    """
+    if isinstance(error, BrokenPipeError):
+        return True
+    return os.name == "nt" and error.errno == errno.EINVAL
+
+
+if __name__ == "__main__":
+    main()

pdatum/client.py

@@ -0,0 +1,113 @@
+"""
+The HTTP client. Knows the API's envelope, its errors and its paging, and
+nothing about how results are printed.
+"""
+
+import time
+
+import requests
+
+from pdatum import __version__
+
+TIMEOUT = 60
+
+# How many times one request waits out a 429 before giving up. A long pull
+# hits the per-key limit on purpose; waiting is the right answer, forever is
+# not.
+MAX_RETRIES = 8
+
+
+class PdatumError(Exception):
+    """A failure the user can act on, reported without a traceback."""
+
+    def __init__(self, message, code=None, status=None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+
+
+def _param(value):
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return value
+
+
+class Client:
+
+    def __init__(self, url, key=None, session=None, sleep=time.sleep):
+        self.url = url.rstrip("/")
+        self.key = key
+        self.session = session or requests.Session()
+        self.session.headers["User-Agent"] = f"pdatum-cli/{__version__}"
+        if key:
+            self.session.headers["Authorization"] = f"Bearer {key}"
+        self._sleep = sleep
+
+    def _send(self, path, params=None):
+        url = f"{self.url}/api/v1{path}"
+        params = {k: _param(v) for k, v in (params or {}).items() if v is not None}
+
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                response = self.session.get(url, params=params, timeout=TIMEOUT)
+            except requests.exceptions.Timeout:
+                raise PdatumError(f"{self.url} took more than {TIMEOUT}s to answer. Try again.")
+            except (requests.exceptions.MissingSchema, requests.exceptions.InvalidURL,
+                    requests.exceptions.InvalidSchema):
+                raise PdatumError(
+                    f"{self.url!r} is not a URL. Set one with: pdatum config --url https://..."
+                )
+            except requests.exceptions.ConnectionError:
+                raise PdatumError(f"Could not reach {self.url}. Check the URL (pdatum config).")
+
+            if response.status_code == 429 and attempt < MAX_RETRIES:
+                try:
+                    wait = float(response.headers.get("Retry-After", "1"))
+                except ValueError:
+                    wait = 1.0
+                self._sleep(max(wait, 0.5))
+                continue
+            break
+
+        if response.status_code >= 400:
+            raise self._error(response)
+        return response
+
+    @staticmethod
+    def _error(response):
+        code, message = None, None
+        try:
+            error = response.json().get("error") or {}
+            code, message = error.get("code"), error.get("message")
+        except (ValueError, AttributeError):
+            pass
+        if not message:
+            message = f"The server answered {response.status_code}."
+        if response.status_code == 401 and code == "missing_key":
+            message += " Set PDATUM_API_KEY, or run: pdatum key save <key>"
+        return PdatumError(message, code=code, status=response.status_code)
+
+    def get(self, path, **params):
+        """One request; the parsed JSON body."""
+        return self._send(path, params).json()
+
+    def text(self, path):
+        return self._send(path).text
+
+    def pages(self, path, on_page=None, **params):
+        """
+        Every record a list endpoint returns, following next_cursor to the
+        end. on_page(received so far, total) is called after each page.
+        """
+        cursor, received = None, 0
+        while True:
+            body = self.get(path, cursor=cursor, **params)
+            for record in body["data"]:
+                yield record
+            received += len(body["data"])
+            if on_page is not None:
+                on_page(received, body.get("total"))
+            cursor = body.get("next_cursor")
+            if not cursor:
+                return

pdatum/config.py

@@ -0,0 +1,107 @@
+"""
+Where the CLI finds its server and its key.
+
+The key is looked for in this order, and the first one found is used:
+
+  1. --api-key on the command line, for one invocation;
+  2. PDATUM_API_KEY in the environment -- the way to give an agent a key,
+     since it needs no file and nothing is written anywhere;
+  3. the config file, written by `pdatum key save`.
+
+The config file is ~/.pdatum.json unless PDATUM_CONFIG_PATH says otherwise.
+Both are resolved on every call rather than at import, so a test (or a
+script) that sets the variable after importing still gets the file it asked
+for -- pkanban once wrote to developers' real credentials for want of that.
+"""
+
+import json
+import os
+from pathlib import Path
+
+DEFAULT_URL = "https://pdatum.pearachute.com"
+
+_runtime_key = None
+
+
+def config_path():
+    raw = os.environ.get("PDATUM_CONFIG_PATH")
+    if raw:
+        # Expanded here because nothing else will: a quoted "~/x.json" would
+        # otherwise create a directory literally named "~".
+        return Path(raw).expanduser()
+    return Path.home() / ".pdatum.json"
+
+
+def load():
+    path = config_path()
+    if not path.exists():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        try:
+            data = json.load(f)
+        except ValueError:
+            return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save(data):
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    try:
+        # The file holds a key. Readable by its owner only, where the
+        # platform has such a thing.
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def set_runtime_key(key):
+    """--api-key: this invocation only, never written anywhere."""
+    global _runtime_key
+    _runtime_key = key
+
+
+def api_key():
+    """(key, where it came from), or (None, None)."""
+    if _runtime_key:
+        return _runtime_key, "--api-key"
+    env = os.environ.get("PDATUM_API_KEY", "").strip()
+    if env:
+        return env, "PDATUM_API_KEY"
+    saved = load().get("api_key")
+    if saved:
+        return saved, str(config_path())
+    return None, None
+
+
+def save_key(key):
+    data = load()
+    data["api_key"] = key
+    save(data)
+
+
+def clear_key():
+    data = load()
+    had = data.pop("api_key", None) is not None
+    save(data)
+    return had
+
+
+def base_url():
+    env = os.environ.get("PDATUM_URL", "").strip()
+    if env:
+        return env.rstrip("/")
+    return (load().get("url") or DEFAULT_URL).rstrip("/")
+
+
+def set_base_url(url):
+    data = load()
+    data["url"] = url.rstrip("/")
+    save(data)
+
+
+def display_key(key):
+    """Enough of a key to recognise it, never enough to use it."""
+    return key[:15] + "..." if key else None

pdatum/output.py

@@ -0,0 +1,79 @@
+"""
+How a command reports: formatted for a person, or JSON for a script.
+
+Copied in shape from pkanban. A command hands emit() the API's payload and a
+callable that renders it for a person; the mode decides which is printed. In
+JSON mode stdout carries only the result and errors go to stderr as JSON, so a
+script can parse stdout without first working out whether it holds an error.
+
+Streams (`jobs pull`, `jobs changes`, `employers pull`) are JSON lines in
+either mode: one record per line on stdout, progress on stderr.
+"""
+
+import json
+import os
+import sys
+
+from rich.console import Console
+
+_json_output = None
+
+console = Console(highlight=False)
+errors = Console(stderr=True, highlight=False)
+
+
+def configure_streams():
+    """
+    UTF-8 on stdout and stderr. On Windows they default to the console code
+    page, and one company name with an accent in it would otherwise end a
+    listing with a UnicodeEncodeError. An explicit PYTHONIOENCODING is left
+    alone.
+    """
+    chosen = bool(os.environ.get("PYTHONIOENCODING", "").strip())
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(errors="replace") if chosen else reconfigure(
+                encoding="utf-8", errors="replace"
+            )
+        except (ValueError, OSError):
+            pass
+
+
+def set_json_output(enabled):
+    global _json_output
+    _json_output = bool(enabled)
+
+
+def json_output():
+    if _json_output is not None:
+        return _json_output
+    return os.environ.get("PDATUM_OUTPUT", "").strip().lower() == "json"
+
+
+def emit(payload, render):
+    if json_output():
+        # Plain print: rich reflows long lines and reads [brackets] as markup,
+        # and either would corrupt JSON.
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+    else:
+        render()
+
+
+def emit_error(message, **extra):
+    if json_output():
+        print(json.dumps({"error": message, **extra}), file=sys.stderr)
+    else:
+        errors.print(f"[red]error:[/red] {message}", markup=True)
+
+
+def line(record):
+    """One JSON-lines record on stdout."""
+    sys.stdout.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def progress(message):
+    """A status line on stderr, where it never mixes with the data."""
+    print(message, file=sys.stderr, flush=True)

pdatum/timespec.py

@@ -0,0 +1,48 @@
+"""
+Times, as a person or an agent would write them, turned into the epoch
+seconds the API takes.
+
+    1727000000              epoch seconds, as-is
+    2026-09-01              midnight UTC that day
+    2026-09-01T12:30:00Z    an ISO timestamp; no offset means UTC
+    7d, 12h, 30m            that long ago
+"""
+
+import re
+import time
+from datetime import datetime, timezone
+
+_RELATIVE = re.compile(r"^(\d+)\s*([dhm])$")
+_UNITS = {"d": 86400, "h": 3600, "m": 60}
+
+
+def parse(value, now=None):
+    text = str(value).strip()
+    if not text:
+        raise ValueError("a time is required")
+
+    if text.isdigit():
+        return int(text)
+
+    match = _RELATIVE.match(text.lower())
+    if match:
+        now = time.time() if now is None else now
+        return int(now - int(match.group(1)) * _UNITS[match.group(2)])
+
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        raise ValueError(
+            f"{value!r} is not a time. Use epoch seconds, a date (2026-09-01), "
+            f"an ISO timestamp, or an age like 7d, 12h, 30m."
+        )
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return int(parsed.timestamp())
+
+
+def show(epoch):
+    """An epoch as a UTC date and time, for people; '-' for none."""
+    if epoch is None:
+        return "-"
+    return datetime.fromtimestamp(epoch, tz=timezone.utc).strftime("%Y-%m-%d %H:%M")

pdatum-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: pdatum
+Version: 0.1.0
+Summary: Job postings and the employers behind them, from the command line -- for scripts and AI agents.
+Author-email: Pearachute <pdatum@pearachute.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pdatum.pearachute.com
+Project-URL: Documentation, https://pdatum.pearachute.com/api/v1/docs
+Project-URL: Repository, https://github.com/japherwocky/pdatum
+Project-URL: Issues, https://github.com/japherwocky/pdatum/issues
+Keywords: jobs,job-postings,employers,data,api,cli,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+# pdatum
+
+Job postings, and the employers behind them, from the command line. Built for
+scripts and AI agents: everything prints JSON on request, errors go to
+stderr, and large pulls stream JSON lines.
+
+pdatum is the data jobwolverine.com and rxraven.com are built on.
+
+```bash
+pip install pdatum
+export PDATUM_API_KEY=pdatum_...    # keys are issued by hand for now
+
+pdatum jobs count --q "data engineer" --posted-since 30d
+pdatum jobs search --q nurse --remote
+pdatum jobs pull --brand rxraven > jobs.jsonl
+pdatum employers get pfizer --json
+```
+
+## Commands
+
+| Command | |
+|---|---|
+| `pdatum jobs count [filters]` | Returns how many open jobs match, and nothing else. It's cheap, so run it first. |
+| `pdatum jobs search [filters] [-n N]` | Shows the newest matches: one page. |
+| `pdatum jobs pull [filters] [--full] [--max N]` | Streams every match to stdout as JSON lines. Progress goes to stderr. |
+| `pdatum jobs get ID` | Returns one job, open or closed, with its full text. |
+| `pdatum jobs changes --since T` | Streams every job added, closed or reopened since `T`. |
+| `pdatum employers list / pull / get SLUG` | Employer records. Each fact names its source. |
+| `pdatum me` | Shows your key, its scopes, and what it has used. |
+| `pdatum skill` | Prints short instructions for an AI agent to save. |
+| `pdatum guide` | Prints the full API reference, from the server. |
+
+The job filters are `--brand`, `--employer`, `-q`, `--location`,
+`--remote/--not-remote`, `--posted-since` and `--posted-before`. A time can be
+`2026-09-01`, an age like `7d`, `12h` or `30m`, or epoch seconds.
+
+## Keeping a copy in sync
+
+```bash
+pdatum jobs pull > jobs.jsonl                       # once
+pdatum jobs changes --since 2026-09-01 > delta.jsonl
+```
+
+Upsert each line of `delta.jsonl` by `id`. A line with `"open": false` means
+that job has closed. The last line on stderr gives the `--since` to use next
+time. A change can arrive twice, but never not at all.
+
+## Keys and configuration
+
+The key is taken from `--api-key`, then `PDATUM_API_KEY`, then the config
+file, which `pdatum key save <key>` writes after checking the key with the
+server. The config file is `~/.pdatum.json`; `PDATUM_CONFIG_PATH` moves it.
+`PDATUM_URL` or `pdatum config --url` points the CLI at another server.
+
+Every command takes `--json`, or set `PDATUM_OUTPUT=json`. Errors go to
+stderr, and the exit code is non-zero: 1 for a failure, 2 for a usage error.
+
+## Development
+
+```bash
+pip install -e .
+python -m unittest discover -s tests
+```
+
+The tests never reach a server. The API this talks to is documented at
+https://pdatum.pearachute.com/api/v1/docs, and `pdatum guide` prints the same
+reference from whichever server you point it at. MIT licensed.

pdatum-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pdatum/__init__.py,sha256=mF3WU4a-Tno-D6LUOLt07GY4G2nafzBaVXm63cTGEXs,105
+pdatum/__main__.py,sha256=x3QFSkX8cA4ibcutpuOootV9LvDGaUQO9xqvcUaEIeo,36
+pdatum/cli.py,sha256=3OURKjtDWBYHwMlR2XJQ-2enEbJBAYKwkPl5c5_nQmI,18681
+pdatum/client.py,sha256=ecTsX7KZxGys4Hq1wXNfVmpRCZ1EuP03GjvNJItDZDo,3895
+pdatum/config.py,sha256=mohu-YWLOP1PxYcLgeTB3pgjteYQ2KnorKB01jiLpPQ,2791
+pdatum/output.py,sha256=NXTSlJ1Stm476MIbk4RS08_j9NRzEBOtrIU1Q8YR5gU,2392
+pdatum/timespec.py,sha256=-H8Eu41hDPPxeQ8d8aRoDUq9Stmr3UjifuTbecemxyo,1425
+pdatum-0.1.0.dist-info/licenses/LICENSE,sha256=lt1XcN23IlsPy5HIzaKHOMpdiebSCiKlacN0cjkFZYg,1067
+pdatum-0.1.0.dist-info/METADATA,sha256=DaoVXUlA8Z1LeCHUQODOF1wAS_KtqQMvnfYcIOUOCJc,3591
+pdatum-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pdatum-0.1.0.dist-info/entry_points.txt,sha256=ibZxHAkSaRSI5yMmbxiFdepMiOxBaYFRBfmbKtGKaUM,43
+pdatum-0.1.0.dist-info/top_level.txt,sha256=kTN3iJxJs4wojc0LOAFWGl5Sa9Fa7KmV96edTpdhlZQ,7
+pdatum-0.1.0.dist-info/RECORD,,

pdatum-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdatum-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdatum = pdatum.cli:main

pdatum-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pearachute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdatum-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdatum