使 ANSI 转义字符序列（用于在终端文本中产生彩色文本和光标定位）在 MS Windows 上工作。

PyPI 发布 | Github 源码 | Tidelift 上的 Colorama 企业版

如果您觉得 Colorama 有用，请 给作者。谢谢！

已在 CPython 3.9, 3.10, 3.11, 3.12, 3.13 和 PyPy 3.11 上测试。

除标准库外无其他依赖。

pip install colorama
# 或者
conda install -c anaconda colorama

ANSI 转义字符序列 long以来一直用于在 Unix 和 Mac 上产生彩色终端文本和光标定位。Colorama 使这在 Windows 上也可用，方法是包装 stdout，移除它发现的 ANSI 序列（这些序列在输出中会显示为乱码），并将它们转换为适当的 win32 调用来修改终端状态。在其他平台上，Colorama 不做任何事情。

其结果是提供了一个简单的跨平台 API，用于从 Python 打印彩色终端文本，并带来一个好结果：现有应用程序或库可以使用 ANSI 序列在 Linux 或 Mac 上生成彩色输出，现在也可以在 Windows 上工作，只需调用 colorama.just_fix_windows_console() (从 v0.4.6 开始) 或 colorama.init() (所有版本，但可能有其他副作用 - 见下文)。

另一种方法是在 Windows 机器上安装 ansi.sys，它为在终端中运行的所有应用程序提供相同的行为。Colorama 适用于无法轻松安装该软件的情况（例如，也许您的应用程序没有安装程序）。

源代码仓库中的演示脚本使用 ANSI 序列打印一些彩色文本。比较它们在 gnome-terminal 内置 ANSI 处理下的输出，与在 Windows 命令提示符下使用 Colorama 的输出：

这些截图显示，在 Windows 上，Colorama 不支持 ANSI 的“暗淡文本”；它看起来与“正常文本”相同。

如果您想从 Colorama 获得的唯一好处是让 ANSI 终端在 Windows 上工作，那么请运行：

from colorama import just_fix_windows_console
just_fix_windows_console()

如果您使用的是较新的 Windows 10 或更高版本，并且您的 stdout/stderr 指向 Windows 控制台，那么这将打开魔法配置开关以启用 Windows 内置的 ANSI 支持。

如果您使用的是较旧版本的 Windows，并且您的 stdout/stderr 指向 Windows 控制台，那么这将通过包装 sys.stdout 和/或 sys.stderr 来实现，该控制台对象会拦截 ANSI 转义序列并发出相应的 Win32 调用来模拟它们。

在所有其他情况下，它不会做任何事情。基本上，这个想法是让 Windows 在 ANSI 转义处理方面像 Unix 一样工作。

多次调用此函数是安全的。在非 Windows 平台调用此函数也是安全的，但它不会做任何事情。当 stdout/stderr 被重定向到文件时，调用此函数也是安全的——它不会对这些流做任何事情。

或者，您可以使用具有更多功能（但也有更多潜在的麻烦）的旧界面：

from colorama import init
init()

这与 just_fix_windows_console 相同，但有以下区别：

• 多次调用 init 不安全；您可能会得到多层包装和损坏的 ANSI 支持。
• Colorama 将应用启发式方法来猜测 stdout/stderr 是否支持 ANSI，如果它认为不支持，则会将 sys.stdout 和 sys.stderr 包装在一个特殊的文件对象中，该对象在打印前会移除 ANSI 转义序列。这发生在所有平台上，并且如果您想编写能够无条件发出 ANSI 转义序列的代码，让 Colorama 决定是否实际输出它们，这可能很方便。但请注意，Colorama 的启发式方法并不特别聪明。
• init 还接受显式的关键字参数来启用/禁用各种功能——见下文。

要停止使用 Colorama，只需在程序退出前调用 deinit()。这将把 stdout 和 stderr 恢复到原始值，从而禁用 Colorama。要再次恢复使用 Colorama，请调用 reinit()；这比再次调用 init() 便宜（但效果相同）。

大多数用户应依赖 colorama >= 0.4.6，并使用 just_fix_windows_console。旧的 init 接口将无限期地支持以获得向后兼容性，但我们不打算修复与它相关的任何问题，同样是为了向后兼容性。

