[SG-9141] pip installed core can't use the ToolkitManager to bootstrap (#1033)

* move the bootstrap hook to the bootstrap folder in order to be able to bootstrap the engine when sgtk is installed using pip
* add test file to cover engine bootstrap when sgtk has been installed using pip
* remove blank line
* do not return unused value
* move and rename hook to his previous name to keep consistancy with existing workflows
* update setup.py file to make sure the new hook folder will be included with the packages
* improve documentation
* run black manually to make hound happy as tests are not included in pre-commit actions
* improve code comments
* Apply suggestions from code review
---------
Co-authored-by: Martin Chesnay <[email protected]>

Author: barbara-darkshot

docs/initializing.rst

@@ -430,6 +430,11 @@ to determine if a bundle is available in Flow Production Tracking or not.
 
 Once the bundles have been uploaded, you can implement the ``core/bootstrap.py`` hook.
 
+.. warning::
+    In order to be able to bootstrap Toolkit regardless of the installation method used, the bootstrap hook needs
+    to be stored within the package itself. That's why this core hook is located in ``core/python/tank/bootstrap/hook``
+    instead of the usual core hooks location.
+
 .. literalinclude:: examples/bootstrap_hook.py
    :language: python
    :start-after: #documentationStart

python/tank/bootstrap/bundle_downloader.py

@@ -34,12 +34,9 @@ def __init__(self, connection, pipeline_config_id, descriptor):
         # First put our base hook implementation into the array.
         base_class_path = os.path.normpath(
             os.path.join(
-                os.path.dirname(__file__),  # ./python/tank/bootstrap
-                "..",  # ./python/tank
-                "..",  # ./python
-                "..",  # ./
-                "hooks",  # ./hooks
-                "bootstrap.py",  # ./hooks/bootstrap.py
+                os.path.dirname(__file__),  # ...tk-core/python/tank/bootstrap
+                "hooks",
+                "bootstrap.py",  # ...tk-core/python/bootstrap/hooks/bootstrap.py
             )
         )
         hook_inheritance_chain = [base_class_path]

hooks/bootstrap.py renamed to python/tank/bootstrap/hooks/bootstrap.py

@@ -14,6 +14,11 @@
 It will be instantiated only after a configuration has been selected by the :class:`~sgtk.bootstrap.ToolkitManager`.
 Therefore, this hook will not be invoked to download a configuration. However, the Toolkit Core,
 applications, frameworks and engines can be downloaded through the hook.
+
+.. warning::
+    In order to be able to bootstrap Toolkit regardless of the installation method used, the bootstrap hook needs
+    to be stored within the package itself. That's why this core hook is located in ``core/python/tank/bootstrap/hook``
+    instead of the usual core hooks location.
 """
 
 from sgtk import get_hook_baseclass

setup.py

@@ -77,7 +77,7 @@ def get_version():
     # Additional data which must sit in packages folders
     package_data={
         # If any package contains data files, include them:
-        "": ["resources/*", ".txt", "*.*"]
+        "": ["resources/*", ".txt", "*.*", "hooks/*.py"]
     },
     # Everything can be found under the python folder, but installed without it
     package_dir={"": "python"},

tests/integration_tests/pip_install_bootstrap.py

@@ -0,0 +1,105 @@
+# Copyright 2025 Autodesk, Inc.  All rights reserved.
+#
+# Use of this software is subject to the terms of the Autodesk license agreement
+# provided at the time of installation or download, or which otherwise accompanies
+# this software in either electronic or hard copy form.
+#
+
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+
+from sgtk_integration_test import SgtkIntegrationTest
+
+
+class BootstrapPipTests(SgtkIntegrationTest):
+    """
+    Tests that it is possible to boostrap an engine when the package installation has been done using pip.
+
+    Note that because we can't really use pip here, we're simulating the installation process.
+    """
+
+    PYTHON_PACKAGE_LIST = ["sgtk", "tank", "tank_vendor"]
+
+    @classmethod
+    def setUpClass(cls):
+        super(BootstrapPipTests, cls).setUpClass()
+
+        # Mockup FPTR entities
+        cls.project = cls.create_or_update_project(
+            "Pip Install SGTK", {"tank_name": "pip_install_sgtk"}
+        )
+        cls.asset = cls.create_or_update_entity(
+            "Asset", "TestAsset", {"project": cls.project}
+        )
+
+        # Figure out our location
+        current_dir = os.path.abspath(os.path.dirname(__file__))
+        python_package_path = os.path.normpath(
+            os.path.join(current_dir, "..", "..", "python")
+        )
+
+        # Install sgtk in a temporary location pip-liked by manually copying the packages to the temporary location
+        cls._sgtk_install_location = tempfile.mkdtemp(prefix="sgtk_install_", dir=None)
+        for package in cls.PYTHON_PACKAGE_LIST:
+            if os.path.isdir(os.path.join(python_package_path, package)):
+                shutil.copytree(
+                    os.path.join(python_package_path, package),
+                    os.path.join(cls._sgtk_install_location, package),
+                    ignore=shutil.ignore_patterns("*.pyc", "__pycache__"),
+                )
+        sys.path.insert(1, cls._sgtk_install_location)
+
+    @classmethod
+    def tearDownClass(cls):
+        super(BootstrapPipTests, cls).tearDownClass()
+
+        # Make sure to remove our sgtk install folder
+        if os.path.isdir(cls._sgtk_install_location):
+            shutil.rmtree(cls._sgtk_install_location)
+
+    def __clean_sgtk_modules(self):
+        """Helper method to remove previously installed sgtk modules."""
+
+        modules_to_remove = []
+
+        for module_name in sys.modules:
+            if module_name.startswith("sgtk") or module_name.startswith("tank"):
+                modules_to_remove.append(module_name)
+
+        for module_name in modules_to_remove:
+            del sys.modules[module_name]
+
+    def test_boostrap_engine(self):
+        """Bootstrap the engine when the sgtk module has been installed using pip."""
+
+        # Make sure to import the right sgtk module by cleaning all the previously imported modules and reimporting
+        # the right one
+        self.__clean_sgtk_modules()
+        import sgtk
+
+        self.assertEqual(
+            os.path.dirname(sgtk.__file__),
+            os.path.join(self._sgtk_install_location, "tank"),
+        )
+        self.assertEqual(
+            os.path.dirname(sgtk.bootstrap.__file__),
+            os.path.join(self._sgtk_install_location, "tank", "bootstrap"),
+        )
+
+        # Bootstrap the engine
+        manager = sgtk.bootstrap.ToolkitManager(self.user)
+        manager.plugin_id = "basic.test"
+        manager.base_configuration = "sgtk:descriptor:path?path={0}".format(
+            os.path.normpath(
+                os.path.join(os.path.dirname(__file__), "data", "site_config")
+            )
+        )
+        engine = manager.bootstrap_engine("tk-shell", self.asset)
+        self.assertEqual(engine.name, "tk-shell")
+
+
+if __name__ == "__main__":
+    unittest.main(failfast=True, verbosity=2)