string — 常见的字符串操作¶

字符串常量¶

此模块中定义的常量为：

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 字符字符串。这是 digits、ascii_letters、punctuation 和 whitespace 的组合。

string.whitespace¶

包含所有被视为空白的 ASCII 字符的字符串。这包括空格、制表符、换行符、回车符、换页符和垂直制表符。

自定义字符串格式化¶

内置的字符串类提供了通过 format() 方法进行复杂变量替换和值格式化的功能，该方法在 PEP 3101 中进行了描述。 Formatter 类位于 string 模块中，允许您使用与内置 format() 方法相同的实现来创建和自定义您自己的字符串格式化行为。

class string.Formatter¶

Formatter 类具有以下公共方法：

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

主要的 API 方法。它接受一个格式字符串和一组任意的位置参数和关键字参数。它只是一个调用 vformat() 的包装器。

在 3.7 版更改: 格式字符串参数现在是仅限位置参数。

vformat(format_string, args, kwargs)¶

此函数执行实际的格式化工作。它作为一个单独的函数公开，用于您希望传入预定义的参数字典，而不是使用 *args 和 **kwargs 语法将字典解包和重新打包为单个参数的情况。 vformat() 完成了将格式字符串分解为字符数据和替换字段的工作。它调用了下面描述的各种方法。

此外，Formatter 定义了许多旨在由子类替换的方法：

parse(format_string)¶

循环遍历 format_string 并返回一个元组 (literal_text, field_name, format_spec, conversion) 的可迭代对象。 vformat() 使用它将字符串分解为文字文本或替换字段。

元组中的值在概念上表示一个文字文本范围，后跟一个替换字段。如果没有文字文本（如果两个替换字段连续出现，则可能会发生这种情况），则 literal_text 将是一个零长度字符串。如果没有替换字段，则 field_name、format_spec 和 conversion 的值将为 None。

get_field(field_name, args, kwargs)¶

给定 parse() 返回的 field_name（见上文），将其转换为要格式化的对象。返回一个元组 (obj, used_key)。默认版本采用 PEP 3101 中定义的字符串形式，例如 “0[name]” 或 “label.title”。args 和 kwargs 与传递给 vformat() 的参数相同。返回值 used_key 与 get_value() 的 key 参数含义相同。

get_value(key, args, kwargs)¶

检索给定的字段值。key 参数可以是整数或字符串。如果是整数，则表示 args 中位置参数的索引；如果是字符串，则表示 kwargs 中的命名参数。

args 参数设置为 vformat() 的位置参数列表，kwargs 参数设置为关键字参数的字典。

对于复合字段名，这些函数仅针对字段名的第一个组件调用；后续组件通过正常的属性和索引操作处理。

例如，字段表达式 “0.name” 会导致使用 key 参数 0 调用 get_value()。在 get_value() 返回后，将通过调用内置函数 getattr() 查找 name 属性。

如果索引或关键字引用了不存在的项，则应引发 IndexError 或 KeyError。

check_unused_args(used_args, args, kwargs)¶

如果需要，实现对未使用参数的检查。此函数的参数是格式字符串中实际引用的所有参数键的集合（整数表示位置参数，字符串表示命名参数），以及对传递给 vformat 的 args 和 kwargs 的引用。可以从这些参数中计算出未使用参数的集合。假设如果检查失败，check_unused_args() 会引发异常。

format_field(value, format_spec)¶

format_field() 只是调用全局 format() 内置函数。提供该方法是为了让子类可以覆盖它。

convert_field(value, conversion)¶

给定转换类型（如 parse() 方法返回的元组中所示），转换值（由 get_field() 返回）。默认版本理解 's' (str)、'r' (repr) 和 'a' (ascii) 转换类型。

格式字符串语法¶

str.format() 方法和 Formatter 类共享相同的格式字符串语法（尽管对于 Formatter，子类可以定义自己的格式字符串语法）。该语法与 格式字符串字面量 的语法相关，但不那么复杂，特别是，它不支持任意表达式。

格式字符串包含由花括号 {} 包围的“替换字段”。任何未包含在花括号中的内容都被视为文字文本，这些文本会被原封不动地复制到输出中。如果需要在文字文本中包含花括号字符，可以通过加倍来转义：{{ 和 }}。

替换字段的语法如下

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

用不太正式的术语来说，替换字段可以以 field_name 开头，该名称指定要格式化并插入到输出中以代替替换字段的对象的值。field_name 后面可以选择跟一个 conversion 字段，该字段前面有一个感叹号 '!'，以及一个 format_spec，该字段前面有一个冒号 ':'。这些指定了替换值的非默认格式。

另请参阅 格式规范迷你语言 部分。

field_name 本身以 arg_name 开头，它可以是一个数字或一个关键字。如果是数字，它指的是一个位置参数；如果是关键字，它指的是一个命名的关键字参数。如果对字符串调用 str.isdecimal() 返回 true，则 arg_name 将被视为数字。如果格式字符串中的数字 arg_name 按顺序为 0、1、2……，则可以省略所有这些数字（而不仅仅是一些），并且数字 0、1、2……将按此顺序自动插入。因为 arg_name 不是用引号分隔的，所以不可能在格式字符串中指定任意字典键（例如，字符串 '10' 或 ':-]'）。arg_name 后面可以跟任意数量的索引或属性表达式。形式为 '.name' 的表达式使用 getattr() 选择命名的属性，而形式为 '[index]' 的表达式使用 __getitem__() 进行索引查找。

