string — Allgemeine Zeichenkettenoperationen

Quellcode: Lib/string.py

---

Siehe auch

Textsequenztyp — str

String Methods

Zeichenkettenkonstanten

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 von der Locale abhängig.

string.ascii_lowercase

Die Kleinbuchstaben 'abcdefghijklmnopqrstuvwxyz'. Dieser Wert ist nicht von der Locale abhängig und wird sich nicht ändern.

string.ascii_uppercase

Die Großbuchstaben 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Dieser Wert ist nicht von der Locale abhängig und wird sich nicht ändern.

string.digits

Die Zeichenkette '0123456789'.

string.hexdigits

Die Zeichenkette '0123456789abcdefABCDEF'.

string.octdigits

Die Zeichenkette '01234567'.

string.punctuation

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

string.printable

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

Hinweis

Von Design her gibt string.printable.isprintable() False zurück. Insbesondere ist string.printable im POSIX-Sinne nicht druckbar (siehe LC_CTYPE).

string.whitespace

Eine Zeichenkette, die alle ASCII-Zeichen enthält, die als Leerzeichen gelten. Dazu gehören die Zeichen Leerzeichen, Tabulator, Zeilenvorschub, Wagenrücklauf, Seitenvorschub und vertikaler Tabulator.

Benutzerdefinierte Zeichenkettenformatierung

Die eingebaute Zeichenkettenklasse bietet die Möglichkeit, komplexe Variablensubstitutionen und Wertformatierungen über die Methode format() durchzuführen, die in PEP 3101 beschrieben wird. Die Klasse Formatter im Modul string ermöglicht es Ihnen, Ihre eigenen Zeichenkettenformatierungsverhaltensweisen mit derselben Implementierung wie die eingebaute Methode format() zu erstellen und anzupassen.

class string.Formatter

Die Klasse Formatter hat die folgenden öffentlichen Methoden:

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

Die primäre API-Methode. Sie nimmt eine Formatzeichenkette und eine beliebige Anzahl von Positions- und Schlüsselwortargumenten entgegen. Sie ist lediglich ein Wrapper, der vformat() aufruft.

Geändert in Version 3.7: Ein Argument für die Formatzeichenkette ist nun Positions-only.

vformat(format_string, args, kwargs)

Diese Funktion führt die eigentliche Formatierungsarbeit durch. Sie ist als separate Funktion verfügbar für Fälle, in denen Sie ein vordefiniertes Wörterbuch von Argumenten übergeben möchten, anstatt das Wörterbuch mithilfe der *args und **kwargs Syntax zu entpacken und erneut zu verpacken. vformat() zerlegt die Formatzeichenkette in Textdaten und Ersetzungsfelder. Sie ruft die verschiedenen unten beschriebenen Methoden auf.

Darüber hinaus definiert Formatter eine Reihe von Methoden, die von Unterklassen überschrieben werden sollen.

parse(format_string)

Iteriert über die `format_string` und gibt ein iterierbares Tupel zurück (literal_text, field_name, format_spec, conversion). Dies wird von vformat() verwendet, um die Zeichenkette in entweder wörtlichen Text oder Ersetzungsfelder aufzuteilen.

Die Werte im Tupel repräsentieren konzeptionell einen Bereich von wörtlichem Text gefolgt von einem einzelnen Ersetzungsfeld. Wenn kein wörtlicher Text vorhanden ist (was passieren kann, wenn zwei Ersetzungsfelder aufeinanderfolgend auftreten), ist literal_text eine leere Zeichenkette. Wenn kein Ersetzungsfeld vorhanden ist, sind die Werte von field_name, format_spec und conversion None. Der Wert von field_name bleibt unverändert und die automatische Nummerierung nicht nummerierter Positionsfelder wird von vformat() vorgenommen.

get_field(field_name, args, kwargs)

