Reference

tamal

break_lines

break_lines(
    text,
    width,
    hyphen=DEFAULT_HYPHEN,
    soft_hyphen=DEFAULT_SOFT_HYPHEN,
    hyphens=DEFAULT_HYPHENS,
    whitespaces=DEFAULT_WHITESPACES,
)

Parameters:

Name	Type	Description	Default
text	str	The text to break into lines.	required
width	int	The target width.	required
hyphen	str	The string to use as hyphen when breaking a word. Can be multi-character string.	DEFAULT_HYPHEN
soft_hyphen	str	Soft hyphens existing in the text are used for breaking. If a soft hyphen is used for breaking, it will be replaced by a hyphen. Soft hyphens are considered "invisible", so they are not accounted against the target width. (The idea is that you add soft hyphens before breaking, break the text and remove the soft hyphens afterwards.) Can be multi-character string.	DEFAULT_SOFT_HYPHEN
hyphens	set[str]	Existing hyphens in the text are used for breaking (and left unchanged). Can be multi-character strings.	DEFAULT_HYPHENS
whitespaces	set[str]	Whitespace strings are used for breaking. Trailing whitespace strings at the end of a broken line will be removed. Can be multi-character strings. paragraph marker.	DEFAULT_WHITESPACES

Returns:

Type	Description
list[str]	The resulting lines.

Examples:

>>> text = 'Hello, World! Nice to meet you.'
>>> target_width = 15
>>> break_lines(text, target_width)
['Hello, World!', 'Nice to meet', 'you.']

Source code in tamal/_wrap.py

def break_lines(
    text: str,
    width: int,
    hyphen: str = DEFAULT_HYPHEN,
    soft_hyphen: str = DEFAULT_SOFT_HYPHEN,
    hyphens: set[str] = DEFAULT_HYPHENS,
    whitespaces: set[str] = DEFAULT_WHITESPACES,
) -> list[str]:
    """
    Parameters:
        text: The text to break into lines.

        width: The target width.

        hyphen: The string to use as hyphen when breaking a word. Can be
            multi-character string.

        soft_hyphen: Soft hyphens existing in the text are used for breaking.
            If a soft hyphen is used for breaking, it will be replaced by a
            hyphen. Soft hyphens are considered "invisible", so they are not
            accounted against the target width. (The idea is that you add soft
            hyphens before breaking, break the text and remove the soft hyphens
            afterwards.) Can be multi-character string.

        hyphens: Existing hyphens in the text are used for breaking (and left
            unchanged). Can be multi-character strings.

        whitespaces: Whitespace strings are used for breaking. Trailing
            whitespace strings at the end of a broken line will be removed. Can
            be multi-character strings.
            paragraph marker.

    Returns:
        The resulting lines.

    Examples:
    ```
    >>> text = 'Hello, World! Nice to meet you.'
    >>> target_width = 15
    >>> break_lines(text, target_width)
    ['Hello, World!', 'Nice to meet', 'you.']

    ```
    """
    lines = []
    while True:
        head, tail = chunk(
            text=text,
            width=width,
            hyphen=hyphen,
            soft_hyphen=soft_hyphen,
            hyphens=hyphens,
            whitespaces=whitespaces,
        )
        for blank in whitespaces:
            head = head.replace(blank, " ")
        lines.append(head)
        if not tail:
            break
        text = tail
    return lines

chunk

chunk(
    text,
    width,
    hyphen=DEFAULT_HYPHEN,
    soft_hyphen=DEFAULT_SOFT_HYPHEN,
    hyphens=DEFAULT_HYPHENS,
    whitespaces=DEFAULT_WHITESPACES,
)

Splitting at hyphens, soft hyphen or whitespace, or forcing a break by adding a hyphen,returning the head with maximum width, and the remaining tail.

Parameters:

Name	Type	Description	Default
text	str	The text to break.	required
width	int	The target width.	required
hyphen	str	The string to use as hyphen when breaking a word. Can be multi-character string.	DEFAULT_HYPHEN
soft_hyphen	str	Soft hyphens existing in the text are used for breaking. If a soft hyphen is used for breaking, it will be replaced by a hyphen. Soft hyphens are considered "invisible", so they are not accounted against the target width. (The idea is that you add soft hyphens before breaking, break the text and remove the soft hyphens afterwards.) Can be multi-character string.	DEFAULT_SOFT_HYPHEN
hyphens	set[str]	Existing hyphens in the text are used for breaking (and left unchanged). Can be multi-character strings.	DEFAULT_HYPHENS
whitespaces	set[str]	Whitespace strings are used for breaking. Trailing whitespace strings at the end of a broken line will be removed. Can be multi-character strings. paragraph marker.	DEFAULT_WHITESPACES

