string

源代码： Lib / string.py

该string模块包含许多有用的常量和类，以及一些不建议使用的遗留函数，这些函数也可用作字符串方法。此外，Python的内置字符串类支持序列类型 - str，unicode，list，tuple，bytearray，buffer，xrange部分中描述的序列类型方法，还支持String Methods部分中描述的字符串特定方法。要输出格式化的字符串，请使用%字符串格式操作部分中描述的模板字符串或运算符。另请参阅re模块，了解基于正则表达式的字符串函数。

1.字符串常量

这个模块中定义的常量是：

string.ascii_letters

下面描述的ascii_lowercase和ascii_uppercase常量的连接。该值不是区域设置相关的。

string.ascii_lowercase

小写字母'abcdefghijklmnopqrstuvwxyz'。此值不是区域设置相关的，不会更改。

string.ascii_uppercase

大写字母'ABCDEFGHIJKLMNOPQRSTUVWXYZ'。此值不是区域设置相关的，不会更改。

string.digits

字符串'0123456789'。

string.hexdigits

字符串'0123456789abcdefABCDEF'。

string.letters

字符串的连接lowercase和uppercase在下面进行描述。具体的值是语言环境相关的，并且在locale.setlocale()被调用时会被更新。

string.lowercase

包含所有被认为是小写字母的字符的字符串。在大多数系统中，这是字符串'abcdefghijklmnopqrstuvwxyz'。具体的值是语言环境相关的，并且在locale.setlocale()被调用时会被更新。

string.octdigits

字符串'01234567'。

string.punctuation

在C区域设置中被认为是标点符号的ASCII字符字符串。

string.printable

被认为可打印的字符串。这是一个digits，letters，punctuation，和whitespace的组合

string.uppercase

包含所有被认为是大写字母的字符的字符串。在大多数系统中，这是字符串'ABCDEFGHIJKLMNOPQRSTUVWXYZ'。具体的值是语言环境相关的，并且在locale.setlocale()被调用时会被更新。

string.whitespace

包含被视为空白的所有字符的字符串。在大多数系统上，这包括字符空间，制表符，换行符，返回，换页和垂直制表符。

2.自定义字符串格式

2.6版本中的新功能。

内置的str和unicode类提供了通过PEP 3101中描述的str.format（）方法执行复杂变量替换和值格式化的功能。字符串模块中的Formatter类允许您创建和自定义您自己的字符串格式化行为 使用与内置format（）方法相同的实现。

class string.Formatter

该Formatter类有下列公共方法：

format(format_string, *args, **kwargs)

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

vformat(format_string, args, kwargs)

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

另外，Formatter定义了一些打算由子类替换的方法：

parse(format_string)

循环format_string并返回一组元组（literal_text，field_name，format_spec，转换）。 这被vformat（）用来将字符串分解为文本文本或替换字段。

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

get_field(field_name, args, kwargs)

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

get_value(key, args, kwargs)

检索给定的字段值。key 参数将是一个整数或字符串。如果它是一个整数，它表示args中位置参数的索引; 如果它是一个字符串，那么它表示kwargs中的命名参数。

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

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

因此，例如，字段表达式'0.name'将导致get_value（）被调用，其关键参数为0. name属性将在get_value（）返回后通过调用内置的getattr（）函数来查找。

如果索引或关键字引用不存在的项目，则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)

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

3.格式化字符串语法

该str.format()方法和Formatter类共享格式字符串的相同语法（尽管在Formatter子类中可以定义它们自己的格式字符串语法）。

格式字符串包含由花括号包围的“替换字段” {}。任何不包含在大括号中的内容都将被视为文字文本，并将其原样复制到输出中。如果您需要在文字中包含大括号字符，则可以通过加倍：{{和来避开}}。

替换字段的语法如下所示：

在不太正式的术语中，替换字段可以以field_name开头，该字段指定要格式化其值的对象，并将其插入到输出中而不是替换字段中。 field_name后面紧跟着一个转换字段，前面有一个感叹号'！'和一个format_spec，前面有一个冒号'：'。 这些指定替代值的非默认格式。

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

field_name本身以一个数字或关键字的arg_name开头。 如果它是一个数字，它指的是一个位置参数，如果它是一个关键字，则它指的是一个已命名的关键字参数。 如果格式字符串中的数字arg_names依次为0,1,2，...，则它们都可以省略（不仅仅是一些），并且数字0,1,2，...将按该顺序自动插入。 由于arg_name不是以引号分隔的，因此不可能在格式字符串中指定任何字典键（例如，字符串'10'或'： - ]'）。 arg_name可以跟随任意数量的索引或属性表达式。 '.name'形式的表达式使用getattr（）来选择指定的属性，而形式'[index]'的表达式则使用__getitem __（）进行索引查找。

在版本2.7中更改：位置参数说明符可以省略，所以'{} {}'相当于'{0} {1}'。

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

格式化之前，转换 字段会导致类型强制转换。通常，格式化值的工作是通过__format__()值本身的方法完成的。但是，在某些情况下，希望强制将某个类型格式化为字符串，并覆盖自己的格式定义。通过在调用之前将该值转换为字符串__format__()，正常的格式化逻辑被绕过。

目前支持两种转换标志：对该值调用str（）的'！s'和调用repr（）的'！r'。

一些例子：

所述format_spec字段包含的值应该如何被呈现，包括这样的细节如场宽度，对齐，填充，小数精度等的规范。每个值类型都可以定义自己的“格式化迷你语言”或format_spec的解释。

大多数内置类型支持通用的格式化迷你语言，下一节将对此进行介绍。

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

有关示例，请参阅格式示例部分。

3.1 格式规范迷你语言

“格式规范”用于格式字符串中包含的替换字段中，以定义如何呈现单个值（请参阅格式字符串语法）。它们也可以直接传递给内置format()函数。每个格式表类型可以定义格式规范如何解释。

大多数内置类型为格式规范实现了以下选项，尽管某些格式化选项仅受数字类型支持。

一般惯例是空字符串（""）产生的结果与您调用str()该值时相同。非空格式字符串通常会修改结果。

标准格式说明符的一般形式是：

如果指定了有效的对齐值，则可以在前面加上一个填充字符，该字符可以是任何字符，如果省略，则默认为空格。在使用该方法时，不可能使用文字大括号（“ {”或“ }”）作为填充字符str.format()。但是，可以插入带有嵌套替换字段的大括号。该限制不影响该format()功能。

各种对齐选项的含义如下：

请注意，除非定义了最小字段宽度，否则字段宽度将始终与要填充它的数据的大小相同，以便在此情况下对齐选项无效。

该sign 的选择是仅适用于数字类型，并且可以是下列之一：

该'#'选项仅适用于整数，仅适用于二进制，八进制或十六进制输出。如果存在的话，它规定的输出将通过此方式分别作为前缀'0b'，'0o'或者'0x'。

该','选项表示使用千位分隔符的逗号。对于感知区域的分隔符，请'n'改为使用整数表示类型。

在版本2.7中更改：添加了该','选项（另请参阅PEP 378）。

width 是定义最小字段宽度的十进制整数。如果未指定，则字段宽度将由内容决定。

如果未给出明确的对齐方式，则在宽度字段前加上一个零（'0'）字符可为数字类型启用符号感知零填充。 这相当于填充字符'0'，对齐类型为'='。

精度是一个十进制数，表示在用'f'和'F'格式化的浮点值之后，或者用'g'格式化的浮点值的小数点前后小数点后应该显示多少位数或 'G'。 对于非数字类型，该字段指示最大字段大小 - 换言之，字段内容将使用多少个字符。 整数值不允许使用精度。

最后，type 决定了数据应该如何呈现。

可用的字符串演示文稿类型是：

可用的整数表示类型是：

除了上述表示类型之外，整数还可以使用下面列出的浮点表示类型进行格式化（除了'n'和None）。这样做时，float()用于在格式化之前将整数转换为浮点数。

浮点和小数值的可用表示类型是：

3.2 格式示例

本节包含str.format（）语法的示例以及与旧％格式的比较。

在大多数情况下，语法与旧的％格式类似，但添加了{}和with：而不是％。 例如，'％03.2f'可以翻译为'{：03.2f}'。

新的格式语法也支持新的和不同的选项，如下面的例子所示。

按位置访问参数：

按名称访问参数：

访问参数的属性：

访问参数的项目：

替换%s和%r：

对齐文本并指定宽度：

更换%+f，%-f以及% f与指定的标志：

替换%x与%o值，转换为不同的基础：

使用逗号作为千位分隔符：

表示一个百分比：

使用特定于类型的格式：

嵌套论据和更复杂的例子：

4.模板字符串

2.4版本中的新功能。

模板提供了更简单的字符串替换，如PEP 292中所述。使用以下规则，模板支持基于$的替换，而不是正常的基于％的替换：

• $$是一种转义字符; 它被替换为一个单一的$。

• $ identifier为与“标识符”的映射关键字匹配的替换占位符命名。 默认情况下，“标识符”必须拼写一个Python标识符。 $字符后的第一个非标识符字符终止了这个占位符规范。

• $ {identifier}相当于$ identifier。 当有效标识符字符跟随占位符但不是占位符的一部分时，它是必需的，例如“$ {noun}通过”。

在字符串中任何其他外观都会导致引发ValueError。

字符串模块提供了一个实现这些规则的Template类。 模板的方法是：

class string.Template(template)

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

substitute(mapping[, **kws])

执行模板替换，返回一个新的字符串。映射是任何类似字典的对象，其键与模板中的占位符相匹配。或者，您可以提供关键字参数，其中关键字是占位符。当映射和kws都被给出并且有重复时，来自kws的占位符优先。

safe_substitute(mapping[, **kws])

与substitute（）类似，但是如果映射和kws中缺少占位符，则不会引发KeyError异常，原始占位符将完整显示在结果字符串中。 另外，与substitute（）不同，$的任何其他外观只会返回$而不是引发ValueError。

虽然其他异常仍可能发生，但此方法称为“安全”，因为替换总是尝试返回可用的字符串，而不是引发异常。在另一种意义上，safe_substitute()可能是安全以外的任何东西，因为它会默默地忽略包含悬挂分隔符，不匹配大括号或​​无效Python标识符占位符的格式错误的模板。

Template 实例还提供一个公共数据属性：

template

这是传递给构造函数的模板参数的对象。一般来说，你不应该改变它，但是只读访问不被强制执行。

以下是如何使用模板的示例：

高级用法：可以派生子类来自Template定义占位符语法，分隔符或用于分析模板字符串的整个正则表达式。为此，您可以覆盖这些类属性：

• 分隔符 - 这是描述引入分隔符的占位符的文字字符串。默认值是$。请注意，这应该不会是一个正则表达式，为实现将调用re.escape()根据需要在此字符串。

• idpattern - 这是描述非支撑占位符模式的正则表达式（大括号将根据需要自动添加）。默认值是正则表达式[_a-z][_a-z0-9]*。

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

• 转义 - 该组匹配转义序列，例如$$，以默认模式。

• named - 此组匹配未占用的占位符名称; 它不应该在捕获组中包含分隔符。

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

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

5.字符串功能

以下函数可用于对字符串和Unicode对象进行操作。它们不可用作字符串方法。

string.capwords(s[, sep])

使用str.split（）将参数拆分为单词，使用str.capitalize（）对每个单词进行大写，然后使用str.join（）连接大写单词。 如果可选的第二个参数sep不存在或无，则空白字符的运行被替换为单个空格，并且前导空格和尾部空白被删除，否则sep将用于拆分和连接单词。

string.maketrans(from, to)

返回适于传递给一个转换表translate()，将每个字符映射在from成在相同位置处的字符to ; 从和到必须有相同的长度。

注意

不要使用从小写和大写派生的字符串作为参数; 在某些地区，这些长度不一样。 对于大小写转换，请始终使用str.lower（）和str.upper（）。

6.弃用的字符串函数

下面的函数列表也被定义为字符串和Unicode对象的方法; 有关这些的更多信息，请参阅字符串方法部分 您应该将这些函数视为已弃用，尽管在Python 3之前它们不会被删除。本模块中定义的函数为：

string.atof(s)

自2.0版弃用：使用float()内置功能。

将字符串转换为浮点数。该字符串必须在Python中具有浮点文字的标准语法，可选地在前面加上符号（+或-）。请注意，这float()在传递字符串时的行为与内置函数相同。

注意

传递字符串时，可能会返回NaN和Infinity的值，具体取决于底层的C库。接受导致这些值返回的特定字符串集合完全取决于C库，并且已知会有所不同。

string.atoi(s[, base])

自2.0版弃用：使用int()内置功能。

将字符串s转换为给定基数中的整数。 该字符串必须由一个或多个数字组成，可选地在前面加上一个符号（+或 - ）。 基数默认为10.如果为0，则根据字符串的前导字符（剥离符号后）选择默认基数：0x或0X表示16，0表示8，其他任何意味着10.如果基数为16 ，一个前导的0x或0X总是被接受，尽管不是必需的。 这在传递字符串时的行为与内置函数int（）相同。 （另请注意：为了更灵活地解释数字文字，请使用内置函数eval（）。）

string.atol(s[, base])

自2.0版弃用：使用long()内置功能。

将字符串s转换为给定基数中的长整数。该字符串必须包含一个或多个数字，可选地以符号（+或-）开头。该基地参数的含义为相同atoi()。尾部l或L不允许，除非基数为0.注意，当调用没有基数或基数设置为10时，long()在传递字符串时表现与内置函数相同。

string.capitalize(word)

仅返回大写第一个字母的单词副本。

string.expandtabs(s[, tabsize])

展开一个字符串中的选项卡，将其替换为一个或多个空格，具体取决于当前列和给定的选项卡大小。在字符串中出现每个换行符后，列号重置为零。这不理解其他非打印字符或转义序列。标签大小默认为是8。

string.find(s, sub[, start[, end]])