然后，可以使用 Colorama 的 ANSI 转义序列的常量简写来执行跨平台彩色文本打印。这些是故意简陋的，见下文。

from colorama import Fore, Back, Style
print(Fore.RED + 'some red text')
print(Back.GREEN + 'and with a green background')
print(Style.DIM + 'and in dim text')
print(Style.RESET_ALL)
print('back to normal now')

......或者简单地通过从您自己的代码手动打印 ANSI 序列：

print('\033[31m' + 'some red text')
print('\033[39m') # and reset to default color

......或者，Colorama 可以与现有的 ANSI 库结合使用，例如古老的 Termcolor、华丽的 Blessings，或出色的 _Rich。

如果您希望 Colorama 的 Fore、Back 和 Style 常量更强大，请考虑使用上述高度强大的库之一来生成颜色等，然后仅将 Colorama 用于其主要目的：将这些 ANSI 序列转换为也适用于 Windows：

同样，请勿提交 PR 以向 Colorama 添加生成新类型 ANSI 代码的功能。我们只对将 ANSI 代码转换为 win32 API 调用感兴趣，而不是像上面那样生成 ANSI 字符的快捷方式。

from colorama import just_fix_windows_console
from termcolor import colored

# 使用 Colorama 使 Termcolor 在 Windows 上也能正常工作
just_fix_windows_console()

# 然后使用 Termcolor 进行所有彩色文本输出
print(colored('Hello, World!', 'green', 'on_red'))

可用格式化常量为：

Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
Style: DIM, NORMAL, BRIGHT, RESET_ALL

Style.RESET_ALL 重置前景、背景和亮度。Colorama 会在程序退出时自动执行此重置。

这些被相对较好地支持，但并非标准的一部分：

Fore: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX
Back: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX

用于重新定位光标的 ANSI 代码是支持的。有关如何生成它们的示例，请参见 demos/demo06.py。

init() 接受一些 **kwargs 来覆盖默认行为。

init(autoreset=False):

如果您发现自己反复发送重置序列来关闭每个 print 结束时的颜色变化，那么 init(autoreset=True) 将会自动执行此操作：

from colorama import init
init(autoreset=True)
print(Fore.RED + 'some red text')
print('automatically back to default color again')

init(strip=None):

传递 True 或 False 来覆盖是否应从输出中剥离 ANSI 代码。默认行为是如果为 Windows 或输出被重定向（非 tty）则剥离。

init(convert=None):

传递 True 或 False 来覆盖是否将输出中的 ANSI 代码转换为 win32 调用。默认行为是如果为 Windows 且输出为 tty（终端）则进行转换。

init(wrap=True):

在 Windows 上，Colorama 通过将 sys.stdout 和 sys.stderr 替换为代理对象来工作，这些代理对象重写 .write() 方法来执行其工作。如果此包装给您带来了问题，则可以通过传递 init(wrap=False) 来禁用它。默认行为是当 autoreset 或 strip 或 convert 为 True 时进行包装。

当禁用包装时，非 Windows 平台上的彩色打印将继续正常工作。要进行跨平台彩色输出，您可以直接使用 Colorama 的 AnsiToWin32 代理：

import sys
from colorama import init, AnsiToWin32
init(wrap=False)
stream = AnsiToWin32(sys.stderr).stream

print(Fore.BLUE + 'blue text on stderr', file=stream)

ANSI 序列通常采用以下形式：

