Merge Console.print_box into Console.print method and modernize

HexDecimal · HexDecimal · commit 2e8efdd90fe7 · 2025-04-03T23:40:44.000-07:00
Changes are mostly backwards compatible expect for a slight change in
text placement.

Also update some old docs which were not using correct directives.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,17 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Changed
+
+- `Console.print` now accepts `height` and `width` keywords and has renamed `string` to `text`.
+- Text printed with `Console.print` using right-alignment has been shifted to the left by 1-tile.
+
+### Deprecated
+
+- Using `Console.print` without keywords for only the `x`, `y`, and `text` parameters has been deprecated.
+  The `string` parameter has been renamed to `text`.
+- `Console.print_box` has been replaced by `Console.print`.
+
 ## [17.1.0] - 2025-03-29
 
 ### Added
diff --git a/docs/tcod/getting-started.rst b/docs/tcod/getting-started.rst
@@ -19,7 +19,7 @@ console will be stretched to fit the window.  You can add arguments to
 :any:`Context.present` to fix the aspect ratio or only scale the console by
 integer increments.
 
-Example::
+.. code-block:: python
 
     #!/usr/bin/env python
     # Make sure 'dejavu10x10_gs_tc.png' is in the same directory as this script.
@@ -38,23 +38,24 @@ Example::
             "dejavu10x10_gs_tc.png", 32, 8, tcod.tileset.CHARMAP_TCOD,
         )
         # Create the main console.
-        console = tcod.console.Console(WIDTH, HEIGHT, order="F")
+        console = tcod.console.Console(WIDTH, HEIGHT)
         # Create a window based on this console and tileset.
         with tcod.context.new(  # New window for a console of size columns×rows.
             columns=console.width, rows=console.height, tileset=tileset,
         ) as context:
             while True:  # Main loop, runs until SystemExit is raised.
                 console.clear()
-                console.print(x=0, y=0, string="Hello World!")
+                console.print(x=0, y=0, text="Hello World!")
                 context.present(console)  # Show the console.
 
                 # This event loop will wait until at least one event is processed before exiting.
                 # For a non-blocking event loop replace `tcod.event.wait` with `tcod.event.get`.
                 for event in tcod.event.wait():
                     context.convert_event(event)  # Sets tile coordinates for mouse events.
                     print(event)  # Print event names and attributes.
-                    if isinstance(event, tcod.event.Quit):
-                        raise SystemExit()
+                    match event:
+                        case tcod.event.Quit():
+                            raise SystemExit()
             # The window will be closed after the above with-block exits.
 
 
@@ -87,7 +88,7 @@ You can call :any:`Context.new_console` every frame or only when the window
 is resized.  This example creates a new console every frame instead of
 clearing the console every frame and replacing it only on resizing the window.
 
-Example::
+.. code-block:: python
 
     #!/usr/bin/env python
     import tcod.context
@@ -103,17 +104,18 @@ Example::
             width=WIDTH, height=HEIGHT, sdl_window_flags=FLAGS
         ) as context:
             while True:
-                console = context.new_console(order="F")  # Console size based on window resolution and tile size.
+                console = context.new_console()  # Console size based on window resolution and tile size.
                 console.print(0, 0, "Hello World")
                 context.present(console, integer_scaling=True)
 
                 for event in tcod.event.wait():
-                    context.convert_event(event)  # Sets tile coordinates for mouse events.
+                    event = context.convert_event(event)  # Sets tile coordinates for mouse events.
                     print(event)  # Print event names and attributes.
-                    if isinstance(event, tcod.event.Quit):
-                        raise SystemExit()
-                    elif isinstance(event, tcod.event.WindowResized) and event.type == "WindowSizeChanged":
-                        pass  # The next call to context.new_console may return a different size.
+                    match event:
+                        case tcod.event.Quit():
+                            raise SystemExit()
+                        case tcod.event.WindowResized(type="WindowSizeChanged"):
+                            pass  # The next call to context.new_console may return a different size.
 
 
     if __name__ == "__main__":
diff --git a/tcod/console.py b/tcod/console.py
@@ -10,7 +10,7 @@
 import warnings
 from os import PathLike
 from pathlib import Path
-from typing import Any, Iterable
+from typing import Any, Iterable, overload
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
@@ -552,6 +552,7 @@ def __deprecate_defaults(  # noqa: C901, PLR0912
             stacklevel=3,
         )
 
