pyblish_functions

def attach_instances_to_product(attach_to, instances):
    """Attach instance to product.

    If we are attaching to other products, create copy of existing
    instances, change data to match its product and replace
    existing instances with modified data.

    Args:
        attach_to (list): List of instances to attach to.
        instances (list): List of instances to attach.

    Returns:
          list: List of attached instances.

    """
    new_instances = []
    for attach_instance in attach_to:
        for i in instances:
            new_inst = copy.deepcopy(i)
            new_inst["version"] = attach_instance.get("version")
            new_inst["productName"] = attach_instance.get("productName")
            new_inst["productType"] = attach_instance.get("productType")
            new_inst["productBaseType"] = attach_instance.get(
                "productBaseType"
            )
            new_inst["family"] = attach_instance.get("family")
            new_inst["append"] = True
            # don't set productGroup if we are attaching
            new_inst.pop("productGroup")
            new_instances.append(new_inst)
    return new_instances

def convert_frames_str_to_list(frames: str) -> list[int]:
    """Convert frames definition string to frames.

    Handles formats as:
        >>> convert_frames_str_to_list('1001')
        [1001]
        >>> convert_frames_str_to_list('1002,1004')
        [1002, 1004]
        >>> convert_frames_str_to_list('1003-1005')
        [1003, 1004, 1005]
        >>> convert_frames_str_to_list('1001-1021x5')
        [1001, 1006, 1011, 1016, 1021]

    Args:
        frames (str): String with frames definition.

    Returns:
        list[int]: List of frames.

    """
    step_pattern = re.compile(r"(?:step|by|every|x|:)(\d+)$")

    output = []
    step = 1
    for frame in frames.split(","):
        if "-" in frame:
            frame_start, frame_end = frame.split("-")
            match = step_pattern.findall(frame_end)
            if match:
                step = int(match[0])
                frame_end = re.sub(step_pattern, "", frame_end)

            output.extend(
                range(int(frame_start), int(frame_end) + 1, step)
            )
        else:
            output.append(int(frame))
    output.sort()
    return output

def copy_extend_frames(instance, representation):
    """Copy existing frames from latest version.

    This will copy all existing frames from product's latest version back
    to render directory and rename them to what renderer is expecting.

    Arguments:
        instance (pyblish.plugin.Instance): instance to get required
            data from
        representation (dict): presentation to operate on

    """

    R_FRAME_NUMBER = re.compile(
        r".+\.(?P<frame>[0-9]+)\..+")

    log.info("Preparing to copy ...")
    start = instance.data.get("frameStart")
    end = instance.data.get("frameEnd")
    project_name = instance.context.data["project"]
    anatomy = instance.context.data["anatomy"]

    folder_entity = ayon_api.get_folder_by_path(
        project_name, instance.data.get("folderPath")
    )

    # get latest version of product
    # this will stop if product wasn't published yet

    version_entity = ayon_api.get_last_version_by_product_name(
        project_name,
        instance.data.get("productName"),
        folder_entity["id"]
    )

    # get its files based on extension
    product_resources = get_resources(
        project_name, version_entity, representation.get("ext")
    )
    r_col, _ = clique.assemble(product_resources)

    # if override remove all frames we are expecting to be rendered,
    # so we'll copy only those missing from current render
    if instance.data.get("overrideExistingFrame"):
        for frame in range(start, end + 1):
            if frame not in r_col.indexes:
                continue
            r_col.indexes.remove(frame)

    # now we need to translate published names from representation
    # back. This is tricky, right now we'll just use same naming
    # and only switch frame numbers
    resource_files = []
    r_filename = os.path.basename(
        representation.get("files")[0])  # first file
    op = re.search(R_FRAME_NUMBER, r_filename)
    pre = r_filename[:op.start("frame")]
    post = r_filename[op.end("frame"):]
    assert op is not None, "padding string wasn't found"
    for frame in list(r_col):
        fn = re.search(R_FRAME_NUMBER, frame)
        # silencing linter as we need to compare to True, not to
        # type
        assert fn is not None, "padding string wasn't found"
        # list of tuples (source, destination)
        staging = representation.get("stagingDir")
        staging = anatomy.fill_root(staging)
        resource_files.append(
            (frame, os.path.join(
                staging, "{}{}{}".format(pre, fn["frame"], post)))
        )

    # test if destination dir exists and create it if not
    output_dir = os.path.dirname(representation.get("files")[0])
    if not os.path.isdir(output_dir):
        os.makedirs(output_dir)

    # copy files
    for source in resource_files:
        copyfile(source[0], source[1])
        log.info("  > {}".format(source[1]))

    log.info("Finished copying %i files" % len(resource_files))

