Types

Types#

The wolpie.types package provides type-safe utilities for string manipulation and truncation.

Functions#

pretty_str#

This function was inspired by Python’s built-in textwrap.shorten but offers improved pretty string truncation capabilities.

import textwrap

textwrap.shorten("Hello world!", width=10, placeholder="...")
# Output: 'Hello...'

but this is 8 long. So it is shorter than the specified width of 10, but that’s not what I want.

I want it to be exactly 10 long, including the placeholder. So I want:

"Hello world"[:10-3] + "..."

This is what inspired the pretty_str function and later the TStr class.

wolpie.types.safe.pretty_str(text, max_chars, placeholder='...')[source]#

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

Example Usage:

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:

  • text (str) – The string to be truncated.

  • max_chars (int) – The maximum number of characters allowed in the output string.

  • placeholder (str) – The string to append if truncation occurs. Default is ‘…’.

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.

Return str:

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

Return type:

str

Classes#

TStr#

I liked the idea of pretty string truncation so much that I wanted to implement it as a class that would automatically truncate itself when it exceeds a specified length.

Why would it be better?

Instead of having to call a function every time you want to truncate a string, you can just use the TStr class and it will take care of it for you.

It’s the difference between:

s = "Hello world!"
s += " Adding more text to make it even longer."
s = pretty_str(s, max_length=10)
print(s)  # Output: 'Hello w...'

and

s = TStr("Hello world!", max_length=10)
s += " Adding more text to make it even longer."
print(s)  # Output: 'Hello w...'
class wolpie.types.safe.TStr(value, max_chars=None, placeholder='...')[source]#

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 Usage:

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..."
Parameters:

value (str) – The initial string value.

Return TStr:

A new TStr instance.

Return type:

Self

max_chars: int | None#
placeholder: str#
Contents