lib

def create_bin(name: str,
               root: object = None,
               set_as_current: bool = True) -> object:
    """
    Create media pool's folder.

    Return folder object and if the name does not exist it will create a new.
    If the input name is with forward or backward slashes then it will create
    all parents and return the last child bin object

    Args:
        name (str): name of folder / bin, or hierarchycal name "parent/name"
        root (resolve.Folder)[optional]: root folder / bin object
        set_as_current (resolve.Folder)[optional]: Whether to set the
            resulting bin as current folder or not.

    Returns:
        object: resolve.Folder
    """
    # get all variables
    media_pool = get_current_resolve_project().GetMediaPool()
    root_bin = root or media_pool.GetRootFolder()

    # create hierarchy of bins in case there is slash in name
    if "/" in name.replace("\\", "/"):
        child_bin = None
        for bname in name.split("/"):
            child_bin = create_bin(bname,
                                   root=child_bin or root_bin,
                                   set_as_current=set_as_current)
        if child_bin:
            return child_bin
    else:
        # Find existing folder or create it
        for subfolder in root_bin.GetSubFolderList():
            if subfolder.GetName() == name:
                created_bin = subfolder
                break
        else:
            created_bin = media_pool.AddSubFolder(root_bin, name)

        if set_as_current:
            media_pool.SetCurrentFolder(created_bin)

        return created_bin

def create_compound_clip(clip_data, name, folder):
    """
    Convert timeline object into nested timeline object

    Args:
        clip_data (dict): timeline item object packed into dict
                          with project, timeline (sequence)
        folder (resolve.MediaPool.Folder): media pool folder object,
        name (str): name for compound clip

    Returns:
        resolve.MediaPoolItem: media pool item with compound clip timeline(cct)
    """
    # get basic objects form data
    resolve_project = clip_data["project"]
    timeline = clip_data["timeline"]
    clip = clip_data["clip"]

    # get details of objects
    clip_item = clip["item"]

    mp = resolve_project.GetMediaPool()

    # get clip attributes
    clip_attributes = get_clip_attributes(clip_item)

    mp_item = clip_item.GetMediaPoolItem()
    _mp_props = mp_item.GetClipProperty

    mp_first_frame = int(_mp_props("Start"))
    mp_last_frame = int(_mp_props("End"))

    # initialize basic source timing for otio
    ci_l_offset = clip_item.GetLeftOffset()
    ci_duration = clip_item.GetDuration()
    rate = float(_mp_props("FPS"))

    # source rational times
    mp_in_rc = otio.opentime.RationalTime((ci_l_offset), rate)
    mp_out_rc = otio.opentime.RationalTime((ci_l_offset + ci_duration - 1), rate)

    # get frame in and out for clip swapping
    in_frame = otio.opentime.to_frames(mp_in_rc)
    out_frame = otio.opentime.to_frames(mp_out_rc)

    # keep original sequence
    tl_origin = timeline

    # Set current folder to input media_pool_folder:
    mp.SetCurrentFolder(folder)

    # check if clip doesn't exist already:
    clips = folder.GetClipList()
    cct = next((c for c in clips
                if c.GetName() in name), None)

    if cct:
        print(f"Compound clip exists: {cct}")
    else:
        # Create empty timeline in current folder and give name:
        cct = mp.CreateEmptyTimeline(name)

        # check if clip doesn't exist already:
        clips = folder.GetClipList()
        cct = next((c for c in clips
                    if c.GetName() in name), None)
        print(f"Compound clip created: {cct}")

        with maintain_current_timeline(cct, tl_origin):
            # Add input clip to the current timeline:
            mp.AppendToTimeline([{
                "mediaPoolItem": mp_item,
                "startFrame": mp_first_frame,
                "endFrame": mp_last_frame
            }])

    # Add collected metadata and attributes to the compound clip:
    if mp_item.GetMetadata(constants.AYON_TAG_NAME):
        clip_attributes[constants.AYON_TAG_NAME] = mp_item.GetMetadata(
            constants.AYON_TAG_NAME)[constants.AYON_TAG_NAME]

    # stringify
    clip_attributes = json.dumps(clip_attributes)

    # add attributes to metadata
    for k, v in mp_item.GetMetadata().items():
        cct.SetMetadata(k, v)

    # add metadata to cct
    cct.SetMetadata(constants.AYON_TAG_NAME, clip_attributes)

    # reset start timecode of the compound clip
    cct.SetClipProperty("Start TC", _mp_props("Start TC"))

    # swap clips on timeline
    swap_clips(clip_item, cct, in_frame, out_frame)

    cct.SetClipColor("Pink")
    return cct

