wip: Completely rework the formatting API and mark the old one as deprecated (to be removed in a future commits)

Author: xulbux

CHANGELOG.md

@@ -33,6 +33,10 @@
 *   Improved the performance of `String.normalize_spaces()` by using `str.translate()` instead of multiple `str.replace()` calls.
 *   Improved the performance of `Data.remove_duplicates()` for lists and tuples: hashable items now deduplicate in O(n) using `dict.fromkeys()`, with an O(n²) equality-check fallback only for unhashable items (*lists, dicts, sets*).
 *   The `Console.log()` method no longer forces the title to be all uppercase, giving the user a bit more freedom in how they want to format their title.
+*   Added a new, typed, operator-based formatting API in `format_codes`.<br>
+    The `Format` class (*alias* `F`) exposes every ANSI style/color attribute and uses `|` to combine codes and `()` to apply them to text – e.g. `(F.BOLD | F.RED)("hi")` and `F.hex("#F67")("hi")`.<br>
+    The new `FormatCodes(*segments, sep="\n")` class builds the ANSI string on construction and exposes `.ansi`, `.raw`, `.code_positions`, `.print()` and `.input()`.<br>
+    A companion `Term` class provides commonly used cursor- and screen-control sequences (`Term.HIDE_CURSOR`, `Term.up(n)`, `Term.move(row, col)`, `Term.title(text)`, …).
 
 **BREAKING CHANGES:**
 
@@ -43,6 +47,9 @@
 *   Removed the `format_linebreaks` param from `Console.log()`, as the whole point of the `log()` method is to get a nicely formatted log message.
 *   The `Console.get_args()` method no longer treats unknown flags as values but therefore saves them to the new `unknown_flags` property of the returned `ParsedArgs` object.
 *   Changed the type of `ParsedArgData.values` and `ArgData.values` from <code>list[*str*]</code> to <code>tuple[*str*, ...]</code>, since the values of an argument should be immutable after parsing.
+*   The original bracket-syntax `FormatCodes` class has been renamed to `deprFormatCodes` and moved into a new `depr_format_codes` module.<br>
+    All internal call sites in the library still use the deprecated implementation; both APIs are exported in parallel.<br>
+    `deprFormatCodes` will be removed in a future release – migrate to the new operator-based API at your convenience.
 
 
 <span id="v1-9-7" />

README.md

@@ -108,12 +108,12 @@ from xulbux.color import rgba, hsla, hexa
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/color"><img src="https://img.shields.io/badge/color-B272FC?style=for-the-badge" alt="color"></a></td>
-      <td><code>rgba</code> <code>hsla</code> <code>hexa</code> <code>Color</code> classes, which include methods to work with<br>
+      <td><code>rgba</code> <code>hsla</code> <code>hexa</code> <code>Color</code> classes, which include methods to work with<br>
         colors in various formats.</td>
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/console"><img src="https://img.shields.io/badge/console-B272FC?style=for-the-badge" alt="console"></a></td>
-      <td><code>Console</code> <code>ProgressBar</code> classes, which include methods for logging<br>
+      <td><code>Console</code> <code>ProgressBar</code> classes, which include methods for logging<br>
         and other actions within the console.</td>
     </tr>
     <tr>
@@ -134,8 +134,8 @@ from xulbux.color import rgba, hsla, hexa
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/format_codes"><img src="https://img.shields.io/badge/format__codes-B272FC?style=for-the-badge" alt="format_codes"></a></td>
-      <td><code>FormatCodes</code> class, which includes methods to print and work with strings that contain<br>
-        special formatting codes, which are then converted to ANSI codes for pretty terminal output.</td>
+      <td><code>Format</code> (<i>alias</i> <code>F</code>) <code>FormatCodes</code> <code>Term</code> classes for building richly formatted terminal output<br>
+        via a typed, operator-based syntax and for emitting cursor- and screen-control sequences.</td>
     </tr>
     <tr>
       <td><a href="https://github.com/xulbux/python-lib-xulbux/wiki/json"><img src="https://img.shields.io/badge/json-B272FC?style=for-the-badge" alt="json"></a></td>