Konvertiert anhand des field_name ein Objekt zum Formatieren. Die automatische Nummerierung des von parse() zurückgegebenen field_name erfolgt durch vformat(), bevor diese Methode aufgerufen wird. Gibt ein Tupel (obj, used_key) zurück. Die Standardimplementierung verarbeitet Zeichenketten der in PEP 3101 definierten Form, wie z. B. „0[name]“ oder „label.title“. args und kwargs sind wie an vformat() übergeben. Der Rückgabewert used_key hat dieselbe Bedeutung wie der Parameter key für get_value().

get_value(key, args, kwargs)

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

Der Parameter args wird auf die Liste der Positionsargumente für vformat() gesetzt, und der Parameter kwargs wird auf das Wörterbuch der Schlüsselwortargumente gesetzt.

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

Beispielsweise würde der Feldausdruck '0.name' dazu führen, dass get_value() mit einem key-Argument von 0 aufgerufen wird. Das Attribut name wird nach der Rückgabe von get_value() durch Aufruf der integrierten Funktion getattr() nachgeschlagen.

Wenn der Index oder das Schlüsselwort auf ein nicht vorhandenes Element verweist, sollte eine IndexError oder KeyError ausgelöst werden.

check_unused_args(used_args, args, kwargs)

Implementiert die Prüfung auf ungenutzte Argumente, falls gewünscht. Die Argumente dieser Funktion sind die Menge aller Argumentschlüssel, auf die tatsächlich in der Formatzeichenkette verwiesen wurde (Ganzzahlen für Positionsargumente und Zeichenketten für benannte Argumente), sowie eine Referenz auf die an vformat übergebenen args und kwargs. Die Menge der ungenutzten Argumente kann aus diesen Parametern berechnet werden. check_unused_args() wird vorausgesetzt, dass es 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 (zurückgegeben von get_field()) unter Berücksichtigung eines Konversionstyps (wie im Tupel, das von der Methode parse() zurückgegeben wird). Die Standardimplementierung versteht die Konversionstypen 's' (str), 'r' (repr) und 'a' (ascii).

Formatzeichenkettensyntax

Die Methode str.format() und die Klasse Formatter teilen sich dieselbe Syntax für Formatzeichenketten (obwohl im Fall von Formatter Unterklassen ihre eigene Formatzeichenkettensyntax definieren können). Die Syntax ist verwandt mit der von formatierten Zeichenketten-Literalen und Template-Zeichenketten-Literalen, ist jedoch weniger ausgefeilt und unterstützt insbesondere keine beliebigen Ausdrücke in Interpolationen.

Formatzeichenketten enthalten "Ersetzungsfelder", die von geschweiften Klammern {} umschlossen sind. Alles, was nicht in Klammern enthalten ist, wird als wörtlicher Text betrachtet, der unverändert auf die Ausgabe kopiert wird. Wenn Sie ein Klammerzeichen in den wörtlichen Text einfügen müssen, kann es durch Verdoppelung maskiert werden: {{ und }}.

Die Grammatik für ein Ersetzungsfeld lautet:

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

Weniger formell 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 ein format_spec-Feld, dem ein Doppelpunkt ':' vorangestellt ist. Diese geben ein nicht-standardmäßiges Format für den Ersatzwert an.

Siehe auch den Abschnitt Format Specification Mini-Language.

Der field_name beginnt selbst mit einem arg_name, der entweder eine Zahl oder ein Schlüsselwort ist. Wenn es sich um eine Zahl handelt, bezieht es sich auf ein Positionsargument, und wenn es sich um ein Schlüsselwort handelt, bezieht es sich auf ein benanntes Schlüsselwortargument. Ein arg_name wird als Zahl behandelt, wenn ein Aufruf von str.isdecimal() auf die Zeichenkette True zurückgeben würde. Wenn die numerischen arg_name in einer Formatzeichenkette 0, 1, 2, … in Folge sind, können sie alle (nicht nur einige) weggelassen werden und die Zahlen 0, 1, 2, … werden automatisch in dieser Reihenfolge eingefügt. Da arg_name nicht durch Anführungszeichen abgegrenzt ist, ist es nicht möglich, beliebige Wörterbuchschlüssel (z. B. die Zeichenketten '10' oder ':-]') innerhalb einer Formatzeichenkette anzugeben. Dem arg_name kann eine beliebige Anzahl von Index- oder Attributausdrücken folgen. Ein Ausdruck der Form '.name' wählt das benannte Attribut mithilfe von getattr() aus, während ein Ausdruck der Form '[index]' eine Indexsuche mithilfe von __getitem__() durchführt.

