字串常數¶

此模組中定義的常數為：

string.ascii_letters¶

下文描述的 ascii_lowercase 和 ascii_uppercase 常數的串接，該值不依賴於區域設定。

string.ascii_lowercase¶

小寫字母 'abcdefghijklmnopqrstuvwxyz'。該值與地區設定無關且不會改變。

string.ascii_uppercase¶

大寫字母 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'。此值與地區設定無關且不會改變。

string.digits¶

字串 '0123456789'。

string.hexdigits¶

字串 '0123456789abcdefABCDEF'。

string.octdigits¶

字串 '01234567'。

string.punctuation¶

在 C 語言中被視為標點符號的 ASCII 字元的字串：!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~。

string.printable¶

ASCII 字元的字串被 Python 是為可被列印輸出的。這是 digits、ascii_letters、punctuation 和 whitespace 的組合。

備註

By design, string.printable.isprintable() returns False. In particular, string.printable is not printable in the POSIX sense (see LC_CTYPE).

string.whitespace¶

包含所有 ASCII 字元的字串都視為空白字元 (whitespace)。 包含空格 (space)、製表符號 (tab)、換行符號 (linefeed)、return、換頁符號 (formfeed) 和垂直製表符號 (vertical tab) 這些字元。

自訂字串格式¶

透過 PEP 3101 中描述的 format() 方法，內建字串類別提供了進行複雜變數替換和數值格式化的能力。string 模組中的 Formatter 類別模組可讓你使用與內建 format() 方法相同的實作來建立和自訂你自己的字串格式化行為。

class string.Formatter¶

Formatter 類別有以下的公開方法：

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

主要的 API 方法。它接收一個格式字串及一組任意的位置引數與關鍵字引數，是呼叫 vformat() 的包裝器 (wrapper)。

在 3.7 版的變更: 現在格式字串引數是僅限位置參數。

vformat(format_string, args, kwargs)¶

This function does the actual work of formatting. It is exposed as a separate function for cases where you want to pass in a predefined dictionary of arguments, rather than unpacking and repacking the dictionary as individual arguments using the *args and **kwargs syntax. vformat() does the work of breaking up the format string into character data and replacement fields. It calls the various methods described below.

In addition, the Formatter defines a number of methods that are intended to be replaced by subclasses:

parse(format_string)¶

將 format_string 放入迴圈，並回傳一個可疊代物件，其元素為 (literal_text, field_name, format_spec, conversion)。這會被 vformat() 用於將字串裁切為字面文本或替換欄位。

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. The value of field_name is unmodified and auto-numbering of non-numbered positional fields is done by vformat().

get_field(field_name, args, kwargs)¶

Given field_name, convert it to an object to be formatted. Auto-numbering of field_name returned from parse() is done by vformat() before calling this method. 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)¶

Retrieve a given field value. The key argument will be either an integer or a string. If it is an integer, it represents the index of the positional argument in args; if it is a string, then it represents a named argument in kwargs.

The args parameter is set to the list of positional arguments to vformat(), and the kwargs parameter is set to the dictionary of keyword arguments.

For compound field names, these functions are only called for the first component of the field name; subsequent components are handled through normal attribute and indexing operations.

So for example, the field expression '0.name' would cause get_value() to be called with a key argument of 0. The name attribute will be looked up after get_value() returns by calling the built-in getattr() function.

If the index or keyword refers to an item that does not exist, then an IndexError or KeyError should be raised.

check_unused_args(used_args, args, kwargs)¶

Implement checking for unused arguments if desired. The arguments to this function is the set of all argument keys that were actually referred to in the format string (integers for positional arguments, and strings for named arguments), and a reference to the args and kwargs that was passed to vformat. The set of unused args can be calculated from these parameters. check_unused_args() is assumed to raise an exception if the check fails.

format_field(value, format_spec)¶

format_field() simply calls the global format() built-in. The method is provided so that subclasses can override it.

convert_field(value, conversion)¶

Converts the value (returned by get_field()) given a conversion type (as in the tuple returned by the parse() method). The default version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion types.

