Support a {--hashseed} placeholder & CLI option.

This can be used to populate the `PYTHONHASHSEED` env var for Python
commands to a random value on old pythons and a fixed value on new
Pythons by pairing a fixed value passed via `dev-cmd --hashseed`.

Author: jsirois

CHANGES.md

@@ -1,5 +1,10 @@
 # Release Notes
 
+## 0.31.0
+
+Add support for a `{--hashseed}` placeholder that is substituted with the value passed to `dev-cmd`
+via `--hashseed` or else a random value suitable for use in PYTHONHASHSEED.
+
 ## 0.30.3
 
 Fix `--py` / `--python` venv creation on Windows.

README.md

@@ -125,13 +125,15 @@ args = ["scripts/query-windows-registry.py"]
 
 A command's python, arguments and env values can be parameterized with values from the execution
 environment. Parameters are introduced in between brackets with an optional default value:
-`{<key>(:<default>)?}`. Parameters can draw from three sources:
+`{<key>(:<default>)?}`. Parameters can draw from four sources:
 1. Environment variables via `{env.<name>}`; e.g.: `{env.HOME}`
 2. The current Python interpreter's marker environment via `{markers.<name>}`; e.g.:
    `{markers.python_version}`
 3. Factors via `{-<name>}`; e.g.: `{-py:{markers.python_version}}`
+4. A hash seed via `{--hashseed}`. The value comes from `dev-cmd --hashseed` if passed; otherwise a
+   random hash seed suitable for use with `PYTHONHASHSEED` is generated.
 
-In all three cases, the parameter name can itself come from a nested parameterization; e.g.:
+In the first three cases, the parameter name can itself come from a nested parameterization; e.g.:
 `{markers.{-marker:{env.MARKER:python_version}}}` selects the environment marker value for the
 environment marker named by the `marker` factor if defined; otherwise the `MARKER` environment
 variable if defined and finally falling back to `python_version` if none of these are defined.

dev_cmd/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2024 John Sirois.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-__version__ = "0.30.3"
+__version__ = "0.31.0"

dev_cmd/parse.py

@@ -28,7 +28,7 @@
     PythonConfig,
     Task,
 )
-from dev_cmd.placeholder import DEFAULT_ENVIRONMENT, Substitution
+from dev_cmd.placeholder import Environment, Substitution
 from dev_cmd.project import PyProjectToml
 
 
