Warning about --python and --override-python-version deprecation

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `rsconnect` now detects Python interpreter version requirements from
   `.python-version`, `pyproject.toml` and `setup.cfg`
+- `--python` and `--override-python-version` options are now deprecated
+  in favor of using `.python-version` requirement file.
 
 ## [1.25.2] - 2025-02-26
 

rsconnect/environment.py

@@ -128,10 +128,20 @@ def create_python_environment(
         python_version_requirement = pyproject.detect_python_version_requirement(directory)
         _warn_on_missing_python_version(python_version_requirement)
 
+        if python is not None:
+            # TODO: Remove the option in a future release
+            logger.warning(
+                "On modern Posit Connect versions, the --python option won't influence "
+                "the Python version used to deploy the application anymore. "
+                "Please use a .python-version file to force a specific interpreter version."
+            )
+
         if override_python_version:
-            # TODO: --override-python-version should be deprecated in the future
-            #       and instead we should suggest the user sets it in .python-version
-            #       or pyproject.toml
+            # TODO: Remove the option in a future release
+            logger.warning(
+                "The --override-python-version option is deprecated, "
+                "please use a .python-version file to force a specific interpreter version."
+            )
             python_version_requirement = f"=={override_python_version}"
 
         # with cli_feedback("Inspecting Python environment"):

tests/test_environment.py

@@ -4,6 +4,7 @@
 import tempfile
 import subprocess
 from unittest import TestCase
+from unittest import mock
 
 import rsconnect.environment
 from rsconnect.exception import RSConnectException
@@ -270,3 +271,37 @@ def fake_inspect_environment(
 
         assert environment.python_interpreter == expected_python
         assert environment == expected_environment
+
+class TestEnvironmentDeprecations:
+    def test_override_python_version(self):
+        with mock.patch.object(rsconnect.environment.logger, "warning") as mock_warning:
+            result = Environment.create_python_environment(get_dir("pip1"), override_python_version=None)
+        assert mock_warning.call_count == 0
+        assert result.python_version_requirement is None
+
+        with mock.patch.object(rsconnect.environment.logger, "warning") as mock_warning:
+            result = Environment.create_python_environment(get_dir("pip1"), override_python_version="3.8")
+        assert mock_warning.call_count == 1
+        mock_warning.assert_called_once_with(
+            "The --override-python-version option is deprecated, "
+            "please use a .python-version file to force a specific interpreter version."
+        )
+        assert result.python_version_requirement == "==3.8"
+
+    def test_python_interpreter(self):
+        current_python_version = ".".join((str(v) for v in sys.version_info[:3]))
+
+        with mock.patch.object(rsconnect.environment.logger, "warning") as mock_warning:
+            result = Environment.create_python_environment(get_dir("pip1"))
+        assert mock_warning.call_count == 0
+        assert result.python == current_python_version
+
+        with mock.patch.object(rsconnect.environment.logger, "warning") as mock_warning:
+            result = Environment.create_python_environment(get_dir("pip1"), python=sys.executable)
+        assert mock_warning.call_count == 1
+        mock_warning.assert_called_once_with(
+            "On modern Posit Connect versions, the --python option won't influence "
+            "the Python version used to deploy the application anymore. "
+            "Please use a .python-version file to force a specific interpreter version."
+        )
+        assert result.python == current_python_version