格式化文字語法¶

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 and template string literals, but it is less sophisticated and, in particular, does not support arbitrary expressions in interpolations.

Format strings contain "replacement fields" surrounded by curly braces {}. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output. If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}.

The grammar for a replacement field is as follows:

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

In less formal terms, the replacement field can start with a field_name that specifies the object whose value is to be formatted and inserted into the output instead of the replacement field. The field_name is optionally followed by a conversion field, which is preceded by an exclamation point '!', and a format_spec, which is preceded by a colon ':'. These specify a non-default format for the replacement value.

另請參閱 格式規格 (Format Specification) 迷你語言 部份。

The field_name itself begins with an arg_name that is either a number or a keyword. If it's a number, it refers to a positional argument, and if it's a keyword, it refers to a named keyword argument. An arg_name is treated as a number if a call to str.isdecimal() on the string would return true. If the numerical arg_names in a format string are 0, 1, 2, ... in sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be automatically inserted in that order. Because arg_name is not quote-delimited, it is not possible to specify arbitrary dictionary keys (e.g., the strings '10' or ':-]') within a format string. The arg_name can be followed by any number of index or attribute expressions. An expression of the form '.name' selects the named attribute using getattr(), while an expression of the form '[index]' does an index lookup using __getitem__().

Some simple format string examples:

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

The conversion field causes a type coercion before formatting. Normally, the job of formatting a value is done by the __format__() method of the value itself. However, in some cases it is desirable to force a type to be formatted as a string, overriding its own definition of formatting. By converting the value to a string before calling __format__(), the normal formatting logic is bypassed.

目前支援三種轉換旗標：'!s' 會對該值呼叫 str()，'!r' 會對該值呼叫 repr()，而 '!a' 則會對該值呼叫 ascii()。

一些範例：

"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

format_spec 欄位描述了值的呈現規格，例如欄位寬度、對齊、填充 (padding)、小數精度等細節資訊。每種值類型都可以定義自己的「格式化迷你語言 (formatting mini-language)」或對 format_spec 的解釋。

大多數內建型別都支援常見的格式化迷你語言，下一節將會詳細說明。

format_spec 欄位還可以在其內部包含巢狀的替換欄位。這些巢狀的替換欄位可能包含欄位名稱、轉換旗標、格式規格描述，但是不允許再更深層的巢狀結構。format_spec 內部的替換欄位會在 format_spec 字串被直譯前被替換。這讓數值的格式能夠被動態地指定。

範例請見 格式範例。

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" | "%"

>>> '{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')      # 解包引數序列
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # 引數索引可以重複
'abracadabra'

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

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

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

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

>>> '{:<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***********'

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # 總會顯示
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # 若為正數則顯示空格
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # 只顯示負號 -- 與 '{:f}; {:f}' 相同
'3.140000; -3.140000'

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

>>> '{:,}'.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'

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

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

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

模板字串 ($-strings)¶

模板字串提供如 PEP 292 所述更簡單的字串替換。模板字串的主要用例是國際化 (i18n)，因為在這種情況下，更簡單的語法和功能使得它比其他 Python 內建字串格式化工具更容易翻譯。基於模板字串建構的 i18n 函式庫範例，請參閱 flufl.i18n 套件。

Template strings support $-based substitutions, using the following rules:

• $$ is an escape; it is replaced with a single $.

• $identifier names a substitution placeholder matching a mapping key of "identifier". By default, "identifier" is restricted to any case-insensitive ASCII alphanumeric string (including underscores) that starts with an underscore or ASCII letter. The first non-identifier character after the $ character terminates this placeholder specification.

• ${identifier} is equivalent to $identifier. It is required when valid identifier characters follow the placeholder but are not part of the placeholder, such as "${noun}ification".

Any other appearance of $ in the string will result in a ValueError being raised.

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

class string.Template(template)¶

The constructor takes a single argument which is the template string.

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

進行模板替換，並回傳一個新的字串。 mapping 是任何有金鑰並符合模板裡佔位符號的字典型物件。或者如果關鍵字就是佔位符號時，你也可以改提供關鍵字引數。當 mapping 跟 kwds 同時給定並存在重複時，kwds 的佔位符號會被優先使用。

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

