From 7c696ce3785276ca5ffddf344ba0020900fb57d0 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Fri, 28 Apr 2023 10:47:24 +0100 Subject: [PATCH] Updated docs for app.run (#2414) * fix run app from python * updated run * remove function * update help * doc update --- CHANGELOG.md | 6 ++++++ docs/guide/devtools.md | 35 +++++++++++++++++++++++++++++------ src/textual/cli/_run.py | 28 +++++----------------------- src/textual/cli/cli.py | 10 +++++----- src/textual/widgets/_tabs.py | 4 +++- 5 files changed, 48 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ead1b47ff..12913fd3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/). +## [0.22.1] - 2023-04-28 + +### Fixed + +- Fixed `textual run` issue https://github.com/Textualize/textual/issues/2391 + ## [0.22.0] - 2023-04-27 ### Fixed diff --git a/docs/guide/devtools.md b/docs/guide/devtools.md index 4fbffe6cb..25138aa69 100644 --- a/docs/guide/devtools.md +++ b/docs/guide/devtools.md @@ -8,7 +8,7 @@ Textual comes with a command line application of the same name. The `textual` command is a super useful tool that will help you to build apps. -Take a moment to look through the available sub-commands. There will be even more helpful tools here in the future. +Take a moment to look through the available subcommands. There will be even more helpful tools here in the future. ```bash textual --help @@ -17,25 +17,48 @@ textual --help ## Run -You can run Textual apps with the `run` subcommand. If you supply a path to a Python file it will load and run the application. +The `run` sub-command runs Textual apps. If you supply a path to a Python file it will load and run the app. ```bash textual run my_app.py ``` -The `run` sub-command will first look for a `App` instance called `app` in the global scope of your Python file. If there is no `app`, it will create an instance of the first `App` class it finds and run that. +This is equivalent to running `python my_app.py` from the command prompt, but will allow you to set various switches which can help you debug, such as `--dev` which enable the [Console](#console). -Alternatively, you can add the name of an `App` instance or class after a colon to run a specific app in the Python file. Here's an example: +See the `run` subcommand's help for details: ```bash -textual run my_app.py:alternative_app +textual run --help +``` + +You can also run Textual apps from a python import. +The following command would import `music.play` and run a Textual app in that module: + +```bash +textual run music.play +``` + +This assumes you have a Textual app instance called `app` in `music.play`. +If your app has a different name, you can append it after a colon: + +```bash +textual run music.play:MusicPlayerApp ``` !!! note - If the Python file contains a call to app.run() then you can launch the file as you normally would any other Python program. Running your app via `textual run` will give you access to a few Textual features such as live editing of CSS files. + This works for both Textual app *instances* and *classes*. +### Running from commands + +If your app is installed as a command line script, you can use the `-c` switch to run it. +For instance, the following will run the `textual colors` command: + +```bash +textual run -c textual colors +``` + ## Live editing If you combine the `run` command with the `--dev` switch your app will run in *development mode*. diff --git a/src/textual/cli/_run.py b/src/textual/cli/_run.py index 782df6c17..dc6c835b3 100644 --- a/src/textual/cli/_run.py +++ b/src/textual/cli/_run.py @@ -17,7 +17,11 @@ from typing import NoReturn, Sequence EXEC_SCRIPT = Template( """\ from textual.app import App -from $MODULE import $APP as app; +try: + from $MODULE import $APP as app; +except ImportError: + raise SystemExit("Unable to import '$APP' from module '$MODULE'") from None + if isinstance(app, App): # If we imported an app, run it app.run() @@ -111,25 +115,6 @@ def exec_command( os.execvpe(command, [command, *args], environment) -def check_import(module_name: str, app_name: str) -> bool: - """Check if a symbol can be imported. - - Args: - module_name: Name of the module - app_name: Name of the app. - - Returns: - True if the app may be imported from the module. - """ - - try: - sys.path.insert(0, "") - module = importlib.import_module(module_name) - except ImportError as error: - return False - return hasattr(module, app_name) - - def exec_import( import_name: str, args: Sequence[str], environment: dict[str, str] ) -> NoReturn: @@ -147,9 +132,6 @@ def exec_import( module, _colon, app = import_name.partition(":") app = app or "app" - if not check_import(module, app): - raise ExecImportError(f"Unable to import {app!r} from {import_name!r}") - script = EXEC_SCRIPT.substitute(MODULE=module, APP=app) # Compiling the script will raise a SyntaxError if there are any invalid symbols compile(script, "textual-exec", "exec") diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py index cdc8e949c..0c66cf596 100644 --- a/src/textual/cli/cli.py +++ b/src/textual/cli/cli.py @@ -147,16 +147,16 @@ def _run_app( ) -> None: """Run a Textual app. - The code to run may be given as a path (ending with .py) or as a Python - import, which will load the code and run an app called "app". You may optionally - add a colon plus the class or class instance you want to run. + The app to run may be given as a path (ending with .py) which will be equivalent to running the + script with python, or as a Python import which will import and run an app called "app". + + In the case of an import, you can import and run an alternative app by appending a colon followed + by the name of the app instance or class. Here are some examples: textual run foo.py - textual run foo.py:MyApp - textual run module.foo textual run module.foo:MyApp diff --git a/src/textual/widgets/_tabs.py b/src/textual/widgets/_tabs.py index acd7bce0f..0af93be65 100644 --- a/src/textual/widgets/_tabs.py +++ b/src/textual/widgets/_tabs.py @@ -404,7 +404,9 @@ class Tabs(Widget, can_focus=True): active_tab = self.query_one(f"#tabs-list > #{active}", Tab) self.query("#tabs-list > Tab.-active").remove_class("-active") active_tab.add_class("-active") - self._highlight_active(animate=previously_active != "") + self.call_after_refresh( + self._highlight_active, animate=previously_active != "" + ) self.post_message(self.TabActivated(self, active_tab)) else: underline = self.query_one(Underline)