dask-setup 2.0.0__tar.gz → 2.2.0__tar.gz

{dask_setup-2.0.0/src/dask_setup.egg-info → dask_setup-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dask_setup
-Version: 2.0.0
+Version: 2.2.0
 Summary: HPC-tuned Dask helpers for single-node runs on NCI Gadi.
 Author: Sam Green
 Project-URL: Homepage, https://github.com/21centuryweather/dask_setup
@@ -11,12 +11,15 @@ Requires-Dist: dask>=2024.1.0
 Requires-Dist: distributed>=2024.1.0
 Requires-Dist: psutil>=5.9
 Requires-Dist: pyyaml>=6.0
+Provides-Extra: multinode
+Requires-Dist: dask-jobqueue>=0.8; extra == "multinode"
 Provides-Extra: dev
-Requires-Dist: ruff~=0.4; extra == "dev"
+Requires-Dist: ruff==0.16.4; extra == "dev"
 Requires-Dist: pytest~=8.2; extra == "dev"
 Requires-Dist: pytest-cov~=5.0; extra == "dev"
 Requires-Dist: xarray; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
+Requires-Dist: dask-jobqueue>=0.8; extra == "dev"
 Dynamic: license-file
 
 # dask_setup
@@ -35,9 +38,9 @@ HPC-tuned Dask helpers for **NCI Gadi** and other PBS/SLURM systems. Wraps `dask
 from dask_setup import setup_dask_client
 
 # Pick a workload type and go
-client, cluster, dask_tmp = setup_dask_client("cpu")   # heavy compute
-client, cluster, dask_tmp = setup_dask_client("io")    # heavy file I/O
-client, cluster, dask_tmp = setup_dask_client("mixed") # both
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="cpu")   # heavy compute
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="io")    # heavy file I/O
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="mixed") # both
 ```
 
 `dask_tmp` is the path to the spill/temp directory (on `$PBS_JOBFS` if available). Pass it to Rechunker, Zarr, or anywhere else you want fast local I/O.
@@ -95,14 +98,27 @@ client, cluster, shared_tmp = setup_dask_client(
 |-----------|---------|-------------|
 | `workload_type` | `"io"` | Worker topology: `"cpu"`, `"io"`, `"mixed"`, `"gpu"`, `"auto"` |
 | `max_workers` | all cores | Hard cap on worker count |
-| `reserve_mem_gb` | auto (20% RAM) | Memory held back for OS/cache (GiB) |
+| `reserve_mem_gb` | auto | Memory held back for OS/cache (GiB): 20% of RAM, clamped to [4, 50] |
 | `max_mem_gb` | total RAM | Upper bound on Dask's total memory use |
 | `dashboard` | `True` | Start dashboard and print SSH tunnel hint |
 | `profile` | `None` | Named config profile |
-| `config` | `None` | Pre-built `DaskSetupConfig` object — mutually exclusive with `profile` |
+| `config` | `None` | Pre-built `DaskSetupConfig` object — same layer as `profile`; if both are given, `profile` wins |
 | `mode` | `"auto"` | `"local"`, `"pbs"`, `"slurm"`, or `"auto"` (v2.0) |
 | `multi_node_config` | `None` | `MultiNodeConfig` for PBS/SLURM multi-node jobs (v2.0) |
 
+Settings are layered, lowest to highest:
+
+```
+library defaults  <  config= or profile=  <  explicit keyword arguments
+```
+
+A parameter you leave unset inherits from the layer below. Passing a value
+always overrides, even when that value happens to equal the default — so
+`reserve_mem_gb=50.0` overrides a profile that says 40.0.
+
+`config=` and `profile=` share a layer rather than stacking: pass one or the
+other, and use explicit keyword arguments for the differences.
+
 ---
 
 ## Common Patterns
@@ -177,6 +193,14 @@ Tunnel from your laptop:
 Then open: http://localhost:8787
 ```
 
+The login host is inferred from the compute node's DNS domain, so it is correct
+at other sites too. Override it with `$DASK_SETUP_LOGIN_HOST` if the guess is
+wrong:
+
+```bash
+export DASK_SETUP_LOGIN_HOST=login.mycluster.edu
+```
+
 ---
 
 ## CLI

dask_setup-2.0.0/PKG-INFO → dask_setup-2.2.0/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: dask_setup
-Version: 2.0.0
-Summary: HPC-tuned Dask helpers for single-node runs on NCI Gadi.
-Author: Sam Green
-Project-URL: Homepage, https://github.com/21centuryweather/dask_setup
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: dask>=2024.1.0
-Requires-Dist: distributed>=2024.1.0
-Requires-Dist: psutil>=5.9
-Requires-Dist: pyyaml>=6.0
-Provides-Extra: dev
-Requires-Dist: ruff~=0.4; extra == "dev"
-Requires-Dist: pytest~=8.2; extra == "dev"
-Requires-Dist: pytest-cov~=5.0; extra == "dev"
-Requires-Dist: xarray; extra == "dev"
-Requires-Dist: numpy; extra == "dev"
-Dynamic: license-file
-
 # dask_setup
 
 [![CI](https://github.com/21centuryweather/dask_setup/workflows/CI/badge.svg)](https://github.com/21centuryweather/dask_setup/actions)
@@ -35,9 +14,9 @@ HPC-tuned Dask helpers for **NCI Gadi** and other PBS/SLURM systems. Wraps `dask
 from dask_setup import setup_dask_client
 
 # Pick a workload type and go
-client, cluster, dask_tmp = setup_dask_client("cpu")   # heavy compute
-client, cluster, dask_tmp = setup_dask_client("io")    # heavy file I/O
-client, cluster, dask_tmp = setup_dask_client("mixed") # both
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="cpu")   # heavy compute
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="io")    # heavy file I/O
+client, cluster, dask_tmp = setup_dask_client(mode="interactive", workload_type="mixed") # both
 ```
 
 `dask_tmp` is the path to the spill/temp directory (on `$PBS_JOBFS` if available). Pass it to Rechunker, Zarr, or anywhere else you want fast local I/O.
@@ -95,14 +74,27 @@ client, cluster, shared_tmp = setup_dask_client(
 |-----------|---------|-------------|
 | `workload_type` | `"io"` | Worker topology: `"cpu"`, `"io"`, `"mixed"`, `"gpu"`, `"auto"` |
 | `max_workers` | all cores | Hard cap on worker count |
-| `reserve_mem_gb` | auto (20% RAM) | Memory held back for OS/cache (GiB) |
+| `reserve_mem_gb` | auto | Memory held back for OS/cache (GiB): 20% of RAM, clamped to [4, 50] |
 | `max_mem_gb` | total RAM | Upper bound on Dask's total memory use |
 | `dashboard` | `True` | Start dashboard and print SSH tunnel hint |
 | `profile` | `None` | Named config profile |
-| `config` | `None` | Pre-built `DaskSetupConfig` object — mutually exclusive with `profile` |
+| `config` | `None` | Pre-built `DaskSetupConfig` object — same layer as `profile`; if both are given, `profile` wins |
 | `mode` | `"auto"` | `"local"`, `"pbs"`, `"slurm"`, or `"auto"` (v2.0) |
 | `multi_node_config` | `None` | `MultiNodeConfig` for PBS/SLURM multi-node jobs (v2.0) |
 
+Settings are layered, lowest to highest:
+
+```
+library defaults  <  config= or profile=  <  explicit keyword arguments
+```
+
+A parameter you leave unset inherits from the layer below. Passing a value
+always overrides, even when that value happens to equal the default — so
+`reserve_mem_gb=50.0` overrides a profile that says 40.0.
+
+`config=` and `profile=` share a layer rather than stacking: pass one or the
+other, and use explicit keyword arguments for the differences.
+
 ---
 
 ## Common Patterns
@@ -177,6 +169,14 @@ Tunnel from your laptop:
 Then open: http://localhost:8787
 ```
 
