repl-toolkit 1.0.0__tar.gz → 1.1.0__tar.gz

{repl_toolkit-1.0.0/repl_toolkit.egg-info → repl_toolkit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repl-toolkit
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Python toolkit for building interactive REPL and headless interfaces with action support
 Author-email: REPL Toolkit Contributors <martin.j.bartlett@gmail.com>
 License: MIT
@@ -639,3 +639,109 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
 - Built on [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) for terminal handling
 - Logging by [loguru](https://github.com/Delgan/loguru) for structured logs
 - Inspired by modern CLI tools and REPL interfaces
+
+## Formatting Utilities
+
+REPL Toolkit includes utilities for automatically detecting and applying formatted text (HTML or ANSI) without needing to explicitly wrap text in format types.
+
+### Auto-Format Detection
+
+The formatting utilities can automatically detect whether text contains HTML tags, ANSI escape codes, or is plain text:
+
+```python
+from repl_toolkit import detect_format_type, auto_format, print_auto_formatted
+
+# Detect format type
+detect_format_type("<b>Bold</b>")  # Returns: 'html'
+detect_format_type("\x1b[1mBold\x1b[0m")  # Returns: 'ansi'
+detect_format_type("Plain text")  # Returns: 'plain'
+
+# Auto-format and print
+print_auto_formatted("<b>Bold HTML</b>")  # Automatically applies HTML formatting
+print_auto_formatted("\x1b[1mBold ANSI\x1b[0m")  # Automatically applies ANSI formatting
+print_auto_formatted("Plain text")  # Prints as-is
+```
+
+### Creating Auto-Printers
+
+The `create_auto_printer()` function creates a printer that can be used as a drop-in replacement for `print()` with automatic format detection:
+
+```python
+from repl_toolkit import create_auto_printer
+
+# Create a printer
+printer = create_auto_printer()
+
+# Use it like print()
+printer("<b>Bold text</b>")  # HTML formatting applied
+printer("\x1b[1mANSI bold\x1b[0m")  # ANSI formatting applied
+printer("Plain text")  # No formatting
+
+# Works with all print() parameters
+printer("<b>Prefix:</b> ", end="", flush=True)
+printer("Hello world\n")
+```
+
+### Integration with Callback Handlers
+
+The auto-printer is particularly useful for integrating with callback handlers from other libraries:
+
+```python
+from repl_toolkit import create_auto_printer
+from some_library import CallbackHandler
+
+# Create handler with auto-formatting printer
+handler = CallbackHandler(
+    response_prefix="<b><darkcyan>🤖 Assistant:</darkcyan></b> ",
+    printer=create_auto_printer()  # Automatically formats HTML tags
+)
+
+# The response_prefix will be properly formatted without needing
+# to explicitly wrap it in HTML() or ANSI()
+```
+
+### Format Detection Rules
+
+The auto-detection uses the following rules:
+
+1. **ANSI Detection**: Looks for ANSI escape codes (`\x1b[...m`)
+   - Pattern: `\x1b\[[0-9;]*m`
+   - Examples: `\x1b[1m`, `\x1b[31;1m`
+
+2. **HTML Detection**: Looks for HTML-like tags
+   - Pattern: `</?[a-zA-Z][a-zA-Z0-9]*\s*/?>`
+   - Examples: `<b>`, `</b>`, `<darkcyan>`, `<tag/>`
+   - Avoids false positives: `a < b`, `<123>`, `<_tag>`
+
+3. **Plain Text**: Everything else
+
+### API Reference
+
+#### `detect_format_type(text: str) -> str`
+Detect the format type of a text string.
+
+**Returns**: `'ansi'`, `'html'`, or `'plain'`
+
+#### `auto_format(text: str)`
+Auto-detect format type and return appropriate formatted text object.
+
+**Returns**: `HTML`, `ANSI`, or `str` object
+
+#### `print_auto_formatted(text: str, **kwargs) -> None`
+Print text with auto-detected formatting.
+
+**Parameters**: Same as `print_formatted_text()` from prompt_toolkit
+
+#### `create_auto_printer() -> Callable`
+Create a printer function with auto-format detection.
+
+**Returns**: Callable with signature `printer(text: str, **kwargs)`
+
+### Example
+
+See `examples/formatting_demo.py` for a complete demonstration of the formatting utilities.
+
+```bash
+python examples/formatting_demo.py
+```
+

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/README.md

@@ -598,3 +598,109 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
 - Built on [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) for terminal handling
 - Logging by [loguru](https://github.com/Delgan/loguru) for structured logs
 - Inspired by modern CLI tools and REPL interfaces
+
+## Formatting Utilities
+
+REPL Toolkit includes utilities for automatically detecting and applying formatted text (HTML or ANSI) without needing to explicitly wrap text in format types.
+
+### Auto-Format Detection
+
+The formatting utilities can automatically detect whether text contains HTML tags, ANSI escape codes, or is plain text:
+
+```python
+from repl_toolkit import detect_format_type, auto_format, print_auto_formatted
+
+# Detect format type
+detect_format_type("<b>Bold</b>")  # Returns: 'html'
+detect_format_type("\x1b[1mBold\x1b[0m")  # Returns: 'ansi'
+detect_format_type("Plain text")  # Returns: 'plain'
+
+# Auto-format and print
+print_auto_formatted("<b>Bold HTML</b>")  # Automatically applies HTML formatting
+print_auto_formatted("\x1b[1mBold ANSI\x1b[0m")  # Automatically applies ANSI formatting
+print_auto_formatted("Plain text")  # Prints as-is
+```
+
+### Creating Auto-Printers
+
+The `create_auto_printer()` function creates a printer that can be used as a drop-in replacement for `print()` with automatic format detection:
+
+```python
+from repl_toolkit import create_auto_printer
+
+# Create a printer
+printer = create_auto_printer()
+
+# Use it like print()
+printer("<b>Bold text</b>")  # HTML formatting applied
+printer("\x1b[1mANSI bold\x1b[0m")  # ANSI formatting applied
+printer("Plain text")  # No formatting
+
+# Works with all print() parameters
+printer("<b>Prefix:</b> ", end="", flush=True)
+printer("Hello world\n")
+```
+
+### Integration with Callback Handlers
+
+The auto-printer is particularly useful for integrating with callback handlers from other libraries:
+
+```python
+from repl_toolkit import create_auto_printer
+from some_library import CallbackHandler
+
+# Create handler with auto-formatting printer
+handler = CallbackHandler(
+    response_prefix="<b><darkcyan>🤖 Assistant:</darkcyan></b> ",
+    printer=create_auto_printer()  # Automatically formats HTML tags
+)
+
+# The response_prefix will be properly formatted without needing
+# to explicitly wrap it in HTML() or ANSI()
+```
+
+### Format Detection Rules
+
+The auto-detection uses the following rules:
+
+1. **ANSI Detection**: Looks for ANSI escape codes (`\x1b[...m`)
+   - Pattern: `\x1b\[[0-9;]*m`
+   - Examples: `\x1b[1m`, `\x1b[31;1m`
+
+2. **HTML Detection**: Looks for HTML-like tags
+   - Pattern: `</?[a-zA-Z][a-zA-Z0-9]*\s*/?>`
+   - Examples: `<b>`, `</b>`, `<darkcyan>`, `<tag/>`
+   - Avoids false positives: `a < b`, `<123>`, `<_tag>`
+
+3. **Plain Text**: Everything else
+
+### API Reference
+
+#### `detect_format_type(text: str) -> str`
+Detect the format type of a text string.
+
+**Returns**: `'ansi'`, `'html'`, or `'plain'`
+
+#### `auto_format(text: str)`
+Auto-detect format type and return appropriate formatted text object.
+
+**Returns**: `HTML`, `ANSI`, or `str` object
+
+#### `print_auto_formatted(text: str, **kwargs) -> None`
+Print text with auto-detected formatting.
+
+**Parameters**: Same as `print_formatted_text()` from prompt_toolkit
+
+#### `create_auto_printer() -> Callable`
+Create a printer function with auto-format detection.
+
+**Returns**: Callable with signature `printer(text: str, **kwargs)`
+
+### Example
+
+See `examples/formatting_demo.py` for a complete demonstration of the formatting utilities.
+
+```bash
+python examples/formatting_demo.py
+```
+

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "repl-toolkit"
-version = "1.0.0"
+version = "1.1.0"
 description = "A Python toolkit for building interactive REPL and headless interfaces with action support"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -100,4 +100,4 @@ warn_redundant_casts = true
 warn_unused_ignores = true
 warn_no_return = true
 warn_unreachable = true
-strict_equality = true
+strict_equality = true

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/repl_toolkit/__init__.py

@@ -11,24 +11,25 @@ Key Features:
 - Protocol-based architecture for type safety
 - Comprehensive test coverage
 - Async-native design
+- Auto-formatting utilities for HTML and ANSI text
 
 Example:
     >>> import asyncio
     >>> from repl_toolkit import run_async_repl, ActionRegistry
-    >>> 
+    >>>
     >>> class MyBackend:
     ...     async def handle_input(self, user_input: str) -> bool:
     ...         print(f"You said: {user_input}")
     ...         return True
-    >>> 
+    >>>
     >>> async def main():
     ...     backend = MyBackend()
     ...     await run_async_repl(backend=backend)
-    >>> 
+    >>>
     >>> # asyncio.run(main())
 """
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __author__ = "REPL Toolkit Contributors"
 __license__ = "MIT"
 
@@ -37,22 +38,34 @@ from .async_repl import AsyncREPL, run_async_repl
 from .headless_repl import run_headless_mode, HeadlessREPL
 from .actions import ActionRegistry, Action, ActionContext, ActionError
 from .ptypes import AsyncBackend, ActionHandler, Completer
+from .formatting import (
+    detect_format_type,
+    auto_format,
+    print_auto_formatted,
+    create_auto_printer,
+)
 
 __all__ = [
     # Core classes
     "AsyncREPL",
     "HeadlessREPL",
-    "ActionRegistry", 
+    "ActionRegistry",
     "Action",
     "ActionContext",
     "ActionError",
-    
+
     # Convenience functions
     "run_async_repl",
     "run_headless_mode",
-    
+
     # Protocols/Types
     "AsyncBackend",
     "ActionHandler",
     "Completer",
-]
+
+    # Formatting utilities
+    "detect_format_type",
+    "auto_format",
+    "print_auto_formatted",
+    "create_auto_printer",
+]

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/repl_toolkit/actions/registry.py

@@ -6,7 +6,7 @@ executing actions that can be triggered through multiple interaction methods.
 """
 
 import importlib
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional
 from loguru import logger
 
 from .shell import shell_command

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/repl_toolkit/async_repl.py

@@ -44,7 +44,8 @@ class AsyncREPL:
         action_registry: Optional[ActionHandler] = None,
         completer: Optional[Completer] = None,
         prompt_string: Optional[str] = None,
-        history_path: Optional[Path] = None
+        history_path: Optional[Path] = None,
+        **kwargs,
     ):
         """
         Initialize the async REPL interface.
@@ -64,10 +65,12 @@ class AsyncREPL:
         self.prompt_string = HTML(prompt_string or "User: ")
         self.action_registry = action_registry or ActionRegistry()
         self.session = PromptSession(
+            message=self.prompt_string,
             history=self._create_history(history_path),
             key_bindings=self._create_key_bindings(),
             multiline=True,
             completer=completer,
+            **kwargs,
         )
         self.main_app = self.session.app
         
@@ -246,7 +249,7 @@ class AsyncREPL:
 
         while True:
             try:
-                user_input = await self.session.prompt_async(self.prompt_string)
+                user_input = await self.session.prompt_async()
                 if self._should_exit(user_input):
                     break
                 if not user_input.strip():
@@ -344,6 +347,7 @@ async def run_async_repl(  # pragma: no cover
     initial_message: Optional[str] = None,
     prompt_string: Optional[str] = None,
     history_path: Optional[Path] = None,
+    **kwargs,
 ):
     """
     Convenience function to create and run an AsyncREPL with action support.
@@ -361,7 +365,7 @@ async def run_async_repl(  # pragma: no cover
     """
     logger.trace("run_async_repl() entry")
     
-    repl = AsyncREPL(action_registry, completer, prompt_string, history_path)
+    repl = AsyncREPL(action_registry, completer, prompt_string, history_path, **kwargs)
     await repl.run(backend, initial_message)
     
     logger.trace("run_async_repl() exit")

repl_toolkit-1.1.0/repl_toolkit/formatting.py

@@ -0,0 +1,151 @@
+"""
+Formatted text utilities for repl_toolkit.
+
+This module provides utilities for working with formatted text in prompt_toolkit,
+including auto-detection of format types and smart printing.
+"""
+
+import re
+from typing import Callable
+from prompt_toolkit import print_formatted_text
+from prompt_toolkit.formatted_text import HTML, ANSI
+
+
+# Pre-compile regex patterns for performance
+_ANSI_PATTERN = re.compile(r'\x1b\[[0-9;]*m')
+_HTML_PATTERN = re.compile(r'</?[a-zA-Z][a-zA-Z0-9]*\s*/?>')
+
+
+def detect_format_type(text: str) -> str:
+    """
+    Detect the format type of a text string.
+    
+    Detects three format types:
+    - 'ansi': Text contains ANSI escape codes (e.g., \\x1b[1m)
+    - 'html': Text contains HTML-like tags (e.g., <b>, <darkcyan>)
+    - 'plain': Plain text with no special formatting
+    
+    Args:
+        text: Text string to analyze
+        
+    Returns:
+        Format type: 'ansi', 'html', or 'plain'
+        
+    Examples:
+        >>> detect_format_type("<b>Bold</b>")
+        'html'
+        >>> detect_format_type("\\x1b[1mBold\\x1b[0m")
+        'ansi'
+        >>> detect_format_type("Plain text")
+        'plain'
+        >>> detect_format_type("a < b and c > d")
+        'plain'
+    """
+    # Check for ANSI escape codes (most specific)
+    if _ANSI_PATTERN.search(text):
+        return 'ansi'
+    
+    # Check for HTML tags
+    # Valid HTML tag names: start with letter, contain letters/numbers
+    if _HTML_PATTERN.search(text):
+        return 'html'
+    
+    # Plain text
+    return 'plain'
+
+
+def auto_format(text: str):
+    """
+    Auto-detect format type and return appropriate formatted text object.
+    
+    This function analyzes the input text and wraps it in the appropriate
+    prompt_toolkit formatted text type (HTML, ANSI, or plain string).
+    
+    Args:
+        text: Text string to format
+        
+    Returns:
+        Formatted text object (HTML, ANSI, or str)
+        
+    Examples:
+        >>> auto_format("<b>Bold</b>")
+        HTML('<b>Bold</b>')
+        >>> auto_format("\\x1b[1mBold\\x1b[0m")
+        ANSI('\\x1b[1mBold\\x1b[0m')
+        >>> auto_format("Plain text")
+        'Plain text'
+    """
+    format_type = detect_format_type(text)
+    
+    if format_type == 'ansi':
+        return ANSI(text)
+    elif format_type == 'html':
+        return HTML(text)
+    else:
+        return text
+
+
+def print_auto_formatted(text: str, **kwargs) -> None:
+    """
+    Print text with auto-detected formatting.
+    
+    This function automatically detects the format type (HTML, ANSI, or plain)
+    and prints the text with appropriate formatting applied.
+    
+    Args:
+        text: Text to print (may contain HTML tags, ANSI codes, or be plain)
+        **kwargs: Additional arguments passed to print_formatted_text
+                 (e.g., end, flush, style, output)
+                 
+    Examples:
+        >>> print_auto_formatted("<b>Bold</b> text")
+        Bold text
+        >>> print_auto_formatted("\\x1b[1mBold\\x1b[0m text")
+        Bold text
+        >>> print_auto_formatted("Plain text")
+        Plain text
+    """
+    formatted = auto_format(text)
+    print_formatted_text(formatted, **kwargs)
+
+
+def create_auto_printer() -> Callable:
+    """
+    Create a printer function with auto-format detection.
+    
+    Returns a callable that can be used as a drop-in replacement for print(),
+    with automatic detection and application of formatting (HTML or ANSI).
+    
+    This is particularly useful for injecting into callback handlers or other
+    components that accept a custom printer function.
+    
+    Returns:
+        Callable printer function with signature: printer(text, **kwargs)
+        
+    Examples:
+        >>> printer = create_auto_printer()
+        >>> printer("<b>Bold</b>", end="", flush=True)
+        Bold
+        >>> printer(" text\\n")
+         text
+        
+    Usage with callback handlers:
+        >>> from some_library import CallbackHandler
+        >>> handler = CallbackHandler(
+        ...     response_prefix="<b>Bot:</b> ",
+        ...     printer=create_auto_printer()
+        ... )
+    """
+    def printer(text: str, **kwargs):
+        """Auto-format and print text."""
+        print_auto_formatted(text, **kwargs)
+    
+    return printer
+
+
+__all__ = [
+    'detect_format_type',
+    'auto_format',
+    'print_auto_formatted',
+    'create_auto_printer',
+]

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/repl_toolkit/ptypes.py

@@ -5,9 +5,10 @@ Defines the interface contracts that backends and handlers must implement
 for compatibility with the REPL toolkit.
 """
 
-from typing import Protocol, runtime_checkable, Optional, List
-from pathlib import Path
+from typing import Protocol, runtime_checkable, List, TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from .actions.action import ActionContext # Avoid circular import
 
 @runtime_checkable
 class AsyncBackend(Protocol):

repl_toolkit-1.1.0/repl_toolkit/tests/test_formatting.py

@@ -0,0 +1,232 @@
+"""
+Tests for formatting utilities.
+"""
+
+import pytest
+from prompt_toolkit.formatted_text import HTML, ANSI
+
+from repl_toolkit.formatting import (
+    detect_format_type,
+    auto_format,
+    print_auto_formatted,
+    create_auto_printer,
+)
+
+
+class TestDetectFormatType:
+    """Tests for detect_format_type function."""
+    
+    def test_detect_html(self):
+        """Test HTML tag detection."""
+        assert detect_format_type("<b>Bold</b>") == "html"
+        assert detect_format_type("<darkcyan>Colored</darkcyan>") == "html"
+        assert detect_format_type("<b><darkcyan>Nested</darkcyan></b>") == "html"
+        assert detect_format_type("<i>Italic</i>") == "html"
+        assert detect_format_type("<u>Underline</u>") == "html"
+    
+    def test_detect_html_uppercase(self):
+        """Test HTML detection with uppercase tags."""
+        assert detect_format_type("<B>Bold</B>") == "html"
+        assert detect_format_type("<TAG>content</TAG>") == "html"
+    
+    def test_detect_html_self_closing(self):
+        """Test HTML self-closing tag detection."""
+        assert detect_format_type("<br/>") == "html"
+        assert detect_format_type("<tag />") == "html"
+    
+    def test_detect_ansi(self):
+        """Test ANSI escape code detection."""
+        assert detect_format_type("\x1b[1mBold\x1b[0m") == "ansi"
+        assert detect_format_type("\x1b[31mRed\x1b[0m") == "ansi"
+        assert detect_format_type("\x1b[1;32mBold Green\x1b[0m") == "ansi"
+        assert detect_format_type("\033[1mBold\033[0m") == "ansi"
+    
+    def test_detect_plain(self):
+        """Test plain text detection."""
+        assert detect_format_type("Plain text") == "plain"
+        assert detect_format_type("No formatting here") == "plain"
+        assert detect_format_type("") == "plain"
+    
+    def test_edge_cases(self):
+        """Test edge cases that should not be detected as HTML."""
+        # Comparison operators
+        assert detect_format_type("a < b and c > d") == "plain"
+        
+        # Numbers in tag names (invalid HTML)
+        assert detect_format_type("<123>content</123>") == "plain"
+        
+        # Hyphens in tag names (invalid HTML)
+        assert detect_format_type("<a-b>content</a-b>") == "plain"
+        
+        # Underscore start (invalid HTML)
+        assert detect_format_type("<_tag>content</_tag>") == "plain"
+        
+        # Angle brackets but not tags
+        assert detect_format_type("Text with <angle brackets> but not tags") == "plain"
+    
+    def test_mixed_content(self):
+        """Test that ANSI takes precedence over HTML."""
+        # If text has both ANSI and HTML-like content, ANSI is detected first
+        mixed = "\x1b[1m<b>Bold</b>\x1b[0m"
+        assert detect_format_type(mixed) == "ansi"
+
+
+class TestAutoFormat:
+    """Tests for auto_format function."""
+    
+    def test_auto_format_html(self):
+        """Test auto-formatting HTML text."""
+        result = auto_format("<b>Bold</b>")
+        assert isinstance(result, HTML)
+        # HTML objects have the text accessible via their value attribute
+        assert result.value == "<b>Bold</b>"
+    
+    def test_auto_format_ansi(self):
+        """Test auto-formatting ANSI text."""
+        result = auto_format("\x1b[1mBold\x1b[0m")
+        assert isinstance(result, ANSI)
+        # ANSI objects have the text accessible via their value attribute
+        assert result.value == "\x1b[1mBold\x1b[0m"
+    
+    def test_auto_format_plain(self):
+        """Test auto-formatting plain text."""
+        result = auto_format("Plain text")
+        assert isinstance(result, str)
+        assert result == "Plain text"
+    
+    def test_auto_format_empty(self):
+        """Test auto-formatting empty string."""
+        result = auto_format("")
+        assert isinstance(result, str)
+        assert result == ""
+
+
+class TestPrintAutoFormatted:
+    """Tests for print_auto_formatted function."""
+    
+    def test_print_html(self):
+        """Test printing HTML formatted text."""
+        # Just verify it doesn't raise an exception
+        # We can't easily test the actual output in pytest
+        try:
+            print_auto_formatted("<b>Bold</b>")
+        except Exception as e:
+            pytest.fail(f"print_auto_formatted raised {e}")
+    
+    def test_print_plain(self):
+        """Test printing plain text."""
+        try:
+            print_auto_formatted("Plain text")
+        except Exception as e:
+            pytest.fail(f"print_auto_formatted raised {e}")
+    
+    def test_print_with_kwargs(self):
+        """Test printing with additional kwargs."""
+        try:
+            print_auto_formatted("Test", end="", flush=True)
+        except Exception as e:
+            pytest.fail(f"print_auto_formatted raised {e}")
+
+
+class TestCreateAutoPrinter:
+    """Tests for create_auto_printer function."""
+    
+    def test_create_printer(self):
+        """Test creating an auto printer."""
+        printer = create_auto_printer()
+        assert callable(printer)
+    
+    def test_printer_html(self):
+        """Test printer with HTML text."""
+        printer = create_auto_printer()
+        try:
+            printer("<b>Bold</b>")
+        except Exception as e:
+            pytest.fail(f"printer raised {e}")
+    
+    def test_printer_plain(self):
+        """Test printer with plain text."""
+        printer = create_auto_printer()
+        try:
+            printer("Plain text")
+        except Exception as e:
+            pytest.fail(f"printer raised {e}")
+    
+    def test_printer_with_kwargs(self):
+        """Test printer with kwargs."""
+        printer = create_auto_printer()
+        try:
+            printer("Test", end="", flush=True)
+        except Exception as e:
+            pytest.fail(f"printer raised {e}")
+    
+    def test_printer_multiple_calls(self):
+        """Test printer with multiple calls."""
+        printer = create_auto_printer()
+        try:
+            printer("<b>Prefix:</b> ", end="", flush=True)
+            printer("Hello", end="", flush=True)
+            printer(" world\n")
+        except Exception as e:
+            pytest.fail(f"printer raised {e}")
+
+
+class TestIntegration:
+    """Integration tests for formatting utilities."""
+    
+    def test_callback_handler_simulation(self):
+        """Test simulating a callback handler usage."""
+        # Simulate ConfigurableCallbackHandler behavior
+        printer = create_auto_printer()
+        response_prefix = "<b><darkcyan>🤖 Assistant:</darkcyan></b> "
+        
+        try:
+            # Print prefix
+            printer(response_prefix, end="", flush=True)
+            
+            # Print message parts
+            printer("Hello", end="", flush=True)
+            printer(" world", end="", flush=True)
+            printer("\n")
+        except Exception as e:
+            pytest.fail(f"callback simulation raised {e}")
+    
+    def test_different_format_types(self):
+        """Test handling different format types in sequence."""
+        printer = create_auto_printer()
+        
+        try:
+            # HTML
+            printer("<b>HTML</b>")
+            
+            # ANSI
+            printer("\x1b[1mANSI\x1b[0m")
+            
+            # Plain
+            printer("Plain")
+        except Exception as e:
+            pytest.fail(f"different format types raised {e}")
+
+
+class TestDocstrings:
+    """Test that docstrings are present and informative."""
+    
+    def test_detect_format_type_docstring(self):
+        """Test detect_format_type has docstring."""
+        assert detect_format_type.__doc__ is not None
+        assert "Detect the format type" in detect_format_type.__doc__
+    
+    def test_auto_format_docstring(self):
+        """Test auto_format has docstring."""
+        assert auto_format.__doc__ is not None
+        assert "Auto-detect format type" in auto_format.__doc__
+    
+    def test_print_auto_formatted_docstring(self):
+        """Test print_auto_formatted has docstring."""
+        assert print_auto_formatted.__doc__ is not None
+        assert "Print text with auto-detected formatting" in print_auto_formatted.__doc__
+    
+    def test_create_auto_printer_docstring(self):
+        """Test create_auto_printer has docstring."""
+        assert create_auto_printer.__doc__ is not None
+        assert "Create a printer function" in create_auto_printer.__doc__

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0/repl_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repl-toolkit
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Python toolkit for building interactive REPL and headless interfaces with action support
 Author-email: REPL Toolkit Contributors <martin.j.bartlett@gmail.com>
 License: MIT
@@ -639,3 +639,109 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
 - Built on [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) for terminal handling
 - Logging by [loguru](https://github.com/Delgan/loguru) for structured logs
 - Inspired by modern CLI tools and REPL interfaces
+
+## Formatting Utilities
+
+REPL Toolkit includes utilities for automatically detecting and applying formatted text (HTML or ANSI) without needing to explicitly wrap text in format types.
+
+### Auto-Format Detection
+
+The formatting utilities can automatically detect whether text contains HTML tags, ANSI escape codes, or is plain text:
+
+```python
+from repl_toolkit import detect_format_type, auto_format, print_auto_formatted
+
+# Detect format type
+detect_format_type("<b>Bold</b>")  # Returns: 'html'
+detect_format_type("\x1b[1mBold\x1b[0m")  # Returns: 'ansi'
+detect_format_type("Plain text")  # Returns: 'plain'
+
+# Auto-format and print
+print_auto_formatted("<b>Bold HTML</b>")  # Automatically applies HTML formatting
+print_auto_formatted("\x1b[1mBold ANSI\x1b[0m")  # Automatically applies ANSI formatting
+print_auto_formatted("Plain text")  # Prints as-is
+```
+
+### Creating Auto-Printers
+
+The `create_auto_printer()` function creates a printer that can be used as a drop-in replacement for `print()` with automatic format detection:
+
+```python
+from repl_toolkit import create_auto_printer
+
+# Create a printer
+printer = create_auto_printer()
+
+# Use it like print()
+printer("<b>Bold text</b>")  # HTML formatting applied
+printer("\x1b[1mANSI bold\x1b[0m")  # ANSI formatting applied
+printer("Plain text")  # No formatting
+
+# Works with all print() parameters
+printer("<b>Prefix:</b> ", end="", flush=True)
+printer("Hello world\n")
+```
+
+### Integration with Callback Handlers
+
+The auto-printer is particularly useful for integrating with callback handlers from other libraries:
+
+```python
+from repl_toolkit import create_auto_printer
+from some_library import CallbackHandler
+
+# Create handler with auto-formatting printer
+handler = CallbackHandler(
+    response_prefix="<b><darkcyan>🤖 Assistant:</darkcyan></b> ",
+    printer=create_auto_printer()  # Automatically formats HTML tags
+)
+
+# The response_prefix will be properly formatted without needing
+# to explicitly wrap it in HTML() or ANSI()
+```
+
+### Format Detection Rules
+
+The auto-detection uses the following rules:
+
+1. **ANSI Detection**: Looks for ANSI escape codes (`\x1b[...m`)
+   - Pattern: `\x1b\[[0-9;]*m`
+   - Examples: `\x1b[1m`, `\x1b[31;1m`
+
+2. **HTML Detection**: Looks for HTML-like tags
+   - Pattern: `</?[a-zA-Z][a-zA-Z0-9]*\s*/?>`
+   - Examples: `<b>`, `</b>`, `<darkcyan>`, `<tag/>`
+   - Avoids false positives: `a < b`, `<123>`, `<_tag>`
+
+3. **Plain Text**: Everything else
+
+### API Reference
+
+#### `detect_format_type(text: str) -> str`
+Detect the format type of a text string.
+
+**Returns**: `'ansi'`, `'html'`, or `'plain'`
+
+#### `auto_format(text: str)`
+Auto-detect format type and return appropriate formatted text object.
+
+**Returns**: `HTML`, `ANSI`, or `str` object
+
+#### `print_auto_formatted(text: str, **kwargs) -> None`
+Print text with auto-detected formatting.
+
+**Parameters**: Same as `print_formatted_text()` from prompt_toolkit
+
+#### `create_auto_printer() -> Callable`
+Create a printer function with auto-format detection.
+
+**Returns**: Callable with signature `printer(text: str, **kwargs)`
+
+### Example
+
+See `examples/formatting_demo.py` for a complete demonstration of the formatting utilities.
+
+```bash
+python examples/formatting_demo.py
+```
+

{repl_toolkit-1.0.0 → repl_toolkit-1.1.0}/repl_toolkit.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 repl_toolkit/__init__.py
 repl_toolkit/async_repl.py
+repl_toolkit/formatting.py
 repl_toolkit/headless_repl.py
 repl_toolkit/ptypes.py
 repl_toolkit.egg-info/PKG-INFO
@@ -17,5 +18,6 @@ repl_toolkit/actions/shell.py
 repl_toolkit/tests/__init__.py
 repl_toolkit/tests/test_actions.py
 repl_toolkit/tests/test_async_repl.py
+repl_toolkit/tests/test_formatting.py
 repl_toolkit/tests/test_headless.py
 repl_toolkit/tests/test_types.py