Geändert in Version 3.1: Die Spezifizierer für Positionsargumente 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 Spezifizierer für Positionsargumente können für Formatter weggelassen werden.

Einige einfache Beispiele für Formatzeichenketten:

"First, thou shalt count to {0}"  # References first positional argument
"Bring me a {}"                   # Implicitly references the first positional argument
"From {} to {}"                   # Same as "From {0} to {1}"
"My quest is {name}"              # References keyword argument 'name'
"Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

Das conversion-Feld bewirkt eine Typumwandlung vor der Formatierung. Normalerweise wird die Formatierung eines Wertes durch die Methode __format__() des Wertes selbst durchgeführt. In einigen Fällen ist es jedoch wünschenswert, einen Typ zu erzwingen, der als Zeichenkette formatiert wird, und seine eigene Formatierungsdefinition zu überschreiben. Durch die Konvertierung des Wertes in eine Zeichenkette vor dem Aufruf von __format__() wird die normale Formatierungslogik umgangen.

Drei Konversionsflags 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}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

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

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

Ein format_spec-Feld kann auch verschachtelte Ersetzungsfelder enthalten. Diese verschachtelten Ersetzungsfelder können einen Feldnamen, ein Konversionsflag und eine Formatangabe enthalten, tiefere Verschachtelungen sind jedoch nicht erlaubt. Die Ersetzungsfelder innerhalb des format_spec werden ersetzt, bevor der format_spec-String interpretiert wird. Dies ermöglicht eine dynamische Angabe der Formatierung eines Wertes.

Siehe den Abschnitt Formatierungsbeispiele für einige Beispiele.

Format Specification Mini-Language

"Formatangaben" werden innerhalb von Ersetzungsfeldern in einer Formatzeichenkette verwendet, um zu definieren, wie einzelne Werte dargestellt werden (siehe Format String Syntax, f-strings und t-strings). Sie können auch direkt an die integrierte Funktion format() übergeben werden. Jeder formatierbare Typ kann definieren, wie die Formatangabe interpretiert werden soll.

Die meisten integrierten Typen implementieren die folgenden Optionen für Formatangaben, obwohl einige der Formatierungsoptionen nur für numerische Typen unterstützt werden.

Eine allgemeine Konvention ist, dass eine leere Formatangabe dasselbe Ergebnis liefert, als hätte man str() für den Wert aufgerufen. Eine nicht leere Formatangabe modifiziert typischerweise das Ergebnis.

Die allgemeine Form eines *standardmäßigen Formatbezeichners* ist:

format_spec:             [options][width_and_precision][type]
options:                 [[fill]align][sign]["z"]["#"]["0"]
fill:                    <any character>
align:                   "<" | ">" | "=" | "^"
sign:                    "+" | "-" | " "
width_and_precision:     [width_with_grouping][precision_with_grouping]
width_with_grouping:     [width][grouping]
precision_with_grouping: "." [precision][grouping] | "." grouping
width:                   digit+
precision:               digit+
grouping:                "," | "_"
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 sein, das jedes Zeichen sein kann und standardmäßig ein Leerzeichen ist, wenn es weggelassen wird. Es ist nicht möglich, ein literales geschweiftes Klammerzeichen („{“ oder „}“) als fill-Zeichen in einem formatierten Zeichenketten-Literal oder bei Verwendung der Methode str.format() zu verwenden. Es ist jedoch möglich, eine geschweifte Klammer mit einem verschachtelten Ersetzungsfeld einzufügen. Diese Einschränkung betrifft nicht die Funktion format().

Die Bedeutung der verschiedenen Ausrichtungsoptionen ist wie folgt:

Option	Bedeutung
'<'	Erzwingt die linksbündige Ausrichtung des Feldes im verfügbaren Platz (dies ist die Standardeinstellung für die meisten Objekte).
'>'	Erzwingt die rechtsbündige Ausrichtung des Feldes im verfügbaren Platz (dies ist die Standardeinstellung für Zahlen).
'='	Fügt die Auffüllung nach dem Vorzeichen (falls vorhanden), aber vor den Ziffern ein. Dies wird zum Drucken von Feldern in der Form '+000000120' verwendet. Diese Ausrichtungsoption ist nur für numerische Typen gültig, mit Ausnahme von complex. Sie wird zur Standardeinstellung für Zahlen, wenn '0' unmittelbar vor der Feldbreite steht.
'^'	Zentriert das Feld im verfügbaren Platz.

Beachten Sie, dass, sofern keine minimale Feldbreite definiert ist, die Feldbreite immer die gleiche Größe wie der Inhalt hat, so dass die Ausrichtungsoption in diesem Fall keine Bedeutung hat.

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

Option	Bedeutung
'+'	Gibt an, dass für positive und 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' konvertiert negative Null-Gleitkommazahlen nach dem Runden auf die Formatpräzision in positive Null. Diese Option ist nur für Gleitkommadarstellungstypen gültig.

Geändert in Version 3.11: Hinzufügen der Option 'z' (siehe auch PEP 682).

Die Option '#' bewirkt die Verwendung der "alternativen Form" für die Konvertierung. Die alternative Form ist für verschiedene Typen unterschiedlich definiert. Diese Option ist nur für Ganzzahl-, Gleitkomma- und komplexe Typen gültig. Bei Ganzzahlen fügt diese Option bei binärer, oktaler oder hexadezimaler Ausgabe das jeweilige Präfix '0b', '0o', '0x' oder '0X' zum Ausgabewert hinzu. Für Gleitkomma- und komplexe Zahlen bewirkt die alternative Form, dass das Ergebnis der Konvertierung immer ein Dezimalpunktzeichen enthält, auch wenn keine Ziffern folgen. Normalerweise erscheint ein Dezimalpunktzeichen im Ergebnis dieser Konvertierungen nur, wenn eine Ziffer folgt. Darüber hinaus werden bei Konvertierungen 'g' und 'G' nachfolgende Nullen nicht aus dem Ergebnis entfernt.

Die width ist eine Dezimalzahl, die die minimale Gesamtbreite des Feldes definiert, einschließlich Präfixen, Trennzeichen und anderen Formatierungszeichen. Wenn nicht angegeben, wird die Feldbreite durch den Inhalt bestimmt.

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

Geändert in Version 3.10: Das Voranstellen von '0' vor dem width-Feld beeinflusst die Standardausrichtung für Zeichenketten nicht mehr.

Die precision ist eine Dezimalzahl, die angibt, wie viele Ziffern nach dem Dezimalpunkt für die Darstellungstypen 'f' und 'F' oder vor und nach dem Dezimalpunkt für die Darstellungstypen 'g' oder 'G' angezeigt werden sollen. Für 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.

Die grouping-Option nach den width- und precision-Feldern gibt ein Zifferngruppentrennzeichen für den ganzzahligen und den gebrochenen Teil einer Zahl an. Sie kann eine der folgenden sein:

Option	Bedeutung
','	Fügt bei dem Ganzzahl-Darstellungstyp 'd' und bei Gleitkomma-Darstellungstypen, mit Ausnahme von 'n', ein Komma alle 3 Ziffern ein. Für andere Darstellungstypen wird diese Option nicht unterstützt.
'_'	Fügt bei dem Ganzzahl-Darstellungstyp 'd' und bei Gleitkomma-Darstellungstypen, mit Ausnahme von 'n', einen Unterstrich alle 3 Ziffern ein. Für die Ganzzahl-Darstellungstypen 'b', 'o', 'x' und 'X' werden Unterstriche alle 4 Ziffern eingefügt. Für andere Darstellungstypen wird diese Option nicht unterstützt.

Verwenden Sie für ein standortabhängiges Trennzeichen stattdessen den Darstellungstyp 'n'.

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).

Geändert in Version 3.14: Unterstützung der Option Gruppierung für den Bruchteil.