+The login host is inferred from the compute node's DNS domain, so it is correct
+at other sites too. Override it with `$DASK_SETUP_LOGIN_HOST` if the guess is
+wrong:
+
+```bash
+export DASK_SETUP_LOGIN_HOST=login.mycluster.edu
+```
+
 ---
 
 ## CLI

{dask_setup-2.0.0 → dask_setup-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dask_setup"
-version = "2.0.0"
+version = "2.2.0"
 description = "HPC-tuned Dask helpers for single-node runs on NCI Gadi."
 authors = [{name="Sam Green"}]
 readme = "README.md"
@@ -23,13 +23,28 @@ Homepage = "https://github.com/21centuryweather/dask_setup"
 dask-setup = "dask_setup.cli:main"
 
 [project.optional-dependencies]
+# Multi-node PBS/SLURM cluster support. Optional: the single-node path never
+# imports it, and setup_pbs_cluster()/setup_slurm_cluster() raise a helpful
+# ImportError if it is missing.
+multinode = [
+    "dask-jobqueue>=0.8",
+]
+
 dev = [
-    "ruff ~= 0.4",
+    # Pinned exactly, not a range. `ruff ~= 0.4` means >=0.4,<1.0, so CI picked
+    # up whatever ruff had released that morning -- and ruff's formatter changes
+    # between minor versions. That turns `ruff format --check` into a job that
+    # can fail on a commit that touched nothing. Bump this deliberately.
+    "ruff == 0.16.4",
     "pytest ~= 8.2",
     "pytest-cov ~= 5.0",
     # Xarray integration testing
     "xarray",
     "numpy",
+    # Multi-node tests exercise a real PBSJob. Without this, CI silently skipped
+    # the multi-node path -- including the regression test for the 4x worker
+    # under-provisioning fixed in 2.2.0.
+    "dask-jobqueue>=0.8",
 ]
 
 [tool.setuptools.package-data]

{dask_setup-2.0.0 → dask_setup-2.2.0}/src/dask_setup/__init__.py

@@ -22,6 +22,7 @@ from .multinode import (
     detect_cluster_mode,
     generate_pbs_script,
     generate_slurm_script,
+    setup_interactive_cluster,
     setup_pbs_cluster,
     setup_slurm_cluster,
 )
@@ -280,7 +281,7 @@ except ImportError:
         )
 
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"
 
 __all__ = [
     # Core API — always available
@@ -326,6 +327,7 @@ __all__ = [
     "MultiNodeConfig",
     "SharedTempDir",
     "detect_cluster_mode",
+    "setup_interactive_cluster",
     "setup_pbs_cluster",
     "setup_slurm_cluster",
     "generate_pbs_script",