pipeline

def add_to_ayon_container(
    container: Union[bpy.types.Collection, bpy.types.Object]
):
    """Add the container (object or collection) to the AYON container."""
    ayon_container = get_ayon_container()
    if isinstance(container, bpy.types.Collection):
        ayon_container.children.link(container)
    elif isinstance(container, bpy.types.Object):
        ayon_container.objects.link(container)

def containerise(name: str,
                 namespace: str,
                 nodes: List,
                 context: Dict,
                 loader: Optional[str] = None,
                 suffix: Optional[str] = "CON") -> bpy.types.Collection:
    """Bundle `nodes` into an assembly and imprint it with metadata

    Containerisation enables a tracking of version, author and origin
    for loaded assets.

    Arguments:
        name: Name of resulting assembly
        namespace: Namespace under which to host container
        nodes: Long names of nodes to containerise
        context: Asset information
        loader: Name of loader used to produce this container.
        suffix: Suffix of container, defaults to `_CON`.

    Returns:
        The container assembly

    """

    node_name = get_container_name(name, namespace, context, suffix)
    container = bpy.data.collections.new(name=node_name)
    # Link the children nodes
    for obj in nodes:
        if isinstance(obj, bpy.types.Object):
            container.objects.link(obj)
        elif isinstance(obj, bpy.types.Collection):
            container.children.link(obj)
        else:
            raise TypeError(f"Unsupported type {type(obj)} in nodes list.")

    data = {
        "schema": "ayon:container-3.0",
        "id": AYON_CONTAINER_ID,
        "name": name,
        "namespace": namespace or '',
        "loader": str(loader),
        "representation": context["representation"]["id"],
        "project_name": context["project"]["name"],
    }

    metadata_update(container, data)
    add_to_ayon_container(container)

    return container

def containerise_existing(
        container: bpy.types.Collection,
        name: str,
        namespace: str,
        context: Dict,
        loader: Optional[str] = None,
        suffix: Optional[str] = "CON") -> bpy.types.Collection:
    """Imprint or update container with metadata.

    Arguments:
        name: Name of resulting assembly
        namespace: Namespace under which to host container
        context: Asset information
        loader: Name of loader used to produce this container.
        suffix: Suffix of container, defaults to `_CON`.

    Returns:
        The container assembly
    """

    node_name = container.name
    if suffix:
        node_name = f"{node_name}_{suffix}"
    container.name = node_name
    data = {
        "schema": "ayon:container-3.0",
        "id": AYON_CONTAINER_ID,
        "name": name,
        "namespace": namespace or '',
        "loader": str(loader),
        "representation": context["representation"]["id"],
        "project_name": context["project"]["name"],
    }

    metadata_update(container, data)
    add_to_ayon_container(container)

    return container

def ensure_ayon_container() -> bpy.types.Collection:
    """Ensure AYON_CONTAINERS exists and is ready for use."""
    ayon_container = bpy.data.collections.get(AYON_CONTAINERS)
    if ayon_container:
        return ayon_container

    # Create and configure container
    ayon_container = bpy.data.collections.new(name=AYON_CONTAINERS)
    bpy.context.scene.collection.children.link(ayon_container)
    ayon_container.color_tag = "COLOR_02"
    ayon_container.use_fake_user = True
    return ayon_container

def get_ayon_container() -> bpy.types.Collection:
    """Get Ayon Container

    Returns:
         bpy.types.Collection: Ayon containers collection
    """
    ayon_container = bpy.data.collections.get(AYON_CONTAINERS)
    if ayon_container:
        return ayon_container

    # Backwards compatibility, check for legacy Avalon container
    avalon_container = bpy.data.collections.get(AVALON_CONTAINERS)
    if avalon_container:
        # Convert legacy Avalon container to Ayon container
        log.debug(
            "Converting legacy Avalon container to AYON container."
        )
        # Rename the collection
        avalon_container.name = AYON_CONTAINERS
        return avalon_container

    # Create a new AYON container if it does not exist
    return ensure_ayon_container()

def get_container_name(name: str,
                       namespace: str,
                       context: Dict,
                       suffix: str):
    """Function to get container name

    Args:
        name: Name of resulting assembly
        namespace: Namespace under which to host container
        context: Asset information
        suffix: Suffix of container

    Returns:
        The name of the container assembly
    """
    node_name = f"{context['folder']['name']}_{name}"
    if namespace:
        node_name = f"{namespace}:{node_name}"
    if suffix:
        node_name = f"{node_name}_{suffix}"

    return node_name

def get_frame_range(task_entity=None) -> Union[Dict[str, int], None]:
    """Get the task entity's frame range and handles

    Args:
        task_entity (Optional[dict]): Task Entity.
            When not provided defaults to current context task.

    Returns:
        Union[Dict[str, int], None]: Dictionary with
            frame start, frame end, handle start, handle end.
    """
    # Set frame start/end
    if task_entity is None:
        task_entity = get_current_task_entity(fields={"attrib"})
    task_attributes = task_entity["attrib"]
    frame_start = int(task_attributes["frameStart"])
    frame_end = int(task_attributes["frameEnd"])
    handle_start = int(task_attributes["handleStart"])
    handle_end = int(task_attributes["handleEnd"])
    frame_start_handle = frame_start - handle_start
    frame_end_handle = frame_end + handle_end

    return {
        "frameStart": frame_start,
        "frameEnd": frame_end,
        "handleStart": handle_start,
        "handleEnd": handle_end,
        "frameStartHandle": frame_start_handle,
        "frameEndHandle": frame_end_handle,
    }

