textwrap — Text wrapping and filling

Вихідний код: Lib/textwrap.py

---

Модуль textwrap надає деякі зручні функції, а також TextWrapper, клас, який виконує всю роботу. Якщо ви просто обтікаєте або заповнюєте один або два текстові рядки, зручні функції мають бути достатньо хорошими; інакше вам слід використовувати екземпляр TextWrapper для ефективності.

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Обертає один абзац у текст (рядок), щоб кожен рядок містив щонайбільше width символів. Повертає список вихідних рядків без кінцевих нових рядків.

Необов’язкові аргументи ключового слова відповідають атрибутам екземпляра TextWrapper, задокументованим нижче.

Перегляньте метод TextWrapper.wrap(), щоб дізнатися більше про те, як поводиться wrap().

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Переносить окремий абзац у текст і повертає один рядок, що містить перенесений абзац. fill() є скороченням для

"\n".join(wrap(text, ...))

Зокрема, fill() приймає ті самі ключові аргументи, що й wrap().

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Згорніть і скоротіть заданий текст, щоб відповідати заданій ширині.

First the whitespace in text is collapsed (all whitespace is replaced by single spaces). If the result fits in the width, it is returned. Otherwise, enough words are dropped from the end so that the remaining words plus the placeholder fit within width:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

Необов’язкові аргументи ключового слова відповідають атрибутам екземпляра TextWrapper, задокументованим нижче. Зауважте, що пробіли згортаються перед тим, як текст передається до функції TextWrapper fill(), тому змінюється значення tabsize, expand_tabs, drop_whitespace і replace_whitespace не матимуть ефекту.

Нове в версії 3.4.

textwrap.dedent(text)

Видаліть усі загальні пробіли на початку кожного рядка в тексті.

Це можна використовувати для того, щоб рядки в потрійних лапках вирівнювалися з лівим краєм дисплея, водночас представляючи їх у вихідному коді у формі відступу.

Зауважте, що табуляції та пробіли розглядаються як пробіли, але вони не однакові: рядки " hello" і "\thello" вважаються такими, що не мають спільних пробілів на початку.

Рядки, що містять лише пробіли, ігноруються у вхідних даних і нормалізуються до одного символу нового рядка у вихідних даних.

Наприклад:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'

textwrap.indent(text, prefix, predicate=None)

Додати префікс до початку виділених рядків у тексті.

Рядки розділяються викликом text.splitlines(True).

За замовчуванням префікс додається до всіх рядків, які не складаються лише з пробілів (включаючи будь-які закінчення рядків).

Наприклад:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

Необов’язковий аргумент предикат може використовуватися для контролю того, які рядки мають відступ. Наприклад, можна легко додати префікс навіть до порожніх рядків із пробілами:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

Нове в версії 3.3.

wrap(), fill() і shorten() працюють, створюючи екземпляр TextWrapper і викликаючи для нього один метод. Цей екземпляр не використовується повторно, тому для програм, які обробляють багато текстових рядків за допомогою wrap() та/або fill(), може бути ефективнішим створити власний об’єкт TextWrapper.

Текст бажано розміщувати через пробіли та одразу після дефісів у словах із переносами; лише тоді довгі слова будуть розбиті, якщо необхідно, якщо TextWrapper.break_long_words не встановлено на false.

class textwrap.TextWrapper(**kwargs)

Конструктор TextWrapper приймає декілька необов’язкових ключових аргументів. Кожен аргумент ключового слова відповідає атрибуту екземпляра, тому, наприклад,

wrapper = TextWrapper(initial_indent="* ")

те саме, що

wrapper = TextWrapper()
wrapper.initial_indent = "* "

You can re-use the same TextWrapper object many times, and you can change any of its options through direct assignment to instance attributes between uses.

Атрибути екземпляра TextWrapper (та ключові аргументи конструктора) такі:

width

(за замовчуванням: 70) Максимальна довжина перенесених рядків. Поки у вхідному тексті немає окремих слів, довші за width, TextWrapper гарантує, що жоден вихідний рядок не буде довшим за width символів.

expand_tabs

(default: True) If true, then all tab characters in text will be expanded to spaces using the expandtabs() method of text.

tabsize