一些简单的格式字符串示例

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

conversion 字段会在格式化之前进行类型强制转换。通常，格式化值的工作由值本身的 __format__() 方法完成。但是，在某些情况下，需要强制将类型格式化为字符串，从而覆盖其自身的格式化定义。通过在调用 __format__() 之前将值转换为字符串，可以绕过正常的格式化逻辑。

当前支持三个转换标志：'!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 字段包含值的显示方式规范，包括字段宽度、对齐方式、填充、小数精度等详细信息。每种值类型都可以定义自己的“格式化迷你语言”或对 format_spec 的解释。

大多数内置类型都支持一种通用的格式化迷你语言，这将在下一节中介绍。

format_spec 字段还可以包含嵌套的替换字段。这些嵌套的替换字段可以包含字段名称、转换标志和格式规范，但不允许更深层的嵌套。在解释 format_spec 字符串之前，将替换 format_spec 中的替换字段。这允许动态指定值的格式。

有关一些示例，请参见 格式示例 部分。

format_spec     ::=  [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]
fill            ::=  <any character>
align           ::=  "<" | ">" | "=" | "^"
sign            ::=  "+" | "-" | " "
width           ::=  digit+
grouping_option ::=  "_" | ","
precision       ::=  digit+
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')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'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)  # 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'

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

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

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

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

模板字符串¶

模板字符串提供更简单的字符串替换，如 PEP 292 中所述。模板字符串的一个主要用例是国际化 (i18n)，因为在这种情况下，更简单的语法和功能使其比 Python 中其他内置字符串格式化工具更容易翻译。有关为 i18n 构建在模板字符串上的库的示例，请参阅 flufl.i18n 包。

模板字符串支持基于 $ 的替换，使用以下规则

• $$ 是转义符；它被替换为单个 $。

• $identifier 命名一个与 "identifier" 的映射键匹配的替换占位符。默认情况下，"identifier" 仅限于以 ASCII 字母或下划线开头且不区分大小写的 ASCII 字母数字字符串（包括下划线）。$ 字符后的第一个非标识符字符终止此占位符规范。

• ${identifier} 等效于 $identifier。当有效的标识符字符跟在占位符之后但不属于占位符的一部分时，例如 "${noun}ification"，则需要使用它。

字符串中任何其他出现 $ 的情况都将导致引发 ValueError。

string 模块提供了一个 Template 类，该类实现了这些规则。Template 的方法是

class string.Template(template)¶

构造函数接受一个参数，即模板字符串。

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 参数的对象。通常，您不应该更改它，但不会强制执行只读访问。

以下是使用模板的示例

>>> 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 – 这是一个正则表达式，描述了非括号占位符的模式。默认值为正则表达式 (?a:[_a-z][_a-z0-9]*)。如果给定了此项，并且 braceidpattern 为 None，则此模式也将应用于括号占位符。

  注意

  由于默认 flags 为 re.IGNORECASE，因此模式 [a-z] 可以与某些非 ASCII 字符匹配。这就是我们在此处使用本地 a 标志的原因。

  版本 3.7 中的变化： braceidpattern 可用于定义在括号内部和外部使用的不同模式。

• braceidpattern – 这类似于 idpattern，但描述了括号占位符的模式。默认为 None，这意味着回退到 idpattern（即，在括号内部和外部使用相同的模式）。如果给定，则允许您为括号和非括号占位符定义不同的模式。

  版本 3.7 中的新增功能。

• flags – 编译用于识别替换的正则表达式时将应用的正则表达式标志。默认值为 re.IGNORECASE。请注意，re.VERBOSE 将始终添加到标志中，因此自定义 idpattern 必须遵循详细正则表达式的约定。

  版本 3.2 中的新增功能。

或者，您可以通过覆盖类属性 pattern 来提供整个正则表达式模式。如果这样做，则该值必须是具有四个命名捕获组的正则表达式对象。捕获组对应于上面给出的规则，以及无效占位符规则

• escaped – 此组匹配默认模式中的转义序列，例如 $$。

• named – 此组匹配非括号占位符名称；它不应在捕获组中包含分隔符。

• braced – 此组匹配括号括起来的占位符名称；它不应在捕获组中包含分隔符或括号。

• invalid – 此组匹配任何其他分隔符模式（通常是单个分隔符），并且它应该出现在正则表达式的最后。

如果模式与模板匹配但没有匹配这些命名组之一，则此类上的方法将引发 ValueError。

辅助函数¶

string.capwords(s, sep=None)¶

使用 str.split() 将参数拆分为单词，使用 str.capitalize() 将每个单词首字母大写，并使用 str.join() 连接首字母大写的单词。如果缺少可选的第二个参数 sep 或为 None，则连续的空白字符将替换为单个空格，并删除前导和尾随空格，否则将使用 sep 来拆分和连接单词。