src/xulbux/__init__.py

@@ -25,6 +25,7 @@
     "File",
     "FileSys",
     "FormatCodes",
+    "deprFormatCodes",
     "Json",
     "Regex",
     "String",
@@ -39,6 +40,7 @@
 from .file import File
 from .file_sys import FileSys
 from .format_codes import FormatCodes
+from .depr_format_codes import deprFormatCodes
 from .json import Json
 from .regex import Regex
 from .string import String

src/xulbux/base/consts.py

@@ -77,26 +77,33 @@ class ANSI:
     """Constants and utilities for ANSI escape code sequences."""
 
     CHAR_ESCAPED: Final = r"\x1b"
-    """Printable ANSI escape character."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Printable ANSI escape character."""
     CHAR: Final = "\x1b"
     """ANSI escape character."""
     START: Final = "["
-    """Start of an ANSI escape sequence."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Start of an ANSI escape sequence."""
     SEP: Final = ";"
-    """Separator between ANSI escape sequence parts."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Separator between ANSI escape sequence parts."""
     END: Final = "m"
-    """End of an ANSI escape sequence."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    End of an ANSI escape sequence."""
 
     @classmethod
     def seq(cls, placeholders: int = 1, /) -> FormattableString:
-        """Generates an ANSI escape sequence with the specified number of placeholders."""
+        """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+        Generates an ANSI escape sequence with the specified number of placeholders."""
 
         return cls.CHAR + cls.START + cls.SEP.join(["{}" for _ in range(placeholders)]) + cls.END
 
     SEQ_COLOR: Final[FormattableString] = CHAR + START + "38" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
-    """ANSI escape sequence with three placeholders for setting the RGB text color."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    ANSI escape sequence with three placeholders for setting the RGB text color."""
     SEQ_BG_COLOR: Final[FormattableString] = CHAR + START + "48" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
-    """ANSI escape sequence with three placeholders for setting the RGB background color."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    ANSI escape sequence with three placeholders for setting the RGB background color."""
 
     SEQ_LINK_OPEN: Final[FormattableString] = CHAR + "]8;;{}" + CHAR + "\\"
     """OSC 8 hyperlink opening sequence with a placeholder for the URL."""
@@ -113,7 +120,8 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "cyan",
         "white",
     }
-    """The standard terminal color names."""
+    """**DEPRECATED** – only used by `depr_format_codes` and as the seed for `COLOR_VARIANTS_MAP`.\n
+    The standard terminal color names."""
 
     COLOR_VARIANTS_MAP: Final[set[str]] = COLOR_MAP | {
         "br:black",
@@ -125,7 +133,8 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "br:cyan",
         "br:white",
     }
-    """All color variants that can be used in formatting."""
+    """**DEPRECATED** – only used by `depr_format_codes` and as the seed for `COLOR_VARIANTS_MAP`.\n
+    All color variants that can be used in formatting."""
 
     CODES_MAP: Final[dict[str | tuple[str, ...], int]] = {
         ################# SPECIFIC RESETS ##################
@@ -186,4 +195,5 @@ def seq(cls, placeholders: int = 1, /) -> FormattableString:
         "bg:br:cyan": 106,
         "bg:br:white": 107,
     }
-    """Dictionary mapping format keys to their corresponding ANSI code numbers."""
+    """**DEPRECATED** – only used by `depr_format_codes`. Will be removed together with that module.\n
+    Dictionary mapping format keys to their corresponding ANSI code numbers."""

src/xulbux/cli/help.py

@@ -1,5 +1,5 @@
 from .. import __version__
-from ..format_codes import FormatCodes
+from ..depr_format_codes import deprFormatCodes
 from ..console import Console
 
 from urllib.error import HTTPError
@@ -52,7 +52,7 @@ def is_latest_version() -> Optional[bool]:
     "punctuator": "br:black",
     "text": "white",
 }