Schließlich bestimmt der Typ, 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	Dasselbe wie 's'.

Die verfügbaren Ganzzahl-Darstellungstypen sind

Typ	Bedeutung
'b'	Binärformat. Gibt die Zahl in Basis 2 aus.
'c'	Zeichen. Konvertiert die Ganzzahl vor der Ausgabe in das entsprechende Unicode-Zeichen.
'd'	Dezimalzahl. Gibt die Zahl in Basis 10 aus.
'o'	Oktalformat. Gibt die Zahl in Basis 8 aus.
'x'	Hexadezimalformat. Gibt die Zahl in Basis 16 aus, wobei Kleinbuchstaben für Ziffern über 9 verwendet werden.
'X'	Hexadezimalformat. Gibt die Zahl in Basis 16 aus, wobei Großbuchstaben für Ziffern über 9 verwendet werden. Wenn '#' angegeben ist, wird das Präfix '0x' ebenfalls zu '0X' großgeschrieben.
'n'	Zahl. Dies ist dasselbe wie 'd', außer dass es die aktuelle Locale-Einstellung verwendet, um die entsprechenden Zifferngruppentrennzeichen einzufügen.
None	Dasselbe wie '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). Wenn dies geschieht, 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. Für eine gegebene Genauigkeit p formatiert die Zahl in wissenschaftlicher Notation, wobei der Buchstabe 'e' den Koeffizienten vom Exponenten trennt. Der Koeffizient hat eine Ziffer vor und p Ziffern nach dem Dezimalpunkt, also insgesamt p + 1 signifikante Stellen. Wenn keine Genauigkeit angegeben ist, wird eine Genauigkeit von 6 Nachkommastellen für float verwendet, und für Decimal werden alle Koeffizientenziffern angezeigt. Wenn p=0 ist, wird der Dezimalpunkt weggelassen, es sei denn, die Option # wird verwendet.
'E'	Wissenschaftliche Notation. Dasselbe wie 'e', außer dass es ein Großbuchstaben 'E' als Trennzeichen verwendet.
'f'	Festkomma-Notation. Für eine gegebene Genauigkeit p formatiert die Zahl als Dezimalzahl mit genau p Ziffern nach dem Dezimalpunkt. Wenn keine Genauigkeit angegeben ist, wird eine Genauigkeit von 6 Nachkommastellen für float verwendet und eine ausreichende Genauigkeit, um alle Koeffizientenziffern für Decimal anzuzeigen. Wenn p=0 ist, wird der Dezimalpunkt weggelassen, es sei denn, die Option # wird verwendet.
'F'	Festkomma-Notation. Dasselbe wie 'f', aber konvertiert nan zu NAN und inf zu INF.
'g'	Allgemeines Format. Für eine gegebene Genauigkeit p >= 1 wird die Zahl auf p signifikante Stellen gerundet und das Ergebnis dann je nach Größenordnung entweder im Festkomma-Format oder in wissenschaftlicher Notation formatiert. Eine Genauigkeit von 0 wird als äquivalent zu einer Genauigkeit von 1 behandelt. Die genauen Regeln lauten wie folgt: Angenommen, das Ergebnis, formatiert mit dem Darstellungstyp 'e' und der Genauigkeit p-1, hätte den Exponenten exp. Dann, wenn m <= exp < p, wobei m -4 für Gleitkommazahlen und -6 für Decimals ist, wird die Zahl mit dem Darstellungstyp 'f' und der Genauigkeit p-1-exp formatiert. Andernfalls wird die Zahl mit dem Darstellungstyp 'e' und der Genauigkeit p-1 formatiert. In beiden Fällen werden unwesentliche nachgestellte Nullen aus dem Signifikanden entfernt, und der Dezimalpunkt wird ebenfalls entfernt, wenn keine verbleibenden Ziffern mehr folgen, es sei denn, die Option '#' wird verwendet. Wenn keine Genauigkeit angegeben ist, wird eine Genauigkeit von 6 signifikanten Stellen für float verwendet. Für Decimal wird der Koeffizient des Ergebnisses aus den Koeffizientenziffern des Werts gebildet; die wissenschaftliche Notation wird für Werte kleiner als 1e-6 im Betrag und für Werte verwendet, bei denen der Stellenwert der niedrigstwertigen Ziffer größer als 1 ist, und die Festkomma-Notation wird andernfalls verwendet. Positive und negative Unendlich, positive und negative Null und NaNs werden als inf, -inf, 0, -0 und nan formatiert, unabhängig von der Genauigkeit.
'G'	Allgemeines Format. Dasselbe wie 'g', außer dass es zu 'E' wechselt, wenn die Zahl zu groß wird. Die Darstellungen von Unendlich und NaN werden ebenfalls großgeschrieben.
'n'	Zahl. Dies ist dasselbe wie 'g', außer dass es die aktuelle Locale-Einstellung verwendet, um die entsprechenden Zifferngruppentrennzeichen für den ganzzahligen Teil einer Zahl einzufügen.
'%'	Prozent. Multipliziert die Zahl mit 100 und zeigt sie im Festkommaformat ('f') an, gefolgt von einem Prozentzeichen.
None	Für float ist dies wie der 'g'-Typ, außer dass bei Verwendung der Festkomma-Notation immer mindestens eine Ziffer nach dem Dezimalpunkt enthalten ist und zur wissenschaftlichen Notation gewechselt wird, wenn exp >= p - 1 ist. Wenn die Genauigkeit nicht angegeben ist, ist letztere so groß wie nötig, um den gegebenen Wert genau darzustellen. Für Decimal ist dies dasselbe wie entweder 'g' oder 'G', abhängig vom Wert von context.capitals für den aktuellen Dezimalkontext. Die Gesamtauswirkung ist, die Ausgabe von str(), modifiziert durch die anderen Formatmodifikatoren, nachzubilden.

