SG-40994 Update deprecation warning message about end of compat with Py 3.7 (#1069)

* Update deprecation warning message about end of compat with Py 3.7

* Address review

* Update python/tank/__init__.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Better for review

* Apply suggestions from code review

Co-authored-by: Martin Chesnay <104032692+mchesnay@users.noreply.github.com>

* Apply suggestion from review

* Unify variable name with tk-core

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Martin Chesnay <104032692+mchesnay@users.noreply.github.com>

Author: 3 people

docs/environment_variables.rst

@@ -45,6 +45,20 @@ Controls debug logging.
 
 .. _environment_variables_authentication:
 
+``SHOTGUN_ALLOW_OLD_PYTHON``
+----------------------------
+
+When set to ``1``, Toolkit will allow being imported from Python versions that are no longer supported.
+Otherwise, when unset (or set to any other value), attempting to import Toolkit from old unsupported Python version will
+raise an exception.
+
+This is not recommended and should only be used for testing purposes.
+
+.. important::
+    The ability to import the module does not guarantee that Toolkit will work properly on the unsupported Python
+    version. In fact, it is very likely that it will not work properly.
+
+
 Authentication
 ==============
 

python/tank/__init__.py

@@ -36,12 +36,30 @@
 import warnings
 
 if sys.version_info < (3, 7):
-    raise Exception("This module requires Python version 3.7 or higher.")
+    if os.environ.get("SHOTGUN_ALLOW_OLD_PYTHON", "0") != "1":
+        # This is our preferred default behavior when using an old
+        # unsupported Python version.
+        # This way, we can control where the exception is raised, and it provides a
+        # comprehensive error message rather than having users facing a random
+        # Python traceback and trying to understand this is due to using an
+        # unsupported Python version.
+
+        raise RuntimeError("This module requires Python version 3.7 or higher.")
+
+    warnings.warn(
+        "Python versions older than 3.7 are no longer supported as of January "
+        "2023. Since the SHOTGUN_ALLOW_OLD_PYTHON variable is enabled, this "
+        "module is raising a warning instead of an exception. "
+        "However, it is very likely that this module will not be able to work "
+        "on this Python version.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
 elif sys.version_info < (3, 9):
     warnings.warn(
-        "Python versions older than 3.9 are no longer supported since 2025-03 "
-        "and compatibility will be removed at any time after 2026-01. "
-        "Please update to Python 3.9 or a newer supported version.",
+        "Python versions older than 3.9 are no longer supported as of March "
+        "2025 and compatibility will be discontinued after March 2026. "
+        "Please update to Python 3.11 or any other supported version.",
         DeprecationWarning,
         stacklevel=2
     )