Библиотека Colorama позволяет управляющим символам ANSI (используются для создания цветного текста в терминале и позиционирования курсора) работать под MS Windows.
Если вы считаете Colorama полезной, не забудьте поблагодарить ее авторов и сделать пожертвование. Спасибо!
Установка
pip install colorama
# или
conda install -c anaconda colorama
Описание
Управляющие символы ANSI давно используются для создания цветного текста и позиционирования курсора в терминале на Unix и Mac. Colorama делает возможным их использование на платформе Windows, оборачивая stdout, удаляя найденные ANSI-последовательности (которые будут выглядеть как тарабарщина при выводе) и преобразуя их в соответствующие вызовы win32 для изменения состояния командной строки. На других платформах Colorama ничего не меняет.
В результате мы получаем простой кроссплатформенный API для отображения цветного терминального текста из Python, а также следующий приятный побочный эффект: существующие приложения или библиотеки, использующие ANSI-последовательности для создания цветного вывода на Linux или Mac, теперь могут работать и на Windows, просто вызвав colorama.init().
Альтернативный подход заключается в установке ansi.sys на машины с Windows, что обеспечивает одинаковое поведение для всех приложений, работающих с командной строкой. Colorama предназначена для ситуаций, когда это не так просто (например, может быть, у вашего приложения нет программы установки).
Демо-скрипты в репозитории исходного кода библиотеки выводят небольшой цветной текст, используя последовательности ANSI. Сравните их работу в Gnome-terminal и в Windows Command-Prompt, где отображение осуществляется с помощью Colorama:
Эти скриншоты показывают, что в Windows Colorama не поддерживает ANSI ‘dim text’ (тусклый текст); он выглядит так же, как и ‘normal text’.
Использование
Инициализация
Приложения должны инициализировать Colorama с помощью:
from colorama import init
init()
В Windows вызов init() отфильтрует управляющие ANSI-последовательности из любого текста, отправленного в stdout или stderr, и заменит их на эквивалентные вызовы Win32.
На других платформах вызов init() не имеет никакого эффекта (если только вы не укажете другие дополнительные возможности; см. раздел «Аргументы Init», ниже). По задумке разработчиков такое поведение позволяет приложениям вызывать init() безоговорочно на всех платформах, после чего вывод ANSI должен просто работать.
Чтобы прекратить использование Colorama до выхода из программы, просто вызовите deinit(). Данный метод вернет stdout и stderr к их исходным значениям, так что Colorama будет отключена. Чтобы возобновить ее работу, используйте reinit(); это выгоднее, чем повторный вызов init() (но делает то же самое).
Цветной вывод
Кроссплатформенное отображение цветного текста может быть упрощено за счет использования константных обозначений для управляющих последовательностей ANSI, предоставляемых библиотекой Colorama:
from colorama import init
init()
from colorama import Fore, Back, Style
print(Fore.GREEN + 'зеленый текст')
print(Back.YELLOW + 'на желтом фоне')
print(Style.BRIGHT + 'стал ярче' + Style.RESET_ALL)
print('обычный текст')
При этом вы также можете использовать ANSI-последовательности напрямую в своем коде:
print('\033[31m' + 'красный текст')
print('\033[39m') # сброс к цвету по умолчанию
Еще одним вариантом является применение Colorama в сочетании с существующими ANSI библиотеками, такими как Termcolor или Blessings. Такой подход настоятельно рекомендуется для чего-то большего, чем тривиальное выделение текста:
from colorama import init
from termcolor import colored
# используйте Colorama, чтобы Termcolor работал и в Windows
init()
# теперь вы можете применять Termcolor для вывода
# вашего цветного текста
print(colored('Termcolor and Colorama!', 'red', 'on_yellow'))
Доступны следующие константы форматирования:
// цвет текста
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 выполнит этот сброс автоматически при выходе из программы.
Позиционирование курсора
Библиотекой поддерживаются ANSI-коды для изменения положения курсора. Пример их генерации смотрите в demos/demo06.py.
Аргументы Init
init() принимает некоторые **kwargs для переопределения поведения по умолчанию.
init(autoreset=False):
Если вы постоянно осуществляете сброс указанных вами цветовых настроек после каждого вывода, init(autoreset=True) будет выполнять это по умолчанию:
from colorama import init, Fore
init(autoreset=True)
print(Fore.GREEN + 'зеленый текст')
print('автоматический возврат к обычному')
init(strip=None):
Передайте True или False, чтобы определить, должны ли коды ANSI удаляться при выводе. Поведение по умолчанию — удаление, если программа запущена на Windows или если вывод перенаправляется (не на tty).
init(convert=None):
Передайте True или False, чтобы определить, следует ли преобразовывать ANSI-коды в выводе в вызовы win32. По умолчанию Colorama будет их конвертировать, если вы работаете под Windows и вывод осуществляется на tty (терминал).
init(wrap=True):
В Windows Colorama заменяет sys.stdout и sys.stderr прокси-объектами, которые переопределяют метод .write() для выполнения своей работы. Если эта обертка вызывает у вас проблемы, то ее можно отключить, передав init(wrap=False). Поведение по умолчанию — обертывание, если autoreset, strip или convert равны True.
Когда обертка отключена, цветной вывод на платформах, отличных от Windows, будет продолжать работать как обычно. Для кроссплатформенного цветного отображения текста можно использовать AnsiToWin32 прокси, предоставляемый Colorama, напрямую:
import sys
from colorama import init, Fore, AnsiToWin32
init(wrap=False)
stream = AnsiToWin32(sys.stderr).stream
# Python 2
print >>stream, Fore.RED + 'красный текст отправлен в stderr'
# Python 3
print(Fore.RED + 'красный текст отправлен в stderr', file=stream)
Распознаваемые ANSI-последовательности
Последовательности ANSI обычно имеют вид:
ESC [ <параметр> ; <параметр> ... <команда>
Где <параметр> — целое число, а <команда> — один символ. В <команда> передается ноль или более параметров. Если параметры не представлены, это, как правило, синоним передачи одного нуля. В последовательности нет пробелов; они были добавлены здесь исключительно для удобства чтения.
Единственные ANSI-последовательности, которые Colorama преобразует в вызовы win32, это:
ESC [ 0 m # сбросить все (цвета и яркость)
ESC [ 1 m # яркий
ESC [ 2 m # тусклый (выглядит так же, как обычная яркость)
ESC [ 22 м # нормальная яркость
# FOREGROUND (цвет текста)
ESC [ 30 м # черный
ESC [ 31 м # красный
ESC [ 32 м # зеленый
ESC [ 33 м # желтый
ESC [ 34 m # синий
ESC [ 35 m # пурпурный
ESC [ 36 m # голубой
ESC [ 37 m # белый
ESC [ 39 m # сброс
# ФОН
ESC [ 40 m # черный
ESC [ 41 m # красный
ESC [ 42 м # зеленый
ESC [ 43 m # желтый
ESC [ 44 m # синий
ESC [ 45 m # пурпурный
ESC [ 46 m # голубой
ESC [ 47 m # белый
ESC [ 49 m # сброс
# позиционирование курсора
ESC [ y;x H # позиционирование курсора в позиции x, y (у направлена вниз)
ESC [ y;x f # позиционирование курсора в точке x, y
ESC [ n A # перемещение курсора на n строк вверх
ESC [ n B # перемещение курсора на n строк вниз
ESC [ n C # перемещение курсора на n символов вперед
ESC [ n D # перемещение курсора на n символов назад
# очистить экран
ESC [ режим J # очистить экран
# очистить строку
ESC [ режим K # очистить строку
Несколько числовых параметров команды ‘m’ могут быть объединены в одну последовательность:
ESC [ 36 ; 45 ; 1 m # яркий голубой текст на пурпурном фоне
Все другие ANSI-последовательности вида ESC [ <параметр> ; <параметр> … <команда> молча удаляются из вывода в Windows.
Любые другие формы ANSI-последовательностей, такие как односимвольные коды или альтернативные начальные символы, не распознаются и не удаляются. Однако было бы здорово добавить их. Вы можете сообщить разработчикам, если это будет полезно для вас, через Issues на GitHub.
Текущий статус и известные проблемы
Лично я тестировал библиотеку только на Windows XP (CMD, Console2), Ubuntu (gnome-terminal, xterm) и OS X.
Некоторые предположительно правильные ANSI-последовательности не распознаются (см. подробности ниже), но, насколько мне известно, никто еще не жаловался на это. Загадка.
См. нерешенные проблемы и список пожеланий: https://github.com/tartley/colorama/issues
Если у вас что-то не работает или делает не то, что вы ожидали, авторы библиотеки будут рады услышать об этом в списке проблем, указанном выше, также они с удовольствием ждут и предоставляют доступ к коммиту любому, кто напишет один или, может, пару рабочих патчей.