def create_instances_for_aov(
    instance,
    skeleton,
    aov_filter,
    skip_integration_repre_list,
    do_not_add_review,
    frames_to_render=None
):
    """Create instances from AOVs.

    This will create new pyblish.api.Instances by going over expected
    files defined on original instance.

    Args:
        instance (pyblish.api.Instance): Original instance.
        skeleton (dict): Skeleton instance data.
        aov_filter (dict): AOV filter.
        skip_integration_repre_list (list): skip
        do_not_add_review (bool): Explicitly disable reviews
        frames_to_render (str | None): Frames to render.

    Returns:
        list of pyblish.api.Instance: Instances created from
            expected files.

    """
    # we cannot attach AOVs to other products as we consider every
    # AOV product of its own.

    # if there are product to attach to and more than one AOV,
    # we cannot proceed.
    if (
        len(instance.data.get("attachTo", [])) > 0
        and len(instance.data.get("expectedFiles")[0].keys()) != 1
    ):
        raise KnownPublishError(
            "attaching multiple AOVs or renderable cameras to "
            "product is not supported yet.")

    additional_data = {
        "renderProducts": instance.data["renderProducts"],
    }

    # Collect color management data if present
    colorspace_config = instance.data.get("colorspaceConfig")
    if colorspace_config:
        additional_data.update({
            "colorspaceConfig": colorspace_config,
            # Display/View are optional
            "display": instance.data.get("sourceDisplay"),
            "view": instance.data.get("sourceView")
        })

        # Get templated path from absolute config path.
        anatomy = instance.context.data["anatomy"]
        template = find_colorspace_template(colorspace_config, anatomy)
        additional_data["colorspaceTemplate"] = template or colorspace_config

    # create instances for every AOV we found in expected files.
    # NOTE: this is done for every AOV and every render camera (if
    #       there are multiple renderable cameras in scene)
    return _create_instances_for_aov(
        instance,
        skeleton,
        aov_filter,
        additional_data,
        skip_integration_repre_list,
        do_not_add_review,
        frames_to_render
    )

def create_instances_for_cache(instance, skeleton):
    """Create instance for cache.

    This will create new instance for every AOV it can detect in expected
    files list.

    Args:
        instance (pyblish.api.Instance): Original instance.
        skeleton (dict): Skeleton data for instance (those needed) later
            by collector.


    Returns:
        list of instances

    Throws:
        ValueError:

    """
    anatomy = instance.context.data["anatomy"]
    product_name = skeleton["productName"]
    product_type = skeleton["productType"]
    product_base_type = skeleton.get("productBaseType")
    if not product_base_type:
        product_base_type = product_type
    exp_files = instance.data["expectedFiles"]

    instances = []
    # go through AOVs in expected files
    for _, files in exp_files[0].items():
        cols, rem = clique.assemble(files)
        # we shouldn't have any reminders. And if we do, it should
        # be just one item for single frame renders.
        if not cols and rem:
            if len(rem) != 1:
                raise ValueError("Found multiple non related files "
                                 "to render, don't know what to do "
                                 "with them.")
            col = rem[0]
            ext = os.path.splitext(col)[1].lstrip(".")
        else:
            # but we really expect only one collection.
            # Nothing else make sense.
            if len(cols) != 1:
                raise ValueError("Only one image sequence type is expected.")  # noqa: E501
            ext = cols[0].tail.lstrip(".")
            col = list(cols[0])

        if isinstance(col, (list, tuple)):
            staging = os.path.dirname(col[0])
        else:
            staging = os.path.dirname(col)

        try:
            staging = remap_source(staging, anatomy)
        except ValueError as e:
            log.warning(e)

        new_instance = copy.deepcopy(skeleton)

        log.info("Creating data for: {}".format(product_name))
        new_instance["productName"] = product_name
        new_instance["productType"] = product_type
        new_instance["productBaseType"] = product_base_type
        # create representation
        if isinstance(col, (list, tuple)):
            files = [os.path.basename(f) for f in col]
        else:
            files = os.path.basename(col)

        rep = {
            "name": ext,
            "ext": ext,
            "files": files,
            "frameStart": int(skeleton["frameStartHandle"]),
            "frameEnd": int(skeleton["frameEndHandle"]),
            # If expectedFile are absolute, we need only filenames
            "stagingDir": staging,
            "fps": new_instance.get("fps"),
            "tags": [],
        }

        new_instance["representations"] = [rep]

        # if extending frames from existing version, copy files from there
        # into our destination directory
        if new_instance.get("extendFrames", False):
            copy_extend_frames(new_instance, rep)
        instances.append(new_instance)
        log.debug("instances:{}".format(instances))
    return instances