Returns:

Type	Description
tuple[Head, Tail]	Head and Tail.

Examples:

>>> text = 'Hello, World! Nice to meet you.'
>>> target_width = 15
>>> chunk(text, target_width)
('Hello, World!', 'Nice to meet you.')

Source code in tamal/_wrap.py

def chunk(
    text: str,
    width: int,
    hyphen: str = DEFAULT_HYPHEN,
    soft_hyphen: str = DEFAULT_SOFT_HYPHEN,
    hyphens: set[str] = DEFAULT_HYPHENS,
    whitespaces: set[str] = DEFAULT_WHITESPACES,
) -> tuple[Head, Tail]:
    """
    Splitting at hyphens, soft hyphen or whitespace, or forcing a break by
    adding a hyphen,returning the head with maximum width, and the remaining
    tail.

    Parameters:
        text: The text to break.

        width: The target width.

        hyphen: The string to use as hyphen when breaking a word. Can be
            multi-character string.

        soft_hyphen: Soft hyphens existing in the text are used for breaking.
            If a soft hyphen is used for breaking, it will be replaced by a
            hyphen. Soft hyphens are considered "invisible", so they are not
            accounted against the target width. (The idea is that you add soft
            hyphens before breaking, break the text and remove the soft hyphens
            afterwards.) Can be multi-character string.

        hyphens: Existing hyphens in the text are used for breaking (and left
            unchanged). Can be multi-character strings.

        whitespaces: Whitespace strings are used for breaking. Trailing
            whitespace strings at the end of a broken line will be removed. Can
            be multi-character strings.
            paragraph marker.

    Returns:
        Head and Tail.

    Examples:
    ```
    >>> text = 'Hello, World! Nice to meet you.'
    >>> target_width = 15
    >>> chunk(text, target_width)
    ('Hello, World!', 'Nice to meet you.')

    ```
    """
    hyphens.add(hyphen)
    width = _visible_index(text, width, soft_hyphen)
    if len(text) <= width:
        return text, ""
    # Sorting break_strings so that longer hyphens prevail in break_indices
    break_strings = sorted(
        list(hyphens | {soft_hyphen} | whitespaces), key=lambda s: len(s)
    )
    break_indices = {
        _latest_occurrence(char, text[: width + len(char) - 1]): char
        for char in break_strings
    }
    break_index = max(break_indices.keys())
    if not break_index:
        return (text[: width - 1] + hyphen, text[width - 1 :])

    char = break_indices[break_index]
    if char in whitespaces:
        return text[:break_index], text[break_index + len(char) :]
    if char in hyphens:
        break_index += len(char)
        return (text[:break_index], text[break_index:])
    if char == soft_hyphen:
        # Replacing the soft hyphen with a hyphen when breaking at it
        return (
            text[:break_index] + hyphen,
            text[break_index + len(char) :],
        )
    raise Exception("Shouldn't be getting here")

wrap

wrap(
    text,
    width,
    hyphen=DEFAULT_HYPHEN,
    soft_hyphen=DEFAULT_SOFT_HYPHEN,
    hyphens=DEFAULT_HYPHENS,
    whitespaces=DEFAULT_WHITESPACES,
    paragraph=DEFAULT_PARAGRAPH,
    new_paragraph=DEFAULT_PARAGRAPH,
)

Parameters:

Name	Type	Description	Default
text	str	The text to wrap.	required
width	int	The target width.	required
hyphen	str	The string to use as hyphen when breaking a word. Can be multi-character string.	DEFAULT_HYPHEN
soft_hyphen	str	Soft hyphens existing in the text are used for breaking. If a soft hyphen is used for breaking, it will be replaced by a hyphen. Soft hyphens are considered "invisible", so they are not accounted against the target width. (The idea is that you add soft hyphens before wrapping, wrap the text and remove the soft hyphens afterwards.) Can be multi-character string.	DEFAULT_SOFT_HYPHEN
hyphens	set[str]	Existing hyphens in the text are used for breaking (and left unchanged). Can be multi-character strings.	DEFAULT_HYPHENS
whitespaces	set[str]	Whitespace strings are used for breaking. Trailing whitespace strings at the end of a broken line will be removed. Can be multi-character strings.	DEFAULT_WHITESPACES
paragraph	str	Marker for the beginning of a new paragraph. Paragraphs marked as such will be represented as paragraphs in the wrapped result. If you want to treat existing line breaks as "hard" line breaks, use the line break chacter both as paragraph marker and as argument for new_paragraph.	DEFAULT_PARAGRAPH
new_paragraph	str	The string to mark a paragraph in the wrapped result.	DEFAULT_PARAGRAPH

Returns:

Type	Description
str	The wrapped text as a string.

Examples:

>>> text = "Hello, World!++++Nice to meet you. This text is a bit long."
>>> target_width = 15
>>> print(wrap(text, target_width, paragraph="++++"))
Hello, World!
<BLANKLINE>
Nice to meet
you. This text
is a bit long.

Source code in tamal/_wrap.py

def wrap(
    text: str,
    width: int,
    hyphen: str = DEFAULT_HYPHEN,
    soft_hyphen: str = DEFAULT_SOFT_HYPHEN,
    hyphens: set[str] = DEFAULT_HYPHENS,
    whitespaces: set[str] = DEFAULT_WHITESPACES,
    paragraph: str = DEFAULT_PARAGRAPH,
    new_paragraph: str = DEFAULT_PARAGRAPH,
) -> str:
    """
    Parameters:
        text: The text to wrap.

        width: The target width.

        hyphen: The string to use as hyphen when breaking a word. Can be
            multi-character string.

        soft_hyphen: Soft hyphens existing in the text are used for breaking.
            If a soft hyphen is used for breaking, it will be replaced by a
            hyphen. Soft hyphens are considered "invisible", so they are not
            accounted against the target width. (The idea is that you add soft
            hyphens before wrapping, wrap the text and remove the soft hyphens
            afterwards.) Can be multi-character string.

        hyphens: Existing hyphens in the text are used for breaking (and left
            unchanged). Can be multi-character strings.

        whitespaces: Whitespace strings are used for breaking. Trailing
            whitespace strings at the end of a broken line will be removed. Can
            be multi-character strings.

        paragraph: Marker for the beginning of a new paragraph. Paragraphs
            marked as such will be represented as paragraphs in the wrapped
            result. If you want to treat existing line breaks as "hard" line
            breaks, use the line break chacter both as paragraph marker and as
            argument for new_paragraph.

        new_paragraph: The string to mark a paragraph in the wrapped result.

    Returns:
        The wrapped text as a string.

    Examples:
    ```
    >>> text = "Hello, World!++++Nice to meet you. This text is a bit long."
    >>> target_width = 15
    >>> print(wrap(text, target_width, paragraph="++++"))
    Hello, World!
    <BLANKLINE>
    Nice to meet
    you. This text
    is a bit long.

    ```
    """
    return new_paragraph.join(
        [
            "\n".join(
                break_lines(
                    p,
                    width=width,
                    hyphen=hyphen,
                    soft_hyphen=soft_hyphen,
                    hyphens=hyphens,
                    whitespaces=whitespaces,
                )
            )
            for p in text.split(paragraph)
        ]
    )

tamal.Head module-attribute

Head = str

tamal.Tail module-attribute

Tail = str

tamal.defaults

tamal.defaults.DEFAULT_HYPHEN module-attribute

DEFAULT_HYPHEN = '-'

tamal.defaults.DEFAULT_HYPHENS module-attribute

DEFAULT_HYPHENS = {'-', '–', '—'}

tamal.defaults.DEFAULT_SOFT_HYPHEN module-attribute

DEFAULT_SOFT_HYPHEN = '·'

tamal.defaults.DEFAULT_WHITESPACES module-attribute

DEFAULT_WHITESPACES = {' ', '\t', '\n'}

tamal.defaults.DEFAULT_PARAGRAPH module-attribute

DEFAULT_PARAGRAPH = '\n\n'