textwrap — 텍스트 줄바꿈과 채우기

textwrap — 텍스트 줄바꿈과 채우기

textwrap 모듈은 텍스트를 자동으로 줄바꿈하거나 채우는 데 쓰는 모듈이에요. 실제 일을 하는 건 TextWrapper 클래스지만, 편의 함수 몇 개도 함께 제공합니다. 텍스트 한두 개만 줄바꿈·채우기할 거라면 편의 함수로 충분하고, 많은 문자열을 처리해야 한다면 효율을 위해 TextWrapper 인스턴스를 직접 쓰는 게 좋아요.

출처: Python 표준 라이브러리 — textwrap

본문

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=' [...]')

text(문자열) 안의 단일 문단을 줄바꿈해서, 각 줄이 최대 width 문자 길이를 넘지 않게 해요. 마지막 개행 없이 출력 줄들의 리스트를 반환합니다.

선택 키워드 인자들은 아래에 문서화된 TextWrapper의 인스턴스 속성에 대응해요. wrap()이 어떻게 동작하는지 더 자세히 보려면 TextWrapper.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=' [...]')

text 안의 단일 문단을 줄바꿈하고, 줄바꿈된 문단을 담은 단일 문자열을 반환해요. fill()은 다음의 줄임말입니다.

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

특히 fill()은 wrap()과 똑같은 키워드 인자를 받아요.

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

주어진 텍스트를 접어서(collapse) 주어진 width에 맞게 잘라내요.

먼저 text의 공백이 접힙니다(모든 공백이 단일 공백으로 치환). 결과가 width에 맞으면 그대로 반환되고, 아니면 뒤에서부터 단어를 충분히 버려서 남은 단어와 플레이스홀더가 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)

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'

버전 3.14에서 변경: dedent() 함수가 이제 공백 문자만으로 이뤄진 빈 줄도 올바르게 정규화합니다. 이전에는 탭과 공백으로 이뤄진 빈 줄만 정규화했어요.

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

text 안의 선택된 줄 시작에 prefix를 추가해요.

줄들은 text.splitlines(True)를 호출해서 구분됩니다.

기본적으로 prefix는 오로지 공백(줄 끝 포함)만으로 이뤄지지 않은 모든 줄에 추가돼요.

예를 들어:

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

선택 인자 predicate로 어떤 줄을 들여쓸지 제어할 수 있어요. 예를 들어 빈 줄과 공백만 있는 줄에도 prefix를 추가하는 건 아주 쉽죠.

>>> 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 = "* "

같은 TextWrapper 객체를 여러 번 재사용할 수 있고, 사용 사이에 인스턴스 속성에 직접 할당해서 어떤 옵션이든 바꿀 수 있어요.

TextWrapper의 인스턴스 속성(그리고 생성자의 키워드 인자)은 다음과 같아요.

  • width — (기본: 70) 줄바꿈된 줄의 최대 길이. 입력 텍스트에 width보다 긴 개별 단어가 없다면, TextWrapper는 출력 줄 어느 것도 width 문자보다 길어지지 않음을 보장해요.
  • expand_tabs — (기본: True) 참이면 text의 모든 탭 문자가 text의 expandtabs() 메서드로 공백으로 확장됩니다.
  • tabsize — (기본: 8) expand_tabs가 참이면 탭 문자가 현재 열(column)과 주어진 탭 크기에 따라 0개 이상의 공백으로 확장돼요. / 버전 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) 참이면 (줄바꿈 후, 들여쓰기 전) 각 줄의 시작과 끝의 공백이 버려져요. 다만 문단 시작 부분의 공백은 뒤에 비공백이 따라오면 버려지지 않아요. 버려지는 공백이 줄 전체를 차지하면 그 줄 전체가 버려집니다.
  • initial_indent — (기본: '') 줄바꿈 출력의 첫 줄 앞에 붙는 문자열. 첫 줄의 길이에 포함돼요. 빈 문자열은 들여쓰기되지 않습니다.
  • subsequent_indent — (기본: '') 첫 줄을 제외한 줄바꿈 출력의 모든 줄 앞에 붙는 문자열. 첫 줄을 제외한 각 줄의 길이에 포함돼요.
  • fix_sentence_endings — (기본: False) 참이면 TextWrapper가 문장 끝을 감지해서 문장이 항상 정확히 두 개의 공백으로 구분되도록 하려 해요. 이는 일반적으로 고정폭(monospaced) 글꼴의 텍스트에서 바람직해요. 다만 이 문장 감지 알고리즘은 완벽하지 않아요. 문장 끝이 소문자 + '.', '!', '?' 중 하나(선택적으로 '"'나 "'" 중 하나가 뒤따름) + 공백으로 이뤄진다고 가정하죠. 이 알고리즘의 문제 하나는 다음 둘 사이의 차이를 감지하지 못한다는 거예요. 
    [...] Dr. Frankenstein's monster [...]
    과 
    [...] See Spot. See Spot run [...]
    fix_sentence_endings는 기본적으로 false예요. 이 문장 감지 알고리즘은 "소문자"의 정의를 string.lowercase에 의존하고, 문장 구분에 마침표 뒤 두 칸 공백이라는 관례에 의존하므로, 영어 텍스트에 특화돼 있어요.
  • break_long_words — (기본: True) 참이면 width보다 긴 단어는 어떤 줄도 width보다 길어지지 않도록 잘립니다. false면 긴 단어가 잘리지 않고 일부 줄이 width보다 길어질 수 있어요. (긴 단어는 width를 초과하는 양을 최소화하기 위해 한 줄에 단독으로 놓여요.)
  • break_on_hyphens — (기본: True) 참이면 영어 관례대로 공백과 복합어의 하이픈 바로 뒤에서 줄바꿈이 우선돼요. false면 공백만 줄바꿈의 후보 장소로 간주하는데, 정말로 잘리지 않는 단어(insecable words)를 원한다면 break_long_words를 false로 설정해야 해요. 이전 버전의 기본 동작은 하이픈으로 연결된 단어를 항상 잘라도 허용하는 것이었어요.
  • max_lines — (기본: None) None이 아니면 출력이 최대 max_lines 줄만 담고, 출력 끝에 placeholder가 나타나요. / 버전 3.4에서 추가.
  • placeholder — (기본: ' [...]') 텍스트가 잘렸을 때 출력 텍스트 끝에 나타날 문자열. / 버전 3.4에서 추가.

TextWrapper는 모듈 수준 편의 함수에 대응하는 공개 메서드 몇 개도 제공해요.

wrap(text) — text(문자열) 안의 단일 문단을 각 줄이 최대 width 문자 길이가 되도록 줄바꿈해요. 모든 줄바꿈 옵션은 TextWrapper 인스턴스의 인스턴스 속성에서 가져옵니다. 마지막 개행 없는 출력 줄들의 리스트를 반환해요. 줄바꿈된 출력에 내용이 없으면 빈 리스트를 반환합니다.

fill(text) — text 안의 단일 문단을 줄바꿈하고, 줄바꿈된 문단을 담은 단일 문자열을 반환해요.