def create_skeleton_instance(
    instance,
    families_transfer=None,
    instance_transfer=None,
):
    """Create skeleton instance from original instance data.

    This will create dictionary containing skeleton
    - common - data used for publishing rendered instances.
    This skeleton instance is then extended with additional data
    and serialized to be processed by farm job.

    Args:
        instance (pyblish.api.Instance): Original instance to
            be used as a source of data.
        families_transfer (list): List of family names to transfer
            from the original instance to the skeleton.
        instance_transfer (dict): Dict with keys as families and
            values as a list of property names to transfer to the
            new skeleton.

    Returns:
        dict: Dictionary with skeleton instance data.

    """
    # list of family names to transfer to new family if present
    if families_transfer is None:
        families_transfer = []

    if instance_transfer is None:
        instance_transfer = {}

    context = instance.context
    data = instance.data.copy()
    anatomy = instance.context.data["anatomy"]

    # get time related data from instance (or context)
    time_data = get_time_data_from_instance_or_context(instance)

    if data.get("extendFrames", False):
        time_data.start, time_data.end = extend_frames(
            data["folderPath"],
            data["productName"],
            time_data.start,
            time_data.end,
        )

    source = data.get("source") or context.data.get("currentFile")
    success, rootless_path = (
        anatomy.find_root_template_from_path(source)
    )
    if success:
        source = rootless_path
    else:
        # `rootless_path` is not set to `source` if none of roots match
        log.warning(("Could not find root path for remapping \"{}\". "
                     "This may cause issues.").format(source))

    # This is a hack to keep the value of 'productType'.
    # Because this function does not use product base type from source
    #   instance and we don't know if product type of the instance was
    #   customized or not, only way how to guess custom product type is
    #   to check if is same as product base type.
    i_product_base_type = instance.data.get("productBaseType")
    i_product_type = instance.data.get("productType")
    product_type = None
    if (
        i_product_base_type
        and i_product_base_type != i_product_type
    ):
        product_type = i_product_type

    # This is the old way of defining product base type
    # - hard-coded product base type
    product_base_type = "render"
    if "prerender.farm" in instance.data["families"]:
        product_base_type = "prerender"

    if not product_type:
        product_type = product_base_type

    families = [product_base_type]

    # pass review to families if marked as review
    if data.get("review"):
        families.append("review")

    instance_skeleton_data = {
        # TODO find out how to define product type
        # - Right now product base type is hardcoded, from where should be
        #   product type taken?
        "productType": product_type,
        "productBaseType": product_base_type,
        "productName": data["productName"],
        "task": data["task"],
        "families": families,
        "folderPath": data["folderPath"],
        "frameStart": time_data.start,
        "frameEnd": time_data.end,
        "handleStart": time_data.handle_start,
        "handleEnd": time_data.handle_end,
        "frameStartHandle": time_data.start - time_data.handle_start,
        "frameEndHandle": time_data.end + time_data.handle_end,
        "comment": data.get("comment"),
        "fps": time_data.fps,
        "source": source,
        "extendFrames": data.get("extendFrames"),
        "overrideExistingFrame": data.get("overrideExistingFrame"),
        "pixelAspect": data.get("pixelAspect", 1),
        "resolutionWidth": data.get("resolutionWidth", 1920),
        "resolutionHeight": data.get("resolutionHeight", 1080),
        "multipartExr": data.get("multipartExr", False),
        "jobBatchName": data.get("jobBatchName", ""),
        "useSequenceForReview": data.get("useSequenceForReview", True),
        "inputVersions": serialize_input_versions(data.get("inputVersions")),
        "colorspace": data.get("colorspace"),
        "hasExplicitFrames": data.get("hasExplicitFrames", False),
        "reuseLastVersion": data.get("reuseLastVersion", False),
    }

    # Pass on the OCIO metadata of what the source display and view are
    # so that the farm can correctly set up color management.
    if "sceneDisplay" in data and "sceneView" in data:
        instance_skeleton_data["sceneDisplay"] = data["sceneDisplay"]
        instance_skeleton_data["sceneView"] = data["sceneView"]
    elif "colorspaceDisplay" in data and "colorspaceView" in data:
        # Backwards compatibility for sceneDisplay and sceneView
        instance_skeleton_data["colorspaceDisplay"] = data["colorspaceDisplay"]
        instance_skeleton_data["colorspaceView"] = data["colorspaceView"]
    if "sourceDisplay" in data and "sourceView" in data:
        instance_skeleton_data["sourceDisplay"] = data["sourceDisplay"]
        instance_skeleton_data["sourceView"] = data["sourceView"]

    if data.get("renderlayer"):
        instance_skeleton_data["renderlayer"] = data["renderlayer"]

    # skip locking version if we are creating v01
    instance_version = data.get("version")  # take this if exists
    if instance_version != 1:
        instance_skeleton_data["version"] = instance_version

    # transfer specific families from original instance to new render
    for item in families_transfer:
        if item in instance.data.get("families", []):
            instance_skeleton_data["families"] += [item]

    # transfer specific properties from original instance based on
    # mapping dictionary `instance_transfer`
    for key, values in instance_transfer.items():
        if key in instance.data.get("families", []):
            for v in values:
                instance_skeleton_data[v] = instance.data.get(v)

    representations = get_transferable_representations(instance)
    instance_skeleton_data["representations"] = representations

    persistent = instance.data.get("stagingDir_persistent") is True
    instance_skeleton_data["stagingDir_persistent"] = persistent

    return instance_skeleton_data