Das Ergebnis sollte korrekt auf eine gegebene Genauigkeit p von Stellen nach dem Dezimalpunkt gerundet werden. Der Rundungsmodus für float entspricht dem des eingebauten round(). Für Decimal wird der Rundungsmodus des aktuellen Kontextes verwendet.

Die verfügbaren Darstellungstypen für complex sind dieselben wie für float ('%' ist nicht erlaubt). 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, wobei letzterer mit einem j-Suffix endet. Wenn der Darstellungstyp fehlt, entspricht das Ergebnis der Ausgabe von str() (komplexe Zahlen mit einem nicht-null Realteil sind auch in Klammern eingeschlossen), möglicherweise modifiziert durch andere Formatmodifikatoren.

Formatbeispiele

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

In den meisten Fällen ist die Syntax ähnlich wie bei der alten %-Formatierung, mit der Ergänzung von {} und mit : anstelle von %. Zum Beispiel kann '%03.2f' übersetzt werden zu '{:03.2f}'.

Die neue Formatierungs-Syntax unterstützt auch neue und andere Optionen, wie in den folgenden Beispielen gezeigt.

Zugriff auf Argumente nach Position

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'

Zugriff auf Argumente nach 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
>>> ('The complex number {0} is formed from the real part {0.real} '
...  'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -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() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

Ausrichten des Textes und Festlegen einer Breite

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # use '*' as a fill char
'***********centered***********'

Ersetzen von %+f, %-f und % f und Festlegen eines Vorzeichens

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

Ersetzen von %x und %o und Konvertieren des Werts in verschiedene Basen

>>> # format also supports binary numbers
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "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 des Unterstrichs als Zifferngruppentrennzeichen

>>> '{:,}'.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'
>>> '{:_}'.format(123456789.123456789)
'123_456_789.12345679'
>>> '{:.,}'.format(123456789.123456789)
'123456789.123,456,79'
>>> '{:,._}'.format(123456789.123456789)
'123,456,789.123_456_79'

Ausdrücken eines Prozentsatzes

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

Verwendung typenspezifischer Formatierung

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

Verschachtelte Argumente 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

Vorlagen-Zeichenketten ($-Zeichenketten)

Hinweis

Das hier beschriebene Feature wurde in Python 2.4 eingeführt; eine einfache Vorlagentechnik, die auf regulären Ausdrücken basiert. Sie ist älter als str.format(), formatierte Zeichenkettenliterale und Vorlagen-Zeichenkettenliterale.

Sie hat keinen Bezug zu Vorlagen-Zeichenkettenliteralen (t-Strings), die in Python 3.14 eingeführt wurden. Diese ergeben string.templatelib.Template-Objekte, die im Modul string.templatelib zu finden sind.

Vorlagen-Zeichenketten bieten einfachere Zeichenkettenersetzungen, wie in PEP 292 beschrieben. Ein Hauptanwendungsfall für Vorlagen-Zeichenketten ist die Internationalisierung (i18n), da in diesem Kontext die einfachere Syntax und Funktionalität die Übersetzung erleichtert als andere eingebaute Zeichenkettenformatierungseinrichtungen in Python. Als Beispiel für eine Bibliothek, die auf Vorlagen-Zeichenketten für i18n basiert, siehe das Paket flufl.i18n.

Vorlagen-Zeichenketten unterstützen $-basierte Ersetzungen nach folgenden Regeln

• $$ ist eine Escape-Sequenz; sie wird durch ein einzelnes $ ersetzt.

• $identifier benennt einen Substitutionsplatzhalter, der mit einem Mapping-Schlüssel von "identifier" übereinstimmt. Standardmäßig ist "identifier" auf eine beliebige ASCII-alphanumerische Zeichenkette (einschließlich Unterstriche) beschränkt, die mit einem Unterstrich oder einem ASCII-Buchstaben beginnt und Groß-/Kleinschreibung ignoriert. Das erste Zeichen, das kein Bezeichner-Zeichen ist und nach dem $-Zeichen kommt, beendet diese Platzhalterspezifikation.

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

Jede andere Darstellung von $ in der Zeichenkette führt zu einem Fehler vom Typ ValueError.

Das Modul string stellt eine Klasse Template zur Verfügung, die diese Regeln implementiert. Die Methoden von Template sind

class string.Template(template)

Der Konstruktor nimmt ein einzelnes Argument entgegen, bei dem es sich um die Vorlagen-Zeichenkette handelt.

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

Führt die Vorlagen-Substitution durch und gibt eine neue Zeichenkette zurück. mapping ist jedes Wörterbuch-ähnliche Objekt mit Schlüsseln, die mit den Platzhaltern in der Vorlage übereinstimmen. Alternativ können Sie Schlüsselwortargumente bereitstellen, bei denen die Schlüssel die Platzhalter sind. Wenn sowohl mapping als auch kwds gegeben sind und es Duplikate gibt, haben die Platzhalter aus kwds Vorrang.

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

Wie substitute(), außer dass, wenn Platzhalter in mapping und kwds fehlen, anstatt eine KeyError-Ausnahme auszulösen, der ursprüngliche Platzhalter intakt in der resultierenden Zeichenkette erscheint. Auch im Gegensatz zu substitute() werden alle anderen Darstellungen von $ einfach $ zurückgeben, anstatt ValueError auszulösen.

Während andere Ausnahmen immer noch auftreten können, wird diese Methode als "sicher" bezeichnet, da sie immer versucht, eine brauchbare Zeichenkette zurückzugeben, anstatt eine Ausnahme auszulösen. In einem anderen Sinne kann safe_substitute() alles andere als sicher sein, da sie fehlerhafte Vorlagen mit losen Trennzeichen, unpassenden Klammern oder Platzhaltern, die keine gültigen Python-Bezeichner sind, stillschweigend ignoriert.

is_valid()

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

Hinzugefügt in Version 3.11.

get_identifiers()

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

Hinzugefügt in Version 3.11.

Template-Instanzen stellen auch 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, aber ein schreibgeschützter Zugriff wird nicht erzwungen.

Hier ist ein Beispiel für die Verwendung einer Vorlage

>>> 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'

Erweiterte Verwendung: Sie können Unterklassen von Template ableiten, um die Platzhalter-Syntax, das Trennzeichen oder den gesamten regulären Ausdruck, der zum Parsen von Vorlagen-Zeichenketten verwendet wird, anzupassen. Dazu können Sie die folgenden Klassenattribute überschreiben

• delimiter – Dies ist die literale Zeichenkette, die den Platzhalter einleitenden Trennzeichen beschreibt. Der Standardwert ist $. Beachten Sie, dass dies kein regulärer Ausdruck sein sollte, da die Implementierung re.escape() auf diese Zeichenkette anwendet, wo nötig. Beachten Sie ferner, dass Sie das Trennzeichen nach der Klassenerstellung nicht ändern können (d. h. ein anderes Trennzeichen muss im Klassen-Namespace der Unterklasse festgelegt werden).

• idpattern – Dies ist der reguläre Ausdruck, der das Muster für nicht in Klammern gesetzte Platzhalter beschreibt. Der Standardwert ist der reguläre Ausdruck (?a:[_a-z][_a-z0-9]*). Wenn dies gegeben und braceidpattern None ist, gilt dieses Muster auch für Platzhalter in Klammern.

  Hinweis

  Da der Standard-flags re.IGNORECASE ist, kann das Muster [a-z] mit einigen Nicht-ASCII-Zeichen übereinstimmen. Deshalb verwenden wir hier das lokale Flag a.

  Geändert in Version 3.7: braceidpattern kann verwendet werden, um separate Muster zu definieren, die innerhalb und außerhalb von Klammern verwendet werden.

• braceidpattern – Dies ist wie idpattern, beschreibt aber das Muster für Platzhalter in Klammern. Standardmäßig ist es None, was bedeutet, dass auf idpattern zurückgegriffen wird (d. h. dasselbe Muster wird sowohl innerhalb als auch außerhalb von Klammern verwendet). Wenn es gegeben ist, können Sie unterschiedliche Muster für Platzhalter in Klammern und ohne Klammern definieren.

  Hinzugefügt in Version 3.7.

• flags – Die Flags des regulären Ausdrucks, die beim Kompilieren des für die Erkennung von Ersetzungen verwendeten regulären Ausdrucks angewendet werden. Der Standardwert ist re.IGNORECASE. Beachten Sie, dass re.VERBOSE immer zu den Flags hinzugefügt wird, sodass benutzerdefinierte idpatterns den Konventionen für ausführliche reguläre Ausdrücke folgen müssen.

  Hinzugefügt in Version 3.2.

Alternativ können Sie den gesamten regulären Ausdruck bereitstellen, indem Sie das Klassenattribut pattern überschreiben. Wenn Sie dies tun, muss der Wert ein reguläres Ausdrucksobjekt mit vier benannten Erfassungsgruppen sein. Die Erfassungsgruppen entsprechen den oben genannten Regeln sowie der Regel für ungültige Platzhalter

• escaped – Diese Gruppe passt auf die Escape-Sequenz, z. B. $$, im Standardmuster.

• named – Diese Gruppe passt auf den Namen des nicht in Klammern gesetzten Platzhalters; sie sollte den Trenner nicht in der Erfassungsgruppe enthalten.

• braced – Diese Gruppe passt auf den Namen des in Klammern gesetzten Platzhalters; sie sollte weder den Trenner noch die Klammern in der Erfassungsgruppe enthalten.

• invalid – Diese Gruppe passt auf jedes andere Trennzeichenmuster (normalerweise ein einzelner Trenner) und sollte zuletzt im regulären Ausdruck erscheinen.

Die Methoden dieser Klasse lösen ValueError aus, wenn das Muster mit der Vorlage übereinstimmt, ohne eine dieser benannten Gruppen abzugleichen.

Hilfsfunktionen

string.capwords(s, sep=None)

Teilt das Argument mit str.split() in Wörter auf, macht jedes Wort mit str.capitalize() zum Anfangsbuchstaben 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 Läufe von Leerzeichen durch ein einzelnes Leerzeichen ersetzt und führende sowie nachgestellte Leerzeichen entfernt, andernfalls wird sep zum Aufteilen und Zusammenfügen der Wörter verwendet.