Open url (#4819)

* Local open url

* Open URL via driver

* Writing meta to open url

* Some docstrings and typing

* Update docstring

* Update docstring in app.py

* CHANGELOG

* Allow opening URL in a new tab

* No errors from App.open_url

* Keyword only new_tab argument in App.open_url

Author: darrenburns

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Added `App.open_url` to open URLs in the web browser. When running via the WebDriver, the URL will be opened in the browser that is controlling the app https://github.com/Textualize/textual/pull/4819
 - Added `Widget.is_mouse_over` https://github.com/Textualize/textual/pull/4818
 - Added `node` attribute to `events.Enter` and `events.Leave` https://github.com/Textualize/textual/pull/4818
 

src/textual/app.py

@@ -3679,3 +3679,13 @@ def action_suspend_process(self) -> None:
             # NOTE: There is no call to publish the resume signal here, this
             # will be handled by the driver posting a SignalResume event
             # (see the event handler on App._resume_signal) above.
+
+    def open_url(self, url: str, *, new_tab: bool = True) -> None:
+        """Open a URL in the default web browser.
+
+        Args:
+            url: The URL to open.
+            new_tab: Whether to open the URL in a new tab.
+        """
+        if self._driver is not None:
+            self._driver.open_url(url, new_tab)

src/textual/driver.py

@@ -3,7 +3,7 @@
 import asyncio
 from abc import ABC, abstractmethod
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Iterator
+from typing import TYPE_CHECKING, Any, Iterator
 
 from . import events
 from .events import MouseUp
@@ -17,7 +17,7 @@ class Driver(ABC):
 
     def __init__(
         self,
-        app: App,
+        app: App[Any],
         *,
         debug: bool = False,
         mouse: bool = True,
@@ -146,6 +146,19 @@ def disable_input(self) -> None:
     def stop_application_mode(self) -> None:
         """Stop application mode, restore state."""
 
+    def open_url(self, url: str, new_tab: bool = True) -> None:
+        """Open a URL in the default web browser.
+
+        Args:
+            url: The URL to open.
+            new_tab: Whether to open the URL in a new tab.
+                This is only relevant when running via the WebDriver,
+                and is ignored when called while running through the terminal.
+        """
+        import webbrowser
+
+        webbrowser.open(url)
+
     def suspend_application_mode(self) -> None:
         """Suspend application mode.
 

src/textual/drivers/web_driver.py

@@ -19,6 +19,7 @@
 from codecs import getincrementaldecoder
 from functools import partial
 from threading import Event, Thread
+from typing import Any
 
 from .. import events, log, messages
 from .._xterm_parser import XTermParser
@@ -40,7 +41,7 @@ class WebDriver(Driver):
 
     def __init__(
         self,
-        app: App,
+        app: App[Any],
         *,
         debug: bool = False,
         mouse: bool = True,
@@ -63,7 +64,8 @@ def __init__(
         self._input_reader = InputReader()
 
     def write(self, data: str) -> None:
-        """Write data to the output device.
+        """Write string data to the output device, which may be piped to
+        the controlling process (i.e. textual-web).
 
         Args:
             data: Raw data.
@@ -73,7 +75,8 @@ def write(self, data: str) -> None:
         self._write(b"D%s%s" % (len(data_bytes).to_bytes(4, "big"), data_bytes))
 
     def write_meta(self, data: dict[str, object]) -> None:
-        """Write meta to the controlling process (i.e. textual-web)
+        """Write a dictionary containing some metadata to stdout, which
+        may be piped to the controlling process (i.e. textual-web).
 
         Args:
             data: Meta dict.
@@ -192,13 +195,17 @@ def _on_meta(self, packet_type: str, payload: bytes) -> None:
             packet_type: Packet type (currently always "M")
             payload: Meta payload (JSON encoded as bytes).
         """
-        payload_map = json.loads(payload)
+        payload_map: dict[str, object] = json.loads(payload)
         _type = payload_map.get("type", {})
-        if isinstance(payload_map, dict):
+        if isinstance(_type, str):
             self.on_meta(_type, payload_map)
+        else:
+            log.error(
+                f"Protocol error: type field value is not a string. Value is {_type!r}"
+            )
 
-    def on_meta(self, packet_type: str, payload: dict) -> None:
-        """Process meta information.
+    def on_meta(self, packet_type: str, payload: dict[str, object]) -> None:
+        """Process a dictionary containing information received from the controlling process.
 
         Args:
             packet_type: The type of the packet.
@@ -216,3 +223,12 @@ def on_meta(self, packet_type: str, payload: dict) -> None:
             self._app.post_message(messages.ExitApp())
         elif packet_type == "exit":
             raise _ExitInput()
+
+    def open_url(self, url: str, new_tab: bool = True) -> None:
+        """Open a URL in the default web browser.
+
+        Args:
+            url: The URL to open.
+            new_tab: Whether to open the URL in a new tab.
+        """
+        self.write_meta({"type": "open_url", "url": url, "new_tab": new_tab})