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

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

* Make module not importable

* Address review and update documentation

* Update shotgun_api3/__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/installation.rst

@@ -6,15 +6,23 @@ Installation
 Minimum Requirements
 ********************
 
-- Python 3.7
-
 .. note::
     Some features of the API are only supported by more recent versions of the Flow Production Tracking server.
     These features are added to the Python API in a backwards compatible way so that existing
     scripts will continue to function as expected. Accessing a method that is not supported for
     your version of Flow Production Tracking will raise an appropriate exception. In general, we attempt to
     document these where possible.
 
+Python versions
+===============
+
+The Python API library supports the following Python versions: `3.9 - 3.11`. We recommend using Python 3.11.
+
+.. important::
+    Python versions older than 3.9 are no longer supported as of March 2025 and compatibility will be discontinued after
+    March 2026.
+
+
 ******************************
 Installing into ``PYTHONPATH``
 ******************************

docs/reference.rst

@@ -994,6 +994,19 @@ Will internally be transformed as if you invoked something like this:
     sg.find('Asset', [['project', 'is', {'id': 999, 'type': 'Project'}]])
 
 
+SHOTGUN_ALLOW_OLD_PYTHON
+========================
+
+When set to ``1``, ``shotgun_api3``  will allow being imported from Python versions that are no longer supported.
+Otherwise, when unset (or set to any other value), importing the module 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 the module will work properly on the unsupported Python
+    version. In fact, it is very likely that it will not work properly.
+
+
 ************
 Localization
 ************

shotgun_api3/__init__.py

@@ -8,14 +8,35 @@
 # agreement to the Shotgun Pipeline Toolkit Source Code License. All rights
 # not expressly granted therein are reserved by Shotgun Software Inc.
 
+import os
 import sys
 import warnings
 
-if sys.version_info < (3, 9):
+if sys.version_info < (3, 7):
+    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,
     )

shotgun_api3/shotgun.py

@@ -222,7 +222,6 @@ def __init__(self, host: str, meta: Dict[str, Any]) -> None:
         :ivar bool is_dev: ``True`` if server is running a development version of the Shotgun
             codebase.
         """
-        self._ensure_python_version_supported()
         # Server host name
         self.host = host
         self.server_info = meta
@@ -249,13 +248,6 @@ def __init__(self, host: str, meta: Dict[str, Any]) -> None:
         self.version = tuple(self.version[:3])
         self._ensure_json_supported()
 
-    def _ensure_python_version_supported(self) -> None:
-        """
-        Checks the if current Python version is supported.
-        """
-        if sys.version_info < (3, 7):
-            raise ShotgunError("This module requires Python version 3.7 or higher.")
-
     def _ensure_support(self, feature: Dict[str, Any], raise_hell: bool = True) -> bool:
         """
         Checks the server version supports a given feature, raises an exception if it does not.