def create_media_pool_item(files: list,
                           root: object = None) -> object:
    """ Create media pool item.

    Args:
        files (list): absolute path to a file
        root (resolve.Folder)[optional]: root folder / bin object

    Returns:
        object: resolve.MediaPoolItem
    """
    # get all variables
    resolve_project = get_current_resolve_project()
    media_pool = resolve_project.GetMediaPool()
    root_bin = root or media_pool.GetRootFolder()

    # make sure files list is not empty and first available file exists
    filepath = next((f for f in files if os.path.isfile(f)), None)
    if not filepath:
        raise FileNotFoundError("No file found in input files list")

    # try to search in bin if the clip does not exist
    existing_mpi = get_media_pool_item(filepath, root_bin)

    if existing_mpi:
        return existing_mpi

    # add media to media-pool
    media_pool_items = media_pool.ImportMedia(files)
    if not media_pool_items:
        raise RuntimeError(f"Failed to import media: {files}")

    # return only first found
    return media_pool_items.pop()

def create_timeline_item(
    media_pool_item: object,
    timeline: object | None = None,
    timeline_in: int | None = None,
    source_start: int | None = None,
    source_end: int | None = None,
    track_name: str | None = None,
) -> object:
    """
    Add media pool item to current or defined timeline.

    Args:
        media_pool_item (resolve.MediaPoolItem): resolve's object
        timeline (Optional[resolve.Timeline]): resolve's object
        timeline_in (Optional[int]): timeline input frame (sequence frame)
        source_start (Optional[int]): media source input frame (sequence frame)
        source_end (Optional[int]): media source output frame (sequence frame)
        track_name (Optional[str]): video track to add the item to. Track is
            created if it does not exist or is not free in item's range.
            Default video track is used if not set.

    Returns:
        object: resolve.TimelineItem
    """
    # get all variables
    resolve_project = get_current_resolve_project()
    media_pool = resolve_project.GetMediaPool()
    clip_name = media_pool_item.GetClipProperty("File Name")
    timeline = timeline or get_current_timeline()

    # timing variables
    if all([
        timeline_in is not None,
        source_start is not None,
        source_end is not None
    ]):
        fps = timeline.GetSetting("timelineFrameRate")
        # number of frames, `source_end` is the last used frame (inclusive)
        duration = source_end - source_start + 1
        timecode_in = frames_to_timecode(timeline_in, fps)
        timecode_out = frames_to_timecode(timeline_in + duration - 1, fps)
    else:
        timecode_in = None
        timecode_out = None

    track_index = None
    if track_name:
        record_range = (None, None)
        if timecode_in:
            record_range = (timeline_in, timeline_in + duration)
        track_index = get_or_create_video_track(
            timeline, track_name, *record_range
        )

    # if timeline was used then switch it to current timeline
    output_timeline_item = None
    with maintain_current_timeline(timeline):
        # Add input mediaPoolItem to clip data
        clip_data = {
            "mediaPoolItem": media_pool_item,
        }

        # Movie media starts at frame 0, so do not test for truthiness.
        # Resolve ignores `endFrame` without `startFrame`.
        if source_start is not None:
            # Note: specifying a startFrame or endFrame will fail to place the
            # timeline item if the item does not have that frame, e.g. a static
            # representation on version that does have frame start and end.
            clip_data["startFrame"] = source_start
        if source_end is not None:
            # `endFrame` of AppendToTimeline is exclusive, while
            # `source_end` is the last used frame
            clip_data["endFrame"] = source_end + 1
        if timecode_in:
            # Note: specifying a recordFrame will fail to place the timeline
            #  item if there's already an existing clip at that time on the
            #  active track.
            clip_data["recordFrame"] = timeline_in
        if track_index:
            clip_data["trackIndex"] = track_index
            # video only, audio would need its own track index
            clip_data["mediaType"] = 1

        # add to timeline
        appended_items = media_pool.AppendToTimeline([clip_data])
        if appended_items:
            output_timeline_item = appended_items[0]

            # Adding the item may fail whilst Resolve will still return a
            # TimelineItem instance - however all `Get*` calls return None
            # Hence, we check whether the result is valid
            if output_timeline_item.GetDuration() is None:
                output_timeline_item = None

    if not output_timeline_item:
        raise RuntimeError(
            f"Clip name '{clip_name}' wasn't created on the timeline: "
            f"'{timeline.GetName()}' \n\n"
            "Please check if correct track position is activated, "
            "or if a clip is not already at the timeline in "
            f"position: '{timecode_in}' out: '{timecode_out}'. \n\n"
            "This may also happen if the loaded media does not have frame "
            "start, end or timecode specified in the clip data.\n\n"
            f"Clip data: {clip_data}"
        )
    return output_timeline_item

def detect_project_fps_mismatch(task_entity=None):
    """ Detect potential fps mismatch between project settings
    and task entity. Return any mismatch as a information
    string to be displayed to the user.
    """
    task_entity = task_entity or get_current_task_entity()
    attributes = task_entity["attrib"]
    task_fps = attributes["fps"]

    resolve_project = get_current_resolve_project()
    resolve_fps = resolve_project.GetSetting("timelineFrameRate")

    if task_fps != resolve_fps:
        return (
            f"Project current fps is {resolve_fps} "
            f"while task fps is {task_fps}."
        )

    return None