ESC [ <param> ; <param> ... <command>

其中 <param> 是一个整数，<command> 是一个字母。零个或多个参数会传递给一个 <command>。如果没有传递参数，通常等同于传递单个零。序列中没有空格；此处为了方便阅读而插入了空格。

Colorama 将以下 ANSI 序列转换为 win32 调用：

ESC [ 0 m       # reset all (colors and brightness)
ESC [ 1 m       # bright
ESC [ 2 m       # dim (looks same as normal brightness)
ESC [ 22 m      # normal brightness

# FOREGROUND:
ESC [ 30 m      # black
ESC [ 31 m      # red
ESC [ 32 m      # green
ESC [ 33 m      # yellow
ESC [ 34 m      # blue
ESC [ 35 m      # magenta
ESC [ 36 m      # cyan
ESC [ 37 m      # white
ESC [ 39 m      # reset

# BACKGROUND
ESC [ 40 m      # black
ESC [ 41 m      # red
ESC [ 42 m      # green
ESC [ 43 m      # yellow
ESC [ 44 m      # blue
ESC [ 45 m      # magenta
ESC [ 46 m      # cyan
ESC [ 47 m      # white
ESC [ 49 m      # reset

# cursor positioning
ESC [ y;x H     # position cursor at x across, y down
ESC [ y;x f     # position cursor at x across, y down
ESC [ n A       # move cursor n lines up
ESC [ n B       # move cursor n lines down
ESC [ n C       # move cursor n characters forward
ESC [ n D       # move cursor n characters backward

# clear the screen
ESC [ mode J    # clear the screen

# clear the line
ESC [ mode K    # clear the line

多个数字参数到 'm' 命令可以合并到一个序列中：

ESC [ 36 ; 45 ; 1 m     # bright cyan text on magenta background

所有其他形式为 ESC [ <param> ; <param> ... <command> 的 ANSI 序列在 Windows 上会被静默地从输出中剥离。

任何其他形式的 ANSI 序列，如单字符代码或替代起始字符，都不会被识别或剥离。添加它们会很酷。通过 GitHub 上的 Issues 告诉我，如果这对您有用。

我个人只在 Windows XP (CMD, Console2), Ubuntu (gnome-terminal, xterm) 和 OS X 上测试过。

一些有效的 ANSI 序列未被识别。

如果您正在修改代码，请参见 README-hacking.md。特别是，请参见其中关于为什么我们不希望 PR 允许 Colorama 生成新类型 ANSI 代码的解释。

查看待处理的 issues 和愿望清单： https://github.com/tartley/colorama/issues

如果您遇到的任何问题不起作用，或者不如您预期或希望的那样，我将很愿意在 issues 列表上听到您的反馈，对补丁感到高兴，并且很乐意将提交权限授予任何提交一个或两个有效补丁的人。

Copyright Jonathan Hartley & Arnon Yaari, 2013-2020. BSD 3-Clause 许可证；见 LICENSE 文件。

colorama 的专业支持作为 Tidelift Subscription 的一部分提供。 Tidelift 为软件开发团队提供了一个单一的购买和维护其软件的来源， 并提供来自最了解它的专家的专业级保证，同时与现有工具无缝集成。

更多致谢请参见 CHANGELOG！

• Marc Schlaich (schlamar) 为 Python2.5 修复了 setup.py。
• Marc Abramowitz，报告并修复了退出时 stdout 关闭导致的崩溃， 提供了 issue #7 的 setuptools/distutils 争论的解决方案， 以及其他修复。
• 用户 'eryksun'，关于正确实例化 ctypes.windll 的指导。
• Matthew McCormick 礼貌地指出了一个在非 Win 平台上的长期存在的崩溃。
• Ben Hoyt，为 64 位 Windows 提供了出色的修复。
• Jesse at Empty Square 提交了 README 中示例的修复。
• 用户 'jamessp'，对光标定位进行了细致的文档修复。
• 用户 'vaal1239', Dave Mckee & Lackner Kristof 针对 Win7 的微小但非常必要的修复。
• Julien Stuyck，明智地建议了 Python3 兼容的 README 更新。
• Daniel Griffith 贡献了多个出色的补丁。
• Oscar Lesta 提供了有价值的修复，以防止 ANSI 字符发送到非 tty 输出。
• Roger Binns，提供了许多建议、有价值的反馈和 bug 报告。
• Tim Golden 提供了关于初步想法的思考和备受赞赏的反馈。
• 用户 'Zearin' 更新了 README 文件。
• John Szakmeister 增加了对浅色支持
• Charles Merriam 为演示增加了文档
• Jurko 修复了 64 位 Windows CPython2.5 w/o ctypes 的问题
• Florian Bruhin 修复了 stdout 或 stderr 为 None 的情况
• Thomas Weininger 修复了 Windows 上的 ValueError
• Remi Rampin 改进了 Github 集成并修复了 README 文件
• Simeon Visser 使用 'with' 关闭了文件句柄，并更新了分类器以包含 Python 3.3 和 3.4
• Andy Neff 修复了 LIGHT_EX 颜色的 RESET。
• Jonathan Hartley 提供了初步想法和实现。