Как красиво оформить консоль python
Обновлено: 05.07.2024
Модуль click - это пакет Python для создания красивых интерфейсов командной строки компонуемым способом с минимальным количеством кода, насколько это необходимо. Он легко настраивается, но по умолчанию поставляется с разумными настройками.
Он направлен на то, чтобы сделать процесс написания инструментов командной строки быстрым и увлекательным, а также предотвратить любое разочарование, вызванное невозможностью реализовать предполагаемый API CLI.
- Произвольное вложение команд.
- Автоматическое создание справки по параметрам командной строки.
- Поддерживает отложенную загрузку подкоманд во время выполнения.
- Меньшее количество кода по сравнению с argparse .
Почему именно click , а не встроенный модуль argparse ?
Модуль argparse имеет некоторые особенности поведения, которые затрудняют обработку произвольных интерфейсов командной строки:
argparse имеет встроенное поведение, которое пытается угадать, является ли что-то параметром или опцией. Такое поведение становится непредсказуемым при работе со сценариями, в которых не используется часть опций и/или параметров.
argparse не поддерживает отключение перемежающихся аргументов. Без этой функции невозможно безопасно реализовать вложенный синтаксический анализ, например как в click .
Установка модуля click в виртуальное окружение.
Простой пример сценария с модулем click :
Если запустить эту программу в командной строке то вывод будет следующим:
К тому же программа, на основе модуля click автоматически генерирует красивые справочные страницы:
Переключение модуля click на пакет setuptools .
Для этого есть две основные (и многие другие) причины:
Во-первых, setuptools автоматически генерирует исполняемые оболочки для Windows, следовательно утилиты командной строки работают и в Windows.
Вторая причина заключается в том, что сценарии setuptools работают с virtualenv в Unix без необходимости активации virtualenv . Это очень полезная концепция, которая позволяет объединить написанные скрипты со всеми зависимостями в виртуальную среду virtualenv .
Базовые концепции модуля click .
Создание команды.
Модуль click основан на объявлении команд через декораторы. Внутри модуля есть интерфейс без декоратора для сложных случаев использования, но он не рекомендуется для высокоуровневого кода.
Управляющие последовательности ANSI
ANSI escape sequences или Управляющие последовательности ANSI — это стандарт, дающий возможность управлять курсором, цветами, начертание в текстовых консолях. Такие последовательности воспринимаются отрисовщиком терминала, как команды отображать последующий текст в определенном формате. Есть также последовательность, которая сбрасывает предыдущие команды, и отображение текста становиться обычным. Существует несколько форматов управляющих последовательностей, различающихся возможностями и появившимися в разных версиях кодировок. Поговорим об этих форматах подробнее.
8 основных цветов и стили
Для обычного пользователя разнообразия цветов этого формата будет более чем исчерпывающим. Но прежде чем задумываться о том, что терракотовый цвет гораздо круче красного, и он вам уж точно нужен, давайте разберемся, как устроена самая простая версия управляющей последовательности ANSI для форматирования текста.
Чтобы изменить текущий цвет шрифта или фона можно использовать следущий синтаксис:
- Начинается управляющая последовательность с любого из этих трёх представлений: \x1b[ (hex) или \u001b[ (Unicode) или \033[ (oct)
- Далее следуют аргументы, разделённые между собой ; (можно указывать в любом порядке)
- В конце ставится буква m
Возможные аргументы
| Модификатор | Код |
|---|---|
| 1 | Жирный |
| 2 | Блеклый |
| 3 | Курсив |
| 4 | Подчёркнутый |
| 5 | Мигание |
| 9 | Зачёркнутый |
Изменения цвета шрифта
| Цвет | Код |
|---|---|
| 30 | Чёрный |
| 31 | Красный |
| 32 | Зелёный |
| 33 | Жёлтый |
| 34 | Синий |
| 35 | Фиолетовый |
| 36 | Бирюзовый |
| 37 | Белый |
Изменения цвета фона
| Цвет | Код |
|---|---|
| 40 | Чёрный |
| 41 | Красный |
| 42 | Зелёный |
| 43 | Жёлтый |
| 44 | Синий |
| 45 | Фиолетовый |
| 46 | Бирюзовый |
| 47 | Белый |
Бонус: другие интересные модификаторы, которые могут поддерживаться не всеми платформами
| Модификатор | Код |
|---|---|
| 38 | RGB цвет (см. раздел "Совсем много цветов") |
| 21 | Двойное подчёркивание |
| 51 | Обрамлённый |
| 52 | Окружённый |
| 53 | Надчёркнутый |
Пример корректного синтаксиса: \033[3;36;44m . После вывода этой конструкции стиль будет изменён для всего последующего текста. Чтобы вернуться к изначальному состоянию можно использовать \033[0m , тогда весь текст с этого места вернётся к изначальному форматированию.
Давайте поэкспементируем. Для примеров я буду использовать Python.
Важно заметить, что форматирование повлияло и на консоль питона, а не только на ее вывод. Именно поэтому очень важно закрывать все "тэги" изменения форматирования.
Часто используемые сочетания (copy-paste-able)
| Код | Описание |
|---|---|
| \033[0m | вернуться к начальному стилю |
| \033[31m <your text goes here> \033[0m | красный текст — для обозначения ошибок |
| \033[1;31m <your text goes here> \033[0m | жирный красный текст — для обозначения критических ошибок |
| \033[32m <your text goes here> \033[0m | зеленый текст — успешное выполнение |
| \033[3;31m <your text goes here> \033[0m | красный курсив — текст ошибки |
| \033[43m <your text goes here> \033[0m | выделение основного, как будто жёлтым маркером |
Больше цветов: аж целых 256
Некоторые терминалы поддерживают вывод целых 256 цветов. Если команда echo $TERM выводит xterm-256color , то ваш терминал всё корректно обработает.
В этом формате синтаксис немного другой:
Для генерации кодов цветов можно использовать генератор.
А палитру доступных цветов можно увидеть на картинке ниже.
Совсем много цветов
Этот формат не всегда поддерживается стандартными консолями.
- \033[38;2;⟨r⟩;⟨g⟩;⟨b⟩m — цвет текста
- \033[48;2;⟨r⟩;⟨g⟩;⟨b⟩m — цвет фона
Python: Использование библиотеки Colorama
Библиотека Colorama позволяет форматировать текст, не запоминая коды цветов. Рассмотрим её использование на примере:
Style позволяет изменить стиль, Fore — цвет шрифта, Back — цвет фона. Использовать переменные из colorama нужно также, как и коды изменения стиля. Но плюс использования библиотеки в том, что Fore.RED более читаем, чем \033[0;31m
Если в colorama.init() указать параметр autoreset=True , то стиль будет автоматически сбрасываться (в конец каждого print будут добавлены сбрасывающие стили последовательности), поэтому вам не придётся об этом каждый раз вспоминать.
А что не так с Windows?
Просто так синтаксис, описанный в начале статьи, не работает в командной строке Windows. Поддержка цветов появлялась постепенно, причём в странном варианте. В начале программы надо сделать системный вызов, активирующий отрисовку цветов. А в более старых версиях необходимо заменить все ANSI последовательности на системные вызовы.
Но colorama.init() сделает всё за вас в большинстве версий Windows. Однако если вы используете другую операционную систему, то функцию init() вызывать в начале программы не обязательно. Также некоторые IDE на Windows (например, PyCharm) тоже поддерживают цвета без каких-либо махинаций.
А еще Windows не поддерживает многие модификаторы, такие как жирный текст. Подробнее можно почитать на странице Colorama
Termcolor
Ещё одна библиотека для вывода цветного текста с более удачным, на мой взлгяд, синтаксисом.
Кстати, проблему с Windows всё ещё можно починить с помощью colorama.init()
Выводы
Стандартные 8 цветов позволяют разнообразить вывод в консоль и расставить акценты. 256 цветов намного расширяют возможности, хотя и поддерживаются не всеми консолями. Windows, к сожалению, не поддерживает многие основные модификаторы, например, курсив. Также есть некоторые цвета, которые не прописаны в стандартах, но могут поддерживаться вашей операционной системой. Если вы хотите больше цветов, то вы можете поискать их в Гугле.
Пока что не любой терминал поддерживает 24-битные цвета и все модификаторы, но мы вряд ли увидим сильные изменения в этой сфере. Так что пока нам остаётся выбирать самые красивые варианты из тех, что доступны в любимом терминале.
Источники
- Картинки с синтаксисом из статьи
- Генератор из статьи на Хабре
Облачные серверы от Маклауд быстрые и безопасные.
Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!
В этой статье показано, как использовать цветной вывод в терминале на Python используя библиотеки и стандартные средства.
Введение
ANSI Escape Sequences
Ваш TeleTypeWriter (TTY), или, скорее, ваш терминал, не только способен показывать вывод программы, он также может отображать движущийся курсор, окрашивать текст, очищать весь экран и многое другое, чем просто статический вывод.
Возможно, вы видели утилиты командной строки с красочным текстом и индикаторами выполнения. Как мы контролируем представление данных, которые мы выводим на терминал?
Текст окрашивается на вашем терминале на основе ANSI Escape Sequences. Эта статья посвящена ANSI Escape последовательностям, для того чтобы применить цветной вывод.
В терминалах широко используются две цветовые схемы:
- 16 цветов (8 фоновых + 8 передних)
- 256 цветов
Давайте начнем раскрашивать наши выходные данные с помощью опции 16 цветов.
Схема 16 цветов в Python
16-цветовая схема состоит из двух наборов по 8 цветов в каждом (8 фонов и 8 передних планов), и они могут быть отображены в терминале с помощью следующего синтаксиса:
Давайте проверим эту схему, напечатав цветной узор с красным жирным текстом и желтым фоном. Код стиля для представления полужирного текста равен 2. Цветовые коды для красного текста переднего плана-31 и 43 для желтого фона.
Итак, чтобы получить этот макет, пишем:
Выполните приведенную выше команду в вашем интерпретаторе Python (или в файле).
Вы увидите следующий вывод:
Как видно, наш текст перетекает на следующую строчку. Нам нужна точка сброса, чтобы остановить печать цветов.
Это можно сделать, добавив \033[0;0m к строке следующим образом:
Код \033[0;0m представляет собой шаблон сброса, который возвращает терминал обратно в исходную цветовую схему.
Это обеспечит следующий результат:
Согласитесь, выглядит намного лучше!
Цветной вывод в Colorama
Давайте установим модуль с помощью pip:
Мы рекомендуем вам установить его в виртуальной среде.
После настройки давайте перейдем к печати цветного текста с помощью Colorama:
Сначала я импортирую функции init, чтобы инициализировать модуль и установить autoreset в True, чтобы нам не пришлось сбрасывать его вручную, Fore (текстовый объект переднего плана), Back (фоновый объект) и Style (объект стиля). Каждый объект имеет свой собственный набор констант, которые могут быть вызваны в функции print.
Шаблон сброса не требуется, так как я установил аргумент autoreset в значение True при инициализации экземпляра.
Вывод программы будет выглядеть так:
Схема 256 цветов в Python
С развитием технологий 256-цветовая схема наиболее часто встречается в терминалах. Если вы используете ОС на базе Linux, вы можете проверить цветовую схему, поддерживаемую терминалом, введя следующую команду:
Если эта команда возвращает xterm-256color, то ваш терминал поддерживает максимум 256 цветов.
Интересно, что это за цвета? Вы все узнаете сразу после того, как поймете синтаксис 256-цветовой схемы. Работа с 256 цветами немного отличается от работы с 16-цветовой схемой:
Основываясь на приведенном выше синтаксисе, давайте попробуем воссоздать логотип StackAbuse в Python с помощью последовательности Escape ANSI.
Логотип содержит бледно-серый фон (\033[48;5;236m) со словами: Stack белого цвета (\033[38;5;231m) и Abuse оранжевого цвета (\033[38;5;208m). И конечно, код сброса должен быть встроен в строку.
Тем не менее, мы можем воссоздать логотип с помощью этой последовательности ANSI:
Потрясающе! Какие еще цвета может печатать терминал? Давайте посмотрим, напечатав все 256 цветов, поддерживаемых терминалом:
Этот код содержит две функции, которые печатают переменную, которую вы передаете в них, в соответствующих последовательностях Escape ANSI. Как только я запущу скрипт и передам Х в определенном диапазоне, например (30,38] для 16-цветовой схемы или (0-255] для 256-цветовой схемы, он распечатает индексы в цветах при этих значениях.
Это позволит распечатать обе цветовые схемы в терминале:
Это может быть очень полезно в качестве краткого руководства при создании утилит командной строки.
Заключение
В этом уроке я рассказал, как печатать цветные выходные данные для символов, которые мы отправляем в поток stdout. Я показал, как это сделать с помощью встроенных функций Python, а также как использовать библиотеку Colorama.
Все мы, специалисты по анализу данных, выполняем множество рутинных и повторяющихся действий. Сюда о т носятся: создание еженедельных отчетов, ETL-операции (извлечение, преобразование, загрузка), обучение моделей с помощью различных наборов данных и т.д. Зачастую на выходе у нас появляется множество Python -скриптов, и каждый раз при выполнении кода нам приходится менять его параметры. Лично меня это бесит! Именно поэтому я стал превращать скрипты в повторно используемые инструменты интерфейса командной строки ( CLI -инструменты). Это повысило эффективность и продуктивность моей каждодневной работы. Начинал я с Argparse , но не особо проникся им, поскольку приходилось писать множество убогого кода. И тут я подумал: неужели нельзя достичь тех же результатов без постоянного переписывания кода? Да и вообще, смогу ли я когда-нибудь получать удовольствие от создания CLI -инструментов?
Так что же такое Click ? Из официальной документации следует:
Click призван сделать процесс написания инструментов командной строки быстрым и увлекательным, избавляя при этом от всякого рода разочарований из-за невозможности реализации желаемого CLI API.
Звучит шикарно! Как считаете?
В данной статье я поделюсь с вами практическим руководством по пошаговому созданию Python CLI с помощью Click на Python и продемонстрирую вам базовые опции и преимущества этой библиотеки. Выполнив данный пример, вы научитесь писать CLI -инструменты быстро и безболезненно :) Давайте уже займемся делом!
В ходе данного урока мы будем пошагово создавать CLI с помощью Click на Python . Я начну с самых основ и в каждом шаге буду рассказывать про концепцию, предлагаемую Click . Дополнительно мне понадобится Poetry для управления пакетами и зависимостями.
Подготовка
Для начала давайте установим Poetry . Существует множество способов установки, однако здесь мы воспользуемся pip :
Затем создадим в Poetry новый проект и назовем его cli-tutorial . Далее добавим зависимости click и funcy и создадим файл cli.py , который позже заполним кодом.
Я включил сюда funcy , поскольку он пригодится мне в дальнейшем. Ну а сейчас мы готовы к реализации своего первого CLI . Небольшое примечание: пример кода можно найти на GitHub.
Наш первый CLI на Click
Наш первоначальный CLI читает CSV -файл с диска, обрабатывает его (как именно он это делает — пока что не важно) и сохраняет результат в Excel . Пути к входному и выходному файлу настраиваются пользователем. И пользователь должен указать путь к входному файлу. Путь к выходному файлу указывается по желанию. Обычно им считается output.xlsx . Вот так выглядит этот код при использовании Click :
И что мы тут делаем?
2. Затем определяем аргументы командной строки через декоратор click.option . Но внимательно следите за правильными названиями аргументов в декорированной функции. Если в click.option добавляется строка без дефиса, то аргумент должен совпадать с этой строкой. Этим и объясняется --in и in_file . Если все имена начинаются с дефисов, то Click создает название аргумента по самому длинному имени и заменяет все дефисы внутри слова на нижнее подчеркивание. Название пишется в нижнем регистре. Пример: --out-file и out_file . Более подробно можно почитать в документации по Click .
3. Через соответствующие аргументы click.option задаем наши предварительные условия значениями по умолчанию или необходимыми аргументами.
4. Добавляем текст справки к нашим аргументами. Он будет показываться при вызове функции через --help . Здесь же отображается docstring из нашей функции.
Теперь можете вызвать этот CLI несколькими способами:
Круто! Вот мы и создали свой первый CLI с помощью Click !
Обратите внимание: я не прописываю read_csv , process_csv и write_excel , т.к. предполагаю, что они существуют и корректно выполняют свою работу.
Спецификация типов
В нашем примере с CLI мы хотели, чтобы пользователь передавал корректный путь к существующему файлу, для которого у нас есть разрешения на чтение. Если эти условия соблюдены, то мы загружаем входной файл. Кроме того, пользователь может задать путь к выходному файлу, и этот путь также должен быть действительным. Все это можно сделать, передав объект click.Path в аргумент type декоратора click.option .
click.Path — это один из нескольких готовых типов в Click . Помимо стандартных решений, вы можете создавать настраиваемые типы. Однако в данной статье эта тема не освещается. Почитать подробнее про пользовательские типы можно в документации.
Логические флаги
Еще одна полезная функция Click — это логические флаги. И, пожалуй, самым известным из них является флаг verbose . При значении true ваш инструмент выводит всю информацию в терминал. При значении false показываются только некоторые данные. В Click это можно реализовать следующим образом:
Все, что от вас требуется, — это добавить еще один декоратор click.option и установить is_flag=True . Теперь для получения подробного вывода нужно всего лишь вызвать CLI :
Переключатель функций
Допустим, нам захотелось не просто хранить результат в локальном process_csv , но и загружать его на сервер. Кроме того, есть не только целевой сервер, но и сервера для разработки, тестирования и реальной базы. И ко всем им нужно обращаться по разным URL . Один из способов выбора сервера — это передача полного URL - адреса как аргумента, который пользователь должен будет прописать. Причем, этот способ не просто рискованный в плане ошибок, но и весьма кропотлив. Поэтому для облегчения жизни пользователей я использую переключатели функций. Принцип их работы лучше всего иллюстрирует код ниже:
Здесь я добавил три декоратора click.option для трех возможных URL -адресов серверов. Важный момент: все три опции содержат одну общую переменную server_url . В зависимости от выбранной опции значение server_url соответствует значению, определенному в flag_value . Их вы выбираете, добавляя в качестве аргумента --dev , --test или --prod . Таким образом, при выполнении:
Запрос на ввод логина и пароля
К счастью или несчастью, наши сервера защищены паролями. Так что для загрузки файла на сервер потребуется имя пользователя и пароль. Конечно же, их можно задать стандартными аргументами click.option . Но тогда ваш пароль сохранится в виде обычного текста в истории команд, а это несет определенную угрозу для безопасности.
Поэтому мы предпочитаем выдавать пользователю запрос на ввод пароля, не передавая его в терминал и не сохраняя в истории команд. Что до логина, то здесь нам по душе простой запрос на ввод с передачей в терминал. А при определенных познаниях в Click ничего проще и не придумаешь. Вот наш код:
Чтобы добавить подсказку для ввода аргумента, установите prompt=True . Это действие добавит запрос везде, где пользователь не проставил аргумент --user , однако он может потребоваться. Если нажать на Enter в запросе, то проставится значение по умолчанию. Оно определяется с помощью другой полезной функции Click .
Запрос на ввод и подтверждение пароля без отправки его в терминал стало чем-то настолько обыденным, что Click придумал для этого специальный декоратор password_option . Важное примечание: пользователь все равно будет передавать пароль через --password MYSECRETPASSWORD . Однако так он сможет этого не делать.
Вот и все. Мы создали полноценный CLI . Перед тем, как подвести финальную черту, мне бы хотелось поделиться еще одной полезной подсказкой.
Poetry-скрипты
Последним штрихом этой статьи, который никак не связан с самим Click , но идеально вписывается в тему CLI , является создание Poetry -скриптов. Эти скрипты позволяют создавать исполняемые модули для вызова Python -функций из командной строки так же, как это делается в Setuptools -скриптах. Как это выглядит? Для начала добавим в файл pyproject.toml следующие строки:
Значение your-wanted-name — это псевдоним для функции process , определенной в модуле cli_tutorial.cli . Теперь вы можете вызвать ее следующим образом:
Таким образом, вы, например, сможете включать несколько CLI -функций в один файл, определять псевдонимы и не добавлять блок if __name__ == “__main__” .
В данной статье я показал вам, как пользоваться Click и Poetry для простого и эффективного создания CLI -инструментов. Это был лишь небольшой пример возможностей Click . В библиотеке есть и другие полезные функции, как, например, обратные вызовы, вложенные команды или предварительный выбор значений. Еще раз призываю всех заинтересовавшихся темой почитать документацию по Click .
Читайте также: