textwrap --- Gói và điền văn bản

Source code: Lib/textwrap.py

Mô-đun textwrap cung cấp một số chức năng tiện lợi cũng như TextWrapper, lớp thực hiện tất cả công việc. Nếu bạn chỉ gói hoặc điền một hoặc hai chuỗi văn bản thì các chức năng tiện lợi sẽ đủ tốt; nếu không, bạn nên sử dụng phiên bản TextWrapper để đạt hiệu quả.

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

Gói một đoạn văn trong text (một chuỗi) để mỗi dòng có độ dài tối đa là width ký tự. Trả về danh sách các dòng đầu ra, không có dòng mới cuối cùng.

Các đối số từ khóa tùy chọn tương ứng với các thuộc tính phiên bản của TextWrapper, được ghi lại bên dưới.

Xem phương pháp TextWrapper.wrap() để biết thêm chi tiết về cách hoạt động của 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=' [...]')

Gói đoạn văn đơn trong text và trả về một chuỗi chứa đoạn văn được gói. fill() là viết tắt của

"\n".join(bọc(văn bản, ...))

Đặc biệt, fill() chấp nhận chính xác các đối số từ khóa giống như wrap().

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

Thu gọn và cắt bớt text đã cho để vừa với width đã cho.

Đầu tiên, khoảng trắng trong text được thu gọn (tất cả khoảng trắng được thay thế bằng khoảng trắng đơn). Nếu kết quả phù hợp với width, nó sẽ được trả về. Nếu không, đủ số từ sẽ bị loại bỏ ở cuối để các từ còn lại cộng với placeholder nằm gọn trong width:

>>> textwrap.shorten("Xin chào thế giới!", width=12)
'Xin chào thế giới!'
>>> textwrap.shorten("Xin chào thế giới!", width=11)
'Xin chào […]'
>>> textwrap.shorten("Xin chào thế giới", width=10, placeholder="...")
'Xin chào...'

Các đối số từ khóa tùy chọn tương ứng với các thuộc tính phiên bản của TextWrapper, được ghi lại bên dưới. Lưu ý rằng khoảng trắng được thu gọn trước khi văn bản được chuyển đến hàm TextWrapper fill(), do đó việc thay đổi giá trị của tabsize, expand_tabs, drop_whitespace và replace_whitespace sẽ không có hiệu lực.

Added in version 3.4.

textwrap.dedent(text)

Xóa mọi khoảng trắng hàng đầu phổ biến khỏi mọi dòng trong text.

Điều này có thể được sử dụng để làm cho các chuỗi trích dẫn ba thẳng hàng với cạnh trái của màn hình, trong khi vẫn hiển thị chúng trong mã nguồn ở dạng thụt lề.

Lưu ý rằng các tab và dấu cách đều được coi là khoảng trắng, nhưng chúng không bằng nhau: các dòng "  hello" và "\thello" được coi là không có khoảng trắng chung ở đầu.

Các dòng chỉ chứa khoảng trắng sẽ bị bỏ qua trong đầu vào và được chuẩn hóa thành một ký tự dòng mới ở đầu ra.

Ví dụ:

kiểm tra chắc chắn():
    # end dòng đầu tiên có \ để tránh dòng trống!
    s = '''\
    xin chào
      thế giới
    '''
    print(repr(s)) # prints ' xin chào\n thế giới\n '
    print(repr(dedent(s))) # prints 'hello\n world\n'

Thay đổi trong phiên bản 3.14: Hàm dedent() hiện chuẩn hóa chính xác các dòng trống chỉ chứa các ký tự khoảng trắng. Trước đây, việc triển khai chỉ chuẩn hóa các dòng trống chứa tab và dấu cách.

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

Thêm prefix vào đầu các dòng đã chọn trong text.

Các dòng được phân tách bằng cách gọi text.splitlines(True).

Theo mặc định, prefix được thêm vào tất cả các dòng không chỉ bao gồm khoảng trắng (bao gồm mọi kết thúc dòng).

