Merge branch 'main' into unmount

Author: willmcgugan

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,6 +7,8 @@ assignees: ''
 
 ---
 
-Textual is currently in active development. I will try to keep the sample functional, but I make no guarantee anything will run right now.
+Please give a brief but clear explanation of what the issue is. Let us know what the behaviour you expect is, and what is actually happening. Let us know what operating system you are running on, and what terminal you are using.
 
-Unless this is a blatant bug, you might want to open a discussion for now.
+Feel free to add screenshots and/or videos. These can be very helpful!
+
+If you can, include a complete working example that demonstrates the bug. Please check it can run without modifications.

.github/workflows/pythonpackage.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
     defaults:
       run:
         shell: bash
@@ -20,9 +20,9 @@ jobs:
           python-version: ${{ matrix.python-version }}
           architecture: x64
       - name: Install and configure Poetry
-        uses: snok/install-poetry@v1.1.6
+        uses: snok/install-poetry@v1.3.3
         with:
-          version: 1.1.6
+          version: 1.2.2
           virtualenvs-in-project: true
       - name: Install dependencies
         run: poetry install --extras "dev"

.gitignore

@@ -116,3 +116,6 @@ venv.bak/
 
 # Snapshot testing report output directory
 tests/snapshot_tests/output
+
+# Sandbox folder - convenient place for us to develop small test apps without leaving the repo
+sandbox/

docs/examples/tutorial/stopwatch03.css

