new API additions — branch param, app_id, files_download, bug fixes by domino-blake · Pull Request #266 · dominodatalab/python-domino

domino-blake · 2026-04-22T22:09:30Z

What does this PR do?

Adds new backwards-compatible methods and parameters, plus one bug fix to _validate_hardware_tier_id. The only existing behaviour change is intentional: _validate_hardware_tier_id now accepts dict input from compute_cluster_properties instead of raising HardwareTierNotFoundException for a valid tier (#174).

A small number of app_publish / app_unpublish deprecation shims (commitId/appId) also land here because they're coupled to the new branch parameter see inline reply for context. Broader rename work lives in PR #267.

New features

job_start(branch=...) — launch a job from a named branch without constructing a
mainRepoGitRef dict manually. Mutually exclusive with commit_id. Closes Request: Allow job_start to specify the job's git repo branch to run on #231.
app_id property — previously private (_app_id), now a public read-only property
returning the current project's app ID. Closes Can we make Domino._app_id a public API? #127.
app_get_status(app_id) — previously private (__app_get_status), now publicly
accessible. Closes Can we make Domino._Domino__app_get_status(app_id) a public API #128.
files_download(path, commit_id=None) — convenience wrapper over blobs_get_v2
that defaults to the latest commit, eliminating the need to call commits_list()
manually. Closes Make a method to download a file without having to get the blob id first #24, Blob Get By File Name #31.

Bug fix

_validate_hardware_tier_id now handles dict input (e.g. {"value": "small-k8s"})
from compute_cluster_properties, which previously caused HardwareTierNotFoundException
even when the tier existed. Closes BUG: in _validate_hardware_tier_id #174.

Docs

Adds runs_start vs job_start comparison table to README.md and README.adoc. Closes Document The Differnce Between domino.runs_start() and domino.job_start() #122.
Documents all new methods and the branch param in both READMEs.

Issues closed

#24, #31, #122, #127, #128, #174, #231

Testing

New tests added for every change:
- tests/test_jobs.py — branch param, hardware tier dict input
- tests/test_app.py — app_get_status
- tests/test_apps.py — app_id property
- tests/test_files.py — files_download
Unit tests passing
All changes are backwards compatible
Documentation updated

ddl-bira-ignacio · 2026-04-28T12:25:49Z

The description says "No existing behaviour changes" but there seems to be a few functional changes

ddl-bira-ignacio

The description says "No existing behaviour changes", but the diff also includes param renames and deprecation shims.

ddl-bira-ignacio · 2026-04-28T12:22:55Z

-            self.get_hardware_tier_id_from_name(hardware_tier_name)
-            if hardware_tier_name
-            else None
+        resolved_hardware_tier_id = (


issue: Looks like this now calls get_hardware_tier_id_from_name even when no tier name was passed. I think we need to keep this conditional

Fixed in eadc0a6. The conditional is restored — get_hardware_tier_id_from_name only runs when hardware_tier_name is non-None. Combined with reverting the parameter type to str 4140ce3, the call site and signature are now consistent.

ddl-bira-ignacio · 2026-04-28T12:24:09Z

        return self._get(url)

-    def get_hardware_tier_id_from_name(self, hardware_tier_name: str):
+    def get_hardware_tier_id_from_name(self, hardware_tier_name: Optional[str]):


suggestion: given hardware_tier_name is used here, I don't think it should be made optional.

Reverted to hardware_tier_name: str. With the call-site conditional restored in the previous commit, this function is never reached with None, so the original signature is correct.

ddl-bira-ignacio · 2026-04-28T12:28:03Z

issue: I see deprecation shims going in across a bunch of methods here, but the tests in this PR are focused on the new features. Would be great to either add shim-specific tests here or split that work into its own PR so coverage stays tight.

Some shim work did land here alongside the new features rather than living cleanly in PR #267:

app_publish / app_unpublish shims (commitId → commit_id, appId → app_id): these are coupled to PR B's new branch parameter on app_publish. Adding branch while leaving the adjacent params in camelCase would have shipped a mixed-casing API, so the renames came with the feature.

runs_start, run_stop, runs_status, get_run_log, runs_stdout, files_list, endpoint_publish shims: you're right that these are unrelated to PR B's scope and leaked in via a "cherry pick" commit that bundled too much. They're also present on PR rename camelCase params to snake_case with deprecation shims #267 (which is the rename PR), so they'll be deduplicated cleanly when PR rename camelCase params to snake_case with deprecation shims #267 merges after this one.

If you'd prefer, I can either:

Strip the unrelated shims from this PR (would require rewriting history on commit 04e72a7 and the downstream commits that depend on it), or

Add shim coverage to this PR's test file for the ones that touch PR B's APIs (app_publish / app_unpublish), and let PR rename camelCase params to snake_case with deprecation shims #267 cover the rest.

ddl-bira-ignacio · 2026-04-28T12:28:51Z

-    # This will fetch app_id of app in current project
    @property
-    def _app_id(self):
+    def app_id(self) -> Optional[str]:


issue: _app_id has been around for a while and some folks might be using it even though it's private. Would it make sense to keep _app_id as a deprecated alias that points to app_id, at least for one release?

Added _app_id as a deprecated alias property that issues a DeprecationWarning and forwards to app_id. Existing callers will keep working for at least one release. 016ab96

ddl-bira-ignacio · 2026-04-28T12:30:17Z

-    def _validate_hardware_tier_id(self, hardware_tier_id: str) -> bool:
+    def _validate_hardware_tier_id(self, hardware_tier_id: Union[str, Dict]) -> bool:
+        if isinstance(hardware_tier_id, dict):
+            hardware_tier_id = hardware_tier_id.get("value", hardware_tier_id)


question: If the dict doesn't have a "value" key, .get just returns the original dict and the tier comparison will never match. Should we raise a clear error here instead of letting it fall through to "not found"?

Now raises a ValueError: dff1872

ddl-bira-ignacio · 2026-04-28T12:31:19Z

+        :return: Raw file content (urllib3 response stream).
+        """
+        if commit_id is None:
+            commit_id = self.commits_list()[0]["id"]


suggestion: Add a guard to commits_list in case it returns empty

Added. commits_list() now gets stored, checked for empty, and a ValueError is raised b4b90d9

…oth_branch_and_commit_id_provided

domino-blake changed the title ~~feat: new API additions — branch param, app_id, files_download, bug fixes~~ new API additions — branch param, app_id, files_download, bug fixes Apr 22, 2026

domino-blake requested review from ddl-bira-ignacio and ddl-ebrown April 22, 2026 22:18

domino-blake mentioned this pull request Apr 23, 2026

Enforce code quality — snake_case renames, linting, type checking, and CI pipeline #262

Closed

6 tasks

ddl-bira-ignacio reviewed Apr 28, 2026

View reviewed changes

domino-blake changed the base branch from blake/pr-quality to master May 12, 2026 13:23

domino-blake added 9 commits May 12, 2026 14:40

#231 add branch parameter to job_start() for git-based projects

41a72ca

Cherry pick

04e72a7

#174 - handle dict input in _validate_hardware_tier_id

c6de570

#24 / #31 - add files_download() convenience method

274efe2

#122 - document runs_start vs jobs_start

2d83437

Update README with the changes

fa03738

fix: update stale error message match in test_app_publish_raises_if_b…

14c6ab8

…oth_branch_and_commit_id_provided

fix: only resolve hardware tier name when one was actually passed

eadc0a6

drop Optional from get_hardware_tier_id_from_name signature

4140ce3

domino-blake force-pushed the blake/pr-features branch from 5bde7ba to 4140ce3 Compare May 12, 2026 13:43

domino-blake added 3 commits May 12, 2026 14:50

add deprecated _app_id alias for backwards compatibility

016ab96

raise clear error when hardware_tier_id dict is missing 'value' key

dff1872

guard files_download against empty commits_list

b4b90d9

Conversation

domino-blake commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Issues closed

Testing

Uh oh!

ddl-bira-ignacio commented Apr 28, 2026

Uh oh!

ddl-bira-ignacio left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

domino-blake May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

domino-blake commented Apr 22, 2026 •

edited

Loading

domino-blake May 12, 2026 •

edited

Loading