Repository navigation
docs: jobs.list() returns Job objects, and how to read job.properties - #6
Merged
Merged
Conversation
The Jobs section was two lines and did not say what came back. Since 0.3.5 jobs.list() returns List[Job] rather than List[Dict], which silently breaks callers doing job["slug"] — and job.properties is now the documented way to find out what a dataset's job_run_params should contain, given the dataset builders are deprecated. Adds the Job field shape, an example of walking properties, the two things that catch people out when turning properties into job_run_params (input_datasets is server-populated; filter_values_criteria is a string selector with a sibling threshold field), and a note about the return-type change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The README's Jobs section was two lines and did not say what
jobs.list()returns:Two things make that a problem now:
e2058a9, released by the bump in1feda40)client.jobs.list()returnsList[Job]rather thanList[Dict[str, Any]]. Callers writtenagainst the old shape fail with
AttributeError: 'dict' object has no attribute 'slug'. Notethe raw payload also spelled the published flag
isPublished, whereJobexposesis_published.job.propertiesis now the documented path. With the dataset builders deprecated in53e6f75, reading a job's parameter definition and constructing a genericDatasetis the wayto build
job_run_params— but nothing said so, or said where to look.This came out of writing a customer-facing script: the missing docs cost a real debugging cycle,
including a 400 that was only explicable by probing the live API.
What changed
Docs only —
README.md, +31 lines, no code touched.Jobfield shape (slug,name,run_type,is_published,description,properties)job.propertiesto list a job's parameters and which are requiredpropertiesintojob_run_params:input_datasetsis listed in the definition but is not ajob_run_paramskey — the serverpopulates it from
input_dataset_idsfilter_values_criteriais a string selector ("percentage"/"count") with a matchingsibling field (
filter_threshold_percentage/filter_threshold_count), not a nested dictVerification
The 0.3.5 attribution was traced rather than assumed:
List[Job]was introduced ine2058a9whilepyproject.tomlstill read0.3.4; the next bump (1feda40) set0.3.5, so that is the firstrelease containing it. The
propertiesfield names in the example were read from a liveGET /jobsresponse.Follow-up, not in this PR
CHANGELOG.mdstill tops out at## [0.3.4]while the project is at0.3.12— eight undocumentedreleases, including this breaking return-type change and the builder deprecations. Happy to add
those entries if wanted.
🤖 Generated with Claude Code