def create_skeleton_instance_cache(instance):
    """Create skeleton instance from original instance data.

    This will create dictionary containing skeleton
    - common - data used for publishing rendered instances.
    This skeleton instance is then extended with additional data
    and serialized to be processed by farm job.

    Args:
        instance (pyblish.api.Instance): Original instance to
            be used as a source of data.

    Returns:
        dict: Dictionary with skeleton instance data.

    """
    # list of family names to transfer to new family if present

    context = instance.context
    data = instance.data.copy()
    anatomy = instance.context.data["anatomy"]

    # get time related data from instance (or context)
    time_data = get_time_data_from_instance_or_context(instance)

    if data.get("extendFrames", False):
        time_data.start, time_data.end = extend_frames(
            data["folderPath"],
            data["productName"],
            time_data.start,
            time_data.end,
        )

    source = data.get("source") or context.data.get("currentFile")
    success, rootless_path = (
        anatomy.find_root_template_from_path(source)
    )
    if success:
        source = rootless_path
    else:
        # `rootless_path` is not set to `source` if none of roots match
        log.warning(("Could not find root path for remapping \"{}\". "
                     "This may cause issues.").format(source))

    product_type = instance.data["productType"]
    product_base_type = instance.data.get("productBaseType")
    if not product_base_type:
        product_base_type = product_type
    # Make sure "render" is in the families to go through
    # validating expected and rendered files
    # during publishing job.
    families = ["render", product_base_type]

    instance_skeleton_data = {
        "productName": data["productName"],
        "productType": product_type,
        "productBaseType": product_base_type,
        "family": product_base_type,
        "families": families,
        "folderPath": data["folderPath"],
        "frameStart": time_data.start,
        "frameEnd": time_data.end,
        "handleStart": time_data.handle_start,
        "handleEnd": time_data.handle_end,
        "frameStartHandle": time_data.start - time_data.handle_start,
        "frameEndHandle": time_data.end + time_data.handle_end,
        "comment": data.get("comment"),
        "fps": time_data.fps,
        "source": source,
        "extendFrames": data.get("extendFrames"),
        "overrideExistingFrame": data.get("overrideExistingFrame"),
        "jobBatchName": data.get("jobBatchName", ""),
        "inputVersions": serialize_input_versions(data.get("inputVersions")),
    }

    # skip locking version if we are creating v01
    instance_version = data.get("version")  # take this if exists
    if instance_version != 1:
        instance_skeleton_data["version"] = instance_version

    representations = get_transferable_representations(instance)
    instance_skeleton_data["representations"] = representations

    persistent = instance.data.get("stagingDir_persistent") is True
    instance_skeleton_data["stagingDir_persistent"] = persistent

    return instance_skeleton_data

