def run_engine_cmd(log, install_root, pipeline_config_root, context_items, command, using_cwd, args):
    """
    Launches an engine and potentially executes a command.

    :param log: logger
    :param install_root: tank installation
    :param pipeline_config_root: PC config location
    :param context_items: list of strings to describe context. Either ["path"],
                               ["entity_type", "entity_id"] or ["entity_type", "entity_name"]

    :param engine_name: engine to run
    :param command: command to run - None will display a list of commands
    :param using_cwd: Was the context passed based on the current work folder?
    """
    log.debug("")
    log.debug("Context items: %s" % str(context_items))
    log.debug("Command: %s" % command)
    log.debug("Command Arguments: %s" % args)
    log.debug("Code Location Root: %s" % install_root)
    log.debug("Sgtk Pipeline Config Location: %s" % pipeline_config_root)
    log.debug("Location of this script (__file__): %s" % os.path.abspath(__file__))

    log.info("")

    log.info("Welcome to the Shotgun pipeline toolkit!")
    log.info("For documentation, see https://toolkit.shotgunsoftware.com/forums")

    # Now create a tk instance and a context if possible

    if len(context_items) == 1:

        ctx_path = context_items[0]

        if using_cwd:
            log.info("Starting the Sgtk for your current directory '%s'" % ctx_path)

        # context str is a path
        if pipeline_config_root is not None:
            # we are running a project specific tank command
            tk =  tank.tank_from_path(pipeline_config_root)

        else:
            # we are running a studio wide command
            try:
                tk = tank.tank_from_path(ctx_path)
            except TankError, e:
                # this path was not valid. That's ok - we just wont have a tank instance
                # when we run our commands later. This may be if we for example have
                # just run tank setup_project from any random folder
                log.debug("Instantiating Sgtk raised: %s" % e)
                tk = None

        # now try to extract a context
        ctx = None
        if tk is not None:
            ctx = tk.context_from_path(ctx_path)

def refresh_engine(engine_name, prev_context, menu_name):
    """
    refresh the current engine
    """    
    current_engine = tank.platform.current_engine()
    
    # first make sure that the disabled menu is reset, if it exists...
    if pm.menu("ShotgunMenuDisabled", exists=True):
        pm.deleteUI("ShotgunMenuDisabled")
    
    # if the scene opened is actually a file->new, then maintain the current
    # context/engine.
    if pm.sceneName() == "":
        return current_engine

    new_path = pm.sceneName().abspath()
    
    # this file could be in another project altogether, so create a new Tank
    # API instance.
    try:
        tk = tank.tank_from_path(new_path)
    except tank.TankError, e:
        OpenMaya.MGlobal.displayInfo("Shotgun: Engine cannot be started: %s" % e)
        # render menu
        create_tank_disabled_menu(menu_name)
        
        # (AD) - this leaves the engine running - is this correct?        
        return current_engine

def __tank_on_save_callback():
    """
    Callback that fires every time a file is saved.
    
    Carefully manage exceptions here so that a bug in Tank never
    interrupts the normal workflows in Nuke.
    """
    # get the new file name
    file_name = nuke.root().name()
    
    try:
        # this file could be in another project altogether, so create a new Tank
        # API instance.
        try:
            tk = tank.tank_from_path(file_name)
        except tank.TankError, e:
            __create_tank_disabled_menu(e)
            return
        
        # try to get current ctx and inherit its values if possible
        curr_ctx = None
        if tank.platform.current_engine():
            curr_ctx = tank.platform.current_engine().context
        
        # and now extract a new context based on the file
        new_ctx = tk.context_from_path(file_name, curr_ctx)
        
        # now restart the engine with the new context
        __engine_refresh(tk, new_ctx)

def refresh_engine(engine_name, prev_context, menu_name):
    """
    refresh the current engine
    """    
    #import rpdb2;rpdb2.start_embedded_debugger("12345")
    current_engine = tank.platform.current_engine()
    
    # first make sure that the disabled menu is reset, if it exists...
    #if pm.menu("ShotgunMenuDisabled", exists=True):
    #    pm.deleteUI("ShotgunMenuDisabled")
    
    # if the scene opened is actually a file->new, then maintain the current
    # context/engine.
    scene_name  = lxtd.current_scene().filename

    if not scene_name:
        return current_engine

    new_path = scene_name
    
    # this file could be in another project altogether, so create a new Tank
    # API instance.
    try:
        tk = tank.tank_from_path(new_path)
    except tank.TankError, e:
        # render menu
        modoshotgunsupport.add_disabled_menu()
        
        # (AD) - this leaves the engine running - is this correct?        
        return current_engine