def detect_project_resolution_mismatch(task_entity=None):
    """ Detect potential resolution mismatch between project settings
    and task entity. Return any mismatch as a information
    string to be displayed to the user.
    """
    task_entity = task_entity or get_current_task_entity()
    attributes = task_entity["attrib"]
    width = attributes["resolutionWidth"]
    height = attributes["resolutionHeight"]

    resolve_project = get_current_resolve_project()
    resolve_width = resolve_project.GetSetting("timelineResolutionWidth")
    resolve_height = resolve_project.GetSetting("timelineResolutionHeight")

    if (str(width), str(height)) != (resolve_width, resolve_height):
        return (
            f"Project current resolution is {resolve_width}x{resolve_height} "
            f"while task resolution is {width}x{height}."
        )

    return None

def export_timeline_otio(timeline):
    """ Export timeline as otio.

    Args:
        timeline (resolve.Timeline): resolve's timeline

    Returns:
        otio_timeline (otio.Timeline): Otio timeline.
    """
    # DaVinci Resolve <= 18.5
    # Legacy export (slower) through AYON.
    if not hasattr(timeline, "Export"):
        return otio_export.create_otio_timeline(
            get_current_resolve_project(),
            timeline=timeline
        )

    # DaVinci Resolve >= 18.5
    # Force export through a temporary file (native)
    temp_otio_file = _get_otio_temp_file(timeline=timeline)
    export_timeline_otio_to_file(timeline, temp_otio_file)
    otio_timeline = otio.adapters.read_from_file(temp_otio_file)

    return otio_timeline

def export_timeline_otio_native(timeline, filepath):
    """Get timeline otio filepath.

    Only supported from Resolve 18.5

    Example:
        # Native otio export is available from Resolve 18.5
        # [major, minor, patch, build, suffix]
        resolve_version = bmdvr.GetVersion()
        if tuple(resolve_version[:2]) < (18, 5):
            # if it is lower then use ayon's otio exporter
            otio_timeline = davinci_export.create_otio_timeline(
                resolve_project, timeline=timeline)
            davinci_export.write_to_file(otio_timeline, filepath)
        else:
            # use native otio export
            export_timeline_otio_native(timeline, filepath)

    Args:
        timeline (resolve.Timeline): resolve's object
        filepath (str): otio file path

    Returns:
        bool: True if success
    """
    from . import bmdvr

    try:
        timeline.Export(filepath, bmdvr.EXPORT_OTIO)
    except Exception as e:
        log.error(f"Failed to export timeline otio: {e}")
        return False
    return True

def export_timeline_otio_to_file(timeline, filepath):
    """Export timeline as otio filepath.

    Args:
        timeline (resolve.Timeline): resolve's timeline
        filepath (str): otio file path

    Returns:
        str: temporary otio filepath
    """
    try:
        from . import bmdvr

        if bmdvr.EXPORT_OTIO is None:
            raise AttributeError("Unsupported native Export OTIO")

        timeline.Export(filepath, bmdvr.EXPORT_OTIO)

    except Exception as error:
        log.debug(
            "Cannot use native OTIO export (%r)."
            "Default to AYON own implementation.",
            error
        )
        otio_timeline = otio_export.create_otio_timeline(
            get_current_resolve_project(),
            timeline=timeline
        )
        otio_export.write_to_file(otio_timeline, filepath)

def get_any_timeline():
    """Get any timeline object.

    Returns:
        object | None: resolve.Timeline
    """
    resolve_project = get_current_resolve_project()
    timeline_count = resolve_project.GetTimelineCount()
    if timeline_count > 0:
        return resolve_project.GetTimelineByIndex(1)

def get_clip_attributes(clip):
    """
    Collect basic attributes from resolve timeline item

    Args:
        clip (resolve.TimelineItem): timeline item object

    Returns:
        dict: all collected attributres as key: values
    """
    mp_item = clip.GetMediaPoolItem()

    return {
        "clipIn": clip.GetStart(),
        "clipOut": clip.GetEnd(),
        "clipLeftOffset": clip.GetLeftOffset(),
        "clipRightOffset": clip.GetRightOffset(),
        "clipMarkers": clip.GetMarkers(),
        "clipFlags": clip.GetFlagList(),
        "sourceId": mp_item.GetMediaId(),
        "sourceProperties": mp_item.GetClipProperty()
    }

