Textlinebreaker

Description

Text Line Breaker is a Python utility class that splits text into multiple lines of a specified maximum width.
It supports alignment options and dynamic width calculation, making it useful for formatting and displaying text in terminal applications.

Features

• Break text into multiple lines with a configurable maximum width.
• Alignment options: left, center, right.
• Dynamic width selection ("min", "2words", "max", or integer values).
• Supports input as string or list of strings.
• Class-based design with built-in string conversion, iteration, and border formatting.

Latest Version 1.0.0

• New class-based API: TextLineBreaker replaces the old split_line function.
• Added methods:
  • __str__() → return formatted text as string
  • __iter__() → iterate through formatted lines
  • .delimiter(char="|") → wrap lines with border characters
• Improved input handling (lists, tabs, fallback terminal width).
• Alignment normalized: "centre" maps to "center".
• Safer and more flexible width validation.

⚠️ Breaking change:
The old function split_line() is no longer the main entry point.
Use the TextLineBreaker class instead.

Table of Contents

• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Parameters
  • Examples
• Migration from 0.2.0
• Contributing
• License

Getting Started

Prerequisites

This package relies only on the Python standard library and does not require additional dependencies.

Installation

• Install the package with pip:

pip install textlinebreaker

• Or upgrade it:

pip install --upgrade textlinebreaker

• Import the class in your program:

from textlinebreaker import TextLineBreaker

Usage

The TextLineBreaker class takes a string or list of strings and breaks it into lines according to the specified maximum width and alignment. The default width is the terminal width.

Parameters

The TextLineBreaker class accepts the following parameters:

• text: the input text.

  • allowed values: str, list[str]

• max_width: maximum width for each line.

  • allowed values: integer (≥ 9, ≤ terminal width), "min", "2words", "max"
  • default: terminal width

• alignment: text alignment inside the line.

  • allowed values: "left", "right", "center", "centre"
  • default: "left"

Examples

from textlinebreaker import TextLineBreaker

text = "Text Line Breaker is a Python class that can split your text into multiple lines and align them neatly."

# Example 1: Left alignment, fixed width
breaker1 = TextLineBreaker(text, max_width=30)
print(breaker1)

# Example 2: Center alignment with borders
breaker2 = TextLineBreaker(text, max_width=30, alignment="center")
print(breaker2.delimiter(char="|"))

# Example 3: Right alignment, width="2words"
breaker3 = TextLineBreaker(text, max_width="2words", alignment="right")
for line in breaker3:
    print(line)

Example output:

=== Left aligned ===
Text Line Breaker is a Python 
class that can split your text
into multiple lines and align 
them neatly.

=== Center aligned with borders ===
|   Text Line Breaker is a   |
|Python class that can split |
|  your text into multiple   |
|lines and align them neatly.|

=== Right aligned ===
Text Line
  Breaker
     is a
   Python
    class
 that can
    split
your text
     into
 multiple
lines and
    align
     them
  neatly.

Migration from 0.2.0

In v0.2.0, you used a function:

from textlinebreaker import split_line

text = "Hello world"
lines = split_line(text, max_width=20, alignment="center")

for line in lines:
    print(line)

In v1.0.0, use the class instead:

from textlinebreaker import TextLineBreaker

text = "Hello world"
breaker = TextLineBreaker(text, max_width=20, alignment="center")

for line in breaker:
    print(line)

Key differences:

• split_line() → replaced by TextLineBreaker class.
• Iterating works directly on the class (for line in breaker).
• print(breaker) prints the whole formatted block.
• .delimiter("|") adds borders around the text.

Contributing

If you'd like to contribute to this project, please follow these steps:

1. Fork the repository on GitHub.
2. Clone the fork to your local machine.
3. Create a new branch for your feature or bug fix.
4. Make your changes and commit them.
5. Push the changes to your fork on GitHub.
6. Create a pull request to the original repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.