def refresh_engine(engine_name, prev_context, menu_name):
    """
    refresh the current engine
    """    
    current_engine = tank.platform.current_engine()
    
    # first make sure that the disabled menu is removed, if it exists...
    menu_was_disabled = remove_sgtk_disabled_menu()
    
    # determine the tk instance and ctx to use:
    tk = current_engine.sgtk
    ctx = prev_context
    if pm.sceneName() == "":
        # if the scene opened is actually a file->new, then maintain the current
        # context/engine.
        if not menu_was_disabled:
            # just return the current engine - no need to restart it!
            return current_engine
    else:
        # loading a scene file
        new_path = pm.sceneName().abspath()
    
        # this file could be in another project altogether, so create a new
        # API instance.
        try:
            tk = tank.tank_from_path(new_path)
        except tank.TankError, e:
            OpenMaya.MGlobal.displayInfo("Shotgun: Engine cannot be started: %s" % e)
            # build disabled menu
            create_sgtk_disabled_menu(menu_name)
            return current_engine

        # and construct the new context for this path:
        ctx = tk.context_from_path(new_path, prev_context)

    def test_from_path(self):
        """
        Ensures tank_from_path will resolve site wide configs.
        """
        os.environ["TANK_CURRENT_PC"] = self.pipeline_config_root
        try:
            result = tank.tank_from_path(self.project_root)
            self.assertEqual(result.project_path, self.project_root)
            self.assertEqual(result.pipeline_configuration.get_path(), self.pipeline_config_root)

            self._invalidate_pipeline_configuration_yml()
            with self.assertRaisesRegex(
                TankInitError,
                "however that is not associated with the pipeline configuration"
            ):
                tank.tank_from_path(self.project_root)
        finally:
            del os.environ["TANK_CURRENT_PC"]

 def test_primary_branch(self):
     """
     Test path from primary branch.
     """
     child_path = os.path.join(self.project_root, "child_dir")
     os.mkdir(os.path.join(self.project_root, "child_dir"))
     result = tank.tank_from_path(child_path)
     self.assertIsInstance(result, Tank)
     self.assertEquals(result.project_path, self.project_root)

 def test_alternate_branch(self):
     """
     Test path not from primary branch.
     """
     os.mkdir(os.path.join(self.alt_root_1, "child_dir"))
     child_path = os.path.join(self.alt_root_1, "child_dir")
     result = tank.tank_from_path(child_path)
     self.assertIsInstance(result, Tank)
     self.assertEquals(result.project_path, self.project_root)

def getTankEntity(projPath):
    '''
    Build a tank instance from project path

    :Params:
        projPath: str
            The path of project that tank defined

    :Returns: 
        a tank instance
    '''
    return tank.tank_from_path(projPath)

    def __get_nuke_path(self):

        # Get the shotgun paths.yml file
        current_engine = sgtk.platform.current_engine()
        context = current_engine.context
        tk = tank.tank_from_path(context.tank.roots["primary"])
        config_path = tk.pipeline_configuration.get_path() + "\\config\\env\\includes\\paths.yml"

        # use yaml to extract the path location
        with open(config_path, 'r') as yml_config_file:
            config_file = yaml.load(yml_config_file)

        nuke_path = config_file["nuke_windows"]
        return nuke_path

def __tank_startup_node_callback():    
    """
    Callback that fires every time a node gets created.
    
    Carefully manage exceptions here so that a bug in Tank never
    interrupts the normal workflows in Nuke.    
    """    
    try:
        # look for the root node - this is created only when a new or existing file is opened.
        tn = nuke.thisNode()
        if tn != nuke.root():
            return
            
        if nuke.root().name() == "Root":
            # file->new
            # base it on the context we 'inherited' from the prev session
            # get the context from the previous session - this is helpful if user does file->new
            project_root = os.environ.get("TANK_NUKE_ENGINE_INIT_PROJECT_ROOT")
            tk = tank.Tank(project_root)
            
            ctx_str = os.environ.get("TANK_NUKE_ENGINE_INIT_CONTEXT")
            if ctx_str:
                try:
                    new_ctx = tank.context.deserialize(ctx_str)
                except:
                    new_ctx = tk.context_empty()
            else:
                new_ctx = tk.context_empty()
    
        else:
            # file->open
            file_name = nuke.root().name()
            
            try:
                tk = tank.tank_from_path(file_name)
            except tank.TankError, e:
                __create_tank_disabled_menu(e)
                return
                
            # try to get current ctx and inherit its values if possible
            curr_ctx = None
            if tank.platform.current_engine():
                curr_ctx = tank.platform.current_engine().context                
                
            new_ctx = tk.context_from_path(file_name, curr_ctx)
    
        # now restart the engine with the new context
        __engine_refresh(tk, new_ctx)

    def __group_yeti_nodes(self, yetinodes):
        # define the group from the current shotgun ass
        scene_name = cmds.file(query=True, sn=True)
        tk = tank.tank_from_path(scene_name)
        templ = tk.template_from_path(scene_name)
        fields = templ.get_fields(scene_name)

        group_name = fields['Asset'] + "_yetiFurNodes_v" + str(fields['version']).zfill(3)

        # select the top group yeti nodes to maintain hierarchy
        nodes = []
        for i in yetinodes:
            p = cmds.listRelatives(i, parent=True, fullPath=True)
            nodes.append(p[0].split('|')[1])

        cmds.select(nodes)
        return cmds.group(cmds.ls(sl=True), name=group_name, relative=True)

