[Перевод] Учебное пособие по Textual21.11.2023 09:30

Перевод туториала по фреймворку для построения TUI (текстовых интерфейсов). Кроссплатформенность, возможность вывода в веб, а также олдскульность.

Добро пожаловать в учебное пособие по Textual!

В конце этой страницы вы получите некоторое представление о разработке приложений с помощью Textual.

Если хотите, чтобы люди что-то делали, сделайте это весёлым.
— Will McGugan (создатель Rich и Textual)

К этому учебному пособию прилагаются видеоуроки, содержащие тот же контент.

Мы сделаем приложение-секундомер (stopwatch). Оно будет отображать список секундомеров с кнопками для запуска, остановки и сброса значения. Пользователь также сможет добавлять и удалять секундомеры при необходимости.

Это будет простое, но полностью функциональное приложение — можете его распространять, если хотите!

Вот так будет выглядеть готовое приложение:

Попробуйте!

Следующая картинка это не скриншот, а полноценное интерактивное приложение Textual, работающее в браузере.

Попробовать приложение online.

В оригинале тут был </code>, но во избежание хабраэффекта я оставил от него только ссылку: </div> </div> <blockquote>Подсказка: Если вам интересно, как публиковать приложения Textual в вебе, смотрите textual-web.</blockquote> <h2>Получаем код</h2> Если хотите попробовать готовое приложение Stopwatch и посмотреть его код, для начала установите Textual, после чего склонируйте репозиторий Textual: <pre><code class="plaintext">git clone https://github.com/Textualize/textual.git</code></pre> Когда репозиторий склонируется, перейдите в каталог <code>docs/examples/tutorial</code> и запустите <code>stopwatch.py</code>. <pre><code class="plaintext">cd textual/docs/examples/tutorial python stopwatch.py</code></pre> <blockquote>Подсказка: Аннотации типов в Textual совершенно не обязательны. Мы включили их в код примера, но хотите ли вы их использовать — решайте сами.</blockquote> Мы большие поклонники аннотаций типов Python в Textualize. Если вы с ними ещё не сталкивались, кратко скажем, что это способ указать типы данных, параметров и возвращаемых значений. Аннотация типа позволяет таким инструментам, как mypy, находить ошибки до запуска вашего кода. Следующая функция содержит аннотации типов: <pre><code class="python">def repeat(text: str, count: int) -> str: """Repeat a string a given number of times.""" return text * count</code></pre> Типы параметров указываются после двоеточия. Так, <code>text: str</code> показывает, что <code>text</code> должен быть строкой, а <code>count: int</code> означает, что <code>count</code> должен быть целым числом. Тип возвращаемого значения указывается после <code>-></code>. Так, <code>-> str:</code> показывает, что метод возвращает строку. Первый шаг в создании приложения Textual — это импортировать класс <code>App</code> и унаследоваться от него. Вот базовый класс приложения, который мы используем в качестве отправной точки для приложения секундомера. <code>stopwatch01.py</code> <pre><code class="python">from textual.app import App, ComposeResult from textual.widgets import Header, Footer class StopwatchApp(App): """A Textual app to manage stopwatches.""" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Если вы запустите этот код, то увидите примерно следующее: <img src="https://habrastorage.org/r/w1560/webt/r3/js/fn/r3jsfnyofo-jjnaij_iba5xjkdg.png" alt="r3jsfnyofo-jjnaij_iba5xjkdg.png" /> Нажмите клавишу <code>D</code> для переключения между светлым и тёмным режимом. <img src="https://habrastorage.org/r/w1560/webt/c6/tk/wo/c6tkwofyjgtfxvbkc2x4prl8ql8.png" alt="c6tkwofyjgtfxvbkc2x4prl8ql8.png" /> Нажмите <code>Ctrl+C</code>, чтобы выйти из приложения и вернуться в командную строку. <h2>Рассмотрим класс <code>App</code> поближе</h2> Давайте более подробно изучим <code>stopwatch01.py</code>. <pre><code class="python">from textual.app import App, ComposeResult from textual.widgets import Header, Footer</code></pre> Первая строка импортирует класс <code>App</code>, который будет базовым для нашего приложения. Вторая импортирует два встроенных виджета: <code>Footer</code>, который показывает в нижней части экрана панель с привязанными клавишами, и <code>Header</code>, который показывает заголовок в верхней части экрана. Виджеты — это повторно используемые компоненты, отвечающие за управление частью экрана. В этом руководстве мы рассмотрим, как их создавать. Следующие строки определяют само приложение: <pre><code class="python">class StopwatchApp(App): """A Textual app to manage stopwatches.""" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark</code></pre> Класс <code>App</code> — это место, где находится большая часть логики приложений Textual. Он отвечает за загрузку конфигурации, настройку виджетов, обработку ключей и многое другое. Вот что в нём задаётся: <ul><li><code>BINDINGS</code> это список кортежей, которые отображают (или привязывают) клавиши к действиям вашего приложения. Первый элемент кортежа это клавиша, второй — имя действия, последний — краткое описание. Пока что у нас только одна привязка, отображающая клавишу <code>D</code> на действие <code>"toggle_dark"</code>. Подробнее см. key bindings в руководстве.</li> <li><code>compose()</code> это метод, где из виджетов конструируется пользовательский интерфейс. Вообще, метод compose () должен возвращать последовательность виджетов, но проще возвращать их по одному через yield (что превращает метод в генератор). В примере мы возвращаем оба импортированных класса, т.е. <code>Header()</code> и <code>Footer()</code>.</li> <li><code>action_toggle_dark()</code> определяет метод действия. Действия — это методы, начинающиеся с <code>action_</code>, за которым идёт имя действия. Приведённый выше список <code>BINDINGS</code> приказывает Textual запустить это действие, когда пользователь нажмёт клавишу <code>D</code>. За подробностями обращайтесь к actions в руководстве.</li> </ul> <pre><code class="python">if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Последние три строки создают экземпляр приложения и вызывают метод run (), который переводит ваш терминал в режим приложения, запускает приложение и ждёт до тех пор, пока вы не выйдете с помощью <code>Ctrl+C</code>. Это происходит в блоке <code>__name__ == "__main__"</code>, чтобы можно было как запустить приложение с помощью <code>python stopwatch01.py</code> так и импортировать его как часть более крупного проекта. В комплекте с Textual есть набор встроенных виджетов, таких как <code>Header</code> и <code>Footer</code>, которые универсальны и могут использоваться повторно. Для секундомера нам нужно будет создать несколько пользовательских виджетов. Прежде чем мы этим займёмся, давайте сначала набросаем дизайн приложения, чтобы знать, к чему мы стремимся. <img src="https://habrastorage.org/r/w1560/webt/mh/ge/tc/mhgetcbszppdq7l5g-4-id06gq0.png" alt="mhgetcbszppdq7l5g-4-id06gq0.png" /> <h2>Пользовательские виджеты</h2> Нам нужен виджет <code>Stopwatch</code>, собранный из таких дочерних виджетов: <ul><li>Кнопка «Start»</li> <li>Кнопка «Stop»</li> <li>Кнопка «Reset»</li> <li>Отображение времени</li> </ul> В Textual есть встроенный виджет <code>Button</code>, который позаботится о первых трёх компонентах. Всё, что нам нужно, это создать виджет для отображения прошедшего времени, ну и сам виджет секундомера. Давайте добавим их в приложение. Пока что это просто скелет, но по ходу дела он обрастёт нужными функциями. <code>stopwatch02.py</code> <pre><code class="python">from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" class Stopwatch(Static): """A stopwatch widget.""" def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay("00:00:00.00") class StopwatchApp(App): """A Textual app to manage stopwatches.""" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch()) def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> В этом коде мы импортировали два новых виджета: <code>Button</code>, который создаёт нажимаемую кнопку и <code>Static</code>, являющийся базовым классом для простых контролов. Также мы импортировали <code>ScrollableContainer</code> из <code>textual.containers</code> который (как подсказывает его имя) является виджетом, содержащим другие виджеты. Мы объявили пустой виджет <code>TimeDisplay</code>, унаследованный от <code>Static</code>. Наполним его позже. Класс виджета <code>Stopwatch</code> также унаследован от <code>Static</code>. У него есть метод <code>compose()</code>, который возвращает последовательность дочерних виджетов, состоящую из трёх объектов <code>Button</code> и одного <code>TimeDisplay</code>. Эти виджеты будут формировать секундомер, как в нашем наброске. <h3>Кнопки</h3> Конструктор <code>Button</code> принимает текст (label), который будет отображаться на кнопке (<code>"Start"</code>, <code>"Stop"</code> или <code>"Reset"</code>). Кроме того, некоторые кнопки получают следующие параметры: <ul><li><code>id</code> это идентификатор, по которому мы можем найти кнопку и применить к ней стили. Подробности будут позже.</li> <li><code>variant</code> это строка, выбирающая стиль по умолчанию. Вариант <code>"success"</code> сделает кнопку зелёной, а <code>"error"</code> — красной.</li> </ul> <h2>Композиция виджетов</h2> Чтобы добавить виджеты в наше приложение, нам сначала нужно вернуть их из метода <code>compose()</code>. Новая строка в <code>StopwatchApp.compose()</code> создаёт единственный объект <code>ScrollableContainer</code>, который содержит прокручиваемый список секундомеров. Когда классы содержат другие виджеты (например, <code>ScrollableContainer</code>), они обычно принимают свои дочерние виджеты в качестве позиционных аргументов. Мы хотим запустить приложение с тремя секундомерами, поэтому создаем три экземпляра <code>Stopwatch</code> и передаем их конструктору контейнера. <h2>Приложение без стилей</h2> Давайте посмотрим, что случится, когда мы запустим <code>stopwatch02.py</code>. <img src="https://habrastorage.org/r/w1560/webt/qu/qh/ud/quqhudpx6utusz-qce9zqnkq3ys.png" alt="quqhudpx6utusz-qce9zqnkq3ys.png" /> Элементы приложения-секундомера уже есть. Кнопки интерактивны, и вы можете прокручивать контейнер, но это не похоже на наш набросок. Это потому, что нам еще предстоит применить к нашим новым виджетам стили. У каждого виджета есть объект <code>styles</code> с набором атрибутов, которые влияют на его внешний вид. Вот как вы можете установить для виджета белый текст на синем фоне: <pre><code class="python">self.styles.background = "blue" self.styles.color = "white"</code></pre> Хотя стили и можно устанавливать таким образом, необходимость в этом возникает редко. Textual поддерживает CSS (Cascading Style Sheets): технологию, используемую в веб-браузерах. CSS-файлы это файлы данных, загружаемые вашим приложением и содержащие информацию о стилях, которые применяются к вашим виджетам. <blockquote>Информация: Диалект CSS, используемый в Textual, сильно проще вебовского CSS и гораздо легче изучается.</blockquote> CSS упрощает итеративный дизайн вашего приложения и делает возможным живое редактирование — вы можете редактировать CSS и видеть изменения без перезапуска приложения! Давайте добавим CSS-файл к нашему приложению. <code>stopwatch03.py</code> <pre><code class="python">from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" class Stopwatch(Static): """A stopwatch widget.""" def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay("00:00:00.00") class StopwatchApp(App): """A Textual app to manage stopwatches.""" CSS_PATH = "stopwatch03.tcss" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch()) def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Добавление классовой переменной <code>CSS_PATH</code> приказывает Textual загрузить следующий файл при запуске приложения: <pre><code class="css">stopwatch03.tcss Stopwatch { layout: horizontal; background: $boost; height: 5; margin: 1; min-width: 50; padding: 1; } TimeDisplay { content-align: center middle; text-opacity: 60%; height: 3; } Button { width: 16; } #start { dock: left; } #stop { dock: left; display: none; } #reset { dock: right; }</code></pre> Если мы запустим приложение сейчас, оно будет выглядеть совсем по-другому. <img src="https://habrastorage.org/r/w1560/webt/n2/-5/ft/n2-5ftfd38fvvzy_l_xa6qfrrta.png" alt="n2-5ftfd38fvvzy_l_xa6qfrrta.png" /> Это уже больше похоже на наш набросок. Давайте посмотрим, как Textual использует <code>stopwatch03.tcss</code> для применения стилей. <h2>Основы CSS</h2> CSS-файлы содержат некоторое количество блоков объявлений. Вот первый такой блок из <code>stopwatch03.tcss</code>: <pre><code class="css">Stopwatch { layout: horizontal; background: $boost; height: 5; margin: 1; min-width: 50; padding: 1; }</code></pre> Первая строка говорит Textual, что стиль должен применяться к виджету <code>Stopwatch</code>. Строки между фигурными скобками содержат непосредственно стили. Вот как этот CSS-код изменяет внешний вид виджета <code>Stopwatch</code>. <img src="https://habrastorage.org/r/w1560/webt/_2/6v/1q/_26v1q8xqfstodnkthityvrutmw.png" alt="_26v1q8xqfstodnkthityvrutmw.png" /> <ul><li><code>layout: horizontal</code> выстраивает дочерние виджеты по горизонтали слева направо.</li> <li><code>background: $boost</code> устанавливает цвет фона в значение <code>$boost</code>. Префикс <code>$</code> означает предварительно заданный цвет из встроенной темы. Цвет можно задавать и другими способами, например, <code>"blue"</code> или <code>rgb(20,46,210)</code>.</li> <li><code>height: 5</code> устанавливает высоту виджета равной 5 строкам текста.</li> <li><code>margin: 1</code> устанавливает внешний отступ вокруг виджета <code>Stopwatch</code> в 1 знакоместо, чтобы между виджетами в списке было небольшое расстояние.</li> <li><code>min-width: 50</code> устанавливает минимальную ширину нашего виджета в 50 знакомест.</li> <li><code>padding: 1</code> устанавливает внутренний отступ вокруг дочерних виджетов в 1 знакоместо.</li> </ul> Вот остаток <code>stopwatch03.tcss</code>, с оставшимися блоками объявлений: <pre><code class="css">TimeDisplay { content-align: center middle; opacity: 60%; height: 3; } Button { width: 16; } #start { dock: left; } #stop { dock: left; display: none; } #reset { dock: right; }</code></pre> Блок <code>TimeDisplay</code> выравнивает текст по центру (<code>content-align</code>), немного приглушает его (<code>opacity</code>), и задаёт ему высоту (<code>height</code>) в 3 строки. Блок <code>Button</code> выставляет ширину (<code>width</code>) кнопок в 16 знакомест. Последние три блока имеют немного другой формат. Если объявление начинается с <code>#</code>, то стили будут применяться к виджетам с соответствующим атрибутом <code>id</code>. Мы задали ID виджетов <code>Button</code>, когда возвращали их в compose. Например, у первой кнопки <code>id="start"</code>, чему соответствует <code>#start</code> в CSS. У кнопок есть стиль <code>dock</code>, который выравнивает виджет по указанному краю. Кнопки старта и остановки пристыкованы к левому краю, а кнопка сброса пристыкована к правому краю. Вы могли обратить внимание, что для кнопки остановки (<code>#stop</code> в CSS) задано <code>display: none;</code>. Это указывает Textual не отображать кнопку. Мы сделали это, потому что не хотим, чтобы кнопка остановки отображалась, когда таймер не запущен. Аналогично, нам не нужно, чтобы кнопка запуска отображалась, когда таймер запущен. Как работать с таким динамическим интерфейсом, мы увидим в следующем разделе. <h2>Динамический CSS</h2> Мы хотим, чтобы наш виджет <code>Stopwatch</code> имел два состояния: состояние по умолчанию с кнопками Start и Reset; и состояние started с кнопкой Stop. Также, когда секундомер запущен, он должен иметь зелёный фон и выделенный жирным шрифтом текст. <img src="https://habrastorage.org/r/w1560/webt/q_/fe/ev/q_feevrawodtbg8jpfqbg0_yxqu.png" alt="q_feevrawodtbg8jpfqbg0_yxqu.png" /> Мы можем достичь этого с помощью классов CSS. Не путайте с классами Python, класс CSS это что-то вроде тега, который вы можете добавить к виджету, чтобы изменить его стили. Вот новый CSS: <code>stopwatch04.tcss</code> <pre><code class="css">Stopwatch { layout: horizontal; background: $boost; height: 5; margin: 1; min-width: 50; padding: 1; } TimeDisplay { content-align: center middle; text-opacity: 60%; height: 3; } Button { width: 16; } #start { dock: left; } #stop { dock: left; display: none; } #reset { dock: right; } .started { text-style: bold; background: $success; color: $text; } .started TimeDisplay { text-opacity: 100%; } .started #start { display: none } .started #stop { display: block } .started #reset { visibility: hidden }</code></pre> Эти новые правила начинаются с префикса <code>.started</code>. Символ <code>.</code> указывает, что <code>.started</code> относится к классу CSS с именем <code>"started"</code>. Новые стили будут применены только к виджетам, имеющим этот CSS-класс. Некоторые из новых стилей содержат несколько селекторов, разделенных пробелом. Пробел указывает, что это правило должно соответствовать второму селектору, если по отношению к первому он является дочерним. Давайте рассмотрим один из этих стилей: <pre><code class="css">.started #start { display: none }</code></pre> Селектор <code>.started</code> соответствует любому виджету с CSS-классом <code>"started"</code>. А <code>#start</code> соответствует дочернему виджету с идентификатором <code>"start"</code>. Таким образом, правило соответствует кнопке Start для секундомеров в запущенном состоянии. Правило равно <code>"display: none"</code>, то есть, Textual не будет отрисовывать кнопку. <h2>Манипулирование классами</h2> Изменение CSS-классов виджета — это удобный способ обновить визуальные элементы без внесения большого количества беспорядочного кода, связанного с отображением. Вы можете добавлять и удалять классы CSS с помощью методов add_class () и remove_class (). Мы будем использовать их для привязки состояния started к кнопкам Start и Stop. Следующий код запустит или остановит секундомеры при нажатии кнопки. <code>stopwatch04.py</code> <pre><code class="python">from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" class Stopwatch(Static): """A stopwatch widget.""" def on_button_pressed(self, event: Button.Pressed) -> None: """Event handler called when a button is pressed.""" if event.button.id == "start": self.add_class("started") elif event.button.id == "stop": self.remove_class("started") def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay("00:00:00.00") class StopwatchApp(App): """A Textual app to manage stopwatches.""" CSS_PATH = "stopwatch04.tcss" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch()) def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Метод <code>on_button_pressed</code> является обработчиком события. Обработчики событий — это методы, вызываемые Textual в ответ на событие, такое как нажатие клавиши, щелчок мыши и т.д. Обработчики событий начинаются с <code>on_</code>, за которым следует название события, которое они будут обрабатывать. Следовательно, <code>on_button_pressed</code> будет обрабатывать нажатие кнопки. Если вы запустите <code>stopwatch04.py</code> сейчас, то сможете переключаться между двумя состояниями по нажатию первой кнопки: <img src="https://habrastorage.org/r/w1560/webt/xj/jl/kf/xjjlkfrtjfg6hr1rymhb2_bexdw.png" alt="xjjlkfrtjfg6hr1rymhb2_bexdw.png" /> В Textual регулярно всплывает тема обновления содержимого виджета время от времени. Это возможно: вы можете вызвать <code>refresh()</code> для отображения новых данных. Однако предпочтительно делать это автоматически с помощью реактивных атрибутов. Реактивный атрибут можно объявить с помощью функции reactive. Давайте воспользуемся ею, чтобы создать таймер, который отображает прошедшее время и постоянно обновляет его. <code>stopwatch05.py</code> <pre><code class="python">from time import monotonic from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.reactive import reactive from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" start_time = reactive(monotonic) time = reactive(0.0) def on_mount(self) -> None: """Event handler called when widget is added to the app.""" self.set_interval(1 / 60, self.update_time) def update_time(self) -> None: """Method to update the time to the current time.""" self.time = monotonic() - self.start_time def watch_time(self, time: float) -> None: """Called when the time attribute changes.""" minutes, seconds = divmod(time, 60) hours, minutes = divmod(minutes, 60) self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}") class Stopwatch(Static): """A stopwatch widget.""" def on_button_pressed(self, event: Button.Pressed) -> None: """Event handler called when a button is pressed.""" if event.button.id == "start": self.add_class("started") elif event.button.id == "stop": self.remove_class("started") def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay() class StopwatchApp(App): """A Textual app to manage stopwatches.""" CSS_PATH = "stopwatch04.tcss" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Create child widgets for the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch()) def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Мы добавили в виджет <code>TimeDisplay</code> два реактивных атрибута: <code>start_time</code> будет содержать время (в секундах) запуска секундомера, а <code>time</code> — время, которое будет отображаться на <code>Stopwatch</code>. Оба атрибута доступны в <code>self</code>, как если бы вы добавили их в <code>__init__</code>. Если вы присвоите значение любому из этих атрибутов, виджет обновится автоматически. <blockquote>Информация: Функция <code>monotonic</code> импортирована из модуля <code>time</code> стандартной библиотеки. Она похожа на <code>time.time</code>, но не возвращается назад, если изменится системное время.</blockquote> Первый аргумент <code>reactive</code> — необязательное значение по умолчанию для атрибута или вызываемый объект, который возвращает значение по умолчанию. В качестве значения по умолчанию для <code>start_time</code> мы передали функцию <code>monotonic</code>, которая будет вызвана для инициализации атрибута текущим временем при добавлении <code>TimeDisplay</code> в приложение. Атрибут <code>time</code> по умолчанию имеет простое значение с плавающей запятой, поэтому <code>self.time</code> будет инициализирован значением 0. Метод <code>on_mount</code> — это обработчик событий, вызываемый при первом добавлении виджета в приложение (монтировании в терминологии Textual). В этом методе мы вызываем set_interval (), чтобы создать таймер, вызывающий <code>self.update_time</code> шестьдесят раз в секунду. Этот метод вычисляет время, прошедшее с момента запуска виджета, и помещает его значение в <code>self.time</code>, что подводит нас к одной из сверхспособностей Reactive. Если вы реализуете метод, который начинается с <code>watch_</code>, за которым следует имя реактивного атрибута, то при изменении атрибута он будет автоматически вызван. Такие методы известны как следящие методы. Когда мы обновляем <code>self.time</code> 60 раз в секунду, это приводит к неявному вызову <code>watch_time</code>, который преобразует прошедшее время в строку и обновляет виджет вызовом <code>self.update</code>. Поскольку это происходит автоматически, нам не нужно передавать начальный аргумент в <code>TimeDisplay</code>. В итоге виджеты <code>Stopwatch</code> показывают время, прошедшее с момента создания виджета: <img src="https://habrastorage.org/r/w1560/webt/j6/47/bi/j647bijeymbtr0cmuosfml4gmj0.png" alt="j647bijeymbtr0cmuosfml4gmj0.png" /> Мы увидели, как обновлять виджеты с помощью таймера, но ещё нужно подключить кнопки, чтобы управлять секундомерами независимо. <h2>Подключение кнопок</h2> Нам нужно уметь запускать, останавливать и сбрасывать каждый секундомер независимо от остальных. Этого можно добиться, добавив несколько методов к классу <code>TimeDisplay</code>. <code>stopwatch06.py</code> <pre><code class="python">from time import monotonic from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.reactive import reactive from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" start_time = reactive(monotonic) time = reactive(0.0) total = reactive(0.0) def on_mount(self) -> None: """Event handler called when widget is added to the app.""" self.update_timer = self.set_interval(1 / 60, self.update_time, pause=True) def update_time(self) -> None: """Method to update time to current.""" self.time = self.total + (monotonic() - self.start_time) def watch_time(self, time: float) -> None: """Called when the time attribute changes.""" minutes, seconds = divmod(time, 60) hours, minutes = divmod(minutes, 60) self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}") def start(self) -> None: """Method to start (or resume) time updating.""" self.start_time = monotonic() self.update_timer.resume() def stop(self) -> None: """Method to stop the time display updating.""" self.update_timer.pause() self.total += monotonic() - self.start_time self.time = self.total def reset(self) -> None: """Method to reset the time display to zero.""" self.total = 0 self.time = 0 class Stopwatch(Static): """A stopwatch widget.""" def on_button_pressed(self, event: Button.Pressed) -> None: """Event handler called when a button is pressed.""" button_id = event.button.id time_display = self.query_one(TimeDisplay) if button_id == "start": time_display.start() self.add_class("started") elif button_id == "stop": time_display.stop() self.remove_class("started") elif button_id == "reset": time_display.reset() def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay() class StopwatchApp(App): """A Textual app to manage stopwatches.""" CSS_PATH = "stopwatch04.tcss" BINDINGS = [("d", "toggle_dark", "Toggle dark mode")] def compose(self) -> ComposeResult: """Called to add widgets to the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch()) def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Вот какие изменения сделаны в <code>TimeDisplay</code>. <ul><li>Мы добавили реактивный атрибут <code>total</code>, который хранит общее время, прошедшее между нажатиями на кнопки старта и останова.</li> <li>В вызов <code>set_interval</code> добавился аргумент <code>pause=True</code>, который запускает таймер в режиме паузы (когда таймер на паузе, он не идёт, пока не будет вызван метод resume ()). Это потому, что мы не хотим, чтобы время обновлялось, пока пользователь не нажмёт кнопку старта.</li> <li>Метод <code>update_time</code> теперь добавляет total к текущему времени, чтобы учесть время между любыми предыдущими нажатиями на кнопки старта и останова.</li> <li>Мы сохранили результат <code>set_interval</code>, который возвращает объект таймера. Позднее мы используем его, чтобы продолжить работу таймера при следующем запуске секундомера.</li> <li>Мы добавили методы <code>start()</code>, <code>stop()</code> и <code>reset()</code>.</li> </ul> Дополнительно к методу <code>on_button_pressed</code> класса <code>Stopwatch</code> добавилось немного кода для управления отображением времени, когда пользователь нажимает кнопку. Рассмотрим его подробнее: <pre><code class="python"> def on_button_pressed(self, event: Button.Pressed) -> None: """Event handler called when a button is pressed.""" button_id = event.button.id time_display = self.query_one(TimeDisplay) if button_id == "start": time_display.start() self.add_class("started") elif button_id == "stop": time_display.stop() self.remove_class("started") elif button_id == "reset": time_display.reset()</code></pre> Этот код добавляет отсутствовавшие функции и делает наше приложение полезным. Мы сделали следующие изменения. <ul><li>Первая строка получает <code>id</code> нажатой кнопки. Мы можем использовать его, чтобы определить, что именно делать.</li> <li>Вторая строка вызывает <code>query_one</code>, чтобы получить ссылку на виджет <code>TimeDisplay</code>.</li> <li>Мы вызываем метод <code>TimeDisplay</code>, соответствующий нажатой кнопке.</li> <li>Мы добавляем класс <code>"started"</code>, если секундомер запущен (<code>self.add_class("started")</code>), и удаляем его (<code>self.remove_class("started")</code>), если он остановлен. Это обновляет внешний вид секундомера через CSS.</li> </ul> Если вы запустите <code>stopwatch06.py</code>, то сможете использовать секундомеры независимо. <img src="https://habrastorage.org/r/w1560/webt/m9/jg/hs/m9jghsp3t1ebxpvafcadtgeo-9a.png" alt="m9jghsp3t1ebxpvafcadtgeo-9a.png" /> Единственное, что нам осталось реализовать, это возможность добавлять и удалять секундомеры. Приложение Stopwatch создаёт виджеты при запуске через метод <code>compose</code>. Нам также понадобится создавать новые виджеты во время работы приложения и удалять их, когда они больше не нужны. Это можно сделать, вызвав mount (), чтобы добавить виджет и remove (), чтобы убрать его. Давайте воспользуемся этими методами, чтобы реализовать добавление и удаление секундомеров в нашем приложении. <code>stopwatch.py</code> <pre><code class="python">from time import monotonic from textual.app import App, ComposeResult from textual.containers import ScrollableContainer from textual.reactive import reactive from textual.widgets import Button, Footer, Header, Static class TimeDisplay(Static): """A widget to display elapsed time.""" start_time = reactive(monotonic) time = reactive(0.0) total = reactive(0.0) def on_mount(self) -> None: """Event handler called when widget is added to the app.""" self.update_timer = self.set_interval(1 / 60, self.update_time, pause=True) def update_time(self) -> None: """Method to update time to current.""" self.time = self.total + (monotonic() - self.start_time) def watch_time(self, time: float) -> None: """Called when the time attribute changes.""" minutes, seconds = divmod(time, 60) hours, minutes = divmod(minutes, 60) self.update(f"{hours:02,.0f}:{minutes:02.0f}:{seconds:05.2f}") def start(self) -> None: """Method to start (or resume) time updating.""" self.start_time = monotonic() self.update_timer.resume() def stop(self): """Method to stop the time display updating.""" self.update_timer.pause() self.total += monotonic() - self.start_time self.time = self.total def reset(self): """Method to reset the time display to zero.""" self.total = 0 self.time = 0 class Stopwatch(Static): """A stopwatch widget.""" def on_button_pressed(self, event: Button.Pressed) -> None: """Event handler called when a button is pressed.""" button_id = event.button.id time_display = self.query_one(TimeDisplay) if button_id == "start": time_display.start() self.add_class("started") elif button_id == "stop": time_display.stop() self.remove_class("started") elif button_id == "reset": time_display.reset() def compose(self) -> ComposeResult: """Create child widgets of a stopwatch.""" yield Button("Start", id="start", variant="success") yield Button("Stop", id="stop", variant="error") yield Button("Reset", id="reset") yield TimeDisplay() class StopwatchApp(App): """A Textual app to manage stopwatches.""" CSS_PATH = "stopwatch.tcss" BINDINGS = [ ("d", "toggle_dark", "Toggle dark mode"), ("a", "add_stopwatch", "Add"), ("r", "remove_stopwatch", "Remove"), ] def compose(self) -> ComposeResult: """Called to add widgets to the app.""" yield Header() yield Footer() yield ScrollableContainer(Stopwatch(), Stopwatch(), Stopwatch(), id="timers") def action_add_stopwatch(self) -> None: """An action to add a timer.""" new_stopwatch = Stopwatch() self.query_one("#timers").mount(new_stopwatch) new_stopwatch.scroll_visible() def action_remove_stopwatch(self) -> None: """Called to remove a timer.""" timers = self.query("Stopwatch") if timers: timers.last().remove() def action_toggle_dark(self) -> None: """An action to toggle dark mode.""" self.dark = not self.dark if __name__ == "__main__": app = StopwatchApp() app.run()</code></pre> Вот суть изменений: <ul><li>У объекта <code>ScrollableContainer</code> в <code>StopWatchApp</code> добавился id <code>"timers"</code>.</li> <li>Добавлен метод <code>action_add_stopwatch</code> для добавления нового секундомера.</li> <li>Добавлен метод <code>action_remove_stopwatch</code> для удаления секундомера.</li> <li>Добавлена привязка горячих клавиш для этих действий.</li> </ul> Метод <code>action_add_stopwatch</code> создаёт и монтирует новый секундомер. Обратите внимание на вызов query_one () с CSS-селектором <code>"#timers"</code>, который возвращает контейнер таймеров по его ID. После монтирования новый секундомер появится в терминале. Последняя строчка в <code>action_add_stopwatch</code> вызывает scroll_visible (), который прокручивает контейнер так, чтобы сделать новый <code>Stopwatch</code> видимым (если нужно). Функция <code>action_remove_stopwatch</code> вызывает query () с CSS-селектором <code>"Stopwatch"</code>, который возвращает все виджеты Stopwatch. Если они есть, то вызывается last () для получения последнего секундомера и remove () для его удаления. Если вы запустите <code>stopwatch.py</code>, то сможете добавлять новые секундомеры клавишей <code>A</code> и удалять их клавишей <code>R</code>. <img src="https://habrastorage.org/r/w1560/webt/oy/ak/ir/oyakirqa95qenbywdceuv-rkkb8.png" alt="oyakirqa95qenbywdceuv-rkkb8.png" /> Поздравляем вас с созданием первого приложения на Textual! В этом руководстве было рассмотрено много нового. Если вы относитесь к тому типу людей, которые предпочитают изучать фреймворк с помощью программирования, не стесняйтесь. Можете доработать <code>stopwatch.py</code> или просмотреть примеры. Прочтите руководство для получения полной информации о том, как создавать сложные приложения TUI с помощью Textual. © <a target="_blank" rel="nofollow" href="https://habr.com/ru/articles/774254/?utm_source=habrahabr&amp;utm_medium=rss&amp;utm_campaign=774254">Habrahabr.ru</a> </div>  <div style="padding-left: 20px;"> <script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-2514821055276660" crossorigin="anonymous"></script>  <ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-2514821055276660" data-ad-slot="1200562049" data-ad-format="auto"></ins> <script> (adsbygoogle = window.adsbygoogle || []).push({}); </script> </div>  <noindex> <div style="margin: 25px;" id="disqus_thread"></div> <script type="text/javascript"> var disqus_shortname = 'pcnewsru'; var disqus_identifier = '1306392'; var disqus_title = '[Перевод] Учебное пособие по Textual'; var disqus_url = 'http://pcnews.ru/blogs/%5Bperevod%5D_ucebnoe_posobie_po_textual-1306392.html'; (function() { var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); })(); </script>   </noindex> </div> </div> <div id="footer-2nd"></div> <div id="footer"> <ul class="horz-menu"> <li class="about"><a href="/info/about.html" title="О проекте">О проекте</a></li> <li class="additional-menu"><a href="/archive.html" title="Архив материалов">Архив</a> </li> <li class="additional-menu"><a href="/info/reklama.html" title="Реклама" class="menu-item">Реклама</a> <a href="/info/partners.html" title="Партнёры" class="menu-item">Партнёры</a> <a href="/info/legal.html" title="Правовая информация" class="menu-item">Правовая информация</a> <a href="/info/contacts.html" title="Контакты" class="menu-item">Контакты</a> <a href="/feedback.html" title="Обратная связь" class="menu-item">Обратная связь</a></li> <li class="email"><a href="mailto:pcnews@pcnews.ru" title="Пишите нам на pcnews@pcnews.ru"><img src="/media/i/email.gif" alt="e-mail"/></a></li> <li style="visibility: hidden"> <noindex>  <script type="text/javascript"> var _tmr = window._tmr || (window._tmr = []); _tmr.push({id: "93125", type: "pageView", start: (new Date()).getTime()}); (function (d, w, id) { if (d.getElementById(id)) return; var ts = d.createElement("script"); ts.type = "text/javascript"; ts.async = true; ts.id = id; ts.src = (d.location.protocol == "https:" ? "https:" : "http:") + "//top-fwz1.mail.ru/js/code.js"; var f = function () { var s = d.getElementsByTagName("script")[0]; s.parentNode.insertBefore(ts, s); }; if (w.opera == "[object Opera]") { d.addEventListener("DOMContentLoaded", f, false); } else { f(); } })(document, window, "topmailru-code"); </script> <noscript> <div style="position:absolute;left:-10000px;"> <img src="//top-fwz1.mail.ru/counter?id=93125;js=na" style="border:0;" height="1" width="1" alt="Рейтинг@Mail.ru"/> </div> </noscript>  </noindex> </li> </ul> </div> <!--[if lte IE 7]> <iframe id="popup-iframe" frameborder="0" scrolling="no">