Ví dụ:

>>> s = 'xin chào\n\n \nworld'
>>> thụt lề, '')
' xin chào\n\n \n thế giới'

Đối số predicate tùy chọn có thể được sử dụng để kiểm soát dòng nào được thụt lề. Ví dụ: có thể dễ dàng thêm prefix vào các dòng trống và chỉ có khoảng trắng

>>> print(thụt lề(s, '+ ', dòng lambda: Đúng))
+ xin chào
+
+
+ thế giới

Added in version 3.3.

wrap(), fill() và shorten() hoạt động bằng cách tạo một phiên bản TextWrapper và gọi một phương thức duy nhất trên đó. Phiên bản đó không được sử dụng lại, do đó, đối với các ứng dụng xử lý nhiều chuỗi văn bản bằng wrap() và/hoặc fill(), việc tạo đối tượng TextWrapper của riêng bạn có thể hiệu quả hơn.

Văn bản tốt nhất nên được bao bọc trong khoảng trắng và ngay sau dấu gạch nối trong các từ có gạch nối; chỉ khi đó các từ dài mới bị ngắt nếu cần thiết, trừ khi TextWrapper.break_long_words được đặt thành false.

class textwrap.TextWrapper(**kwargs)

Hàm tạo TextWrapper chấp nhận một số đối số từ khóa tùy chọn. Mỗi đối số từ khóa tương ứng với một thuộc tính thể hiện, ví dụ

trình bao bọc = TextWrapper(initial_indent="* ")

giống như

trình bao bọc = TextWrapper()
Wrapper.initial_indent = "* "

Bạn có thể sử dụng lại cùng một đối tượng TextWrapper nhiều lần và bạn có thể thay đổi bất kỳ tùy chọn nào của nó thông qua việc gán trực tiếp cho các thuộc tính phiên bản giữa các lần sử dụng.

Các thuộc tính phiên bản TextWrapper (và các đối số từ khóa cho hàm tạo) như sau:

width

(mặc định: 70) Độ dài tối đa của các đường được gói. Miễn là không có từ riêng lẻ nào trong văn bản đầu vào dài hơn width, TextWrapper đảm bảo rằng không có dòng đầu ra nào dài hơn ký tự width.

expand_tabs

(mặc định: True) Nếu đúng thì tất cả các ký tự tab trong text sẽ được mở rộng thành khoảng trắng bằng phương pháp expandtabs() của text.

tabsize

(mặc định: 8) Nếu expand_tabs là đúng thì tất cả các ký tự tab trong text sẽ được mở rộng thành 0 hoặc nhiều khoảng trắng, tùy thuộc vào cột hiện tại và kích thước tab nhất định.

Added in version 3.3.

replace_whitespace

(mặc định: True) Nếu đúng, sau khi mở rộng tab nhưng trước khi gói, phương thức wrap() sẽ thay thế mỗi ký tự khoảng trắng bằng một khoảng trắng. Các ký tự khoảng trắng được thay thế như sau: tab, dòng mới, tab dọc, nguồn cấp dữ liệu biểu mẫu và trả về vận chuyển ('\t\n\v\f\r').

Ghi chú

Nếu expand_tabs sai và replace_whitespace đúng, mỗi ký tự tab sẽ được thay thế bằng một khoảng trắng, not giống như mở rộng tab.

Ghi chú

Nếu replace_whitespace sai, dòng mới có thể xuất hiện ở giữa dòng và gây ra kết quả lạ. Vì lý do này, văn bản phải được chia thành các đoạn (sử dụng str.splitlines() hoặc tương tự) được gói riêng.

drop_whitespace

(mặc định: True) Nếu đúng, khoảng trắng ở đầu và cuối mỗi dòng (sau khi ngắt dòng nhưng trước khi thụt lề) sẽ bị loại bỏ. Tuy nhiên, khoảng trắng ở đầu đoạn văn sẽ không bị loại bỏ nếu không có khoảng trắng theo sau nó. Nếu khoảng trắng bị loại bỏ chiếm toàn bộ một dòng thì toàn bộ dòng đó sẽ bị loại bỏ.

initial_indent

(mặc định: '') Chuỗi sẽ được thêm vào dòng đầu tiên của đầu ra được gói. Tính theo chiều dài của dòng đầu tiên. Chuỗi trống không được thụt lề.

subsequent_indent

(mặc định: '') Chuỗi sẽ được thêm vào trước tất cả các dòng đầu ra được bao bọc ngoại trừ dòng đầu tiên. Tính theo chiều dài của mỗi dòng ngoại trừ dòng đầu tiên.

fix_sentence_endings

(mặc định: False) Nếu đúng, TextWrapper sẽ cố gắng phát hiện phần cuối câu và đảm bảo rằng các câu luôn cách nhau đúng hai dấu cách. Điều này thường được mong muốn đối với văn bản có phông chữ đơn cách. Tuy nhiên, thuật toán phát hiện câu không hoàn hảo: nó giả định rằng phần cuối câu bao gồm một chữ cái viết thường, theo sau là một trong các '.', '!' hoặc '?', có thể theo sau là một trong các '"' hoặc "'", theo sau là một khoảng trắng. Một vấn đề với thuật toán này là nó không thể phát hiện ra sự khác biệt giữa "Dr." trong

[…] Con quái vật của Tiến sĩ Frankenstein […]

và "Tại chỗ." trong

[…] Xem tại chỗ. Xem Chạy tại chỗ […]

fix_sentence_endings theo mặc định là sai.

Do thuật toán phát hiện câu dựa vào string.lowercase để định nghĩa "chữ thường" và quy ước sử dụng hai dấu cách sau dấu chấm để phân tách các câu trên cùng một dòng, nên thuật toán này dành riêng cho văn bản tiếng Anh.

break_long_words

(mặc định: True) Nếu đúng thì các từ dài hơn width sẽ bị ngắt để đảm bảo rằng không có dòng nào dài hơn width. Nếu sai, các từ dài sẽ không bị ngắt quãng và một số dòng có thể dài hơn width. (Các từ dài sẽ được tự xếp thành một dòng để giảm thiểu số lượng vượt quá width.)

break_on_hyphens

(mặc định: True) Nếu đúng, việc bao bọc sẽ diễn ra tốt hơn ở các khoảng trắng và ngay sau dấu gạch nối trong các từ ghép, như thông lệ trong tiếng Anh. Nếu sai, chỉ khoảng trắng mới được coi là vị trí thích hợp để ngắt dòng, nhưng bạn cần đặt break_long_words thành false nếu bạn muốn các từ thực sự không thể tách được. Hành vi mặc định trong các phiên bản trước là luôn cho phép ngắt các từ có dấu gạch nối.

max_lines

(mặc định: None) Nếu không phải None thì đầu ra sẽ chứa tối đa các dòng max_lines, với placeholder xuất hiện ở cuối đầu ra.

Added in version 3.4.

placeholder

(mặc định: ' [...]') Chuỗi sẽ xuất hiện ở cuối văn bản đầu ra nếu nó bị cắt bớt.

Added in version 3.4.

TextWrapper cũng cung cấp một số phương thức công khai, tương tự như các hàm tiện lợi ở cấp mô-đun:

wrap(text)

Gói một đoạn văn trong text (một chuỗi) để mỗi dòng có độ dài tối đa là width ký tự. Tất cả các tùy chọn gói được lấy từ các thuộc tính phiên bản của phiên bản TextWrapper. Trả về danh sách các dòng đầu ra, không có dòng mới cuối cùng. Nếu đầu ra được gói không có nội dung thì danh sách trả về sẽ trống.

fill(text)

Gói một đoạn văn trong text và trả về một chuỗi chứa đoạn văn được gói.