def get_clip_resolution_from_media_pool(timeline_item_data):
    """Return the clip resolution from media pool data.

    Args:
        timeline_item_data (dict): Timeline item to investigate.

    Returns:
        resolution_info (dict): The parsed resolution data.
    """
    clip_item = timeline_item_data["clip"]["item"]
    media_pool_item = clip_item.GetMediaPoolItem()
    clip_properties = media_pool_item.GetClipProperty()

    try:
        width, height = clip_properties["Resolution"].split("x")
    except (KeyError, ValueError):
        width = height = None

    try:
        clip_par = clip_properties["PAR"]  # Pixel Aspect Resolution
        pixel_aspect = constants.PAR_VALUES[clip_par]

    except (KeyError, ValueError):  # Unknown or undetected PAR
        pixel_aspect = 1.0

    return {"width": width, "height": height, "pixelAspect": pixel_aspect}

def get_current_resolve_project():
    """Get current resolve project object.

    Returns:
        resolve.Project
    """
    project_manager = get_project_manager()
    return project_manager.GetCurrentProject()

def get_current_timeline(new=False):
    """Get current timeline object.

    Args:
        new (bool)[optional]: [DEPRECATED] if True it will create
            new timeline if none exists

    Returns:
        object | None: resolve.Timeline
    """
    resolve_project = get_current_resolve_project()
    timeline = resolve_project.GetCurrentTimeline()

    # return current timeline if any
    if timeline:
        return timeline

    # TODO: [deprecated] and will be removed in future
    if new:
        return get_new_timeline()

def get_current_timeline_items(
        filter: bool = False,
        track_type: str = None,
        track_name: str = None,
        selecting_color: str = None) -> List[Dict[str, Any]]:
    """Get all available current timeline track items"""
    track_type = track_type or "video"
    selecting_color = selecting_color or constants.SELECTED_CLIP_COLOR
    resolve_project = get_current_resolve_project()

    # get timeline anyhow
    timeline = get_current_timeline() or get_any_timeline()
    if not timeline:
        return []

    selected_clips = []

    # get all tracks count filtered by track type
    selected_track_count = timeline.GetTrackCount(track_type)

    # loop all tracks and get items
    _clips = {}
    for track_index in range(1, (int(selected_track_count) + 1)):
        _track_name = timeline.GetTrackName(track_type, track_index)

        # filter out all unmatched track names
        if track_name and _track_name not in track_name:
            continue

        timeline_items = timeline.GetItemListInTrack(track_type, track_index)
        _clips[track_index] = timeline_items

        _data = {
            "project": resolve_project,
            "timeline": timeline,
            "track": {
                "name": _track_name,
                "index": track_index,
                "type": track_type,
            }
        }
        # get track item object and its color
        for clip_index, ti in enumerate(_clips[track_index]):
            data = _data.copy()
            data["clip"] = {
                "item": ti,
                "index": clip_index
            }
            ti_color = ti.GetClipColor()
            if filter and selecting_color in ti_color or not filter:
                selected_clips.append(data)
    return selected_clips

def get_media_pool_item(filepath, root: object = None) -> object:
    """
    Return clip if found in folder with use of input file path.

    Args:
        filepath (str): absolute path to a file
        root (resolve.Folder)[optional]: root folder / bin object

    Returns:
        object: resolve.MediaPoolItem
    """
    resolve_project = get_current_resolve_project()
    media_pool = resolve_project.GetMediaPool()
    root = root or media_pool.GetRootFolder()
    fname = os.path.basename(filepath)

    for _mpi in root.GetClipList():
        _mpi_name = _mpi.GetClipProperty("File Name")
        _mpi_name = get_reformated_path(_mpi_name, first=True)
        if fname in _mpi_name:
            return _mpi
    return None

def get_media_storage():
    """Get media storage object.

    Returns:
        resolve.MediaStorage
    """
    from . import bmdvr, media_storage
    if not media_storage:
        media_storage = bmdvr.GetMediaStorage()
    return media_storage

def get_new_timeline(timeline_name: str = None):
    """Get new timeline object.

    Arguments:
        timeline_name (str): New timeline name.

    Returns:
        object: resolve.Timeline
    """
    resolve_project = get_current_resolve_project()
    media_pool = resolve_project.GetMediaPool()
    new_timeline = media_pool.CreateEmptyTimeline(
        timeline_name or constants.AYON_TIMELINE_NAME)
    resolve_project.SetCurrentTimeline(new_timeline)
    return new_timeline

def get_or_create_video_track(
        timeline: object,
        name: str,
        start: int | None = None,
        end: int | None = None
) -> int:
    """Get video track by name, create it if missing.

    Existing track is used only if it is unlocked and, when `start` and `end`
    are given, free in that range. Otherwise the next numbered track
    (`<name>_2`, `<name>_3`, ...) is tried or created.

    Args:
        timeline (resolve.Timeline): resolve's object
        name (str): base track name
        start (Optional[int]): first timeline frame required to be free
        end (Optional[int]): timeline frame after the last required frame

    Returns:
        int: 1-based track index
    """
    check_range = start is not None and end is not None
    suffix = 1
    while True:
        track_name = name if suffix == 1 else f"{name}_{suffix}"
        suffix += 1

        track_index = get_video_track_index_by_name(timeline, track_name)
        if track_index is None:
            if not timeline.AddTrack("video"):
                raise RuntimeError(
                    f"Failed to add video track '{track_name}' to timeline "
                    f"'{timeline.GetName()}'"
                )
            track_index = int(timeline.GetTrackCount("video"))
            timeline.SetTrackName("video", track_index, track_name)
            return track_index

        if timeline.GetIsTrackLocked("video", track_index):
            continue

        if check_range and not is_track_range_free(
            timeline, track_index, start, end
        ):
            continue
        return track_index

