From a069ed049ab926017854c714972afe12f84607b6 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 19 Feb 2024 12:34:16 -0500 Subject: [PATCH 1/2] feat: rename run_always to run_install Signed-off-by: Henry Schreiner --- docs/tutorial.rst | 9 ++++++--- docs/usage.rst | 2 +- nox/_options.py | 2 +- nox/sessions.py | 26 ++++++++++++++++++++++---- tests/test_sessions.py | 22 +++++++++++++--------- 5 files changed, 43 insertions(+), 18 deletions(-) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index ac76a543..4b3131f1 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -143,20 +143,20 @@ If your project is a Python package and you want to install it: In some cases such as Python binary extensions, your package may depend on code compiled outside of the Python ecosystem. To make sure a low-level -dependency (e.g. ``libfoo``) is available during installation +dependency (e.g. ``libfoo``) is available during installation: .. code-block:: python @nox.session def tests(session): ... - session.run_always( + session.run_install( "cmake", "-DCMAKE_BUILD_TYPE=Debug", "-S", libfoo_src_dir, "-B", build_dir, external=True, ) - session.run_always( + session.run_install( "cmake", "--build", build_dir, "--config", "Debug", @@ -166,6 +166,9 @@ dependency (e.g. ``libfoo``) is available during installation session.install(".") ... +These commands will run even if you are only installing, and will not run if +the environment is being reused without reinstallation. + Running commands ---------------- diff --git a/docs/usage.rst b/docs/usage.rst index 2864e35e..96e41c63 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -186,7 +186,7 @@ The ``--no-install`` option causes the following session methods to return early - :func:`session.install ` - :func:`session.conda_install ` -- :func:`session.run_always ` +- :func:`session.run_instsall ` This option has no effect if the virtualenv is not being reused. diff --git a/nox/_options.py b/nox/_options.py index 24987b44..02c1b977 100644 --- a/nox/_options.py +++ b/nox/_options.py @@ -484,7 +484,7 @@ def _session_completer( action="store_true", help=( "Skip invocations of session methods for installing packages" - " (session.install, session.conda_install, session.run_always)" + " (session.install, session.conda_install, session.run_install)" " when a virtualenv is being reused." ), ), diff --git a/nox/sessions.py b/nox/sessions.py index bab59d5b..02e1e69f 100644 --- a/nox/sessions.py +++ b/nox/sessions.py @@ -390,18 +390,20 @@ def run( **kwargs, ) - def run_always( + def run_install( self, *args: str | os.PathLike[str], env: Mapping[str, str] | None = None, include_outer_env: bool = True, **kwargs: Any, ) -> Any | None: - """Run a command **always**. + """Run a command in the install step. This is a variant of :meth:`run` that runs even in the presence of ``--install-only``. This method returns early if ``--no-install`` is - specified and the virtualenv is being reused. + specified and the virtualenv is being reused. (In nox 2023.04.22 and + earlier, this was called ``run_always``, and that continues to be + available as an alias.) Here are some cases where this method is useful: @@ -447,7 +449,7 @@ def run_always( return None if not args: - raise ValueError("At least one argument required to run_always().") + raise ValueError("At least one argument required to run_install().") return self._run( *args, @@ -456,6 +458,22 @@ def run_always( **kwargs, ) + def run_always( + self, + *args: str | os.PathLike[str], + env: Mapping[str, str] | None = None, + include_outer_env: bool = True, + **kwargs: Any, + ) -> Any | None: + """This is an alias to ``run_install``, which better describes the use case. + + :meta private: + """ + + return self.run_install( + *args, env=env, include_outer_env=include_outer_env, **kwargs + ) + def _run( self, *args: str | os.PathLike[str], diff --git a/tests/test_sessions.py b/tests/test_sessions.py index 00a912c6..1926a332 100644 --- a/tests/test_sessions.py +++ b/tests/test_sessions.py @@ -358,25 +358,25 @@ def test_run_external_with_error_on_external_run_condaenv(self): with pytest.raises(nox.command.CommandFailed, match="External"): session.run(sys.executable, "--version") - def test_run_always_bad_args(self): + def test_run_install_bad_args(self): session, _ = self.make_session_and_runner() with pytest.raises(ValueError) as exc_info: - session.run_always() + session.run_install() exc_args = exc_info.value.args - assert exc_args == ("At least one argument required to run_always().",) + assert exc_args == ("At least one argument required to run_install().",) - def test_run_always_success(self): + def test_run_install_success(self): session, _ = self.make_session_and_runner() - assert session.run_always(operator.add, 1300, 37) == 1337 + assert session.run_install(operator.add, 1300, 37) == 1337 - def test_run_always_install_only(self, caplog): + def test_run_install_install_only(self, caplog): session, runner = self.make_session_and_runner() runner.global_config.install_only = True - assert session.run_always(operator.add, 23, 19) == 42 + assert session.run_install(operator.add, 23, 19) == 42 @pytest.mark.parametrize( ( @@ -437,13 +437,17 @@ def test_run_shutdown_process_timeouts( (False, False, True), ], ) - def test_run_always_no_install(self, no_install, reused, run_called): + @pytest.mark.parametrize("run_install_func", ["run_always", "run_install"]) + def test_run_install_no_install( + self, no_install, reused, run_called, run_install_func + ): session, runner = self.make_session_and_runner() runner.global_config.no_install = no_install runner.venv._reused = reused with mock.patch.object(nox.command, "run") as run: - session.run_always("python", "-m", "pip", "install", "requests") + run_install = getattr(session, run_install_func) + run_install("python", "-m", "pip", "install", "requests") assert run.called is run_called From 9044cef66074e8ca7d500b750b915416386a4df1 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Mon, 19 Feb 2024 16:36:46 -0500 Subject: [PATCH 2/2] Update docs/usage.rst --- docs/usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage.rst b/docs/usage.rst index 96e41c63..bc237610 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -186,7 +186,7 @@ The ``--no-install`` option causes the following session methods to return early - :func:`session.install ` - :func:`session.conda_install ` -- :func:`session.run_instsall ` +- :func:`session.run_install ` This option has no effect if the virtualenv is not being reused.