-CLI_HELP = FormatCodes.to_ansi(
+CLI_HELP = deprFormatCodes.to_ansi(
     rf"""[_]
   [b|#7075FF]               __  __
   [b|#7075FF]  _  __ __  __/ / / /_  __  ___  __
@@ -89,6 +89,6 @@ def show_help() -> None:
     """CLI command function for `xulbux-lib` command,<br>
     which shows some information about the library."""
 
-    FormatCodes._config_terminal()
+    deprFormatCodes._config_terminal()
     print(CLI_HELP)
     Console.pause_exit("  [dim](Press any key to exit...)\n\n", pause=True)

src/xulbux/cli/tools.py

@@ -1,4 +1,4 @@
-from ..format_codes import FormatCodes
+from ..depr_format_codes import deprFormatCodes
 from ..console import Console
 
 
@@ -10,19 +10,19 @@ def render_format_codes():
     vals = args.input.values
 
     if not vals:
-        FormatCodes.print(
+        deprFormatCodes.print(
             "\n[_|i|dim]Provide a string to parse and render\n"
             "its format codes as ANSI terminal output.[_]\n"
         )
 
     else:
-        ansi = FormatCodes.to_ansi("".join(vals))
-        ansi_escaped = FormatCodes.escape_ansi(ansi)
-        ansi_stripped = FormatCodes.remove_ansi(ansi)
+        ansi = deprFormatCodes.to_ansi("".join(vals))
+        ansi_escaped = deprFormatCodes.escape_ansi(ansi)
+        ansi_stripped = deprFormatCodes.remove_ansi(ansi)
 
         print(f"\n{ansi}\n")
 
         if len(ansi) != len(ansi_stripped):
-            FormatCodes.print(f"[_|i|dim]{ansi_escaped}[_]\n")
+            deprFormatCodes.print(f"[_|i|dim]{ansi_escaped}[_]\n")
         else:
-            FormatCodes.print("[_|i|dim](The provided string doesn't contain any valid format codes.)\n")
+            deprFormatCodes.print("[_|i|dim](The provided string doesn't contain any valid format codes.)\n")

src/xulbux/console.py

@@ -7,7 +7,7 @@
 from .base.decorators import mypyc_attr
 from .base.consts import CHARS, ANSI
 
-from .format_codes import _PATTERNS as _FC_PATTERNS, FormatCodes
+from .depr_format_codes import _PATTERNS as _FC_PATTERNS, deprFormatCodes
 from .string import String
 from .color import Color
 from .regex import LazyRegex
@@ -454,9 +454,9 @@ def pause_exit(
         *   `exit_code` – The exit code to use when exiting the program.
         *   `reset_ansi` – Whether to reset the ANSI formatting after printing the prompt."""
 
-        FormatCodes.print(prompt, end="", flush=True)
+        deprFormatCodes.print(prompt, end="", flush=True)
         if reset_ansi:
-            FormatCodes.print("[_]", end="")
+            deprFormatCodes.print("[_]", end="")
         if pause:
             cls._read_single_key()
         if exit:
@@ -532,7 +532,7 @@ def log(
         px, mx = " " * title_px, " " * title_mx
 
         # TITLE LENGTH INCLUDING PADDING AND MARGIN
-        title_len: int = len(FormatCodes.remove(title)) + (title_px * 2) + (title_mx * 2)
+        title_len: int = len(deprFormatCodes.remove(title)) + (title_px * 2) + (title_mx * 2)
 
         # CALCULATE DISTANCE TO NEXT TAB STOP
         tab: str = " " * (-title_len % tab_size)
@@ -541,7 +541,7 @@ def log(
         wrap_len: int = cls.width - (title_len + len(tab))
 
         # REMOVE ALL FORMAT CODES AS THEY WON'T AFFECT THE VISIBLE LENGTH OF THE PROMPT
-        clean_prompt, removals = (*FormatCodes.remove(str(prompt), get_removals=True, _ignore_linebreaks=True), )
+        clean_prompt, removals = (*deprFormatCodes.remove(str(prompt), get_removals=True, _ignore_linebreaks=True), )
 
         # SPLIT PROMPT INTO LINES AND THEN SPLIT EACH LINE INTO CHUNKS THAT FIT WITHIN THE WRAP LENGTH
         prompt_lst: list[str] = list(chain.from_iterable(cls._process_lines(clean_prompt, wrap_len)))
@@ -557,7 +557,7 @@ def log(
             f"{tab}{f'[{default_color}]' if default_color else ''}{prompt}[_]"
         )
 
-        FormatCodes.print(out, default_color=default_color, end=end)
+        deprFormatCodes.print(out, default_color=default_color, end=end)
 
     @classmethod
     def debug(
@@ -782,7 +782,7 @@ def log_box_filled(
             + "[*]"
         ) for line, unfmt in zip(lines, unfmt_lines)]
 
-        FormatCodes.print(
+        deprFormatCodes.print(
             ( \
                 f"{start}{spaces_l}[{bg_fc}]{pady}[*]\n"
                 + "\n".join(lines)
@@ -893,7 +893,7 @@ def log_box_bordered(
             + border_r
         ) for line, unfmt in zip(lines, unfmt_lines)]
 
-        FormatCodes.print(
+        deprFormatCodes.print(
             ( \
                 f"{start}{border_t}[_]\n"
                 + "\n".join(lines)
@@ -928,14 +928,14 @@ def confirm(
         information about formatting codes, see the `format_codes` module documentation."""
 
         confirmed = cls.input(
-            FormatCodes.to_ansi(
+            deprFormatCodes.to_ansi(
                 f"{start}{str(prompt)} [_|dim](({'Y' if default_is_yes else 'y'}/{'n' if default_is_yes else 'N'}): )",
                 default_color=default_color,
             )
         ).strip().lower() in ({"", "y", "yes"} if default_is_yes else {"y", "yes"})
 
         if end:
-            FormatCodes.print(end, end="")
+            deprFormatCodes.print(end, end="")
         return confirmed
 
     @classmethod
@@ -967,11 +967,11 @@ def multiline_input(
         kb = KeyBindings()
         kb.add("c-d", eager=True)(cls._multiline_input_submit)
 
-        FormatCodes.print(start + str(prompt), default_color=default_color)
+        deprFormatCodes.print(start + str(prompt), default_color=default_color)
         if show_keybindings:
-            FormatCodes.print("[dim][[b](CTRL+D)[dim] : end of input][_dim]")
+            deprFormatCodes.print("[dim][[b](CTRL+D)[dim] : end of input][_dim]")
         input_string = _pt.prompt(input_prefix, multiline=True, wrap_lines=True, key_bindings=kb)
-        FormatCodes.print("[_]" if reset_ansi else "", end=end[1:] if end.startswith("\n") else end)
+        deprFormatCodes.print("[_]" if reset_ansi else "", end=end[1:] if end.startswith("\n") else end)
 
         return input_string
 
@@ -1084,7 +1084,7 @@ def input(
 
         custom_style = Style.from_dict({"bottom-toolbar": "noreverse"})
         session: _pt.PromptSession[str] = _pt.PromptSession(
-            message=_pt.formatted_text.ANSI(FormatCodes.to_ansi(str(prompt), default_color=default_color)),
+            message=_pt.formatted_text.ANSI(deprFormatCodes.to_ansi(str(prompt), default_color=default_color)),
             validator=_ConsoleInputValidator(
                 helper.get_text,
                 mask_char=mask_char,
@@ -1094,13 +1094,13 @@ def input(
             validate_while_typing=True,
             key_bindings=kb,
             bottom_toolbar=helper.bottom_toolbar,
-            placeholder=_pt.formatted_text.ANSI(FormatCodes.to_ansi(f"[i|br:black]{placeholder}[_i|_c]"))
+            placeholder=_pt.formatted_text.ANSI(deprFormatCodes.to_ansi(f"[i|br:black]{placeholder}[_i|_c]"))
             if placeholder else "",
             style=custom_style,
         )
-        FormatCodes.print(start, end="")
+        deprFormatCodes.print(start, end="")
         session.prompt()
-        FormatCodes.print(end, end="")
+        deprFormatCodes.print(end, end="")
 
         if (result_text := helper.get_text()) in {"", None}:
             if default_val is not None:
@@ -1242,7 +1242,7 @@ def _prepare_log_box(
         else:
             lines = [line for val in values for line in str(val).splitlines()]
 
-        unfmt_lines = [FormatCodes.remove(line, default_color) for line in lines]
+        unfmt_lines = [deprFormatCodes.remove(line, default_color) for line in lines]
         max_line_len = max(len(line) for line in unfmt_lines) if unfmt_lines else 0
 
         return lines, unfmt_lines, max_line_len
@@ -1632,7 +1632,7 @@ def bottom_toolbar(self) -> _pt.formatted_text.ANSI:
             if self.max_len and len(text_to_check) == self.max_len:
                 toolbar_msgs.append("[b|#000|bg:br:yellow]( Maximum length reached )")
 
-            return _pt.formatted_text.ANSI(FormatCodes.to_ansi(" ".join(toolbar_msgs)))
+            return _pt.formatted_text.ANSI(deprFormatCodes.to_ansi(" ".join(toolbar_msgs)))
 
         except Exception:
             return _pt.formatted_text.ANSI("")
@@ -1987,7 +1987,7 @@ def _draw_progress_bar(self, current: int, total: int, /, label: Optional[str] =
             )
 
         bar = f"{self._create_bar(current, total, max(1, bar_width))}[*]"
-        progress_text = _PATTERNS.bar.sub(FormatCodes.to_ansi(bar), formatted)
+        progress_text = _PATTERNS.bar.sub(deprFormatCodes.to_ansi(bar), formatted)
 
         self._current_progress_str = progress_text
         self._last_line_len = len(progress_text)
@@ -2014,9 +2014,9 @@ def _get_formatted_info_and_bar_width(
                 fmt_parts.append(fmt_part)
 
         fmt_str = self.sep.join(fmt_parts)
-        fmt_str = FormatCodes.to_ansi(fmt_str)
+        fmt_str = deprFormatCodes.to_ansi(fmt_str)
 
-        bar_space = Console.width - len(FormatCodes.remove_ansi(_PATTERNS.bar.sub("", fmt_str)))
+        bar_space = Console.width - len(deprFormatCodes.remove_ansi(_PATTERNS.bar.sub("", fmt_str)))
         bar_width = min(bar_space, self.max_width) if bar_space > 0 else 0
 
         return fmt_str, bar_width
@@ -2315,8 +2315,8 @@ def _animation_loop(self) -> None:
 
                 self._flush_buffer()
 
-                frame = FormatCodes.to_ansi(f"{self.frames[self._frame_index % len(self.frames)]}[*]")
-                formatted = FormatCodes.to_ansi(self.sep.join(
+                frame = deprFormatCodes.to_ansi(f"{self.frames[self._frame_index % len(self.frames)]}[*]")
+                formatted = deprFormatCodes.to_ansi(self.sep.join(
                     fmt_part for part in self.throbber_format if \
                     (fmt_part := _PATTERNS.animation.sub(frame, _PATTERNS.label.sub(self.label or "", part)))
                 ))

src/xulbux/data.py

@@ -5,7 +5,7 @@
 
 from .base.types import IndexIterableTT, IndexIterable, DataObjTT, DataObj as DataObjType
 
-from .format_codes import FormatCodes
+from .depr_format_codes import deprFormatCodes
 from .string import String
 from .regex import Regex
 
@@ -541,7 +541,7 @@ def print(
         ----------------------------------------------------------------------------------------------------------------
         For more detailed information about formatting codes, see the `format_codes` module documentation."""
 
-        FormatCodes.print(
+        deprFormatCodes.print(
             cls.render(
                 data,
                 indent=indent,