def get_otio_clip_instance_data(otio_timeline, timeline_item_data):
    """
    Return otio objects for timeline, track and clip

    Args:
        timeline_item_data (dict): timeline_item_data from list returned by
                                resolve.get_current_timeline_items()
        otio_timeline (otio.schema.Timeline): otio object

    Returns:
        dict: otio clip object

    """

    timeline_item = timeline_item_data["clip"]["item"]
    track_name = timeline_item_data["track"]["name"]
    timeline_range = create_otio_time_range_from_timeline_item_data(
        timeline_item_data)

    try:  # opentimelineio >= 0.16.0
        all_clips = otio_timeline.find_clips()
    except AttributeError:  # legacy
        all_clips = otio_timeline.each_clip()

    for otio_clip in all_clips:
        track_name = otio_clip.parent().name
        parent_range = otio_clip.range_in_parent()
        if track_name not in track_name:
            continue
        if otio_clip.name not in timeline_item.GetName():
            continue
        if is_overlapping_otio_ranges(
                parent_range, timeline_range, strict=True):

            # add pypedata marker to otio_clip metadata
            for marker in otio_clip.markers:
                if constants.AYON_MARKER_NAME in marker.name:
                    otio_clip.metadata.update(marker.metadata)
            return {"otioClip": otio_clip}

    return None

def get_project_manager():
    """Get project manager object.

    Returns:
        resolve.ProjectManager
    """
    from . import bmdvr, project_manager
    if not project_manager:
        project_manager = bmdvr.GetProjectManager()

    return project_manager

def get_publish_attribute(timeline_item):
    """ Get Publish attribute from marker on timeline item

    Attribute:
        timeline_item (resolve.TimelineItem): resolve's object
    """
    tag_data = get_timeline_item_ayon_tag(timeline_item)
    return tag_data["publish"]

def get_pype_clip_metadata(clip):
    """
    Get AYON metadata created by creator plugin

    Attributes:
        clip (resolve.TimelineItem): resolve's object

    Returns:
        dict: hierarchy, orig clip attributes
    """
    mp_item = clip.GetMediaPoolItem()
    metadata = mp_item.GetMetadata()

    return metadata.get(constants.AYON_TAG_NAME)

def get_reformated_path(path, padded=False, first=False):
    """
    Return fixed python expression path

    Args:
        path (str): path url or simple file name

    Returns:
        type: string with reformatted path

    Example:
        get_reformated_path("plate.[0001-1008].exr") > plate.%04d.exr

    """
    first_frame_pattern = re.compile(r"\[(\d+)\-\d+\]")

    if "[" in path:
        padding_pattern = r"(\d+)(?=-)"
        padding = len(re.findall(padding_pattern, path).pop())
        num_pattern = r"(\[\d+\-\d+\])"
        if padded:
            path = re.sub(num_pattern, f"%0{padding}d", path)
        elif first:
            first_frame = re.findall(first_frame_pattern, path, flags=0)
            if len(first_frame) >= 1:
                first_frame = first_frame[0]
            path = re.sub(num_pattern, first_frame, path)
        else:
            path = re.sub(num_pattern, "%d", path)
    return path

def get_timeline_item(media_pool_item: object,
                      timeline: object = None) -> object:
    """
    Returns clips related to input mediaPoolItem.

    Args:
        media_pool_item (resolve.MediaPoolItem): resolve's object
        timeline (resolve.Timeline)[optional]: resolve's object

    Returns:
        object: resolve.TimelineItem
    """
    clip_name = media_pool_item.GetClipProperty("File Name")
    output_timeline_item = None
    timeline = timeline or get_current_timeline()

    with maintain_current_timeline(timeline):
        # search the timeline for the added clip

        for ti_data in get_current_timeline_items():
            ti_clip_item = ti_data["clip"]["item"]
            ti_media_pool_item = ti_clip_item.GetMediaPoolItem()

            # Skip items that do not have a media pool item, like for example
            # an "Adjustment Clip" or a "Fusion Composition" from the effects
            # toolbox
            if not ti_media_pool_item:
                continue

            if clip_name in ti_media_pool_item.GetClipProperty("File Name"):
                output_timeline_item = ti_clip_item

    return output_timeline_item