類似於 substitute()，但如果 mapping 與 kwds 中缺少佔位符號的話，原始的佔位符號會完整地出現在結果字串裡，而不會引發 KeyError 例外。此外，與 substitute() 不同的是，任何包含 $ 的字句會直接回傳 $ 而非引發 ValueError。

雖然仍可能發生其他例外，但這個方法被認為是「安全」的，因為它總是試圖回傳一個有用的字串而不是引發例外。從另一個角度來看，safe_substitute() 可能並非完全安全，因為它會默默忽略格式錯誤的模板，這些模板包含了多餘的左右定界符、不匹配的括號，或者不是有效的 Python 識別字的佔位符號。

is_valid()¶

如果模板有將導致 substitute() 引發 ValueError 的無效佔位符號，就會回傳 False。

在 3.11 版被加入.

get_identifiers()¶

回傳模板中有效識別字的串列，按照它們首次出現的順序，並忽略任何無效的識別字。

在 3.11 版被加入.

Template 實例也提供一個公開的資料屬性：

template¶

這是傳遞給建構函式 template 引數的物件。一般來說，你不應該改變它，但並沒有強制設定成唯讀。

以下是如何使用 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'

進階用法：你可以衍生 Template 類別來自訂佔位符號語法、左右定界符字元，或者用於剖析模板字串的正規表示式。你可以透過覆寫這些類別屬性來達成：

• delimiter -- 這是描述引入左右定界符的文字字串。預設值是 $。請注意這不是正規表示式，因為實作會在需要時對這個字串呼叫 re.escape()。也請注意你不能在建立類別後修改左右定界符。（意即在子類別的命名空間中必須設置不同的左右定界符）

• idpattern -- This is the regular expression describing the pattern for non-braced placeholders. The default value is the regular expression (?a:[_a-z][_a-z0-9]*). If this is given and braceidpattern is None this pattern will also apply to braced placeholders.

  備註

  Since default flags is re.IGNORECASE, pattern [a-z] can match with some non-ASCII characters. That's why we use the local a flag here.

  在 3.7 版的變更: braceidpattern can be used to define separate patterns used inside and outside the braces.

• braceidpattern -- This is like idpattern but describes the pattern for braced placeholders. Defaults to None which means to fall back to idpattern (i.e. the same pattern is used both inside and outside braces). If given, this allows you to define different patterns for braced and unbraced placeholders.

  在 3.7 版被加入.

• flags -- The regular expression flags that will be applied when compiling the regular expression used for recognizing substitutions. The default value is re.IGNORECASE. Note that re.VERBOSE will always be added to the flags, so custom idpatterns must follow conventions for verbose regular expressions.

  在 3.2 版被加入.

Alternatively, you can provide the entire regular expression pattern by overriding the class attribute pattern. If you do this, the value must be a regular expression pattern string, or a compiled regular expression object, with four named capturing groups. The capturing groups correspond to the rules given above, along with the invalid placeholder rule:

• escaped -- 此群組與跳脫序列匹配，例如在預設模式下為 $$。

• named -- 此群組與不帶大括號的佔位符號名稱匹配；它不應包含擷取群組中的左右定界符號。

• braced -- 此群組與大括號括起來的佔位符號名稱匹配；它不應在擷取群組中包含左右定界符或大括號。

• invalid -- 此群組與任何其他左右定界符模式（通常是單一左右定界符）匹配，且它應該出現在正規表示式的最後。

當此模式有匹配於模板但這些命名組中卻有任一個不匹配，此類別的方法將引發 ValueError。

輔助函式¶

string.capwords(s, sep=None)¶

使用 str.split() 將引數分割為字詞，使用 str.capitalize() 將每個單字大寫，並使用 str.join() 將大寫字詞連接起來。如果可選的第二引數 sep 不存在或為 None，則連續的空白字元將替換為單一空格，並且刪除前導和尾隨空白；在其他情況下則使用 sep 來分割和連接單字。