def shotgun_run_action(log, install_root, pipeline_config_root, is_localized, args):
    """
    Executes the special shotgun run action command from inside of shotgun
    """

    # we are talking to shotgun! First of all, make sure we switch on our html style logging
    log.handlers[0].formatter.enable_html_mode()

    log.debug("Running shotgun_run_action command")
    log.debug("Arguments passed: %s" % args)

    try:
        tk = tank.tank_from_path(pipeline_config_root)
        # attach our logger to the tank instance
        # this will be detected by the shotgun and shell engines
        # and used.
        tk.log = log
    except TankError, e:
        raise TankError("Could not instantiate an Sgtk API Object! Details: %s" % e )

def get_idA(objA=[]):
    """
    Store asset ids
    :return:
    """

    assetID_A = []

    for x in objA:
        ass_path = cmds.getAttr(x + '.definition')

        tk_ref = tank.tank_from_path(ass_path)
        context_ref = tk_ref.context_from_path(ass_path)

        if context_ref:
            if context_ref.entity:
                if context_ref.entity.get('id'):
                    assetID_A.append(int(context_ref.entity.get('id')))

    return assetID_A

    def _get_context_from_script(self, script):
        """
        Returns an sgtk.context.Context object from the given script path.

        :param script:  The path to a script file on disk.
        """
        tk = tank.tank_from_path(script)

        context = tk.context_from_path(
            script,
            previous_context=self.engine.context,
        )

        if context.project is None:
            raise tank.TankError(
                "The Nuke engine needs at least a project "
                "context in order to start! Your context: %s" % context
            )
        else:
            return context

def add_alembic_tag():
    selection = libUtilities.get_selected()
    if selection:
        for node in selection:
            # Add the alembic Tag
            scene_name = cmds.file(query=True, sn=True)
            tk = tank.tank_from_path(scene_name)
            templ = tk.template_from_path(scene_name)
            fields = templ.get_fields(scene_name)

            asset_name = "assetNameOrShotStep"

            if "Asset" in fields:
                asset_name = fields["Asset"]

            elif "Shot" in fields:
                asset_name = fields["Step"]
         
            libUtilities.addStrAttr(node, 'Alembic')
            node.Alembic.set(asset_name)
            # Add the frame rate tag
            libUtilities.addAttr(node, "Step", 100, 0.0001, df=1)
            node.Step.setKeyable(False)
            node.Step.showInChannelBox(False)
            # Frame Relative Sample
            libUtilities.addBoolAttr(node, "RelativeFrameSample")
            node.RelativeFrameSample.setKeyable(False)
            node.RelativeFrameSample.showInChannelBox(False)
            libUtilities.addAttr(node, "RelativeLow", 100, -100, df=-.2)
            node.RelativeLow.setKeyable(False)
            node.RelativeLow.showInChannelBox(False)
            libUtilities.addAttr(node, "RelativeHigh", 100, -100, df=.2)
            node.RelativeHigh.setKeyable(False)
            node.RelativeHigh.showInChannelBox(False)
            libUtilities.addStrAttr(node, "WARNING")
            node.WARNING.set("DO NOT EDIT ANYTHING BELOW THIS ATTRIBUTE")
            node.WARNING.lock()
            libUtilities.addStrAttr(node, "ModelUsed")
            libUtilities.addStrAttr(node, "Namespace")
    else:
        libGUI.nothing_selected_box()

    def _on_save_callback(self):
        """
        Callback that fires every time a file is saved.
        """
        try:
            # Get the new file name.
            file_name = nuke.root().name()
            try:
                # This file could be in another project altogether, so
                # create a new Tank instance.
                tk = tank.tank_from_path(file_name)
            except tank.TankError, e:
                self.engine.menu_generator.create_sgtk_disabled_menu(e)
                return

            # Extract a new context based on the file and change to that
            # context.
            new_context = tk.context_from_path(
                file_name,
                previous_context=self.context,
            )

            self.change_context(new_context)