+    @deprecated("Switch to using keywords and then replace with 'console.print(...)'")
     def print_(
         self,
         x: int,
@@ -579,6 +580,7 @@ def print_(
         alignment = self.default_alignment if alignment is None else alignment
         lib.TCOD_console_printf_ex(self.console_c, x, y, bg_blend, alignment, _fmt(string))
 
+    @deprecated("Switch to using keywords and then replace with 'console.print(...)'")
     def print_rect(  # noqa: PLR0913
         self,
         x: int,
@@ -973,55 +975,159 @@ def __str__(self) -> str:
         """Return a simplified representation of this consoles contents."""
         return "<{}>".format("\n ".join("".join(chr(c) for c in line) for line in self._tiles["ch"]))
 
+    @overload
+    @deprecated(
+        "Switch all parameters to keywords such as 'console.print(x=..., y=..., text=..., width=..., height=..., fg=..., bg=..., bg_blend=..., alignment=...)'"
+        "\n'string' keyword should be renamed to `text`"
+    )
+    def print(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        fg: tuple[int, int, int] | None = None,
+        bg: tuple[int, int, int] | None = None,
+        bg_blend: int = tcod.constants.BKGND_SET,
+        alignment: int = tcod.constants.LEFT,
+        *,
+        string: str = "",
+    ) -> int: ...
+
+    @overload
+    def print(
+        self,
+        x: int,
+        y: int,
+        text: str,
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        fg: tuple[int, int, int] | None = None,
+        bg: tuple[int, int, int] | None = None,
+        bg_blend: int = tcod.constants.BKGND_SET,
+        alignment: int = tcod.constants.LEFT,
+    ) -> int: ...
+
     def print(  # noqa: PLR0913
         self,
         x: int,
         y: int,
-        string: str,
+        text: str = "",
         fg: tuple[int, int, int] | None = None,
         bg: tuple[int, int, int] | None = None,
         bg_blend: int = tcod.constants.BKGND_SET,
         alignment: int = tcod.constants.LEFT,
-    ) -> None:
-        r"""Print a string on a console with manual line breaks.
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        string: str = "",
+    ) -> int:
+        r"""Print a string of Unicode text on this console.
 
-        `x` and `y` are the starting tile, with ``0,0`` as the upper-left
-        corner of the console.
+        Prefer using keywords for this method call to avoid ambiguous parameters.
 
-        `string` is a Unicode string which may include color control
-        characters.  Strings which are too long will be truncated until the
-        next newline character ``"\n"``.
+        Args:
+            x: Starting X coordinate, with the left-most tile as zero.
+            y: Starting Y coordinate, with the top-most tile as zero.
+            text: A Unicode string which may include color control characters.
+            width: Width in tiles to constrain the printing region.
+                If a `width` is given then `text` will have automatic word wrapping applied to it.
+                A `width` of `None` means `text` will only have manual line breaks.
+            height: Height in tiles to constrain the printing region.
+            fg: RGB tuple to use as the foreground color, or `None` to leave the foreground unchanged.
+                Tuple values should be 0-255.
+            bg: RGB tuple to use as the background color, or `None` to leave the foreground unchanged.
+                Tuple values should be 0-255.
+            bg_blend: Background blend type used by libtcod.
+                Typically starts with `libtcodpy.BKGND_*`.
+            alignment: One of `libtcodpy.LEFT`, `libtcodpy.CENTER`, or `libtcodpy.RIGHT`
+            string: Older deprecated name of the `text` parameter.
 
-        `fg` and `bg` are the foreground text color and background tile color
-        respectfully.  This is a 3-item tuple with (r, g, b) color values from
-        0 to 255.  These parameters can also be set to `None` to leave the
-        colors unchanged.
+        Returns:
+            The height of `text` in lines via word wrapping and line breaks.
 
-        `bg_blend` is the blend type used by libtcod.
+        Example::
 
-        `alignment` can be `tcod.LEFT`, `tcod.CENTER`, or `tcod.RIGHT`.
+            >>> from tcod import libtcodpy
+            >>> console = tcod.console.Console(20, 1)
+            >>> console.clear(ch=ord('·'))
+            >>> console.print(x=0, y=0, text="left")
+            1
+            >>> console.print(x=console.width, y=0, text="right", alignment=libtcodpy.RIGHT)
+            1
+            >>> console.print(x=10, y=0, text="center", alignment=libtcodpy.CENTER)
+            1
+            >>> print(console)
+            <left···center··right>
+
+            >>> console = tcod.console.Console(20, 4)
+            >>> console.clear(ch=ord('·'))
+            >>> console.print(x=1, y=1, text="words within bounds", width=8)
+            3
+            >>> print(console)
+            <····················
+             ·words··············
+             ·within·············
+             ·bounds·············>
+            >>> WHITE = (255, 255, 255)
+            >>> BLACK = (0, 0, 0)
+            >>> console.print(x=0, y=0, text="Black text on white background", fg=BLACK, bg=WHITE)
+            1
 
         .. versionadded:: 8.5
 
         .. versionchanged:: 9.0
+
             `fg` and `bg` now default to `None` instead of white-on-black.
 
         .. versionchanged:: 13.0
+
             `x` and `y` are now always used as an absolute position for negative values.
+
+        .. versionchanged:: Unreleased
+
+            Added `text` parameter to replace `string`.
+
+            Added `width` and `height` keyword parameters to bind text to a rectangle and replace other print functions.
+            Right-aligned text with `width=None` now treats the `x` coordinate as a past-the-end index, this will shift
+            the text of older calls to the left by 1 tile.
+
+            Now returns the number of lines printed via word wrapping.
         """
-        string_ = string.encode("utf-8")
-        lib.TCOD_console_printn(
-            self.console_c,
-            x,
-            y,
-            len(string_),
-            string_,
-            (fg,) if fg is not None else ffi.NULL,
-            (bg,) if bg is not None else ffi.NULL,
-            bg_blend,
-            alignment,
+        if width is not None and width <= 0:
+            return 0
+        if width is None and alignment == tcod.constants.LEFT:  # Fix alignment
+            width = 0x100000
+        if width is None and alignment == tcod.constants.CENTER:  # Fix center alignment
+            x -= 0x100000
+            width = 0x200000
+        if width is None and alignment == tcod.constants.RIGHT:  # Fix right alignment
+            x -= 0x100000
+            width = 0x100000
+        rgb_fg = ffi.new("TCOD_ColorRGB*", fg) if fg is not None else ffi.NULL
+        rgb_bg = ffi.new("TCOD_ColorRGB*", bg) if bg is not None else ffi.NULL
+        utf8 = (string or text).encode("utf-8")
+        return _check(
+            int(
+                lib.TCOD_printn_rgb(
+                    self.console_c,
+                    {
+                        "x": x,
+                        "y": y,
+                        "width": width or 0,
+                        "height": height or 0,
+                        "fg": rgb_fg,
+                        "bg": rgb_bg,
+                        "flag": bg_blend,
+                        "alignment": alignment,
+                    },
+                    len(utf8),
+                    utf8,
+                )
+            )
         )
 
+    @deprecated("Switch to using keywords and then replace with 'console.print(...)'")
     def print_box(  # noqa: PLR0913
         self,
         x: int,
@@ -1144,9 +1250,9 @@ def draw_frame(  # noqa: PLR0913
             >>> console.draw_frame(x=6, y=0, width=3, height=3, decoration="123456789")
             >>> console.draw_frame(x=9, y=0, width=3, height=3, decoration="/-\\| |\\-/")
             >>> console.draw_frame(x=0, y=3, width=12, height=3)
-            >>> console.print_box(x=0, y=3, width=12, height=1, string=" Title ", alignment=libtcodpy.CENTER)
+            >>> console.print(x=0, y=3, width=12, height=1, string=" Title ", alignment=libtcodpy.CENTER)
             1
-            >>> console.print_box(x=0, y=5, width=12, height=1, string="┤Lower├", alignment=libtcodpy.CENTER)
+            >>> console.print(x=0, y=5, width=12, height=1, string="┤Lower├", alignment=libtcodpy.CENTER)
             1
             >>> print(console)
             <┌─┐╔═╗123/-\
diff --git a/tests/test_console.py b/tests/test_console.py
@@ -70,8 +70,10 @@ def test_console_defaults() -> None:
 def test_console_methods() -> None:
     console = tcod.console.Console(width=12, height=10)
     console.put_char(0, 0, ord("@"))
-    console.print_(0, 0, "Test")
-    console.print_rect(0, 0, 2, 8, "a b c d e f")
+    with pytest.deprecated_call():
+        console.print_(0, 0, "Test")
+    with pytest.deprecated_call():
+        console.print_rect(0, 0, 2, 8, "a b c d e f")
     console.get_height_rect(0, 0, 2, 8, "a b c d e f")
     with pytest.deprecated_call():
         console.rect(0, 0, 2, 2, True)