(за замовчуванням: 8) Якщо expand_tabs має значення true, тоді всі символи табуляції в тексті буде розгорнуто до нуля або більше пробілів, залежно від поточного стовпця та заданого розміру табуляції.

Нове в версії 3.3.

replace_whitespace

(за замовчуванням: True). Якщо істинно, після розгортання табуляції, але перед обтіканням, метод wrap() замінить кожен пробільний символ на один пробіл. Замінені пробіли: символи табуляції, нового рядка, вертикальної табуляції, переходу форми та повернення каретки ('\t\n\v\f\r').

Примітка

Якщо expand_tabs має значення false і replace_whitespace має значення true, кожен символ табуляції буде замінено одним пробілом, що не те саме, що розширення табуляції.

Примітка

Якщо replace_whitespace має значення false, новий рядок може з’являтися в середині рядка та викликати дивний результат. З цієї причини текст має бути розділений на абзаци (за допомогою str.splitlines() або подібного), які переносять окремо.

drop_whitespace

(за замовчуванням: True). Якщо true, пробіли на початку та в кінці кожного рядка (після обтікання, але перед відступом) видаляються. Проте пробіли на початку абзацу не видаляються, якщо за ними слідують непробіли. Якщо відкинутий пробіл займає весь рядок, весь рядок буде відкинуто.

initial_indent

(за замовчуванням: '') Рядок, який буде додано до першого рядка обгорнутого виводу. Зараховується до довжини першого рядка. Порожній рядок не має відступу.

subsequent_indent

(за замовчуванням: '') Рядок, який буде додано до всіх рядків обгорнутого виводу, крім першого. Враховується в довжину кожного рядка, крім першого.

fix_sentence_endings

(default: False) If true, TextWrapper attempts to detect sentence endings and ensure that sentences are always separated by exactly two spaces. This is generally desired for text in a monospaced font. However, the sentence detection algorithm is imperfect: it assumes that a sentence ending consists of a lowercase letter followed by one of '.', '!', or '?', possibly followed by one of '"' or "'", followed by a space. One problem with this algorithm is that it is unable to detect the difference between «Dr.» in

[...] Dr. Frankenstein's monster [...]

і «Пляма». в

[...] See Spot. See Spot run [...]

fix_sentence_endings за замовчуванням має значення false.

Оскільки алгоритм виявлення речень покладається на string.lowercase для визначення «маленької літери» та умовність використання двох пробілів після крапки для розділення речень в одному рядку, він є специфічним для англомовних текстів.

break_long_words

(за замовчуванням: True). Якщо значення true, то слова, довші за width, будуть розбиті, щоб переконатися, що жоден рядок не буде довшим за width. Якщо значення false, довгі слова не будуть розбиті, а деякі рядки можуть бути довшими за width. (Довгі слова будуть розміщені в рядку самостійно, щоб мінімізувати кількість перевищень width.)

break_on_hyphens

(за замовчуванням: True). Якщо істинно, перенесення відбуватиметься переважно через пробіли та одразу після дефісів у складних словах, як це прийнято в англійській мові. Якщо false, лише пробіли вважатимуться потенційно хорошими місцями для розриву рядків, але вам потрібно встановити break_long_words на false, якщо ви хочете справді нероздільні слова. Поведінка за замовчуванням у попередніх версіях полягала в тому, що завжди дозволялося розривати слова через дефіс.

max_lines

(за замовчуванням: None). Якщо не None, то вихідні дані міститимуть щонайбільше max_lines рядків із заповнювачем у кінці виведення.

Нове в версії 3.4.

placeholder

(за замовчуванням: ' [...]') Рядок, який відображатиметься в кінці вихідного тексту, якщо його було скорочено.

Нове в версії 3.4.

TextWrapper також надає деякі публічні методи, аналогічні зручним функціям на рівні модуля:

wrap(text)

Переносить окремий абзац у текст (рядок), щоб кожен рядок містив щонайбільше width символів. Усі параметри обтікання беруться з атрибутів екземпляра екземпляра TextWrapper. Повертає список вихідних рядків без кінцевих нових рядків. Якщо обернутий результат не має вмісту, повернутий список порожній.

fill(text)

Переносить один абзац у текст і повертає один рядок, що містить перенесений абзац.