def extend_frames(folder_path, product_name, start, end):
    """Get latest version of asset nad update frame range.

    Based on minimum and maximum values.

    Arguments:
        folder_path (str): Folder path.
        product_name (str): Product name.
        start (int): Start frame.
        end (int): End frame.

    Returns:
        (int, int): update frame start/end

    """
    # Frame comparison
    prev_start = None
    prev_end = None

    project_name = get_current_project_name()
    folder_entity = ayon_api.get_folder_by_path(
        project_name, folder_path, fields={"id"}
    )
    version_entity = ayon_api.get_last_version_by_product_name(
        project_name,
        product_name,
        folder_entity["id"]
    )

    # Set prev start / end frames for comparison
    if not prev_start and not prev_end:
        prev_start = version_entity["attrib"]["frameStart"]
        prev_end = version_entity["attrib"]["frameEnd"]

    updated_start = min(start, prev_start)
    updated_end = max(end, prev_end)

    return updated_start, updated_end

def find_colorspace_template(
    colorspace_path: str,
    anatomy: Anatomy,
) -> str | None:
    """Find template for colorspace path.

    Try to use builtin OCIO if path is relative to it. If not, try to
        remap path using anatomy. If that fails, return None.

    Args:
        colorspace_path (str): Path to colorspace.
        anatomy (Anatomy): Project anatomy object.

    Returns:
        str | None: Template to use for colorspace path.

    """
    builtin_path = os.getenv("BUILTIN_OCIO_ROOT")
    if builtin_path:
        builtin_path = Path(builtin_path).resolve().absolute()
        path = Path(colorspace_path).resolve().absolute()
        if path.is_relative_to(builtin_path):
            relative = str(path.relative_to(builtin_path))
            if platform.system().lower() == "windows":
                relative = relative.replace("\\", "/")
            return f"{{BUILTIN_OCIO_ROOT}}/{relative}"

    output = None
    try:
        output = remap_source(colorspace_path, anatomy)
        if platform.system().lower() == "windows":
            output = output.replace("\\", "/")
    except ValueError:
        pass
    return output