def get_timeline_item_ayon_tag(timeline_item):
    """
    Get ayon track item tag created by creator or loader plugin.

    Args:
        timeline_item (resolve.TimelineItem): resolve object

    Returns:
        dict: ayon tag data

    """
    return_tag = None

    if constants.AYON_MARKER_WORKFLOW:
        return_tag = get_ayon_marker(timeline_item)
    else:
        media_pool_item = timeline_item.GetMediaPoolItem()

        # get all tags from track item
        _tags = media_pool_item.GetMetadata()
        if not _tags:
            return None
        for key, data in _tags.items():
            # return only correct tag defined by global name
            if key in constants.AYON_TAG_NAME:
                return_tag = json.loads(data)

    return return_tag

def get_timeline_item_by_name(name: str) -> object:
    """Get timeline item by name.

    Args:
        name (str): name of timeline item

    Returns:
        object: resolve.TimelineItem

    """
    for _ti_data in get_current_timeline_items():
        _ti_clip = _ti_data["clip"]["item"]
        tag_data = get_timeline_item_ayon_tag(_ti_clip)
        tag_name = tag_data.get("namespace")
        if not tag_name:
            continue
        if tag_name in name:
            return _ti_clip
    return None

def get_timeline_media_pool_item(timeline, root=None) -> object:
    """Return MediaPoolItem from Timeline


    Args:
        timeline (resolve.Timeline): timeline object
        root (resolve.Folder): root folder / bin object

    Returns:
        resolve.MediaPoolItem: media pool item from timeline
    """

    # Due to limitations in the Resolve API we can't get
    # the media pool item directly from the timeline.
    # We can find it by name, however names are not
    # enforced to be unique across bins. So, we give it
    # unique name.
    original_name = timeline.GetName()
    identifier = str(uuid.uuid4().hex)
    try:
        timeline.SetName(identifier)
        for item in iter_all_media_pool_clips(root=root):
            if item.GetName() != identifier:
                continue
            return item
    finally:
        # Revert to original name
        timeline.SetName(original_name)

def get_track_end_frame(
        timeline: object, track_index: int, track_type: str = "video"
) -> int | None:
    """Return the first timeline frame after the last item of the track.

    Returns:
        Optional[int]: None if the track has no items.
    """
    items = timeline.GetItemListInTrack(track_type, track_index) or []
    return max((int(item.GetEnd()) for item in items), default=None)

def get_video_track_index_by_name(timeline: object, name: str) -> int:
    """Return index of the first video track with given name.

    Args:
        timeline (resolve.Timeline): resolve's object
        name (str): track name

    Returns:
        Optional[int]: 1-based track index, None if there is no such track.
    """
    for track_index in range(1, int(timeline.GetTrackCount("video")) + 1):
        if timeline.GetTrackName("video", track_index) == name:
            return track_index
    return None

def imprint(timeline_item, data=None):
    """
    Adding `AYON data` into a timeline item track item tag.

    Also including publish attribute into tag.

    Arguments:
        timeline_item (resolve.TimelineItem): resolve's object
        data (dict): Any data which needs to be imprinted

    Examples:
        data = {
            'folderPath': '/shots/sq020sh0280',
            'productBaseType': 'render',
            'productName': 'renderMain'
        }
    """
    data = data or {}

    set_timeline_item_ayon_tag(timeline_item, data)

    # add publish attribute
    set_publish_attribute(timeline_item, True)

def is_track_range_free(
        timeline: object,
        track_index: int,
        start: int,
        end: int,
        track_type: str = "video"
) -> bool:
    """Check that no item of the track overlaps with `start` - `end` range.

    Args:
        timeline (resolve.Timeline): resolve's object
        track_index (int): 1-based track index
        start (int): first timeline frame of the range
        end (int): timeline frame after the last frame of the range
        track_type (str): resolve's track type

    Returns:
        bool: True if the range is not used by any item.
    """
    # item `GetEnd` and `end` are exclusive, so an item ending at `start`
    # is right before the range and does not overlap
    items = timeline.GetItemListInTrack(track_type, track_index) or []
    return not any(
        int(item.GetStart()) < end and int(item.GetEnd()) > start
        for item in items
    )

def iter_all_media_pool_clips(root=None):
    """Recursively iterate all media pool clips in current project

    Args:
        root (Optional[resolve.Folder]): root folder / bin object.
            When None, defaults to media pool root folder.
    """
    root = root or get_current_resolve_project().GetMediaPool().GetRootFolder()
    queue = [root]
    for folder in queue:
        for clip in folder.GetClipList():
            yield clip
        queue.extend(folder.GetSubFolderList())

