pdatum 0.1.0__tar.gz

pdatum-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,67 @@
+# 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/pdatum/__init__.py

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

pdatum-0.1.0/pdatum/__main__.py

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