from typing import Any, Tuple


def 取频率最高前N项(元组数据: Tuple[Any, ...], 数量: int):
    """返回按出现频率从高到低排序的前 N 项。

    功能说明:
        - 这个函数用于返回按出现频率从高到低排序的前 N 项。
        - 常用于从元组中读取某个成员、某一段数据，或者计算出一个统计结果。
        - 如果当前数据不适合处理，函数会返回约定好的结果，方便新手直接判断这次是否成功取到值。

    Returns:
        成功时返回 ``((成员, 次数), ...)`` 结构；失败时返回空元组 ``()``。
    """
    try:
        if not isinstance(元组数据, tuple) or not isinstance(数量, int) or 数量 <= 0:
            return ()

        频率列表 = []
        for 元素 in 元组数据:
            已找到 = False
            for 项 in 频率列表:
                if 项[0] == 元素:
                    项[1] += 1
                    已找到 = True
                    break
            if not 已找到:
                频率列表.append([元素, 1])

        排序后 = sorted(频率列表, key=lambda 项: (-项[1], 频率列表.index(项)))
        return tuple((元素, 次数) for 元素, 次数 in 排序后[:数量])
    except Exception:
        return ()


if __name__ == "__main__":
    print("===== 示例1：取频率最高前2项 =====")
    数据 = ("a", "b", "a", "c", "a", "b")
    print("结果:", 取频率最高前N项(数据, 2))

    print("\n===== 示例2：数量超过唯一成员数 =====")
    数据 = (1, 2, 2, 3)
    print("结果:", 取频率最高前N项(数据, 10))

    print("\n===== 示例3：并列频率保持首次出现顺序 =====")
    数据 = ("x", "y", "x", "y", "z")
    print("结果:", 取频率最高前N项(数据, 2))

    print("\n===== 示例4：数量非法 =====")
    数据 = (1, 2, 3)
    print("结果:", 取频率最高前N项(数据, 0))

    print("\n===== 示例5：空元组 =====")
    数据 = ()
    print("结果:", 取频率最高前N项(数据, 2))

    print("\n===== 示例6：应用场景-取访问来源Top3 =====")
    来源列表 = ("百度", "知乎", "百度", "官网", "知乎", "百度", "公众号")
    print("结果:", 取频率最高前N项(来源列表, 3))