@contextlib.contextmanager
def maintain_current_timeline(to_timeline: object,
                              from_timeline: object = None):
    """Maintain current timeline selection during context

    Attributes:
        from_timeline (resolve.Timeline)[optional]:
    Example:
        >>> print(from_timeline.GetName())
        timeline1
        >>> print(to_timeline.GetName())
        timeline2

        >>> with maintain_current_timeline(to_timeline):
        ...     print(get_current_timeline().GetName())
        timeline2

        >>> print(get_current_timeline().GetName())
        timeline1
    """
    project = get_current_resolve_project()
    working_timeline = from_timeline or project.GetCurrentTimeline()

    # search timeline withing project timelines in case the
    # to_timeline is MediaPoolItem
    # Note: this is a hacky way of identifying if object is timeline since
    #   mediapool item is not having AddTrack attribute. API is not providing
    #   any other way to identify the object type. And hasattr is returning
    #   false info.
    if "AddTrack" not in dir(to_timeline):
        tcount = project.GetTimelineCount()
        for idx in range(0, int(tcount)):
            timeline = project.GetTimelineByIndex(idx + 1)
            if timeline.GetName() == to_timeline.GetName():
                to_timeline = timeline
                break

    try:
        # switch to the input timeline
        result = project.SetCurrentTimeline(to_timeline)
        if not result:
            raise ValueError(f"Failed to switch to timeline: {to_timeline}")

        current_timeline = project.GetCurrentTimeline()
        yield current_timeline
    finally:
        # put the original working timeline to context
        project.SetCurrentTimeline(working_timeline)

@contextlib.contextmanager
def maintain_page_by_name(page_name):
    """Maintain specific page by name.

    Args:
        page_name (str): name of the page

    Example:
        >>> with maintain_page_by_name("Deliver"):
        ...     print("Deliver page is open")
        Deliver page is open
    """
    from . import bmdvr
    current_page = bmdvr.GetCurrentPage()

    if not bmdvr.OpenPage(page_name):
        raise ValueError(f"Could not open page {page_name}")

    try:
        yield
    finally:
        bmdvr.OpenPage(current_page)

def remove_media_pool_item(media_pool_item: object) -> bool:
    """Remove media pool item.

    Args:
        media_pool_item (resolve.MediaPoolItem): resolve's object

    Returns:
        bool: True if success
    """
    resolve_project = get_current_resolve_project()
    media_pool = resolve_project.GetMediaPool()
    return media_pool.DeleteClips([media_pool_item])

def set_project_fps(task_entity=None):
    """ Attempt to set project frame rate from AYON current task.
    This might not be possible if a timeline already exists within the project.
    Return a error string if any issue so it can be displayed to the user.
    """
    task_entity = task_entity or get_current_task_entity()
    attributes = task_entity["attrib"]

    # Set project frame rate and resolution
    resolve_project = get_current_resolve_project()
    project_fps = attributes["fps"]

    SUPPORTED_FPS = {
        16.0: "16",
        18.0: "18",
        23.976: "23.976",
        24.0: "24",
        25.0: "25",
        29.97: "29.97",
        30.0: "30",
        47.952: "47.952",
        48.0: "48",
        50.0: "50"
    }

    if float(project_fps) in SUPPORTED_FPS:
        if not resolve_project.SetSetting(
            "timelineFrameRate",
            SUPPORTED_FPS[float(project_fps)]
        ):
            # Resolve does not allow to edit timeline fps
            # project settings once a timeline has been created.
            return (
                "Cannot override Project fps from AYON."
                " This could be because a timeline already exists."
            )

        return None

    else:
        return (
            "Fps set in AYON project is not supported by Resolve"
            f" attempt to set {project_fps},"
            f" supported are {tuple(SUPPORTED_FPS.keys())}."
        )

def set_project_manager_to_folder_name(folder_name):
    """
    Sets context of Project manager to given folder by name.

    Searching for folder by given name from root folder to nested.
    If no existing folder by name it will create one in root folder.

    Args:
        folder_name (str): name of searched folder

    Returns:
        bool: True if success

    Raises:
        Exception: Cannot create folder in root

    """
    # initialize project manager
    project_manager = get_project_manager()

    set_folder = False

    # go back to root folder
    if project_manager.GotoRootFolder():
        log.info(f"Testing existing folder: {folder_name}")
        folders = _convert_resolve_list_type(
            project_manager.GetFoldersInCurrentFolder())
        log.info(f"Testing existing folders: {folders}")
        # get me first available folder object
        # with the same name as in `folder_name` else return False
        if next((f for f in folders if f in folder_name), False):
            log.info(f"Found existing folder: {folder_name}")
            set_folder = project_manager.OpenFolder(folder_name)

    if set_folder:
        return True

    # if folder by name is not existent then create one
    # go back to root folder
    log.info(f"Folder `{folder_name}` not found and will be created")
    if project_manager.GotoRootFolder():
        try:
            # create folder by given name
            project_manager.CreateFolder(folder_name)
            project_manager.OpenFolder(folder_name)
            return True
        except NameError as e:
            log.error((f"Folder with name `{folder_name}` cannot be created!"
                       f"Error: {e}"))
            return False