返回找到子字符串子的s中的最低索引，使得子完全包含在s [start：end]中。 失败时返回-1。 开始和结束的默认值以及负值的解释与切片相同。

string.rfind(s, sub[, start[, end]])

类似于find()但不同的是找到最高的索引。

string.index(s, sub[, start[, end]])

类似于find()但是当没有找到子字符串时引发ValueError。

string.rindex(s, sub[, start[, end]])

类似于rfind()但是当没有找到子字符串时引发ValueError。

string.count(s, sub[, start[, end]])

返回字符串s [start：end]中子字符串sub（不重叠）出现的次数。 开始和结束的默认值以及负值的解释与切片相同。

string.lower(s)

返回s 的副本，但将大写字母转换为小写。

string.split(s[, sep[, maxsplit]])

返回字符串s的单词列表。 如果可选的第二个参数sep不存在或无，则这些单词由任意空白字符串（空格，制表符，换行符，返回，换页符）分隔。 如果第二个参数sep存在而不是None，它指定一个字符串作为字分隔符。 然后返回的列表将具有比字符串中分隔符的非重叠出现次数多一个项目。 如果给出maxsplit，则至多出现maxsplit分割数，并且字符串的其余部分作为列表的最后一个元素返回（因此列表最多只能有maxsplit + 1个元素）。 如果未指定maxsplit或-1，则分割数量没有限制（所有可能的分割）。

分割空字符串的行为取决于sep的值。如果未指定sep或指定为None，则结果将为空列表。如果将sep指定为任何字符串，则结果将是包含一个空字符串的元素的列表。

string.rsplit(s[, sep[, maxsplit]])

返回字符串s的单词列表，从结尾扫描s。 出于所有意图和目的，除非明确指定了可选的第三个参数maxsplit并且非零，否则生成的单词列表与split（）返回的相同。 如果给出maxsplit，maxsplit最大分割数 - 最右边的 - 发生，并且字符串的其余部分作为列表的第一个元素返回（因此列表最多只能有maxsplit + 1个元素）。

2.4版本中的新功能。

string.splitfields(s[, sep[, maxsplit]])

该函数的行为与split（）相同。 （过去，split（）仅用于一个参数，而splitfields（）仅用于两个参数。）

string.join(words[, sep])

连接单词的列表或元组，以及中间出现的单词。 sep的默认值是单个空格字符。 string.join（string.split（s，sep），sep）总是等于s。

string.joinfields(words[, sep])

该函数的行为与join（）相同。 （过去，join（）仅用于一个参数，而joinfields（）仅用于两个参数。）请注意，字符串对象上没有joinfields（）方法。 改用join（）方法。

string.lstrip(s[, chars])

返回删除前导字符的字符串的副本。 如果省略字符或无，则删除空白字符。 如果给出而不是无，字符必须是字符串; 该字符串中的字符将从字符串的起始处被剥离，该方法被调用。

在版本2.2.3中更改：添加了chars参数。该字符参数不能在早期版本的2.2传递。

string.rstrip(s[, chars])

返回删除了尾随字符的字符串副本。 如果省略字符或无，则删除空白字符。 如果给出而不是无，字符必须是字符串; 该字符串中的字符将从该字符串的末尾剥离，该方法被调用。

在版本2.2.3中更改：添加了chars参数。该字符参数不能在早期版本的2.2传递。

string.strip(s[, chars])

返回删除前后两个字符的字符串副本。 如果省略字符或无，则删除空白字符。 如果给出而不是无，字符必须是字符串; 该字符串中的字符将从该字符串的两端剥离。

在版本2.2.3中更改：添加了chars参数。该字符参数不能在早期版本的2.2传递。

string.swapcase(s)

返回s 的副本，但将小写字母转换为大写，反之亦然。

string.translate(s, table[, deletechars])

从s中删除所有位于deletechars中的字符（如果存在），然后使用table转换字符，该表必须是一个256个字符的字符串，给出每个字符值的翻译，并按序号进行索引。 如果表格是None，那么只执行字符删除步骤。

string.upper(s)

返回s 的副本，但小写字母转换为大写。

string.ljust(s, width[, fillchar])string.rjust(s, width[, fillchar])string.center(s, width[, fillchar])

这些函数分别在给定宽度的字段中左对齐，右对齐和居中字符串。它们返回一个至少包含宽度字符的字符串，通过填充字符串fillchar（默认为空格）创建字符串s，直到右侧，左侧或双侧的给定宽度。该字符串不会被截断。

string.zfill(s, width)

在数字字符串 s 的 左边用零数字填充，直到达到给定的宽度。正确处理以符号开头的字符串。

string.replace(s, old, new[, maxreplace])

返回字符串s 的副本，其中所有出现的子字符串旧被新的替换。如果给出可选参数maxreplace，则会替换第一个maxreplace事件。