def get_product_name_and_group_from_template(
    project_name: str,
    task_entity: Union[dict[str, Any], None],
    product_type: str,
    variant: str,
    host_name: str,
    dynamic_data: Optional[dict[str, Any]] = None,
    *,
    folder_entity: Union[dict[str, Any], None] = None,
    product_base_type: str = None,
    project_entity: Optional[dict[str, Any]] = None,
    project_settings: Optional[dict[str, Any]] = None,
) -> tuple[str, str]:
    """Get product name and group name from template.

    NOTE: This function is/was used only in ayon-houdini which uses/d kwargs
        for all arguments. When houdini starts to use 'folder_entity' and
        'product_base_type' this should change order of arguments.

    This will get product name and group name from template based on
    data provided. It is doing similar work as
    `func::_get_legacy_product_name_and_group` but using templates.

    To get group name, template is called without any dynamic data, so
    (depending on the template itself) it should be product name without
    aov.

    Todo:
        Maybe we should introduce templates for the groups themselves.

    Args:
        project_name (str): Project name.
        task_entity (Union[dict[str, Any], None]): Task entity.
        host_name (str): Host name.
        product_type (str): Product type.
        variant (str): Variant.
        dynamic_data (Optional[dict[str, Any]]): Dynamic data
            (aov, renderlayer, camera, ...).
        folder_entity (Union[dict[str, Any], None]): Folder entity.
        product_base_type (str): Product base type.
        project_entity (Optional[dict[str, Any]]): Project entity.
        project_settings (Optional[dict[str, Any]]): Project settings.

    Returns:
        tuple: product name and group name.

    """
    if not folder_entity and task_entity:
        folder_entity = None
        if task_entity:
            folder_entity = ayon_api.get_folder_by_path(
                project_name, task_entity["folderId"]
            )

    if not product_base_type:
        log.warning(
            f"DEPRECATION WARNING: Product base type not provided,"
            f" using product type: {product_type}"
        )
        product_base_type = product_type

    if not project_entity:
        project_entity = ayon_api.get_project(project_name)

    if not project_settings:
        project_settings = get_project_settings(project_name)

    # remove 'aov' from data used to format group. See todo comment above
    # for possible solution.
    if dynamic_data is None:
        dynamic_data = {}
    _dynamic_data = copy.deepcopy(dynamic_data)
    _dynamic_data.pop("aov", None)

    resulting_group_name = get_product_name(
        project_name=project_name,
        folder_entity=folder_entity,
        task_entity=task_entity,
        host_name=host_name,
        product_base_type=product_base_type,
        product_type=product_type,
        dynamic_data=_dynamic_data,
        variant=variant,
        project_entity=project_entity,
        project_settings=project_settings,
    )

    resulting_product_name = get_product_name(
        project_name=project_name,
        folder_entity=folder_entity,
        task_entity=task_entity,
        host_name=host_name,
        product_base_type=product_base_type,
        product_type=product_type,
        dynamic_data=dynamic_data,
        variant=variant,
        project_entity=project_entity,
        project_settings=project_settings,
    )
    return resulting_product_name, resulting_group_name

def get_resources(project_name, version_entity, extension=None):
    """Get the files from the specific version.

    This will return all get all files from representation.

    Todo:
        This is really weird function, and it's use is
        highly controversial. First, it will not probably work
        ar all in final release of AYON, second, the logic isn't sound.
        It should try to find representation matching the current one -
        because it is used to pull out files from previous version to
        be included in this one.

    .. deprecated:: 3.15.5
       This won't work in AYON and even the logic must be refactored.

    Args:
        project_name (str): Name of the project.
        version_entity (dict): Version entity.
        extension (str): extension used to filter
            representations.

    Returns:
        list: of files

    """
    warnings.warn((
        "This won't work in AYON and even "
        "the logic must be refactored."), DeprecationWarning)
    extensions = []
    if extension:
        extensions = [extension]

    # there is a `context_filter` argument that won't probably work in
    # final release of AYON. SO we'll rather not use it
    repre_entities = list(ayon_api.get_representations(
        project_name, version_ids={version_entity["id"]}
    ))

    filtered = []
    for repre_entity in repre_entities:
        if repre_entity["context"]["ext"] in extensions:
            filtered.append(repre_entity)

    representation = filtered[0]
    directory = get_representation_path(
        project_name, representation
    )
    print("Source: ", directory)
    resources = sorted(
        [
            os.path.normpath(os.path.join(directory, file_name))
            for file_name in os.listdir(directory)
        ]
    )

    return resources

def get_time_data_from_instance_or_context(instance):
    """Get time data from instance (or context).

    If time data is not found on instance, data from context will be used.

    Args:
        instance (pyblish.api.Instance): Source instance.

    Returns:
        TimeData: dataclass holding time information.

    """
    context = instance.context
    return TimeData(
        start=instance.data.get("frameStart", context.data.get("frameStart")),
        end=instance.data.get("frameEnd", context.data.get("frameEnd")),
        fps=instance.data.get("fps", context.data.get("fps")),
        step=instance.data.get("byFrameStep", instance.data.get("step", 1)),
        handle_start=instance.data.get(
            "handleStart", context.data.get("handleStart")
        ),
        handle_end=instance.data.get(
            "handleEnd", context.data.get("handleEnd")
        )
    )