def set_project_resolution(task_entity=None):
    """ Attempt to set project resolution from AYON current task.
    Return a error string if any issue so it can be displayed to the user.
    """
    task_entity = task_entity or get_current_task_entity()
    attributes = task_entity["attrib"]

    resolve_project = get_current_resolve_project()
    width = attributes["resolutionWidth"]
    height = attributes["resolutionHeight"]

    resolution_params = {
        "timelineResolutionHeight": height,
        "timelineResolutionWidth": width,
    }

    # In order to set vertical resolution in resolve,
    # the "Use vertical resolution" option need to be enabled.
    # This is not exposed from the Python API.
    if height > width:
            return (
                "Cannot override Project resolution from AYON."
                f" Vertical resolution {width}x{height}"
                " is unsupported from the API."
            )

    for resolve_param, value in resolution_params.items():
        if not resolve_project.SetSetting(
            resolve_param,
            str(int(value))
        ):
            return (
                "Cannot override Project resolution from AYON."
                f" trying to set {resolve_param} = {value}"
            )

    SUPPORTED_PIXEL_ASPECTS = {
        1.0: "Square",
        16/9: "16:9 anamorphic",
        4/3: "4:3 standard definition",
        2.0: "Cinemascope",
    }
    pixel_aspect_ratio = round(attributes["pixelAspect"], 2)

    for supported_pa in SUPPORTED_PIXEL_ASPECTS:
        if round(supported_pa, 2) != pixel_aspect_ratio:
            continue

        if not resolve_project.SetSetting(
            "timelinePixelAspectRatio",
            SUPPORTED_PIXEL_ASPECTS[supported_pa]
        ):
            return (
                "Cannot override Project pixel aspect ratio from AYON."
                " trying to set timelinePixelAspectRatio = "
                f"{SUPPORTED_PIXEL_ASPECTS[supported_pa]}"
            )

        return None

    else:
        return (
            "Pixel Aspect Ratio set in AYON project is not supported"
            f" by Resolve, attempt to set {pixel_aspect_ratio},"
            f" supported are {tuple(SUPPORTED_PIXEL_ASPECTS.keys())}."
        )

def set_publish_attribute(timeline_item, value):
    """ Set Publish attribute to marker on timeline item

    Attribute:
        timeline_item (resolve.TimelineItem): resolve's object
    """
    tag_data = get_timeline_item_ayon_tag(timeline_item)
    tag_data["publish"] = value
    # set data to the publish attribute
    set_timeline_item_ayon_tag(timeline_item, tag_data)

def set_timeline_item_ayon_tag(timeline_item, data=None):
    """
    Set ayon track item tag to input timeline_item.

    Attributes:
        trackItem (resolve.TimelineItem): resolve api object

    Returns:
        dict: json loaded data
    """
    data = data or {}

    # get available ayon tag if any
    tag_data = get_timeline_item_ayon_tag(timeline_item)

    if constants.AYON_MARKER_WORKFLOW:
        # delete tag as it is not updatable
        if tag_data:
            delete_ayon_marker(timeline_item)

        tag_data.update(data)
        set_ayon_marker(timeline_item, tag_data)
    else:
        if tag_data:
            media_pool_item = timeline_item.GetMediaPoolItem()
            # it not tag then create one
            tag_data.update(data)
            media_pool_item.SetMetadata(
                constants.AYON_TAG_NAME, json.dumps(tag_data))
        else:
            tag_data = data
            # if ayon tag available then update with input data
            # add it to the input track item
            timeline_item.SetMetadata(
                constants.AYON_TAG_NAME, json.dumps(tag_data))

    return tag_data

def swap_clips(from_clip, to_clip, to_in_frame, to_out_frame):
    """
    Swapping clips on timeline in timelineItem

    It will add take and activate it to the frame range which is inputted

    Args:
        from_clip (resolve.TimelineItem)
        to_clip (resolve.mediaPoolItem)
        to_clip_name (str): name of to_clip
        to_in_frame (float): cut in frame, usually `GetLeftOffset()`
        to_out_frame (float): cut out frame, usually left offset plus duration

    Returns:
        bool: True if successfully replaced

    """
    # copy ACES input transform from timeline clip to new media item
    mediapool_item_from_timeline = from_clip.GetMediaPoolItem()
    _idt = mediapool_item_from_timeline.GetClipProperty('IDT')
    to_clip.SetClipProperty('IDT', _idt)

    _clip_prop = to_clip.GetClipProperty
    to_clip_name = _clip_prop("File Name")
    # add clip item as take to timeline
    take = from_clip.AddTake(
        to_clip,
        float(to_in_frame),
        float(to_out_frame)
    )

    if not take:
        return False

    for take_index in range(1, (int(from_clip.GetTakesCount()) + 1)):
        take_item = from_clip.GetTakeByIndex(take_index)
        take_mp_item = take_item["mediaPoolItem"]
        if to_clip_name in take_mp_item.GetName():
            from_clip.SelectTakeByIndex(take_index)
            from_clip.FinalizeTake()
            return True
    return False