docstring for log

docs/guide/devtools.md

@@ -47,5 +47,5 @@ In the other console, run your application using `textual run` and the `--dev` s
 textual run --dev my_app.py
 ```
 
-Anything you `print` from your application will be displayed in the console window. You can also call the `log()` method on App and Widget objects for advanced formatting. Try it with `self.log(self.tree)`.
+Anything you `print` from your application will be displayed in the console window. You can also call the [`log()`][textual.message_pump.MessagePump.log] method on App and Widget objects for advanced formatting. Try it with `self.log(self.tree)`.
 

src/textual/app.py

@@ -487,13 +487,20 @@ class App(Generic[ReturnType], DOMNode):
         _textual_calling_frame: inspect.FrameInfo | None = None,
         **kwargs,
     ) -> None:
-        """Write to logs.
+        """Write to logs or devtools.
+
+        Positional args will logged. Keyword args will be prefixed with the key.
+
+        Example:
+            ```python
+            data = [1,2,3]
+            self.log("Hello, World", state=data)
+            self.log(self.tree)
+            self.log(locals())
+            ```
 
         Args:
-            *objects (Any): Positional arguments are converted to string and written to logs.
             verbosity (int, optional): Verbosity level 0-3. Defaults to 1.
-            _textual_calling_frame (inspect.FrameInfo | None): The frame info to include in
-                the log message sent to the devtools server.
         """
         if verbosity > self.log_verbosity:
             return

src/textual/message_pump.py

@@ -110,9 +110,33 @@ class MessagePump(metaclass=MessagePumpMeta):
     def is_running(self) -> bool:
         return self._running
 
-    def log(self, *args, **kwargs) -> None:
-        """Write to logs or devtools."""
-        return self.app.log(*args, **kwargs, _textual_calling_frame=inspect.stack()[1])
+    def log(
+        self,
+        *args: Any,
+        verbosity: int = 1,
+        **kwargs,
+    ) -> None:
+        """Write to logs or devtools.
+
+        Positional args will logged. Keyword args will be prefixed with the key.
+
+        Example:
+            ```python
+            data = [1,2,3]
+            self.log("Hello, World", state=data)
+            self.log(self.tree)
+            self.log(locals())
+            ```
+
+        Args:
+            verbosity (int, optional): Verbosity level 0-3. Defaults to 1.
+        """
+        return self.app.log(
+            *args,
+            **kwargs,
+            verbosity=verbosity,
+            _textual_calling_frame=inspect.stack()[1],
+        )
 
     def _attach(self, parent: MessagePump) -> None:
         """Set the parent, and therefore attach this node to the tree.