import sys


def 进度条(当前值, 总值, 长度=40):
    """
    打印控制台进度条，可用于展示任务执行进度。

    功能说明：
        - 根据当前进度与总进度计算百分比，并在同一行实时刷新展示；
        - 采用 “█” 与 “-” 组合绘制固定长度的可视化进度条；
        - 当进度达到或超过总值时自动换行；
        - 本函数为简单进度展示工具，不抛异常，适合作为底层打印函数使用。

    Args:
        当前值 (int): 当前的进度值。
        总值 (int): 总进度值，用于计算整体进度比例。
        长度 (int): 进度条的可视长度（字符数），默认 40。

    Returns:
        bool:
            - True：打印成功或刷新成功；
            - False：打印过程中出现异常。

    Notes:
        - 使用 sys.stdout.write 实现原地刷新行为；
        - 若总值为 0 将导致除零错误，因此调用方应确保总值 > 0；
        - 当当前值超过总值时，进度按 100% 显示，但不会抛出异常。
    """
    try:
        百分比 = 当前值 / 总值
        完成长度 = int(长度 * 百分比)
        进度 = "█" * 完成长度 + "-" * (长度 - 完成长度)
        sys.stdout.write(f"\r|{进度}| {当前值}/{总值} ({百分比:.2%})")
        sys.stdout.flush()

        if 当前值 >= 总值:
            print()  # 完成后换行

        return True

    except Exception as e:
        print(f"打印时出现异常: {e}")
        return False