def get_transferable_representations(instance):
    """Transfer representations from original instance.

    This will get all representations on the original instance that
    are flagged with `publish_on_farm` and return them to be included
    on skeleton instance if needed.

    Args:
        instance (pyblish.api.Instance): Original instance to be processed.

    Return:
        list of dicts: List of transferable representations.

    """
    anatomy = instance.context.data["anatomy"]
    to_transfer = []

    for representation in instance.data.get("representations", []):
        if "publish_on_farm" not in representation.get("tags", []):
            continue

        trans_rep = representation.copy()

        # remove publish_on_farm from representations tags
        trans_rep["tags"].remove("publish_on_farm")

        staging_dir = trans_rep.get("stagingDir")

        if staging_dir:
            try:
                trans_rep["stagingDir"] = remap_source(staging_dir, anatomy)
            except ValueError:
                log.warning(
                    ("Could not find root path for remapping \"{}\". "
                     "This may cause issues on farm.").format(staging_dir))

        to_transfer.append(trans_rep)
    return to_transfer

def prepare_cache_representations(skeleton_data, exp_files, anatomy):
    """Create representations for file sequences.

    This will return representations of expected files if they are not
    in hierarchy of aovs. There should be only one sequence of files for
    most cases, but if not - we create representation from each of them.

    Arguments:
        skeleton_data (dict): instance data for which we are
                         setting representations
        exp_files (list): list of expected files
        anatomy (Anatomy)
    Returns:
        list of representations

    """
    representations = []
    collections, _remainders = clique.assemble(exp_files)

    # create representation for every collected sequence
    for collection in collections:
        ext = collection.tail.lstrip(".")

        staging = os.path.dirname(list(collection)[0])
        success, rootless_staging_dir = (
            anatomy.find_root_template_from_path(staging)
        )
        if success:
            staging = rootless_staging_dir
        else:
            log.warning((
                "Could not find root path for remapping \"{}\"."
                " This may cause issues on farm."
            ).format(staging))

        frame_start = int(skeleton_data.get("frameStartHandle"))
        rep = {
            "name": ext,
            "ext": ext,
            "files": [os.path.basename(f) for f in list(collection)],
            "frameStart": frame_start,
            "frameEnd": int(skeleton_data.get("frameEndHandle")),
            # If expectedFile are absolute, we need only filenames
            "stagingDir": staging,
            "fps": skeleton_data.get("fps")
        }

        representations.append(rep)

    return representations

