Tackle issues

.flake8

@@ -1,14 +1,26 @@
 [flake8]
 max-complexity = 33
-# Default plus E266 - There should be only one leading # for a block comment
 ignore =
-    E121,  # A line is less indented than it should be for hanging indents
-    E123,  # Closing brackets should match the same indentation level of the line that their opening bracket started on
-    E126,  # A continuation line is indented farther than it should be for a hanging indent
-    E226,  # There should be one space before and after an arithmetic operator (+, -, /, and *)
-    E704,  # Multiple statements of a function definition should be on their own separate lines
-    W503,  # Line breaks should occur after the binary operator to keep all variable names aligned
-    W504,  # Line breaks should occur before the binary operator to keep all operators aligned
-    E266,  # There should be only one leading # for a block comment
-    E203,  # Colons should not have any space before them
-    E501,  # Line lengths are recommended to be no greater than 79 characters
+    # A line is less indented than it should be for hanging indents
+    E121,
+    # Closing brackets should match the same indentation level
+    E123,
+    # A continuation line is indented farther than it should be
+    E126,
+    # There should be one space before and after an arithmetic operator
+    E226,
+    # Multiple statements of a function definition should be on their own lines
+    E704,
+    # Line breaks should occur after the binary operator
+    W503,
+    # Line breaks should occur before the binary operator
+    W504,
+    # There should be only one leading # for a block comment
+    E266,
+    # Colons should not have any space before them
+    E203,
+    # Line lengths are recommended to be no greater than 79 characters
+    E501,
+per-file-ignores =
+    # Auto-generated OpenAPI client — forward-reference annotations flagged as undefined
+    domino/_impl/custommetrics/*.py: F821

.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install lint tools
+        run: pip install black==25.1.0 isort==5.13.2 "flake8==7.2.0"
+
+      - name: black
+        run: black --check .
+
+      - name: isort
+        run: isort --check .
+
+      - name: flake8
+        run: flake8 .
+
+      - name: snake_case
+        run: |
+          find domino -name "*.py" \
+            | grep -v "domino/_impl/" \
+            | grep -v "domino/airflow/" \
+            | xargs python scripts/check_snake_case.py
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package and type stubs
+        run: |
+          pip install -e .
+          pip install "mypy==1.15.0" \
+            types-pyyaml \
+            types-requests \
+            types-retry \
+            types-pytz \
+            types-tabulate \
+            types-python-dateutil \
+            types-redis \
+            types-protobuf \
+            types-frozendict \
+            types-urllib3
+
+      - name: mypy
+        run: |
+          mypy domino/ \
+            --no-warn-no-return \
+            --namespace-packages \
+            --explicit-package-bases \
+            --ignore-missing-imports \
+            --follow-imports=silent \
+            --python-version=3.10
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e .
+          pip install pytest pytest-cov requests-mock docker pytest-mock
+
+      - name: Run tests
+        run: |
+          pytest tests/ \
+            --ignore=tests/agents \
+            --ignore=tests/integration \
+            --ignore=tests/scripts \
+            --ignore=tests/test_operator.py \
+            --ignore=tests/test_spark_operator.py \
+            -v --tb=short \
+            --cov=domino \
+            --cov-report=xml \
+            --cov-report=term-missing
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml

.pre-commit-config.yaml

@@ -1,6 +1,15 @@
 repos:
+  - repo: local
+    hooks:
+      - id: check-snake-case
+        name: Check snake_case naming
+        entry: python scripts/check_snake_case.py
+        language: python
+        files: ^domino/.*\.py$
+        exclude: ^domino/_impl/|^domino/airflow/
+        pass_filenames: true
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v5.0.0
     hooks:
       - id: check-case-conflict
       - id: check-merge-conflict
@@ -11,21 +20,20 @@ repos:
       - id: no-commit-to-branch
         args: [-b, master]
       - id: trailing-whitespace
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.2
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.2.0
     hooks:
       - id: flake8
   - repo: https://github.com/PyCQA/isort
-    rev: 5.9.3
+    rev: 5.13.2
     hooks:
       - id: isort
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 25.1.0
     hooks:
       - id: black
-        language_version: python # Should be a command that runs python3.6+
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910
+    rev: v1.15.0
     hooks:
       - id: mypy
         args:
@@ -35,6 +43,7 @@ repos:
             --explicit-package-bases,
             --ignore-missing-imports,
             --follow-imports=silent,
+            --python-version=3.10,
           ]
         additional_dependencies:
           - "types-pyyaml"
@@ -45,7 +54,5 @@ repos:
           - "types-python-dateutil"
           - "types-redis"
           - "types-protobuf"
-          - "types-python-dateutil"
           - "types-frozendict"
-          - "types-typing-extensions"
           - "types-urllib3"

CHANGELOG.md

@@ -5,10 +5,45 @@ All notable changes to the `python-domino` library will be documented in this fi
 ## [Unreleased]
 
 ### Added
-* Updated app_publish() to allow selecting branch/commitRef
-* Updated app_publish() to allow selecing specific app
-
-### Changed
+* `app_publish()` now accepts `branch` and `commit_id` parameters to launch an app from a specific git ref.
+* `app_publish()` now accepts an explicit `app_id` parameter to target a specific app.
+* `scripts/check_snake_case.py` — AST-based lint script that catches camelCase parameter names in new code.
+* GitHub Actions CI workflow (`.github/workflows/ci.yml`) that runs lint, type-checking, and tests on every PR and push to `master`. All checks must pass before a PR can be merged.
+* 18 new unit tests covering deprecation warnings for all renamed parameters (`tests/test_deprecations.py`).
+* `pyproject.toml` with `isort` and `black` configuration (`profile = "black"`, `target-version = ["py310"]`).
+
+### Deprecated
+The following public API parameters have been renamed to follow PEP 8 (`snake_case`).
+The old names continue to work but will emit a `DeprecationWarning`. They will be
+removed in the next major version.
+
+| Method | Old name | New name |
+|--------|----------|----------|
+| `runs_start`, `runs_start_blocking` | `isDirect` | `is_direct` |
+| `runs_start`, `runs_start_blocking` | `commitId` | `commit_id` |
+| `runs_start`, `runs_start_blocking` | `publishApiEndpoint` | `publish_api_endpoint` |
+| `run_stop` | `runId` | `run_id` |
+| `run_stop` | `saveChanges` | `save_changes` |
+| `runs_status` | `runId` | `run_id` |
+| `get_run_log` | `runId` | `run_id` |
+| `get_run_log` | `includeSetupLog` | `include_setup_log` |
+| `runs_stdout` | `runId` | `run_id` |
+| `files_list` | `commitId` | `commit_id` |
+| `endpoint_publish` | `commitId` | `commit_id` |
+| `app_publish` | `unpublishRunningApps` | `unpublish_running_apps` |
+| `app_publish` | `hardwareTierId` | `hardware_tier_id` |
+| `app_publish` | `environmentId` | `environment_id` |
+| `app_publish` | `externalVolumeMountIds` | `external_volume_mount_ids` |
+| `app_publish` | `commitId` | `commit_id` |
+| `app_publish` | `appId` | `app_id` |
+| `app_unpublish` | `appId` | `app_id` |
+
+### Changed
+* Resolved all 38 pre-existing `mypy` type errors across `domino/`, bringing the codebase to a clean `mypy` pass with `--python-version=3.10`.
+* Resolved all `flake8`, `isort`, and `black` formatting errors across the codebase.
+* Updated `.pre-commit-config.yaml` to latest tool versions: `pre-commit-hooks` v5.0.0, `flake8` 7.2.0, `isort` 5.13.2, `black` 25.1.0, `mypy` v1.15.0. Added the `check-snake-case` hook.
+* Updated `tox.ini` to run the full test suite across Python 3.10, 3.11, and 3.12 (previously only ran two files on Python 3.9).
+* Updated `pytest.ini` with coverage configuration.
 
 ## [2.1.0]
 

README.adoc

@@ -426,6 +426,19 @@ Remove a tag from a project.
 
 === Executions
 
+NOTE: *`runs_start` vs `job_start` — which should I use?* +
+The SDK exposes two ways to start an execution. `job_start` uses the v4 Jobs API and is recommended for all new work. `runs_start` uses the legacy v1 API and is retained for backwards compatibility only.
+[cols="1,2,2", options="header"]
+|===
+| | `runs_start` / `runs_start_blocking` | `job_start` / `job_start_blocking`
+| *API version* | v1 (legacy) | v4 (current)
+| *Command format* | List of strings: `["main.py", "arg1"]` | Single string: `"main.py arg1"`
+| *Compute clusters* | Not supported | Spark, Ray, Dask, MPI via `compute_cluster_properties`
+| *Git ref targeting* | Commit ID only | Commit ID, branch, or `main_repo_git_ref` dict
+| *External volumes* | Not supported | Supported via `external_volume_mounts`
+| *Recommended for* | Legacy scripts | All new work
+|===
+
 See these code example files:
 
 * {python-domino-repo}/blob/Release-{latest-version}/examples/start_run_and_check_status.py[`start_run_and_check_status.py`^]
@@ -523,29 +536,87 @@ Retrieve a file from the Domino server in a project from its path and commit id.
 * _commit_id:_ ID of the commit to retrieve the file from.
 * _project_id:_ ID of the project to retrieve the file from.
 
+==== files_download(path, commit_id=None)
+
+Convenience wrapper around `blobs_get_v2` that downloads a file by path without
+needing to look up a commit ID first.
+
+* _path (string):_ Path to the file within the project, e.g. `"/README.md"`.
+* _commit_id (string):_ (Optional) The commit to download from. Defaults to the latest commit.
+
+Returns a raw file content stream (urllib3 response).
+
+[source,python]
+----
+content = d.files_download("/results/output.csv").read()
+----
+
 === Apps
 
-==== app_publish(unpublishRunningApps=True, hardwareTierId=None)
+==== app_publish(unpublish_running_apps=True, hardware_tier_id=None, environment_id=None, external_volume_mount_ids=None, commit_id=None, branch=None, app_id=None)
 
 Publish an app within a project, or republish an existing app.
 
-* _unpublishRunningApps:_ (Defaults to True) Check for an active app instance in the current project and unpublish it before re/publishing.
-* _hardwareTierId:_ (Optional) Launch the app on the specified hardware tier.
+* _unpublish_running_apps:_ (Defaults to `true`) Check for an active app instance in the current project and stop it before re/publishing.
+* _hardware_tier_id:_ (Optional) Launch the app on the specified hardware tier ID.
+* _environment_id:_ (Optional) Launch the app with the specified environment ID.
+* _external_volume_mount_ids:_ (Optional) List of external volume mount IDs to attach to the app.
+* _commit_id:_ (Optional) Launch the app from a specific commit. Cannot be combined with `branch`.
+* _branch:_ (Optional) Launch the app from the tip of a specific branch. Cannot be combined with `commit_id`.
+* _app_id:_ (Optional) The ID of the app to publish. If omitted, the project's default app is used (or a new one is created if none exists).
+
+[source,python]
+----
+# Publish from a specific branch
+d.app_publish(branch="my-feature-branch")
+
+# Publish from a specific commit
+d.app_publish(commit_id="abc123def456")
 
-==== app_unpublish()
+# Publish a specific app by ID
+d.app_publish(app_id="aabbccddeeff001122334457")
+----
+
+NOTE: The parameters `unpublishRunningApps`, `hardwareTierId`, `environmentId`, `externalVolumeMountIds`, `commitId`, and `appId` are deprecated and will be removed in the next major version. Use the `snake_case` equivalents listed above.
+
+==== app_unpublish(app_id=None)
 
 Stop the running app in the project.
 
+* _app_id:_ (Optional) The ID of the app to stop. If omitted, the project's default app is used.
+
+==== app_get_status(app_id)
+
+Return the current status of an app.
+
+* _app_id (string):_ The ID of the app to query.
+
+Returns the status string (e.g. `"Running"`, `"Stopped"`, `"Failed"`), or `None` if the app does not exist.
+
+==== app_id
+
+Read-only property. Returns the ID of the first app in the current project, or `None` if no app exists.
+
+[source,python]
+----
+print(d.app_id)  # e.g. "aabbccddeeff001122334457"
+----
+
 === Jobs
 
-==== job_start(command, commit_id=None, hardware_tier_name=None, environment_id=None, on_demand_spark_cluster_properties=None, compute_cluster_properties=None, external_volume_mounts=None, title=None):
+NOTE: Prefer `job_start` over `runs_start` for all new work. See the <<Executions>> section for a full comparison.
+
+==== job_start(command, commit_id=None, branch=None, hardware_tier_name=None, environment_id=None, on_demand_spark_cluster_properties=None, compute_cluster_properties=None, external_volume_mounts=None, title=None, main_repo_git_ref=None):
 
-Start a new job (execution) in the project.
+Start a new job (execution) in the project using the v4 Jobs API.
 
 * _command (string):_ Command to execute in Job.
 For example: `domino.job_start(command="main.py arg1 arg2")`
-* _commit_id (string):_ (Optional) The `commitId` to launch from.
-If not provided, the job launches from the latest commit.
+* _commit_id (string):_ (Optional) The commit ID to launch from.
+If not provided, the job launches from the latest commit. Mutually exclusive with `branch`.
+* _branch (string):_ (Optional) The branch name to launch from.
+If not provided, the job launches from the latest commit on the default branch.
+Mutually exclusive with `commit_id` and `main_repo_git_ref`.
 * _hardware_tier_name (string):_ (Optional) The hardware tier NAME to launch job in.
 If not provided, the project's default tier is used.
 * _environment_id (string):_ (Optional) The environment ID with which to launch the job.
@@ -593,6 +664,9 @@ If `on_demand_spark_cluster_properties` and `compute_cluster_properties` are bot
 * _external_volume_mounts (List[string]):_ (Optional) External volume mount IDs to mount to execution.
 If not provided, the job launches with no external volumes mounted.
 * _title (string):_ (Optional) Title for Job.
+* _main_repo_git_ref (dict):_ (Optional) Raw git ref dict for advanced use cases.
+For example: `{"type": "branches", "value": "my-feature-branch"}` or `{"type": "tags", "value": "v1.2.3"}`.
+Mutually exclusive with `branch`.
 
 ==== job_stop(job_id, commit_results=True):