def refresh_engine(engine_name, prev_context, menu_name):
    """
    refresh the current engine
    """
    logger.debug("Refreshing the engine, previous context: '%r'", prev_context)
    current_engine = tank.platform.current_engine()

    if not current_engine:
        # If we don't have an engine for some reason then we don't have
        # anything to do.
        logger.debug("No currently initialized engine found; aborting the refresh of the engine")
        return

    if pm.sceneName() == "":
        # This is a File->New call, so we just leave the engine in the current
        # context and move on.
        logger.debug("New file call, aborting the refresh of the engine.")
        return

    # determine the tk instance and ctx to use:
    tk = current_engine.sgtk

    # loading a scene file
    new_path = pm.sceneName().abspath()

    # this file could be in another project altogether, so create a new
    # API instance.
    try:
        tk = tank.tank_from_path(new_path)
        logger.debug("Extracted sgtk instance: '%r' from path: '%r'", tk, new_path)

    except tank.TankError, e:
        logger.exception("Could not execute tank_from_path('%s')" % new_path)
        OpenMaya.MGlobal.displayInfo("Shotgun: Engine cannot be started: %s" % e)
        # build disabled menu
        create_sgtk_disabled_menu(menu_name)
        return

    def _startup_node_callback(self):
        """
        Callback that fires every time a node gets created.
        """
        try:
            # Look for the root node. This is created only when a new or existing
            # file is opened.
            if nuke.thisNode() != nuke.root():
                return

            if nuke.root().name() == "Root":
                # This is a file->new call, so base it on the context we
                # stored from the previous session.
                tk = tank.Tank(self.init_project_root)

                if self.init_context:
                    new_ctx = self.init_context
                else:
                    new_ctx = tk.context_empty()
            else:
                # This is a file->open call, so we can get the new context
                # from the file path that was opened.
                file_name = nuke.root().name()
                try:
                    tk = tank.tank_from_path(file_name)
                except tank.TankError, e:
                    self.engine.menu_generator.create_sgtk_disabled_menu(e)
                    return

                new_ctx = tk.context_from_path(
                    file_name,
                    previous_context=self.context,
                )

            # Now change the context for the engine and apps.
            self.change_context(new_ctx)

    def test_project_setup(self, rw_dir, sg):
        # prepare the mock db - reuse the tank implementation as it's already what tank needs
        project = {      'type': 'Project',
                         'id': 1,
                         'sg_project_folder' : u'project_folder',
                         'sg_project_short_name' : 'testy',
                         'tank_name': None,
                         # 'name': u'project_name_™äü' } // tank can't do unicode, but we can
                         'name': u'project_name' }

        local_storage = {'code' : constants.PRIMARY_STORAGE_NAME,
                         'mac_path' : str(rw_dir),
                         'linux_path' : str(rw_dir), 
                         'windows_path' : str(rw_dir),
                         'id' : 1,
                         'type' : 'LocalStorage'}
        sg.set_entities([project, local_storage])
        sg.set_server_info(version_tuple=(4, 3, 9))

        for dummy in ('PublishedFile','PublishedFileType', 'PublishedFileDependency'):
            sg.set_entity_schema(dummy, dict())
        # end for each dummmy
        sg.set_entity_schema('Project', dict((k, None) for k in project.keys()))


        stp = SetupTankProject()

        pb, wb = self._setup_bootstrapper_at(rw_dir, 'btank')
        config_uri = self._default_configuration_tree()
        patch_installer = SetupProjectPatcher()
        settings = DictObject({'bootstrapper' : {'host_path' : pb, # will work on all platforms in our case
                                                 'posix_symlink_path' : pb, 
                                                 'windows_symlink_path' : wb,
                                                 'enforce_winlink_entry' : True,
                                                 'assume_smb_share' : False},
                               'tank' : {'windows_python2_interpreter_path' : 'c:\\foo',
                                         'configuration_uri': config_uri}})
        location = stp.handle_project_setup(sg, log, DictObject(project), settings)
        assert location.isdir(), "expected a valid tank instance as return value"


        # If it's correct, folder structure should be doable.
        tk = tank.tank_from_path(location)
        tk.create_filesystem_structure(project['type'], project['id'])


        ##############################
        # Test Event Engine Plugin ##
        ############################
        plugin = sgevents.TankProjectEventEnginePlugin(sg, log)

        ctx = bapp.main().context().push('project-setup-settings')
        ctx.settings().set_value_by_schema(setup_project_schema, settings)

        event = {'entity' : {'type' : 'Project', 'id' : project['id']}}
        event = DictObject(event)

        try:
            plugin.handle_event(sg, log, event)
        except OSError as err:
            assert err.errno == 17, "project directory can't be created as it exists"