from datetime import datetime


def 获取今日剩余时长(返回类型: int = 1, 精确到毫秒: bool = False) -> float:
    """计算从现在到今天结束还剩多少时间。

    功能说明:
        - 这个函数用于计算当前时间距离今天 ``23:59:59`` 还剩下多久。
        - 你可以选择返回秒、分钟或小时。
        - 也可以决定要不要保留小数，适合做倒计时显示或任务截止提醒。
        - 参数不合法或计算异常时，函数返回 ``0.0``。

    Args:
        返回类型: 返回单位，``0`` 表示秒，``1`` 表示分钟，``2`` 表示小时。
        精确到毫秒: 是否保留小数部分，``True`` 保留，``False`` 只取整数。

    Returns:
        返回今天剩余时长；出错时返回 ``0.0``。
    """
    try:
        当前时间 = datetime.now()
        今日结束 = datetime.combine(当前时间.date(), datetime.max.time()).replace(microsecond=0)
        剩余秒数 = (今日结束 - 当前时间).total_seconds()

        if not 精确到毫秒:
            剩余秒数 = int(剩余秒数)

        if 返回类型 == 0:
            return float(剩余秒数)
        if 返回类型 == 1:
            return float(剩余秒数) / 60
        if 返回类型 == 2:
            return float(剩余秒数) / 3600
        return 0.0
    except Exception:
        return 0.0


if __name__ == "__main__":
    print("===== 示例1：按秒返回今天剩余时长 =====")
    print("结果:", 获取今日剩余时长(0))

    print("\n===== 示例2：按分钟返回今天剩余时长 =====")
    print("结果:", 获取今日剩余时长(1))

    print("\n===== 示例3：按小时返回今天剩余时长 =====")
    print("结果:", 获取今日剩余时长(2))

    print("\n===== 示例4：保留小数部分 =====")
    print("结果:", 获取今日剩余时长(2, True))

    print("\n===== 示例5：返回类型写错时返回 0.0 =====")
    print("结果:", 获取今日剩余时长(99))

    print("\n===== 示例6：应用场景-展示今天距离下班前的剩余小时数 =====")
    剩余小时 = 获取今日剩余时长(2, True)
    print("今天还剩约", round(剩余小时, 2), "小时")
