textwrap — Περιτύλιγμα και γέμισμα κειμένου

Πηγαίος κώδικας: Lib/textwrap.py

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

Περιτυλίγει την ενιαία παράγραφο στο text (μία συμβολοσειρά) έτσι ώστε κάθε γραμμή να έχει το πολύ 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=' [...]')

Γεμίζει την ενιαία παράγραφο στο 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=' [...]')

Συμπτύξτε και περικόψτε το δοθέν text ώστε να χωράει στο δοθέν width.

Αρχικά, ο χώρος στο text συμπτύσσεται (όλος ο χώρος αντικαθίσταται με μονά κενά). Αν το αποτέλεσμα χωράει στο width, επιστρέφεται. Διαφορετικά, αρκετές λέξεις απορρίπτονται από το τέλος ώστε οι υπόλοιπες λέξεις συν το placeholder να χωρούν μέσα στο 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, που τεκμηριώνονται παρακάτω. Σημειώστε ότι ο χώρος συμπτύσσεται πριν το κείμενο περαστεί στη συνάρτηση fill() της TextWrapper, έτσι ώστε η αλλαγή της τιμής των tabsize, expand_tabs, drop_whitespace και replace_whitespace να μην έχει καμία επίδραση.

Added in version 3.4.

textwrap.dedent(text)

Αφαιρεί οποιοδήποτε κοινό αρχικό κενό από κάθε γραμμή στο text.

Αυτό μπορεί να χρησιμοποιηθεί για να ευθυγραμμίσετε τις τριπλές παραθέσεις με την αριστερή άκρη της οθόνης, ενώ παρουσιάζονται στον πηγαίο κώδικα σε μορφή εσοχής.

Σημειώστε ότι τα tab και τα κενά θεωρούνται και τα δύο ως κενό, αλλά δεν είναι ίσα: οι γραμμές "  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)

Προσθέτει το prefix στην αρχή των επιλεγμένων γραμμών στο text.

Οι γραμμές διαχωρίζονται καλώντας 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

Added in version 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) Αν είναι true, τότε όλοι οι χαρακτήρες tab στο text θα επεκταθούν σε κενά χρησιμοποιώντας τη μέθοδο expandtabs() του text.

tabsize

(προεπιλογή: 8) Αν expand_tabs είναι true, τότε όλοι οι χαρακτήρες tab στο text θα επεκταθούν σε μηδέν ή περισσότερα κενά, ανάλογα με την τρέχουσα στήλη και το δεδομένο μέγεθος tab.

Added in version 3.3.

replace_whitespace

(προεπιλογή: True) Αν είναι true, μετά την επέκταση των tab αλλά πριν το περιτύλιγμα, η μέθοδος wrap() θα αντικαταστήσει κάθε χαρακτήρα κενών με ένα μόνο κενό. Οι χαρακτήρες κενών που αντικαθίστανται είναι οι εξής: tab, νέα γραμμή, κάθετος, τροφοδότης μορφής και carriage return ('\t\n\v\f\r').

Σημείωση

(προεπιλογή: True) Αν το expand_tabs είναι false και το replace_whitespace είναι true, κάθε χαρακτήρας tab θα αντικατασταθεί από ένα μόνο κενό, το οποίο δεν είναι το ίδιο με την επέκταση των tab.

Σημείωση

Αν το replace_whitespace είναι false, οι νέες γραμμές μπορεί να εμφανιστούν στη μέση μιας γραμμής και να προκαλέσουν παράξενα αποτελέσματα. Για αυτόν τον λόγο, το κείμενο θα πρέπει να διαχωρίζεται σε παραγράφους (χρησιμοποιώντας str.splitlines() ή παρόμοια) οι οποίες περιτυλίγονται ξεχωριστά.

drop_whitespace

(προεπιλογή: True) Αν είναι true, το κενό στην αρχή και στο τέλος κάθε γραμμής (μετά το περιτύλιγμα αλλά πριν την εσοχή) αφαιρείται. Το κενό στην αρχή της παραγράφου, ωστόσο, δεν αφαιρείται αν ακολουθείται από μη κενό. Αν το κενό που αφαιρείται καταλαμβάνει ολόκληρη τη γραμμή, ολόκληρη η γραμμή αφαιρείται.

initial_indent

(προεπιλογή: '') Συμβολοσειρά που θα προστεθεί στην αρχή της πρώτης γραμμής της περιτυλιγμένης εξόδου. Μετράει προς το μήκος της πρώτης γραμμής. Η κενή συμβολοσειρά δεν έχει εσοχή.

subsequent_indent

(προεπιλογή: '') Συμβολοσειρά που θα προστεθεί στην αρχή όλων των γραμμών της περιτυλιγμένης εξόδου εκτός από την πρώτη. Μετράει προς το μήκος κάθε γραμμής εκτός από την πρώτη.

fix_sentence_endings

(προεπιλογή: False) Αν είναι true, η TextWrapper προσπαθεί να ανιχνεύσει τα τέλη προτάσεων και να διασφαλίσει ότι οι προτάσεις διαχωρίζονται πάντα από ακριβώς δύο κενά. Αυτό είναι γενικά επιθυμητό για κείμενα σε γραμματοσειρά μονού διαστήματος. Ωστόσο, ο αλγόριθμος ανίχνευσης προτάσεων δεν είναι τέλειος: υποθέτει ότι ένα τέλος πρότασης αποτελείται από ένα πεζό γράμμα ακολουθούμενο από ένα από τα '.', '!' ή '?', πιθανώς ακολουθούμενο από ένα από τα '"' ή "'", ακολουθούμενο από ένα κενό. Ένα πρόβλημα με αυτόν τον αλγόριθμο είναι ότι δεν μπορεί να ανιχνεύσει τη διαφορά μεταξύ «Dr.» στο

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

and «Spot.» in

[...] 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) Αν είναι true, το περιτύλιγμα θα συμβαίνει προτιμότερα σε κενά και αμέσως μετά τις παύλες σε σύνθετες λέξεις, όπως είναι συνηθισμένο στα αγγλικά. Αν είναι false, μόνο τα κενά θα θεωρούνται ως πιθανές καλές θέσεις για διακοπές γραμμής, αλλά πρέπει να ορίσετε το break_long_words σε false αν θέλετε πραγματικά αδιάσπαστες λέξεις. Η προεπιλεγμένη συμπεριφορά στις προηγούμενες εκδόσεις ήταν να επιτρέπεται πάντα η διάσπαση των λέξεων με παύλες.

max_lines

(προεπιλογή: None) Αν δεν είναι None, τότε η έξοδος θα περιέχει το πολύ max_lines γραμμές, με το placeholder να εμφανίζεται στο τέλος της εξόδου.

Added in version 3.4.

placeholder

(προεπιλογή: ' [...]') Συμβολοσειρά που θα εμφανίζεται στο τέλος του κειμένου εξόδου αν έχει περικοπεί.

Added in version 3.4.

Η TextWrapper παρέχει επίσης μερικές δημόσιες μεθόδους, παρόμοιες με τις συναρτήσεις ευκολίας σε επίπεδο module:

wrap(text)

Περιτυλίγει την ενιαία παράγραφο στο text (μία συμβολοσειρά) έτσι ώστε κάθε γραμμή να έχει το πολύ width χαρακτήρες. Όλες οι επιλογές περιτυλίγματος λαμβάνονται από τις ιδιότητες στιγμιότυπου της TextWrapper κλάσης. Επιστρέφει μια λίστα με τις γραμμές εξόδου, χωρίς τελικούς χαρακτήρες νέας γραμμής. Αν η περιτυλιγμένη έξοδος δεν έχει περιεχόμενο, η επιστρεφόμενη λίστα είναι κενή.

fill(text)

Γεμίζει την ενιαία παράγραφο στο text και επιστρέφει μια μοναδική συμβολοσειρά που περιέχει την γεμισμένη παράγραφο.