Types

API Reference - Types

Complete API reference for the wolpie.types module.

safe

Classes

TStr

Bases: str

A string subclass that automatically truncates its content to a maximum length when created or modified through string operations. The TStr class uses the pretty_str function for truncation under the hood.

Example

from wolpie.types import TStr
# or from wolpie import TStr

# Basic creation
s = TStr("hello world", max_chars=10)
print(s)  # Output: "hello w..."
print(len(s))  # Output: 10

# String operations maintain TStr type and truncation
s1 = TStr("hello", max_chars=10)
s2 = s1 + " world"
print(type(s2))  # Output: <class 'wolpie.types.safe.TStr'>
print(s2)  # Output: "hello w..."

Attributes

max_chars instance-attribute

max_chars

placeholder instance-attribute

placeholder

Functions

pretty_str

pretty_str(text, max_chars, placeholder='...')

A function that truncates a string to a maximum number of characters, appending a placeholder if truncation occurs.

Example

from wolpie.types import pretty_str
# or from wolpie import pretty_str

# Basic usage
result = pretty_str("hello world", max_chars=10)
print(result)  # Output: "hello w..."

# No truncation needed
result = pretty_str("short", max_chars=10)
print(result)  # Output: "short"

# Custom placeholder
result = pretty_str("hello world", max_chars=10, placeholder=">>")
print(result)  # Output: "hello wo>>"

# Empty placeholder
result = pretty_str("hello world", max_chars=5, placeholder="")
print(result)  # Output: "hello"

Parameters:

Name	Type	Description	Default
text	str	The string to be truncated.	required
max_chars	int	The maximum number of characters allowed in the output string.	required
placeholder	str	The string to append if truncation occurs. Default is '...'.	'...'

Returns:

Type	Description
str	The truncated string, if necessary, with the placeholder appended.

Raises:

Type	Description
TypeError	If text is not a string.
ValueError	If max_chars is not a positive integer or if placeholder length is greater than or equal to max_chars.
TypeError	If placeholder is not a string.
ValueError	If placeholder length is greater than or equal to max_chars.

Source code in src/wolpie/types/safe.py

def pretty_str(
    text: str,
    max_chars: int,
    placeholder: str = "...",
) -> str:
    """A function that truncates a string to a maximum number of characters,
    appending a placeholder if truncation occurs.

    Example:
        ```python
        from wolpie.types import pretty_str
        # or from wolpie import pretty_str

        # Basic usage
        result = pretty_str("hello world", max_chars=10)
        print(result)  # Output: "hello w..."

        # No truncation needed
        result = pretty_str("short", max_chars=10)
        print(result)  # Output: "short"

        # Custom placeholder
        result = pretty_str("hello world", max_chars=10, placeholder=">>")
        print(result)  # Output: "hello wo>>"

        # Empty placeholder
        result = pretty_str("hello world", max_chars=5, placeholder="")
        print(result)  # Output: "hello"
        ```

    Args:
        text: The string to be truncated.
        max_chars: The maximum number of characters allowed in the output string.
        placeholder: The string to append if truncation occurs. Default is '...'.

    Returns:
        The truncated string, if necessary, with the placeholder appended.

    Raises:
        TypeError: If text is not a string.
        ValueError: If max_chars is not a positive integer or if placeholder length is greater than or
            equal to max_chars.
        TypeError: If placeholder is not a string.
        ValueError: If placeholder length is greater than or equal to max_chars.
    """

    # ====> VALIDATION
    if not isinstance(text, str):
        _err: str = f"text must be a string, not {type(text).__name__}"
        raise TypeError(_err)
    if not isinstance(max_chars, int) or max_chars <= 0:
        _err: str = f"max_chars must be a positive integer, got {max_chars}"
        raise ValueError(_err)
    if not isinstance(placeholder, str):
        _err: str = f"placeholder must be a string, not {type(placeholder).__name__}"
        raise TypeError(_err)
    if len(placeholder) >= max_chars:
        _err: str = f"placeholder length ({len(placeholder)}) must be smaller than max_chars ({max_chars})"
        raise ValueError(_err)

    # ====> TRUNCATE
    if len(text) <= max_chars:
        return text
    return text[: max_chars - len(placeholder)] + placeholder