94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
build a small python cli tool called `usajobs.py` for exploring usajobs results.
|
|
|
|
goal:
|
|
- query the official usajobs api
|
|
- apply strict local filters
|
|
- show results in a readable terminal table
|
|
- let me select rows to export into an org-mode file
|
|
|
|
stack:
|
|
- python 3.11+
|
|
- click for cli args
|
|
- requests for api
|
|
- rich for table + row selection prompt
|
|
- pathlib/json/csv stdlib only otherwise
|
|
|
|
env vars:
|
|
- USAJOBS_EMAIL
|
|
- USAJOBS_KEY
|
|
|
|
basic command:
|
|
`python jobs.py search --location "Washington, DC" --radius 25 --salary-min 150 --grade-min 15 --grade-max 15 --series 2210 --series 0340 --clearance 3 --clearance 4`
|
|
|
|
option behavior:
|
|
- --radius 25 means 25 miles
|
|
- --salary-min 150 means $150,000
|
|
- --grade-min/--grade-max filter locally against low/high grade
|
|
- --series may repeat; pass to api as semicolon list
|
|
- --clearance may repeat; pass to api as semicolon list
|
|
- --pay-plan may repeat, default gs and gg
|
|
- --limit defaults 100
|
|
- --out defaults jobs.org
|
|
- --cache-dir defaults .cache/usajobs
|
|
|
|
search behavior:
|
|
1. call https://data.usajobs.gov/api/search using official headers:
|
|
host: data.usajobs.gov
|
|
user-agent: $USAJOBS_EMAIL
|
|
authorization-key: $USAJOBS_KEY
|
|
2. request fields=full, resultsperpage=500, sortfield=opendate, sortdirection=desc
|
|
3. cache raw json response per query/page under .cache/usajobs
|
|
4. apply local filters after fetching:
|
|
- pay plan in allowed pay plans
|
|
- low_grade >= grade_min
|
|
- high_grade <= grade_max
|
|
- salary max >= salary_min, or salary min >= salary_min if max absent
|
|
- location string contains/near requested location as available
|
|
5. output table with columns:
|
|
idx, title, agency, grade, salary, location, close date, clearance match, url
|
|
6. selection/export:
|
|
- after displaying table, allow user to arrow/highlight and mark for export
|
|
- pick sensible defaults, eg x or m for mark, u for unmark, a for all, e for export
|
|
- export selected jobs to new file with short slug name + datetime stamp
|
|
- org output format:
|
|
```
|
|
** <shortened job title> [[url][link]]
|
|
:properties:
|
|
:agency: <agency>
|
|
:grade: <pay plan> <low>-<high>
|
|
:close_date: <date>
|
|
:end:
|
|
|
|
salary: <salary range>
|
|
location: <location>
|
|
travel: <travel percentage or unknown>
|
|
clearance: <clearance/security text or unknown>
|
|
|
|
*** posting
|
|
<raw posting text>
|
|
```
|
|
7. (stretch) Cache each query, allow arrow/scroll through them like a cli, recall, or save filters. could be too much.
|
|
|
|
implementation notes:
|
|
- write clean functional code:
|
|
- build_params()
|
|
- fetch_page()
|
|
- fetch_all()
|
|
- normalize_job()
|
|
- passes_filters()
|
|
- render_table()
|
|
- parse_selection()
|
|
- export_org()
|
|
- normalize both official api shape and frontend-ish shape if present:
|
|
- api jobs may use MatchedObjectDescriptor
|
|
- details may be under UserArea.Details
|
|
- raw posting text should combine title, summary, duties, requirements, qualifications, evaluations, other info, key requirements.
|
|
- shortened job title should be max 80 chars, strip all-caps screaming where reasonable, preserve meaning.
|
|
- include helpful errors if env vars missing.
|
|
- include a --offline flag that only reads cached json and does not call api.
|
|
- include a --debug flag that prints api params and counts before/after filtering.
|
|
|
|
acceptance test:
|
|
- running the command with `--salary-min 150 --grade-min 15 --grade-max 15 --radius 25` should not show gs/gg-13 jobs after local filtering.
|
|
- selecting `none` exits without writing.
|