@@ -134,6 +134,7 @@ def _parse_commands(
     project_dir: Path,
     python: Python | None,
     marker_environment: dict[str, str] | None,
+    placeholder_env: Environment,
 ) -> Iterator[Command | DeactivatedCommand]:
     if not commands:
         raise InvalidModelError(
@@ -270,7 +271,7 @@ def _parse_commands(
             used_factors: set[Factor] = set()
 
             def substitute(text: str) -> Substitution:
-                substitution = DEFAULT_ENVIRONMENT.substitute(text, *factors)
+                substitution = placeholder_env.substitute(text, *factors)
                 seen_factors.update(
                     (
                         seen_factor.factor,
@@ -909,7 +910,10 @@ def _gather_all_required_step_names(
 
 
 def parse_dev_config(
-    pyproject_toml: PyProjectToml, *requested_steps: str, requested_python: Python | None = None
+    pyproject_toml: PyProjectToml,
+    *requested_steps: str,
+    placeholder_env: Environment,
+    requested_python: Python | None = None,
 ) -> tuple[Configuration, tuple[str, ...]]:
     pyproject_data = pyproject_toml.parse()
     try:
@@ -990,6 +994,7 @@ def pop_dict(key: str, *, path: str) -> dict[str, Any] | None:
         project_dir=pyproject_toml.path.parent,
         python=requested_python,
         marker_environment=marker_environment,
+        placeholder_env=placeholder_env,
     ):
         existing = commands.setdefault(cmd.name, cmd)
         if isinstance(existing, DeactivatedCommand) and isinstance(cmd, Command):

dev_cmd/placeholder.py

@@ -59,6 +59,7 @@ class Environment(Substituter[State, str]):
     markers: Mapping[str, str] = field(
         default_factory=cast(Callable[[], Mapping[str, str]], markers.default_environment)
     )
+    hashseed: int = 0
 
     def substitute(self, text: str, *factors: Factor) -> Substitution:
         state = State(factors)
@@ -84,7 +85,14 @@ def substitution(self, text: str, section: slice, state: State) -> None:
             )
         default = deflt if sep else None
         value: str | None
-        if key.startswith("-"):
+        if key == "--hashseed":
+            if default is not None:
+                raise ValueError(
+                    f"The {{--hashseed}} placeholder does not accept a default. Found placeholder: "
+                    f"{{{symbol}}}"
+                )
+            value = str(self.hashseed)
+        elif key.startswith("-"):
             flag, flag_sep, rest = symbol.partition("?")
             if flag_sep:
                 substitution = self.substitute(rest)

dev_cmd/run.py

@@ -16,6 +16,7 @@
 from dataclasses import dataclass
 from multiprocessing.pool import ThreadPool
 from typing import Any, Collection, DefaultDict, Iterable, Iterator, Mapping
+from uuid import uuid4
 
 from dev_cmd import __version__, color, parse, venv
 from dev_cmd.color import ColorChoice
@@ -35,7 +36,7 @@
     VenvConfig,
 )
 from dev_cmd.parse import parse_dev_config
-from dev_cmd.placeholder import DEFAULT_ENVIRONMENT
+from dev_cmd.placeholder import Environment
 from dev_cmd.project import find_pyproject_toml
 
 DEFAULT_EXIT_STYLE = ExitStyle.AFTER_STEP
@@ -208,12 +209,19 @@ class Options:
     quiet: bool
     parallel: bool
     timings: bool
+    hashseed: int
     extra_args: tuple[str, ...]
     python: str | None = None
     exit_style: ExitStyle | None = None
     grace_period: float | None = None
 
 
+def _random_hashseed() -> int:
+    # The PYTHONHASHSEED is an integer in the range 0 to 4294967295. We use the time_low field of
+    # the UUID which is 32 bits.
+    return min(4294967295, uuid4().time_low)
+
+
 def _parse_args() -> Options:
     parser = ArgumentParser(
         description=(
@@ -263,6 +271,12 @@ def _parse_args() -> Options:
         action="store_true",
         help="Emit timing information for each command run.",
     )
+    parser.add_argument(
+        "--hashseed",
+        type=int,
+        default=_random_hashseed(),
+        help="Set the {--hashseed} command placeholder value.",
+    )
 
     if venv.AVAILABLE:
         parser.add_argument(
@@ -373,6 +387,7 @@ def _parse_args() -> Options:
         quiet=options.quiet,
         parallel=parallel,
         timings=options.timings,
+        hashseed=options.hashseed,
         extra_args=tuple(extra_args) if extra_args is not None else (),
         python=getattr(options, "python", None),
         exit_style=options.exit_style,
@@ -383,6 +398,7 @@ def _parse_args() -> Options:
 def _list(
     console,  # type: Console
     config,  # type: Configuration
+    placeholder_env,  # type: Environment
 ):
     # type: (...) -> Any
 
@@ -423,11 +439,11 @@ def _list(
             extra_info = ""
             if flag_value is not None:
                 extra_info = f"{flag_value} "
-                substituted_flag_value = DEFAULT_ENVIRONMENT.substitute(flag_value).value
+                substituted_flag_value = placeholder_env.substitute(flag_value).value
                 if substituted_flag_value != flag_value:
                     extra_info += f"(currently {substituted_flag_value}) "
             if default is not None:
-                substituted_default = DEFAULT_ENVIRONMENT.substitute(default).value
+                substituted_default = placeholder_env.substitute(default).value
                 if substituted_default != default:
                     extra_info += f"[default: {default} (currently {substituted_default})]"
                 else:
@@ -476,14 +492,17 @@ def main() -> Any:
     options = _parse_args()
     console = Console(quiet=options.quiet)
     python = Python(options.python) if options.python else None
+    placeholder_env = Environment(hashseed=options.hashseed)
     try:
         pyproject_toml = find_pyproject_toml()
-        config, steps = parse_dev_config(pyproject_toml, *options.steps, requested_python=python)
+        config, steps = parse_dev_config(
+            pyproject_toml, *options.steps, placeholder_env=placeholder_env, requested_python=python
+        )
     except DevCmdError as e:
         return 1 if console.quiet else f"{color.red('Configuration error')}: {color.yellow(str(e))}"
 
     if options.list:
-        return _list(console, config)
+        return _list(console, config, placeholder_env)
 
     success = False
     try:

pyproject.toml

@@ -125,6 +125,7 @@ dependency-group = "type-check"
 
 [tool.dev-cmd.commands.test]
 python = "{-py:}"
+env = {"PYTHONHASHSEED" = "{--hashseed}"}
 args = ["pytest"]
 cwd = "tests"
 accepts-extra-args = true

tests/test_parse.py

@@ -14,6 +14,7 @@
 from dev_cmd.errors import InvalidModelError
 from dev_cmd.model import Command, Configuration, Group, Task
 from dev_cmd.parse import parse_dev_config
+from dev_cmd.placeholder import Environment
 from dev_cmd.project import PyProjectToml
 
 
@@ -26,7 +27,9 @@ def parse_config(tmp_path: Path) -> Iterator[ConfigurationParser]:
     def parse(content: str, *requested_steps: str) -> Configuration:
         pyproject_toml = tmp_path / "pyproject.toml"
         pyproject_toml.write_text(content)
-        return parse_dev_config(PyProjectToml(pyproject_toml), *requested_steps)[0]
+        return parse_dev_config(
+            PyProjectToml(pyproject_toml), *requested_steps, placeholder_env=Environment(hashseed=0)
+        )[0]
 
     yield parse
 

tests/test_placeholder.py

@@ -1,19 +1,18 @@
 # Copyright 2025 John Sirois.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 import re
 import sys
 
 import pytest
 from packaging.markers import default_environment
 
 from dev_cmd.model import Factor
-from dev_cmd.placeholder import DEFAULT_ENVIRONMENT, Environment, SeenFactor, Substitution
+from dev_cmd.placeholder import Environment, SeenFactor, Substitution
 
 
 @pytest.fixture
 def env() -> Environment:
-    return DEFAULT_ENVIRONMENT
+    return Environment()
 
 
 def substitute(env: Environment, text: str) -> str:
@@ -126,3 +125,17 @@ def test_substitute_intra_recursive() -> None:
         seen_factors=[SeenFactor(Factor("py"))],
         used_factors=[Factor("py{markers.{env.USE_MARKER}}")],
     ) == env.substitute("{-{env.USE_FACTOR}}", Factor("py{markers.{env.USE_MARKER}}"))
+
+
+def test_substitute_hashseed() -> None:
+    env = Environment(hashseed=42)
+    assert Substitution.create("42") == env.substitute("{--hashseed}")
+
+    with pytest.raises(
+        ValueError,
+        match=re.escape(
+            "The {--hashseed} placeholder does not accept a default. Found placeholder: "
+            "{--hashseed:137}"
+        ),
+    ):
+        env.substitute("{--hashseed:137}")