@@ -2,8 +2,9 @@ Stopwatch {
     layout: horizontal;
     background: $boost;
     height: 5;
-    padding: 1;
     margin: 1;
+    min-width: 50;
+    padding: 1;
 }
 
 TimeDisplay {

docs/examples/tutorial/stopwatch04.css

@@ -2,8 +2,8 @@ Stopwatch {
     layout: horizontal;
     background: $boost;
     height: 5;
-    min-width: 50;
     margin: 1;
+    min-width: 50;
     padding: 1;
 }
 

docs/examples/widgets/data_table.py

@@ -26,4 +26,6 @@ def on_mount(self) -> None:
         table.add_rows(rows)
 
 
-app = TableApp()
+if __name__ == "__main__":
+    app = TableApp()
+    app.run()

docs/guide/devtools.md

@@ -44,7 +44,7 @@ If you combine the `run` command with the `--dev` switch your app will run in *d
 textual run --dev my_app.py
 ```
 
-One of the the features of *dev* mode is live editing of CSS files: any changes to your CSS will be reflected in the terminal a few milliseconds later.
+One of the features of *dev* mode is live editing of CSS files: any changes to your CSS will be reflected in the terminal a few milliseconds later.
 
 This is a great feature for iterating on your app's look and feel. Open the CSS in your editor and have your app running in a terminal. Edits to your CSS will appear almost immediately after you save.
 

docs/guide/events.md

@@ -4,15 +4,15 @@ We've used event handler methods in many of the examples in this guide. This cha
 
 ## Messages
 
-Events are a particular kind of *message* sent by Textual in response to input and other state changes. Events are reserved for use by Textual but you can also create custom messages for the purpose of coordinating between widgets in your app.
+Events are a particular kind of *message* sent by Textual in response to input and other state changes. Events are reserved for use by Textual, but you can also create custom messages for the purpose of coordinating between widgets in your app.
 
 More on that later, but for now keep in mind that events are also messages, and anything that is true of messages is true of events.
 
 ## Message Queue
 
 Every [App][textual.app.App] and [Widget][textual.widget.Widget] object contains a *message queue*. You can think of a message queue as orders at a restaurant. The chef takes an order and makes the dish. Orders that arrive while the chef is cooking are placed in a line. When the chef has finished a dish they pick up the next order in the line.
 
-Textual processes messages in the same way. Messages are picked off a queue and processed (cooked) by a handler method. This guarantees messages and events are processed even if your code can not handle them right way.
+Textual processes messages in the same way. Messages are picked off a queue and processed (cooked) by a handler method. This guarantees messages and events are processed even if your code can not handle them right away.
 
 This processing of messages is done within an asyncio Task which is started when you mount the widget. The task monitors a queue for new messages and dispatches them to the appropriate handler when they arrive.
 
@@ -28,7 +28,7 @@ The widget's task will pick the first message from the queue (a key event for th
 --8<-- "docs/images/events/queue.excalidraw.svg"
 </div>
 
-When the `on_key` method returns, Textual will get the next event from the the queue and repeat the process for the remaining keys. At some point the queue will be empty and the widget is said to be in an *idle* state.
+When the `on_key` method returns, Textual will get the next event from the queue and repeat the process for the remaining keys. At some point the queue will be empty and the widget is said to be in an *idle* state.
 
 !!! note
 
@@ -75,7 +75,7 @@ As before, the event bubbles to its parent (the App class).
 --8<-- "docs/images/events/bubble3.excalidraw.svg"
 </div>
 
-The App class is always the root of the DOM, so there is no where for the event to bubble to.
+The App class is always the root of the DOM, so there is nowhere for the event to bubble to.
 
 ### Stopping bubbling
 
@@ -110,7 +110,7 @@ The message class is defined within the widget class itself. This is not strictl
 
 ## Sending events
 
-In the previous example we used [emit()][textual.message_pump.MessagePump.emit] to send an event to it's parent. We could also have used [emit_no_wait()][textual.message_pump.MessagePump.emit_no_wait] for non async code. Sending messages in this way allows you to write custom widgets without needing to know in what context they will be used.
+In the previous example we used [emit()][textual.message_pump.MessagePump.emit] to send an event to its parent. We could also have used [emit_no_wait()][textual.message_pump.MessagePump.emit_no_wait] for non async code. Sending messages in this way allows you to write custom widgets without needing to know in what context they will be used.
 
 There are other ways of sending (posting) messages, which you may need to use less frequently.
 
@@ -127,7 +127,7 @@ Most of the logic in a Textual app will be written in message handlers. Let's ex
 Textual uses the following scheme to map messages classes on to a Python method.
 
 - Start with `"on_"`.
-- Add the messages namespace (if any) converted from CamelCase to snake_case plus an underscore `"_"`
+- Add the messages' namespace (if any) converted from CamelCase to snake_case plus an underscore `"_"`
 - Add the name of the class converted from CamelCase to snake_case.
 
 <div class="excalidraw">
@@ -156,7 +156,7 @@ This pattern is a convenience that saves writing out a parameter that may not be
 
 Message handlers may be coroutines. If you prefix your handlers with the `async` keyword, Textual will `await` them. This lets your handler use the `await` keyword for asynchronous APIs.
 
-If your event handlers are coroutines it will allow multiple events to be processed concurrently, but bear in mind an individual widget (or app) will not be able to pick up a new message from its message queue until the handler has returned. This is rarely a problem in practice; as long has handlers return within a few milliseconds the UI will remain responsive. But slow handlers might make your app hard to use.
+If your event handlers are coroutines it will allow multiple events to be processed concurrently, but bear in mind an individual widget (or app) will not be able to pick up a new message from its message queue until the handler has returned. This is rarely a problem in practice; as long as handlers return within a few milliseconds the UI will remain responsive. But slow handlers might make your app hard to use.
 
 !!! info
 

docs/guide/reactivity.md

@@ -165,7 +165,11 @@ If you click the buttons in the above example it will show the current count. Wh
 
 ## Watch methods
 
-Watch methods are another superpower. Textual will call watch methods when reactive attributes are modified. Watch methods begin with `watch_` followed by the name of the attribute. If the watch method accepts a positional argument, it will be called with the new assigned value. If the watch method accepts *two* positional arguments, it will be called with both the *old* value and the *new* value.
+Watch methods are another superpower.
+Textual will call watch methods when reactive attributes are modified.
+Watch methods begin with `watch_` followed by the name of the attribute.
+If the watch method accepts a positional argument, it will be called with the new assigned value.
+If the watch method accepts *two* positional arguments, it will be called with both the *old* value and the *new* value.
 
 The following app will display any color you type in to the input. Try it with a valid color in Textual CSS. For example `"darkorchid"` or `"#52de44"`.
 
@@ -192,6 +196,12 @@ The following app will display any color you type in to the input. Try it with a
 
 The color is parsed in `on_input_submitted` and assigned to `self.color`. Because `color` is reactive, Textual also calls `watch_color` with the old and new values.
 
+### When are watch methods called?
+
+Textual only calls watch methods if the value of a reactive attribute _changes_.
+If the newly assigned value is the same as the previous value, the watch method is not called.
+You can override this behaviour by passing `always_update=True` to `reactive`.
+
 ## Compute methods
 
 Compute methods are the final superpower offered by the `reactive` descriptor. Textual runs compute methods to calculate the value of a reactive attribute. Compute methods begin with `compute_` followed by the name of the reactive value.

docs/tutorial.md

@@ -108,7 +108,7 @@ Let's examine `stopwatch01.py` in more detail.
 --8<-- "docs/examples/tutorial/stopwatch01.py"
 ```
 
-The first line imports the Textual `App` class, which we will use as the base class for our App. The second line imports two builtin widgets: `Footer` which shows a bar at the bottom of the screen with current keys, and `Header` which shows a title and the current time at the top of the screen. Widgets are re-usable components responsible for managing a part of the screen. We will cover how to build widgets in this tutorial.
+The first line imports the Textual `App` class, which we will use as the base class for our App. The second line imports two builtin widgets: `Footer` which shows a bar at the bottom of the screen with bound keys, and `Header` which shows a title at the top of the screen. Widgets are re-usable components responsible for managing a part of the screen. We will cover how to build widgets in this tutorial.
 
 The following lines define the app itself:
 
@@ -165,7 +165,7 @@ The Stopwatch widget class also extends `Static`. This class has a `compose()` m
 
 #### The buttons
 
-The Button constructor takes a label to be displayed in the button (`"Start"`, `"Stop"`, or `"Reset"`). Additionally some of the buttons set the following parameters:
+The Button constructor takes a label to be displayed in the button (`"Start"`, `"Stop"`, or `"Reset"`). Additionally, some of the buttons set the following parameters:
 
 - `id` is an identifier we can use to tell the buttons apart in code and apply styles. More on that later.
 - `variant` is a string which selects a default style. The "success" variant makes the button green, and the "error" variant makes it red.
@@ -233,8 +233,9 @@ Stopwatch {
     layout: horizontal;
     background: $boost;
     height: 5;
-    padding: 1;
     margin: 1;
+    min-width: 50;
+    padding: 1;
 }
 ```
 
@@ -249,8 +250,9 @@ Here's how this CSS code changes how the `Stopwatch` widget is displayed.
 - `layout: horizontal` aligns child widgets horizontally from left to right.
 - `background: $boost` sets the background color to `$boost`. The `$` prefix picks a pre-defined color from the builtin theme. There are other ways to specify colors such as `"blue"` or `rgb(20,46,210)`.
 - `height: 5` sets the height of our widget to 5 lines of text.
-- `padding: 1` sets a padding of 1 cell around the child widgets.
 - `margin: 1` sets a margin of 1 cell around the `Stopwatch` widget to create a little space between widgets in the list.
+- `min-width: 50` sets the minimum width of our widget to 50 cells.
+- `padding: 1` sets a padding of 1 cell around the child widgets.
 
 
 Here's the rest of `stopwatch03.css` which contains further declaration blocks:
@@ -288,7 +290,7 @@ The last 3 blocks have a slightly different format. When the declaration begins
 
 The buttons have a `dock` style which aligns the widget to a given edge. The start and stop buttons are docked to the left edge, while the reset button is docked to the right edge.
 
-You may have noticed that the stop button (`#stop` in the CSS) has `display: none;`. This tells Textual to not show the button. We do this because we don't want to display the stop button when the timer is *not* running. Similarly we don't want to show the start button when the timer is running. We will cover how to manage such dynamic user interfaces in the next section.
+You may have noticed that the stop button (`#stop` in the CSS) has `display: none;`. This tells Textual to not show the button. We do this because we don't want to display the stop button when the timer is *not* running. Similarly, we don't want to show the start button when the timer is running. We will cover how to manage such dynamic user interfaces in the next section.
 
 ### Dynamic CSS
 
@@ -333,7 +335,7 @@ The following code will start or stop the stopwatches in response to clicking a
 --8<-- "docs/examples/tutorial/stopwatch04.py"
 ```
 
-The `on_button_pressed` method is an *event handler*. Event handlers are methods called by Textual in response to an *event* such as a key press, mouse click, etc. Event handlers begin with `on_` followed by the name of the event they will handler. Hence `on_button_pressed` will handle the button pressed event.
+The `on_button_pressed` method is an *event handler*. Event handlers are methods called by Textual in response to an *event* such as a key press, mouse click, etc. Event handlers begin with `on_` followed by the name of the event they will handle. Hence `on_button_pressed` will handle the button pressed event.
 
 If you run `stopwatch04.py` now you will be able to toggle between the two states by clicking the first button: