string — Allgemeine Zeichenkettenoperationen

Source code: Lib/string.py

Siehe auch

Textsequenztyp – str

String-Methoden

String-Konstanten

Die in diesem Modul definierten Konstanten sind:

string.ascii_letters

Die Konkatenation der unten beschriebenen Konstanten ascii_lowercase und ascii_uppercase. Dieser Wert ist nicht locale-abhängig.

string.ascii_lowercase

Die Kleinbuchstaben 'abcdefghijklmnopqrstuvwxyz'. Dieser Wert ist nicht locale-abhängig und ändert sich nicht.

string.ascii_uppercase

Die Großbuchstaben 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Dieser Wert ist nicht locale-abhängig und ändert sich nicht.

string.digits

Die Zeichenkette '0123456789'.

string.hexdigits

Die Zeichenkette '0123456789abcdefABCDEF'.

string.octdigits

Die Zeichenkette '01234567'.

string.punctuation

Zeichenkette von ASCII-Zeichen, die im C-locale als Satzzeichen gelten: !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable

Zeichenkette von ASCII-Zeichen, die in Python als druckbar gelten. Dies ist eine Kombination aus digits, ascii_letters, punctuation und whitespace.

Bemerkung

Designbedingt gibt string.printable.isprintable() False zurück. Insbesondere ist string.printable im POSIX-Sinn nicht druckbar (siehe LC_CTYPE).

string.whitespace

Eine Zeichenkette, die alle ASCII-Zeichen enthält, die als Whitespace gelten. Dies umfasst die Zeichen Leerzeichen, Tabulator, Zeilenvorschub (linefeed), Zeilenrücklauf (return), Seitenvorschub (formfeed) und vertikaler Tabulator.

Benutzerdefinierte String-Formatierung

The built-in string class provides the ability to do complex variable substitutions and value formatting via the format() method described in PEP 3101. The Formatter class in the string module allows you to create and customize your own string formatting behaviors using the same implementation as the built-in format() method.

class string.Formatter

Die Klasse Formatter hat die folgenden öffentlichen Methoden:

format(format_string, /, *args, **kwargs)

Die Haupt-API-Methode. Sie nimmt einen Formatstring sowie eine beliebige Menge an Positions- und Schlüsselwort-Argumenten entgegen. Sie ist nur ein Wrapper, der vformat() aufruft.

Geändert in Version 3.7: Ein Formatstring-Argument ist jetzt positional-only.

vformat(format_string, args, kwargs)

Diese Funktion führt die eigentliche Formatierungsarbeit durch. Sie ist als separate Funktion für Fälle verfügbar, in denen du ein vordefiniertes Dictionary von Argumenten übergeben möchtest, anstatt das Dictionary mit der Syntax *args und **kwargs als einzelne Argumente zu entpacken und neu zu verpacken. vformat() übernimmt das Aufteilen des Formatstrings in Zeichendaten und Ersetzungsfelder. Sie ruft die verschiedenen unten beschriebenen Methoden auf.

Darüber hinaus definiert Formatter eine Reihe von Methoden, die dazu gedacht sind, von Unterklassen überschrieben zu werden:

parse(format_string)

Durchläuft den format_string und gibt ein Iterable aus Tupeln (literal_text, field_name, format_spec, conversion) zurück. Dies wird von vformat() verwendet, um die Zeichenkette entweder in Literaltext oder Ersetzungsfelder zu zerlegen.

The values in the tuple conceptually represent a span of literal text followed by a single replacement field. If there is no literal text (which can happen if two replacement fields occur consecutively), then literal_text will be a zero-length string. If there is no replacement field, then the values of field_name, format_spec and conversion will be None.

get_field(field_name, args, kwargs)

Given field_name as returned by parse() (see above), convert it to an object to be formatted. Returns a tuple (obj, used_key). The default version takes strings of the form defined in PEP 3101, such as „0[name]“ or „label.title“. args and kwargs are as passed in to vformat(). The return value used_key has the same meaning as the key parameter to get_value().

get_value(key, args, kwargs)

Ruft einen gegebenen Feldwert ab. Das Argument key ist entweder eine Ganzzahl oder eine Zeichenkette. Wenn es eine Ganzzahl ist, repräsentiert es den Index des Positionsarguments in args; wenn es eine Zeichenkette ist, repräsentiert es ein benanntes Argument in kwargs.

Der Parameter args ist auf die Liste der Positionsargumente für vformat() gesetzt und der Parameter kwargs auf das Dictionary der Schlüsselwort-Argumente.

Bei zusammengesetzten Feldnamen werden diese Funktionen nur für die erste Komponente des Feldnamens aufgerufen; nachfolgende Komponenten werden über normale Attribut- und Indizierungsoperationen verarbeitet.

So würde beispielsweise der Feldausdruck ‚0.name‘ dazu führen, dass get_value() mit dem Argument key gleich 0 aufgerufen wird. Das Attribut name wird nach der Rückgabe von get_value() durch den Aufruf der eingebauten Funktion getattr() nachgeschlagen.

Wenn sich der Index oder das Schlüsselwort auf ein Element bezieht, das nicht existiert, sollte ein IndexError oder KeyError ausgelöst werden.

check_unused_args(used_args, args, kwargs)

Implementiert bei Bedarf die Prüfung auf unbenutzte Argumente. Die Argumente dieser Funktion sind die Menge aller Argument-Schlüssel, auf die im Formatstring tatsächlich verwiesen wurde (Ganzzahlen für Positionsargumente und Zeichenketten für benannte Argumente), sowie eine Referenz auf args und kwargs, die an vformat übergeben wurden. Die Menge der unbenutzten Argumente kann aus diesen Parametern berechnet werden. Es wird davon ausgegangen, dass check_unused_args() eine Ausnahme auslöst, wenn die Prüfung fehlschlägt.

format_field(value, format_spec)

format_field() ruft einfach die globale eingebaute Funktion format() auf. Die Methode wird bereitgestellt, damit Unterklassen sie überschreiben können.

convert_field(value, conversion)

Konvertiert den Wert (der von get_field() zurückgegeben wird) anhand eines Konvertierungstyps (wie in dem von der Methode parse() zurückgegebenen Tupel). Die Standardversion unterstützt die Konvertierungstypen ‚s‘ (str), ‚r‘ (repr) und ‚a‘ (ascii).

Syntax für Formatzeichenketten

The str.format() method and the Formatter class share the same syntax for format strings (although in the case of Formatter, subclasses can define their own format string syntax). The syntax is related to that of formatted string literals, but it is less sophisticated and, in particular, does not support arbitrary expressions.

Formatstrings enthalten „Ersetzungsfelder“, die von geschweiften Klammern {} umgeben sind. Alles, was nicht in Klammern steht, wird als Literaltext betrachtet und unverändert in die Ausgabe kopiert. Wenn ein Klammerzeichen im Literatext enthalten sein muss, kann es durch Verdopplung maskiert werden: {{ und }}.

Die Grammatik für ein Ersetzungsfeld lautet wie folgt:

replacement_field ::= "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name        ::= arg_name ("." attribute_name | "[" element_index "]")*
arg_name          ::= [identifier | digit+]
attribute_name    ::= identifier
element_index     ::= digit+ | index_string
index_string      ::= <any source character except "]"> +
conversion        ::= "r" | "s" | "a"
format_spec       ::= format-spec:format_spec

Einfacher ausgedrückt kann das Ersetzungsfeld mit einem field_name beginnen, der das Objekt angibt, dessen Wert formatiert und anstelle des Ersetzungsfeldes in die Ausgabe eingefügt werden soll. Auf den field_name folgt optional ein conversion-Feld, dem ein Ausrufezeichen '!' vorangestellt ist, und eine format_spec, der ein Doppelpunkt ':' vorangestellt ist. Diese geben ein vom Standard abweichendes Format für den Ersetzungswert an.

Siehe auch den Abschnitt Formatspezifikation Mini-Sprache.

Der field_name selbst beginnt mit einem arg_name, der entweder eine Zahl oder ein Schlüsselwort ist. Wenn es eine Zahl ist, bezieht sie sich auf ein Positionsargument, und wenn es ein Schlüsselwort ist, bezieht es sich auf ein benanntes Schlüsselwort-Argument. Ein arg_name wird als Zahl behandelt, wenn ein Aufruf von str.isdecimal() auf der Zeichenkette true zurückgeben würde. Wenn die numerischen arg_names in einem Formatstring nacheinander 0, 1, 2, … lauten, können sie alle weggelassen werden (nicht nur einige), und die Zahlen 0, 1, 2, … werden automatisch in dieser Reihenfolge eingesetzt. Da arg_name nicht in Anführungszeichen steht, ist es nicht möglich, beliebige Dictionary-Schlüssel (z. B. die Zeichenketten '10' oder ':-]') innerhalb eines Formatstrings anzugeben. Auf den arg_name können beliebig viele Index- oder Attributausdrücke folgen. Ein Ausdruck der Form '.name' wählt das benannte Attribut mittels getattr() aus, während ein Ausdruck der Form '[index]' ein Nachschlagen des Index mittels __getitem__() durchführt.

Geändert in Version 3.1: Die Positionsargument-Spezifikatoren können für str.format() weggelassen werden, sodass '{} {}'.format(a, b) äquivalent zu '{0} {1}'.format(a, b) ist.

Geändert in Version 3.4: Die Positionsargument-Spezifikatoren können für Formatter weggelassen werden.

Einige einfache Beispiele für Formatstrings:

"First, thou shalt count to {0}"  # Bezieht sich auf das erste Positionsargument
"Bring me a {}"                   # Bezieht sich implizit auf das erste Positionsargument
"From {} to {}"                   # Entspricht \"From {0} to {1}"
"My quest is {name}"              # Bezieht sich auf das Schlüsselwort-Argument 'name'
"Weight in tons {0.weight}"       # Attribut 'weight' des ersten Positionsarguments
"Units destroyed: {players[0]}"   # Erstes Element des Schlüsselwort-Arguments 'players'.

Das conversion-Feld erzwingt vor der Formatierung eine Typumwandlung. Normalerweise wird die Formatierung eines Wertes von dessen eigener Methode __format__() durchgeführt. In einigen Fällen ist es jedoch erwünscht, die Formatierung eines Typs als Zeichenkette zu erzwingen und seine eigene Formatierungsdefinition zu übergehen. Durch das Konvertieren des Wertes in eine Zeichenkette vor dem Aufruf von __format__() wird die normale Formatierungslogik umgangen.

Drei Konvertierungsflags werden derzeit unterstützt: '!s', das str() für den Wert aufruft, '!r', das repr() aufruft, und '!a', das ascii() aufruft.

Einige Beispiele:

"Harold's a clever {0!s}"        # Ruft zuerst str() für das Argument auf
"Bring out the holy {name!r}"    # Ruft zuerst repr() für das Argument auf
"More {!a}"                      # Ruft zuerst ascii() für das Argument auf

Das Feld format_spec enthält eine Spezifikation darüber, wie der Wert dargestellt werden soll, einschließlich Details wie Feldbreite, Ausrichtung, Auffüllung, Dezimalpräzision und so weiter. Jeder Werttyp kann seine eigene „Formatierungs-Minisprache“ oder Interpretation der format_spec definieren.

Die meisten eingebauten Typen unterstützen eine gemeinsame Formatierungs-Mini-Sprache, die im nächsten Abschnitt beschrieben wird.

Ein format_spec-Feld kann auch verschachtelte Ersetzungsfelder enthalten. Diese verschachtelten Ersetzungsfelder können einen Feldnamen, ein Konvertierungskennzeichen und eine Formatangabe enthalten, eine tiefere Verschachtelung ist jedoch nicht zulässig. Die Ersetzungsfelder innerhalb von format_spec werden ersetzt, bevor die format_spec-Zeichenkette interpretiert wird. Dies ermöglicht es dir, die Formatierung eines Werts dynamisch anzugeben.

Siehe den Abschnitt Formatierungsbeispiele für einige Beispiele.

Formatspezifikation Mini-Sprache

„Format specifications“ are used within replacement fields contained within a format string to define how individual values are presented (see Syntax für Formatzeichenketten and f-Strings). They can also be passed directly to the built-in format() function. Each formattable type may define how the format specification is to be interpreted.

Die meisten eingebauten Typen implementieren die folgenden Optionen für Formatspezifikationen, obwohl einige der Formatierungsoptionen nur von den numerischen Typen unterstützt werden.

Eine allgemeine Konvention besagt, dass eine leere Formatspezifikation dasselbe Ergebnis erzeugt, wie wenn du str() für den Wert aufgerufen hättest. Eine nicht leere Formatspezifikation verändert in der Regel das Ergebnis.

Die allgemeine Form einer Standard-Formatspezifikation ist:

format_spec ::= [options][width][grouping]["." precision][type]
options     ::= [[fill]align][sign]["z"]["#"]["0"]
fill        ::= <any character>
align       ::= "<" | ">" | "=" | "^"
sign        ::= "+" | "-" | " "
width       ::= digit+
grouping    ::= "," | "_"
precision   ::= digit+
type        ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                | "G" | "n" | "o" | "s" | "x" | "X" | "%"

Wenn ein gültiger align-Wert angegeben ist, kann ihm ein fill-Zeichen vorangestellt werden, das ein beliebiges Zeichen sein kann und standardmäßig ein Leerzeichen ist, wenn es weggelassen wird. Es ist nicht möglich, eine geschweifte Klammer (“{“ oder „}“) als fill-Zeichen in einem formatted string literal oder bei der Verwendung der str.format() Methode zu verwenden. Es ist jedoch möglich, eine geschweifte Klammer mit einem verschachtelten Ersetzungsfeld einzufügen. Diese Einschränkung betrifft die format()-Funktion nicht.

Die Bedeutung der verschiedenen Ausrichtungsoptionen ist wie folgt:

Option

Bedeutung

'<'

Erzwingt, dass das Feld innerhalb des verfügbaren Platzes linksbündig ausgerichtet wird (dies ist der Standardwert für die meisten Objekte).

'>'

Erzwingt, dass das Feld innerhalb des verfügbaren Platzes rechtsbündig ausgerichtet wird (dies ist der Standard für Zahlen).

'='

Erzwingt, dass die Auffüllung nach dem Vorzeichen (falls vorhanden), aber vor den Ziffern platziert wird. Dies wird für die Ausgabe von Feldern in der Form ‚+000000120‘ verwendet. Diese Ausrichtungsoption ist nur für numerische Typen gültig, ausgenommen complex. Sie wird für Zahlen standardmäßig verwendet, wenn ‚0‘ direkt vor der Feldbreite steht.

'^'

Erzwingt, dass das Feld innerhalb des verfügbaren Platzes zentriert ausgerichtet wird.

Beachte, dass die Feldbreite, sofern keine Mindestfeldbreite definiert ist, immer dieselbe Größe wie die darin enthaltenen Daten hat, sodass die Ausrichtungsoption in diesem Fall keine Bedeutung hat.

Die Option sign ist nur für numerische Typen gültig und kann eine der folgenden sein:

Option

Bedeutung

'+'

Gibt an, dass sowohl für positive als auch für negative Zahlen ein Vorzeichen verwendet werden soll.

'-'

Gibt an, dass nur für negative Zahlen ein Vorzeichen verwendet werden soll (dies ist das Standardverhalten).

Leerzeichen

Gibt an, dass bei positiven Zahlen ein führendes Leerzeichen und bei negativen Zahlen ein Minuszeichen verwendet werden soll.

Die Option 'z' wandelt negative Null-Gleitkommawerte nach dem Runden auf die Formatpräzision in eine positive Null um. Diese Option ist nur für Gleitkomma-Darstellungstypen gültig.

Geändert in Version 3.11: Die Option 'z' wurde hinzugefügt (siehe auch PEP 682).

Die Option '#' bewirkt, dass die „alternative Form“ für die Umwandlung verwendet wird. Die alternative Form ist für verschiedene Typen unterschiedlich definiert. Diese Option ist nur für die Typen Integer, Float und Complex gültig. Wenn bei Integern eine Binär-, Oktal- oder Hexadezimalausgabe verwendet wird, fügt diese Option dem Ausgabewert das entsprechende Präfix '0b', '0o', '0x' oder '0X' hinzu. Bei Float und Complex führt die alternative Form dazu, dass das Ergebnis der Umwandlung immer ein Dezimalpunkt-Zeichen enthält, selbst wenn keine Ziffern folgen. Normalerweise erscheint ein Dezimalpunkt-Zeichen im Ergebnis dieser Umwandlungen nur, wenn eine Ziffer folgt. Zudem werden bei 'g'- und 'G'- Umwandlungen nachstehende Nullen nicht aus dem Ergebnis entfernt.

Die Breite width ist eine dezimale Ganzzahl, die die minimale Gesamtfeldbreite definiert, einschließlich etwaiger Präfixe, Trennzeichen und anderer Formatierungszeichen. Wenn sie nicht angegeben ist, wird die Feldbreite durch den Inhalt bestimmt.

Wenn keine explizite Ausrichtung angegeben ist, aktiviert eine vorangestellte Null ('0') vor dem Feld width eine vorzeichenberücksichtigende Nullauffüllung für numerische Typen, ausgenommen complex. Dies entspricht einem fill-Zeichen von '0' mit einem alignment-Typ von '='.

Geändert in Version 3.10: Eine vorangestellte '0' vor dem Feld width hat keinen Einfluss mehr auf die Standardausrichtung von Zeichenketten.

The grouping option after the width field specifies a digit group separator for the integral part of a number. It can be one of the following:

Option

Bedeutung

','

Fügt alle 3 Ziffern ein Komma ein für den Ganzzahl-Darstellungstyp 'd' und Gleitkomma-Darstellungstypen, ausgenommen 'n'. Für andere Darstellungstypen wird diese Option nicht unterstützt.

'_'

Fügt alle 3 Ziffern einen Unterstrich ein für den Ganzzahl-Darstellungstyp 'd' und Gleitkomma-Darstellungstypen, ausgenommen 'n'. Für die Ganzzahl-Darstellungstypen 'b', 'o', 'x' und 'X' werden Unterstriche jeweils nach 4 Ziffern eingefügt. Für andere Darstellungstypen wird diese Option nicht unterstützt.

Verwende stattdessen den 'n' Gleitkomma-Darstellungstyp oder Ganzzahl-Darstellungstyp für ein lokalspezifisches Trennzeichen.

Geändert in Version 3.1: Die Option ',' wurde hinzugefügt (siehe auch PEP 378).

Geändert in Version 3.6: Die Option '_' wurde hinzugefügt (siehe auch PEP 515).

Die Präzision (precision) ist eine dezimale Ganzzahl, die angibt, wie viele Stellen nach dem Dezimalpunkt bei den Darstellungstypen 'f' und 'F' oder vor und nach dem Dezimalpunkt bei den Darstellungstypen 'g' oder 'G' angezeigt werden sollen. Bei Zeichenketten-Darstellungstypen gibt das Feld die maximale Feldgröße an – mit anderen Worten, wie viele Zeichen aus dem Feldinhalt verwendet werden. Die precision ist für Ganzzahl-Darstellungstypen nicht zulässig.

Schließlich bestimmt der Typ (type), wie die Daten dargestellt werden sollen.

Die verfügbaren Zeichenketten-Darstellungstypen sind:

Typ

Bedeutung

's'

Zeichenkettenformat. Dies ist der Standardtyp für Zeichenketten und kann weggelassen werden.

None

Gleichbedeutend mit 's'.

Die verfügbaren Ganzzahl-Darstellungstypen sind:

Typ

Bedeutung

'b'

Binärformat. Gibt die Zahl zur Basis 2 aus.

'c'

Zeichen. Konvertiert die Ganzzahl vor der Ausgabe in das entsprechende Unicode-Zeichen.

'd'

Dezimalzahl. Gibt die Zahl zur Basis 10 aus.

'o'

Oktalformat. Gibt die Zahl zur Basis 8 aus.

'x'

Hexadezimalformat. Gibt die Zahl zur Basis 16 aus und verwendet dabei Kleinbuchstaben für die Ziffern über 9.

'X'

Hexadezimalformat. Gibt die Zahl zur Basis 16 aus und verwendet dabei Großbuchstaben für die Ziffern über 9. Falls '#' angegeben ist, wird auch der Präfix '0x' zu '0X' großgeschrieben.

'n'

Zahl. Dies entspricht 'd', verwendet jedoch die aktuelle Ländereinstellung, um die passenden Zifferngruppentrennzeichen einzufügen. Beachte, dass die Standard-Ländereinstellung nicht der System-Ländereinstellung entspricht. Je nach Anwendungsfall möchtest du möglicherweise LC_NUMERIC mit locale.setlocale() setzen, bevor du 'n' verwendest.

None

Gleichbedeutend mit 'd'.

Zusätzlich zu den oben genannten Darstellungstypen können Ganzzahlen mit den unten aufgeführten Gleitkomma-Darstellungstypen formatiert werden (außer 'n' und None). Dabei wird float() verwendet, um die Ganzzahl vor der Formatierung in eine Gleitkommazahl zu konvertieren.

Die verfügbaren Darstellungstypen für float und Decimal Werte sind:

Typ

Bedeutung

'e'

Wissenschaftliche Notation. Formatiert die Zahl für eine gegebene Präzision p in wissenschaftlicher Notation, wobei der Buchstabe ‚e‘ den Koeffizienten vom Exponenten trennt. Der Koeffizient hat eine Ziffer vor und p Ziffern nach dem Dezimalpunkt, was insgesamt p + 1 signifikante Stellen ergibt. Wenn keine Präzision angegeben ist, wird für float eine Präzision von 6 Ziffern nach dem Dezimalpunkt verwendet und für Decimal werden alle Ziffern des Koeffizienten angezeigt. Falls p=0 gilt, wird der Dezimalpunkt weggelassen, es sei denn, die Option # wird verwendet.

Bei float enthält der Exponent immer mindestens zwei Ziffern und ist null, wenn der Wert null ist.

'E'

Wissenschaftliche Notation. Entspricht 'e', verwendet jedoch ein großes ‚E‘ als Trennzeichen.

'f'

Festkommanotation. Formatiert die Zahl für eine gegene Präzision p als Dezimalzahl mit genau p Ziffern nach dem Dezimalpunkt. Wenn keine Präzision angegeben ist, wird für float eine Präzision von 6 Ziffern nach dem Dezimalpunkt verwendet und für Decimal eine ausreichende Präzision, um alle Ziffern des Koeffizienten anzuzeigen. Falls p=0 gilt, wird der Dezimalpunkt weggelassen, es sei denn, die Option # wird verwendet.

'F'

Festkommanotation. Entspricht 'f', wandelt jedoch nan in NAN und inf in INF um.

'g'

Allgemeines Format. Für eine gegebene Präzision p >= 1 rundet dies die Zahl auf p signifikante Stellen und formatiert das Ergebnis je nach seiner Größenordnung entweder in Festkommanotation oder in wissenschaftlicher Notation. Eine Präzision von 0 wird wie eine Präzision von 1 behandelt.

Die genauen Regeln lauten wie folgt: Angenommen, das mit dem Darstellungstyp 'e' und der Präzision p-1 formatierte Ergebnis hätte den Exponenten exp. Wenn dann m <= exp < p gilt, wobei m für Floats -4 und für Decimals -6 ist, wird die Zahl mit dem Darstellungstyp 'f' und der Präzision p-1-exp formatiert. Andernfalls wird die Zahl mit dem Darstellungstyp 'e' und der Präzision p-1 formatiert. In beiden Fällen werden irrelavante nachstehende Nullen aus der Mantisse entfernt, und auch der Dezimalpunkt wird entfernt, wenn keine weiteren Ziffern folgen, es sei denn, die Option '#' wird verwendet.

Wenn keine Präzision angegeben ist, wird für float eine Präzision von 6 signifikanten Stellen verwendet. Für Decimal wird der Koeffizient des Ergebnisses aus den Koeffizientenziffern des Werts gebildet; wissenschaftliche Notation wird für Werte verwendet, deren Absolutwert kleiner als 1e-6 ist sowie für Werte, bei denen der Stellenwert der niederwertigsten Ziffer größer als 1 ist, andernfalls wird Festkommanotation verwendet.

Positives und negatives Unendlich, positive und negative Null sowie NaNs werden unabhängig von der Präzision als inf, -inf, 0, -0 bzw. nan formatiert.

'G'

Allgemeines Format. Entspricht 'g', wechselt jedoch zu 'E', wenn die Zahl zu groß wird. Die Darstellungen von Unendlich und NaN werden ebenfalls in Großbuchstaben ausgegeben.

'n'

Zahl. Dies entspricht 'g', verwendet jedoch die aktuelle Ländereinstellung, um die passenden Zifferngruppentrennzeichen für den ganzzahligen Teil einer Zahl einzufügen. Beachte, dass die Standard-Ländereinstellung nicht der System-Ländereinstellung entspricht. Je nach Anwendungsfall möchtest du möglicherweise LC_NUMERIC mit locale.setlocale() setzen, bevor du 'n' verwendest.

'%'

Prozentsatz. Multipliziert die Zahl mit 100 und zeigt sie im Festkomma-Format ('f') an, gefolgt von einem Prozentzeichen.

None

Für float entspricht dies dem Typ 'g', mit dem Unterschied, dass bei der Verwendung der Festkommanotation zur Formatierung des Ergebnisses immer mindestens eine Ziffer nach dem Dezimalpunkt enthalten ist und zur wissenschaftlichen Notation gewechselt wird, wenn exp >= p - 1 gilt. Wenn keine Präzision angegeben ist, wird letztere so groß wie nötig gewählt, um den gegebenen Wert getreu darzustellen.

Für Decimal entspricht dies entweder 'g' oder 'G', abhängig vom Wert von context.capitals des aktuellen Decimal-Kontexts.

Der Gesamteffekt besteht darin, der Ausgabe von str() zu entsprechen, wie sie durch die anderen Formatmodifikatoren geändert wird.

Das Ergebnis sollte korrekterweise auf eine gegebene Präzision p von Ziffern nach dem Dezimalpunkt gerundet werden. Der Rundungsmodus für float entspricht dem der eingebauten Funktion round(). Für Decimal wird der Rundungsmodus des aktuellen Kontexts verwendet.

Die verfügbaren Darstellungstypen für complex entsprechen denen für float ('%' ist nicht zulässig). Sowohl der Real- als auch der Imaginärteil einer komplexen Zahl werden gemäß dem angegebenen Darstellungstyp als Gleitkommazahlen formatiert. Sie werden durch das obligatorische Vorzeichen des Imaginärteils getrennt, welcher durch ein angehängtes j abgeschlossen wird. Fehlt der Darstellungstyp, entspricht das Ergebnis der Ausgabe von str() (komplexe Zahlen mit einem Realteil ungleich Null werden zusätzlich von Klammern umschlossen), eventuell geändert durch andere Formatmodifikatoren.

Formatierungsbeispiele

Dieser Abschnitt enthält Beispiele für die str.format()-Syntax und einen Vergleich mit der alten %-Formatierung.

In den meisten Fällen ähnelt die Syntax der alten %-Formatierung, mit der Ergänzung von {} und der Verwendung von : anstelle von %. Beispielsweise kann '%03.2f' in '{:03.2f}' übersetzt werden.

Die neue Format-Syntax unterstützt auch neue und andere Optionen, die in den folgenden Beispielen gezeigt werden.

Zugriff auf Argumente über die Position:

">>> '{0}, {1}, {2}'.format('a', 'b', 'c')
"'a, b, c'
">>> '{}, {}, {}'.format('a', 'b', 'c')  # nur 3.1+
"'a, b, c'
">>> '{2}, {1}, {0}'.format('a', 'b', 'c')
"'c, b, a'
">>> '{2}, {1}, {0}'.format(*'abc')      # Entpacken einer Argumentsequenz
"'c, b, a'
">>> '{0}{1}{0}'.format('abra', 'cad')   # Indizes der Argumente können wiederholt werden
"'abracadabra'

Zugriff auf Argumente über den Namen:

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
"'Coordinates: 37.24N, -115.81W'
">>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
">>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
"'Coordinates: 37.24N, -115.81W'

Zugriff auf Attribute von Argumenten:

">>> c = 3-5j
">>> ('Die komplexe Zahl {0} besteht aus dem Realteil {0.real} '
"...  'und dem Imaginärteil {0.imag}.').format(c)
"'Die komplexe Zahl (3-5j) besteht aus dem Realteil 3.0 und dem Imaginärteil -5.0.'
">>> class Point:
"...     def __init__(self, x, y):
"...         self.x, self.y = x, y
"...     def __str__(self):
"...         return 'Point({self.x}, {self.y})'.format(self=self)
"...
">>> str(Point(4, 2))
"'Point(4, 2)'

Zugriff auf Elemente von Argumenten:

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

Ersetzen von %s und %r:

>>> "repr() zeigt Anführungszeichen: {!r}; str() nicht: {!s}".format('test1', 'test2')
"repr() zeigt Anführungszeichen: 'test1'; str() nicht: test2"

Ausrichten von Text und Angeben einer Breite:

>>> '{:<30}'.format('linksbündig')
'linksbündig                   '
>>> '{:>30}'.format('rechtsbündig')
'                  rechtsbündig'
>>> '{:^30}'.format('zentriert')
'          zentriert           '
>>> '{:*^30}'.format('zentriert') # '*' als Füllzeichen verwenden
'**********zentriert***********'

Ersetzen von %+f, %-f und % f sowie Angeben eines Vorzeichens:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # immer anzeigen
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # Leerzeichen für positive Zahlen anzeigen
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # nur das Minus anzeigen -- entspricht '{:f}; {:f}'
'3.140000; -3.140000'

Ersetzen von %x und %o und Umwandeln des Werts in verschiedene Basen:

>>> # format unterstützt auch Binärzahlen
>>> \"int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}\".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # mit 0x, 0o oder 0b als Präfix:
>>> \"int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}\".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

Verwendung des Kommas oder Unterstrichs als Tausendertrennzeichen:

>>> '{:,}'.format(1234567890)
'1,234,567,890'
>>> '{:_}'.format(1234567890)
'1_234_567_890'
>>> '{:_b}'.format(1234567890)
'100_1001_1001_0110_0000_0010_1101_0010'
>>> '{:_x}'.format(1234567890)
'4996_02d2'

Angabe eines Prozentsatzes:

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

Verwendung typspezifischer Formatierung:

>>> import datetime as dt
>>> d = dt.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

Verschachteln von Argumenten und komplexere Beispiele:

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
...     for base in 'dXob':
...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011

Template strings

Vorlage-Zeichenketten bieten einfachere Ersetzungen von Zeichenketten, wie in PEP 292 beschrieben. Ein Hauptanwendungsfall für Vorlage-Zeichenketten ist die Internationalisierung (i18n), da die einfachere Syntax und Funktionalität in diesem Kontext die Übersetzung im Vergleich zu anderen eingebauten Zeichenketten-Formatierungsmöglichkeiten in Python erleichtert. Ein Beispiel für eine auf Vorlage-Zeichenketten aufbauende Bibliothek für i18n ist das Paket flufl.i18n.

Vorlage-Zeichenketten unterstützen $-basierte Ersetzungen nach den folgenden Regeln:

  • $$ ist ein Maskierungszeichen; es wird durch ein einzelnes $ ersetzt.

  • $identifier benennt einen Ersetzungs-Platzhalter, der einem Mapping-Schlüssel von \"identifier\" entspricht. Standardmäßig ist \"identifier\" auf jede ASCII-alphanumerische Zeichenkette (einschließlich Unterstrichen) ohne Berücksichtigung von Groß-/Kleinschreibung beschränkt, die mit einem Unterstrich oder einem ASCII-Buchstaben beginnt. Das erste Nicht-Bezeichner-Zeichen nach dem $-Zeichen beendet diese Platzhalter-Spezifikation.

  • ${identifier} ist äquivalent zu $identifier. Es ist erforderlich, wenn gültige Bezeichner-Zeichen auf den Platzhalter folgen, aber nicht Teil des Platzhalters sind, wie etwa \"${noun}ification\".

Jedes andere Vorkommen von $ in der Zeichenkette führt dazu, dass ein ValueError ausgelöst wird.

The string module provides a Template class that implements these rules. The methods of Template are:

class string.Template(template)

Der Konstruktor nimmt ein einzelnes Argument entgegen, welches die Vorlage-Zeichenkette ist.

substitute(mapping={}, /, **kwds)

Führt die Ersetzung der Vorlage durch und gibt eine neue Zeichenkette zurück. mapping ist ein beliebiges Dictionary-ähnliches Objekt mit Schlüsseln, die den Platzhaltern in der Vorlage entsprechen. Alternativ können Sie Schlüsselwort-„Argumente angeben, wobei die Schlüsselwörter die Platzhalter sind. Wenn sowohl mapping als auch kwds angegeben sind und es Überschneidungen gibt, haben die Platzhalter aus kwds Vorrang.

safe_substitute(mapping={}, /, **kwds)

Wie substitute(), außer dass, wenn Platzhalter in mapping und kwds fehlen, anstelle des Auslösens einer KeyError-Ausnahme der originale Platzhalter unverändert in der resultierenden Zeichenkette erscheint. Auch werden im Gegensatz zu substitute() alle anderen Vorkommen von $ einfach als $ zurückgegeben, anstatt einen ValueError auszulösen.

Während weiterhin andere Ausnahmen auftreten können, wird diese Methode „safe“ genannt, da sie immer versucht, eine brauchbare Zeichenkette zurückzugeben, anstatt eine Ausnahme auszulösen. In einem anderen Sinne ist safe_substitute() möglicherweise alles andere als sicher, da sie stillschweigend fehlerhafte Vorlagen ignoriert, die unvollständige Trennzeichen, unpaarige Klammern oder Platzhalter enthalten, welche keine gültigen Python-Bezeichner sind.

is_valid()

Gibt False zurück, wenn die Vorlage ungültige Platzhalter enthält, die dazu führen, dass substitute() einen ValueError auslöst.

Added in version 3.11.

get_identifiers()

Gibt eine Liste der gültigen Bezeichner in der Vorlage in der Reihenfolge ihres ersten Auftretens zurück und ignoriert dabei ungültige Bezeichner.

Added in version 3.11.

Template-Instanzen stellen außerdem ein öffentliches Datenattribut bereit:

template

Dies ist das Objekt, das an das template-Argument des Konstruktors übergeben wird. Im Allgemeinen sollten Sie es nicht ändern, allerdings wird ein schreibgeschützter Zugriff nicht erzwungen.

Hier ist ein Beispiel für die Verwendung von Template:

>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'

Fortgeschrittene Nutzung: Sie können Unterklassen von Template ableiten, um die Platzhalter-Syntax, das Trennzeichen oder den gesamten regulären Ausdruck zum Parsen von Vorlage-Zeichenketten anzupassen. Dazu kannst du diese Klassenattribute überschreiben:

  • delimiter – Dies ist die Zeichenkette, die das einleitende Trennzeichen eines Platzhalters beschreibt. Der Standardwert ist $. Beachte, dass dies kein regulärer Ausdruck sein sollte, da die Implementierung bei Bedarf re.escape() auf diese Zeichenkette anwendet. Beachte weiterhin, dass du das Trennzeichen nach der Klassenerstellung nicht mehr ändern kannst (d. h. ein anderes Trennzeichen muss im Klassennamensraum der Unterklasse gesetzt werden).

  • idpattern – Dies ist der reguläre Ausdruck, der das Muster für Platzhalter ohne geschweifte Klammern beschreibt. Der Standardwert ist der reguläre Ausdruck (?a:[_a-z][_a-z0-9]*). Wenn dieser angegeben ist und braceidpattern None ist, gilt dieses Muster auch für Platzhalter mit geschweiften Klammern.

    Bemerkung

    Da standardmäßig flags auf re.IGNORECASE gesetzt ist, kann das Muster [a-z] auch auf einige Nicht-ASCII-Zeichen passen. Aus diesem Grund wird hier das lokale Flag a verwendet.

    Geändert in Version 3.7: braceidpattern kann verwendet werden, um unterschiedliche Muster für die Verwendung innerhalb und außerhalb der geschweiften Klammern zu definieren.

  • braceidpattern – Dies ist wie idpattern, beschreibt jedoch das Muster für Platzhalter mit geschweiften Klammern. Der Standardwert ist None, was bedeutet, dass auf idpattern zurückgegriffen wird (d. h. dasselbe Muster wird sowohl innerhalb als auch außerhalb von Klammern verwendet). Falls angegeben, ermöglicht dies die Definition unterschiedlicher Muster für Platzhalter mit und ohne geschweifte Klammern.

    Added in version 3.7.

  • flags – Die Flags für reguläre Ausdrücke, die beim Kompilieren des regulären Ausdrucks zur Erkennung von Ersetzungen angewendet werden. Der Standardwert ist re.IGNORECASE. Beachte, dass re.VERBOSE den Flags immer hinzugefügt wird, weshalb benutzerdefinierte idpattern den Konventionen für ausführliche reguläre Ausdrücke entsprechen müssen.

    Added in version 3.2.

Alternativ kannst du das gesamte reguläre Ausdrucksmuster bereitstellen, indem du das Klassenattribut pattern überschreibst. In diesem Fall muss der Wert eine Zeichenkette mit einem regulären Ausdrucksmuster oder ein kompiliertes Objekt für reguläre Ausdrücke sein, mit vier benannten Erfassungsgruppen. Die Erfassungsgruppen entsprechen den oben genannten Regeln sowie der Regel für ungültige Platzhalter:

  • escaped – Diese Gruppe passt auf die Escapesequenz, z.B. $$, im Standardmuster.

  • named – Diese Gruppe passt auf den Namen des Platzhalters ohne geschweifte Klammern; sie sollte das Trennzeichen nicht in der Erfassungsgruppe enthalten.

  • braced – Diese Gruppe passt auf den in geschweifte Klammern eingeschlossenen Namen des Platzhalters; sie sollte weder das Trennzeichen noch die Klammern in der Erfassungsgruppe enthalten.

  • invalid – Diese Gruppe passt auf jedes andere Trennzeichenmuster (normalerweise ein einzelnes Trennzeichen) und sollte als Letztes im regulären Ausdruck stehen.

Die Methoden dieser Klasse lösen ValueError aus, wenn das Muster auf die Vorlage passt, ohne dass eine dieser benannten Gruppen übereinstimmt.

Hilfsfunktionen

string.capwords(s, sep=None)

Teilt das Argument mithilfe von str.split() in Wörter auf, schreibt jedes Wort mithilfe von str.capitalize() groß und fügt die großgeschriebenen Wörter mit str.join() wieder zusammen. Wenn das optionale zweite Argument sep fehlt oder None ist, werden Abfolgen von Whitespace-Zeichen durch ein einzelnes Leerzeichen ersetzt und führende sowie abschließende Whitespaces entfernt; andernfalls wird sep zum Aufteilen und Zusammenfügen der Wörter verwendet.