def install():
    """Install Blender configuration for AYON."""
    sys.excepthook = pype_excepthook_handler

    pyblish.api.register_host("blender")
    pyblish.api.register_plugin_path(str(PUBLISH_PATH))

    register_loader_plugin_path(str(LOAD_PATH))
    register_creator_plugin_path(str(CREATE_PATH))
    register_workfile_build_plugin_path(str(WORKFILE_BUILD_PATH))

    if lib.get_blender_version() < (5, 0, 0):
        # User script directories had issues in custom management in older
        # Blender releases - appending user scripts within AYON was a
        # workaround only in-place to solve that issue.
        lib.append_user_scripts()
    lib.set_app_templates_path()

    register_event_callback("new", on_new)
    register_event_callback("open", on_open)
    register_event_callback("before.save", on_before_save)

    _register_callbacks()

    if not IS_HEADLESS:
        ops.register()

        # should be performed after registering the plugin
        _deferred_build_workfile_from_template(on_app_launched=True)

def ls() -> Iterator:
    """List containers from active Blender scene.

    This is the host-equivalent of api.ls(), but instead of listing assets on
    disk, it lists assets already loaded in Blender; once loaded they are
    called containers.
    """
    container_ids = {
        AYON_CONTAINER_ID,
        # Backwards compatibility
        AVALON_CONTAINER_ID
    }

    for id_type in container_ids:
        for container in lib.lsattr("id", id_type):
            yield parse_container(container)

    # Compositor nodes are not in `bpy.data` that `lib.lsattr` looks in.
    node_tree = lib.get_scene_node_tree()
    if node_tree:
        for node in node_tree.nodes:
            ayon_prop = node.get(AYON_PROPERTY)
            if not ayon_prop:
                avalon_prop = node.get(AVALON_PROPERTY)
                if not avalon_prop:
                    continue
                else:
                    node[AYON_PROPERTY] = avalon_prop
                    ayon_prop = avalon_prop
                    del node[AVALON_PROPERTY]

            if ayon_prop.get("id") not in container_ids:
                continue

            yield parse_container(node)

    # Shader nodes are not available in a way that `lib.lsattr` can find.
    for material in bpy.data.materials:
        material_node_tree = material.node_tree
        if not material_node_tree:
            continue

        for shader_node in material_node_tree.nodes:
            ayon_shader_node = get_ayon_property(shader_node)
            if not ayon_shader_node:
                continue

            if ayon_shader_node.get("id") not in container_ids:
                continue

            yield parse_container(shader_node)

def metadata_update(node: bpy.types.bpy_struct_meta_idprop, data: Dict):
    """Imprint the node with metadata.

    Existing metadata will be updated.
    """

    if not node.get(AYON_PROPERTY):
        node[AYON_PROPERTY] = dict()
    for key, value in data.items():
        if value is None:
            continue
        node[AYON_PROPERTY][key] = value

def on_before_save(event):
    """Handle the event before saving a Blender file.

    When saving to a new scene name, e.g. on incrementing the workfile then
    update the render paths to match the new scene name by replacing the old
    scene name with the new one in all render paths.
    """
    blend_path_before: str = bpy.data.filepath
    blend_path_after: str = event.get("filename")

    if not blend_path_before:
        # Saving from a new unsaved file, no need to check for changes.
        return

    blend_name_before: str = os.path.splitext(
        os.path.basename(blend_path_before))[0]
    blend_name_after: str = os.path.splitext(
        os.path.basename(blend_path_after))[0]
    if blend_name_before != blend_name_after:
        print(f"Detected scene name change from {blend_name_before} to "
              f"{blend_name_after}")
        # TODO: We may want to allow disabling this feature, especially after
        #  Blender 4.5+ supporting the `{blend_name}` in templates in render
        #  paths to avoid needing to hardcode the blender scene filename into
        #  those paths.
        # Update any render paths if they previously contained the scene name
        # Warning: if the scene name is `a` before and now `helloworld` then
        #  this may easily get out of hand by turning `asset` into
        #  `helloworldsset`, but since filenames tend to be longer and
        #  contain version numbers, this is not expected to happen often.
        search_replace_render_paths(blend_name_before, blend_name_after)

def parse_container(container: bpy.types.Collection,
                    validate: bool = True) -> Dict:
    """Return the container node's full container data.

    Args:
        container: A container node name.
        validate: turn the validation for the container on or off

    Returns:
        The container schema data for this container node.

    """

    data = lib.read(container)

    # Append transient data
    data["objectName"] = container.name
    data["node"] = container  # store parsed object for easy access in loader

    if validate:
        schema.validate(data)

    return data

def publish():
    """Shorthand to publish from within host."""

    return pyblish.util.publish()

def set_context_settings(frame_range: bool = True,
                         resolution: bool = True,
                         scene_units: bool = False):
    """Set context settings for the current scene.

    Args:
        frame_range (bool): Set frame range context variable.
        resolution (bool): Set resolution context variable.
        scene_units (bool): Set scene units context variable.
    """
    task_entity = get_current_task_entity()
    if not task_entity:
        # No task entity found, nothing to set
        return
    if frame_range:
        set_frame_range(task_entity)
    if resolution:
        set_resolution(task_entity)
    if scene_units:
        set_unit_scale_from_settings(scene_units=scene_units)

def uninstall():
    """Uninstall Blender configuration for AYON."""
    sys.excepthook = ORIGINAL_EXCEPTHOOK

    pyblish.api.deregister_host("blender")
    pyblish.api.deregister_plugin_path(str(PUBLISH_PATH))

    deregister_loader_plugin_path(str(LOAD_PATH))
    deregister_creator_plugin_path(str(CREATE_PATH))
    deregister_workfile_build_plugin_path(str(WORKFILE_BUILD_PATH))

    if not IS_HEADLESS:
        ops.unregister()