def prepare_representations(
    skeleton_data,
    exp_files,
    anatomy,
    aov_filter,
    skip_integration_repre_list,
    do_not_add_review,
    context,
    color_managed_plugin,
    frames_to_render=None
):
    """Create representations for file sequences.

    This will return representations of expected files if they are not
    in hierarchy of aovs. There should be only one sequence of files for
    most cases, but if not - we create representation from each of them.

    Arguments:
        skeleton_data (dict): instance data for which we are
                         setting representations
        exp_files (list): list of expected files
        anatomy (Anatomy):
        aov_filter (dict): add review for specific aov names
        skip_integration_repre_list (list): exclude specific extensions,
        do_not_add_review (bool): explicitly skip review
        color_managed_plugin (publish.ColormanagedPyblishPluginMixin)
        frames_to_render (str | None): implicit or explicit range of frames
            to render this value is sent to Deadline in JobInfo.Frames
    Returns:
        list of representations

    """
    representations = []
    host_name = os.environ.get("AYON_HOST_NAME", "")
    collections, remainders = clique.assemble(exp_files)

    if frames_to_render is not None:
        frames_to_render = convert_frames_str_to_list(frames_to_render)
    else:
        # Backwards compatibility for older logic
        frame_start = int(skeleton_data.get("frameStartHandle"))
        frame_end = int(skeleton_data.get("frameEndHandle"))
        frames_to_render = list(range(frame_start, frame_end + 1))

    # create representation for every collected sequence
    for collection in collections:
        ext = collection.tail.lstrip(".")
        preview = False
        # TODO 'useSequenceForReview' is temporary solution which does
        #   not work for 100% of cases. We must be able to tell what
        #   expected files contains more explicitly and from what
        #   should be review made.
        # - "review" tag is never added when is set to 'False'
        if skeleton_data["useSequenceForReview"]:
            # toggle preview on if multipart is on
            if skeleton_data.get("multipartExr", False):
                log.debug(
                    "Adding preview tag because its multipartExr"
                )
                preview = True
            else:
                render_file_name = list(collection)[0]
                # if filtered aov name is found in filename, toggle it for
                # preview video rendering
                preview = match_aov_pattern(
                    host_name, aov_filter, render_file_name
                )

        staging = os.path.dirname(list(collection)[0])
        success, rootless_staging_dir = (
            anatomy.find_root_template_from_path(staging)
        )
        if success:
            staging = rootless_staging_dir
        else:
            log.warning((
                "Could not find root path for remapping \"{}\"."
                " This may cause issues on farm."
            ).format(staging))

        frame_start = frames_to_render[0]
        frame_end = frames_to_render[-1]
        if skeleton_data.get("slate"):
            frame_start -= 1
            frames_to_render.insert(0, frame_start)

        filenames = [
            os.path.basename(filepath)
            for filepath in _get_real_files_to_render(
                collection, frames_to_render
            )
        ]
        # explicitly disable review by user
        preview = preview and not do_not_add_review
        rep = {
            "name": ext,
            "ext": ext,
            "files": filenames,
            "stagingDir": staging,
            "frameStart": frame_start,
            "frameEnd": frame_end,
            "fps": skeleton_data.get("fps"),
            "tags": ["review"] if preview else [],
        }

        # poor man exclusion
        if ext in skip_integration_repre_list:
            rep["tags"].append("delete")

        if skeleton_data.get("multipartExr", False):
            rep["tags"].append("multipartExr")

        # support conversion from tiled to scanline
        if skeleton_data.get("convertToScanline"):
            log.info("Adding scanline conversion.")
            rep["tags"].append("toScanline")

        representations.append(rep)

        if preview:
            skeleton_data["families"] = _add_review_families(
                skeleton_data["families"])

    # add remainders as representations
    for remainder in remainders:
        ext = remainder.split(".")[-1]

        staging = os.path.dirname(remainder)
        success, rootless_staging_dir = (
            anatomy.find_root_template_from_path(staging)
        )
        if success:
            staging = rootless_staging_dir
        else:
            log.warning((
                "Could not find root path for remapping \"{}\"."
                " This may cause issues on farm."
            ).format(staging))

        rep = {
            "name": ext,
            "ext": ext,
            "files": os.path.basename(remainder),
            "stagingDir": staging,
        }

        preview = match_aov_pattern(
            host_name, aov_filter, remainder
        )
        preview = preview and not do_not_add_review
        if preview:
            rep.update({
                "fps": skeleton_data.get("fps"),
                "tags": ["review"]
            })
            skeleton_data["families"] = \
                _add_review_families(skeleton_data["families"])

        already_there = False
        for repre in skeleton_data.get("representations", []):
            # might be added explicitly before by publish_on_farm
            already_there = repre.get("files") == rep["files"]
            if already_there:
                log.debug("repre {} already_there".format(repre))
                break

        if not already_there:
            representations.append(rep)

    for rep in representations:
        # inject colorspace data
        color_managed_plugin.set_representation_colorspace(
            rep, context,
            colorspace=skeleton_data["colorspace"]
        )

    return representations

def remap_source(path, anatomy):
    """Try to remap path to rootless path.

    Args:
        path (str): Path to be remapped to rootless.
        anatomy (Anatomy): Anatomy object to handle remapping
            itself.

    Returns:
        str: Remapped path.

    Throws:
        ValueError: if the root cannot be found.

    """
    success, rootless_path = (
        anatomy.find_root_template_from_path(path)
    )
    if success:
        return rootless_path
    raise ValueError(
        f"Root from template path cannot be found: {path}"
    )