内置函数

Python 解释器内置了许多始终可用的函数和类型。它们在此处按字母顺序列出。

内置函数

abs(number, /)

返回一个数的绝对值。参数可以是整数、浮点数,或实现了 __abs__() 的对象。如果参数是复数,则返回其模。

aiter(async_iterable, /)

返回一个异步迭代器,用于异步可迭代对象。等价于调用 x.__aiter__()

注意:与 iter() 不同,aiter() 没有双参数变体。

在 3.10 版本加入。

all(iterable, /)

如果 iterable 的所有元素都为真(或者如果 iterable 为空),则返回 True。等价于

def all(iterable): for element in iterable: if not element: return False return True
可等待 anext(async_iterator, /) 可等待 anext(async_iterator, default, /)

当被 await 时,返回给定异步迭代器的下一个项,如果给定 default 且迭代器已耗尽,则返回 default

这是内置函数 next() 的异步变体,行为类似。

它调用 async_iterator__anext__() 方法,返回一个可等待对象。await 它会返回迭代器的下一个值。如果给定了 default,则在迭代器耗尽时返回它,否则会引发 StopAsyncIteration

在 3.10 版本加入。

any(iterable, /)

如果 iterable 的任何元素为真,则返回 True。如果 iterable 为空,则返回 False。等价于

def any(iterable): for element in iterable: if element: return True return False
ascii(object, /)

repr() 类似,返回一个包含对象可打印表示的字符串,但使用 \x\u\U 转义序列转义 repr() 返回的字符串中的非 ASCII 字符。这会生成一个类似于 Python 2 中 repr() 返回的字符串。

bin(integer, /)

将整数转换为以“0b”为前缀的二进制字符串。结果是有效的 Python 表达式。如果 integer 不是 Python int 对象,它必须定义一个返回整数的 __index__() 方法。一些例子

>>> bin(3) '0b11' >>> bin(-10) '-0b1010'

无论是否需要前缀“0b”,都可以使用以下任何一种方式。

>>> format(14, '#b'), format(14, 'b') ('0b1110', '1110') >>> f'{14:#b}', f'{14:b}' ('0b1110', '1110')

有关更多信息,请参阅 format()

class bool(object=False, /)

返回一个布尔值,即 TrueFalse。参数使用标准真值测试过程进行转换。如果参数为假或省略,则返回 False;否则,返回 Truebool 类是 int 的子类(参见数字类型 — int、float、complex)。它不能进一步子类化。它唯一的实例是 FalseTrue(参见布尔类型 - bool)。

版本 3.7 中的改变: 参数现在仅限位置。

breakpoint(*args, **kws)

此函数会将您带入调用位置的调试器。具体来说,它会调用 sys.breakpointhook(),直接传递 argskws。默认情况下,sys.breakpointhook() 调用 pdb.set_trace(),不期望任何参数。在这种情况下,它纯粹是一个方便函数,因此您不必显式导入 pdb 或输入太多代码即可进入调试器。但是,sys.breakpointhook() 可以设置为其他函数,breakpoint() 将自动调用该函数,从而允许您进入选择的调试器。如果 sys.breakpointhook() 不可访问,此函数将引发 RuntimeError

默认情况下,breakpoint() 的行为可以通过 PYTHONBREAKPOINT 环境变量进行更改。有关使用详细信息,请参阅 sys.breakpointhook()

请注意,如果 sys.breakpointhook() 已被替换,则无法保证这一点。

引发 审计事件 builtins.breakpoint,参数为 breakpointhook

在 3.7 版本加入。

class bytearray(source=b'') class bytearray(source, encoding, errors='strict')

返回一个新的字节数组。bytearray 类是 0 并且 format_spec 非空,或者 format_spec 或返回值不是字符串,则会引发 TypeError 异常。

3.4 版本新增: 如果 format_spec 不是空字符串,则 object().__format__(format_spec) 会引发 TypeError

class frozenset(iterable=(), /)

返回一个新的 frozenset 对象,可选地从 iterable 中获取元素。frozenset 是一个内置类。有关此类的文档,请参阅 frozenset集合类型 — set、frozenset

对于其他容器,请参阅内置的 setlisttuple> 和 dict> 类,以及 collections 模块。

getattr(object, name, /) getattr(object, name, default, /)

返回 object 的命名属性的值。name 必须是一个字符串。如果该字符串是对象某个属性的名称,则结果是该属性的值。例如,getattr(x, 'foobar') 等价于 x.foobar。如果命名属性不存在,则如果提供了 default,则返回 default,否则引发 AttributeErrorname 不需要是 Python 标识符(参见 setattr())。

备注

由于 私有名称修饰 在编译时发生,因此必须手动修饰私有属性(具有两个前导下划线的属性)的名称才能使用 getattr() 检索它。

globals()

返回实现当前模块命名空间的字典。对于函数内的代码,这在函数定义时设置,并且无论函数在哪里调用都保持不变。

hasattr(object, name, /)

参数是一个对象和一个字符串。如果字符串是对象某个属性的名称,则结果为 True,否则为 False。(这是通过调用 getattr(object, name) 并查看它是否引发 AttributeError> 来实现的。)

hash(object, /)

返回对象的哈希值(如果它有的话)。哈希值是整数。它们用于在字典查找期间快速比较字典键。比较相等的数值具有相同的哈希值(即使它们是不同类型,例如 1 和 1.0)。

备注

对于具有自定义 __hash__() 方法的对象,请注意 hash() 会根据主机机器的位宽截断返回值。

help() help(request)

调用内置帮助系统。(此函数用于交互式使用。)如果没有给出参数,则交互式帮助系统会在解释器控制台启动。如果参数是字符串,则会将该字符串视为模块、函数、类、方法、关键字或文档主题的名称,并在控制台上打印帮助页面。如果参数是任何其他类型的对象,则会生成该对象的帮助页面。

请注意,如果在调用 help() 时,函数的参数列表中出现斜杠(/),这意味着斜杠之前的参数是仅限位置的。更多信息请参阅 关于仅限位置参数的 FAQ 条目

此函数由 site 模块添加到内置命名空间。

3.4 版本新增: pydocinspect 的更改意味着可调用对象的报告签名现在更加全面和一致。

hex(integer, /)

将整数转换为以“0x”为前缀的小写十六进制字符串。如果 integer 不是 Python int 对象,它必须定义一个返回整数的 __index__() 方法。一些示例

>>> hex(255) '0xff' >>> hex(-42) '-0x2a'

如果你想将整数转换为带或不带前缀的大写或小写十六进制字符串,你可以使用以下任一方式

>>> '%#x' % 255, '%x' % 255, '%X' % 255 ('0xff', 'ff', 'FF') >>> format(255, '#x'), format(255, 'x'), format(255, 'X') ('0xff', 'ff', 'FF') >>> f'{255:#x}', f'{255:x}', f'{255:X}' ('0xff', 'ff', 'FF')

有关更多信息,请参阅 format()

另请参阅 int(),它用于将十六进制字符串转换为基数为 16 的整数。

备注

要获取浮点数的十六进制字符串表示,请使用 float.hex() 方法。

id(object, /)

返回对象的“身份”。这是一个整数,保证在对象的生命周期内是唯一的且常量。两个生命周期不重叠的对象可能具有相同的 id() 值。

CPython 实现细节: 这是对象在内存中的地址。

引发 审计事件 builtins.id,参数为 id

input() input(prompt, /)

如果存在 prompt 参数,它会写入标准输出,不带尾随换行符。然后函数从输入中读取一行,将其转换为字符串(去除尾随换行符),并返回。当读取到 EOF 时,会引发 EOFError。示例

>>> s = input('--> ') --> Monty Python's Flying Circus >>> s "Monty Python's Flying Circus"

如果加载了 readline 模块,则 input() 将使用它来提供复杂的行编辑和历史记录功能。

在读取输入之前,引发 审计事件 builtins.input,参数为 prompt

成功读取输入后,引发 审计事件 builtins.input/result,并附带结果。

class int(number=0, /) class int(string, /, base=10)

返回从数字或字符串构造的整数对象,如果没有给出参数则返回 0

示例:

>>> int(123.45) 123 >>> int('123') 123 >>> int(' -12_345\n') -12345 >>> int('FACE', 16) 64206 >>> int('0xface', 0) 64206 >>> int('01110011', base=2) 115

如果参数定义了 __int__(),则 int(x) 返回 x.__int__()。如果参数定义了 __index__(),则返回 x.__index__()。对于浮点数,这会向零截断。

如果参数不是数字或者给出了 base,那么它必须是表示基数 base 中的整数的字符串、bytesbytearray 实例。可选地,字符串可以前面带有 +-(之间没有空格),可以有前导零,可以被空格包围,并且可以在数字之间散布单个下划线。

基数 n 整数字符串包含数字,每个数字代表从 0 到 n-1 的值。值 0–9 可以由任何 Unicode 十进制数字表示。值 10–35 可以由 az(或 AZ)表示。默认的 base 是 10。允许的基数是 0 和 2–36。基数 2、8 和 16 字符串可以可选地以 0b/0B0o/0O0x/0X 为前缀,就像代码中的整数字面量一样。对于基数 0,字符串的解释方式类似于 代码中的整数字面量,实际基数由前缀确定为 2、8、10 或 16。基数 0 也不允许前导零:int('010', 0) 是非法的,而 int('010')int('010', 8) 是合法的。

整数类型在 数字类型 — int、float、complex 中描述。

3.4 版本新增: 如果 base 不是 int 的实例,并且 base 对象具有 base.__index__ 方法,则调用该方法以获取基数的整数。以前的版本使用 base.__int__ 而不是 base.__index__

版本 3.6 中的改变: 允许使用下划线对数字进行分组,如代码字面量所示。

3.7 版本新增: 第一个参数现在是仅限位置的。

3.8 版本新增: 如果 __int__() 未定义,则回退到 __index__()

3.11 版本新增: int 字符串输入和字符串表示可以限制,以帮助避免拒绝服务攻击。当在将字符串转换为 int 或将 int 转换为字符串时超出限制时,会引发 ValueError。请参阅 整数字符串转换长度限制 文档。

3.14 版本新增: int() 不再委托给 __trunc__() 方法。

isinstance(object, classinfo, /)

如果 object 参数是 classinfo 参数的实例,或是其(直接、间接或 虚拟)子类的实例,则返回 True。如果 object 不是给定类型的对象,则函数始终返回 False。如果 classinfo 是类型对象(或递归地,其他此类元组)的元组,或者是多个类型的 联合类型,则如果 object 是其中任何一个类型的实例,则返回 True。如果 classinfo 不是类型或类型元组以及此类元组,则会引发 TypeError 异常。如果早期检查成功,则对于无效类型可能不会引发 TypeError

3.10 版本新增: classinfo 可以是 联合类型

issubclass(class, classinfo, /)

如果 classclassinfo 的子类(直接、间接或 虚拟),则返回 True。一个类被认为是其自身的子类。classinfo 可以是类对象元组(或递归地,其他此类元组)或 联合类型,在这种情况下,如果 classclassinfo 中任何条目的子类,则返回 True。在任何其他情况下,会引发 TypeError 异常。

3.10 版本新增: classinfo 可以是 联合类型

iter(iterable, /) iter(callable, sentinel, /)

返回一个 迭代器 对象。第一个参数的解释因第二个参数的存在与否而有很大不同。如果没有第二个参数,则单个参数必须是支持 可迭代 协议(__iter__() 方法)的集合对象,或者必须支持序列协议(从 0 开始的整数参数的 __getitem__() 方法)。如果它不支持这些协议中的任何一个,则会引发 TypeError。如果给出第二个参数 sentinel,则第一个参数必须是可调用对象。在这种情况下创建的迭代器将在每次调用其 __next__() 方法时调用 callable 而不带参数;如果返回的值等于 sentinel,则会引发 StopIteration,否则将返回该值。

另请参见 迭代器类型

iter() 第二种形式的一个有用应用是构建块读取器。例如,从二进制数据库文件中读取固定宽度的块直到文件末尾

from functools import partial with open('mydata.db', 'rb') as f: for block in iter(partial(f.read, 64), b''): process_block(block)
len(object, /)

返回对象的长度(项目数)。参数可以是序列(如字符串、字节、元组、列表或范围)或集合(如字典、集合或冻结集合)。

CPython 实现细节: len 在长度大于 sys.maxsize 时(例如 range(2 ** 100))引发 OverflowError

class list(iterable=(), /)

list 实际上是一个可变序列类型,而不是一个函数,如 列表序列类型 — list、tuple、range 中所述。

locals()

返回一个映射对象,表示当前局部符号表,其中变量名作为键,其当前绑定的引用作为值。

在模块作用域中,以及在使用 exec()eval() 并只传递一个命名空间时,此函数返回与 globals() 相同的命名空间。

在类作用域中,它返回将传递给元类构造函数的命名空间。

当使用 exec()eval() 并单独传递局部和全局参数时,它返回传递给函数调用的局部命名空间。

在上述所有情况下,在给定执行帧中每次调用 locals() 都将返回 相同 的映射对象。通过 locals() 返回的映射对象所做的更改将作为已赋值、重新赋值或删除的局部变量可见,并且赋值、重新赋值或删除局部变量将立即影响返回的映射对象的内容。

优化作用域 中(包括函数、生成器和协程),每次调用 locals() 都会返回一个新字典,其中包含函数局部变量和任何非局部单元格引用的当前绑定。在这种情况下,通过返回的字典进行的名称绑定更改 不会 写回相应的局部变量或非局部单元格引用,并且赋值、重新赋值或删除局部变量和非局部单元格引用 不会 影响先前返回的字典的内容。

在函数、生成器或协程中,将 locals() 作为推导式的一部分调用,等同于在包含作用域中调用它,不同之处在于推导式初始化的迭代变量将包含在内。在其他作用域中,它的行为就像推导式作为嵌套函数运行一样。

locals() 作为生成器表达式的一部分调用,等同于在嵌套生成器函数中调用它。

3.12 版本新增: locals() 在推导式中的行为已按照 PEP 709 中的描述进行了更新。

3.13 版本新增: 作为 PEP 667 的一部分,修改此函数返回的映射对象的语义现已定义。在 优化作用域 中的行为现已如上所述。除了定义之外,在其他作用域中的行为与以前的版本保持不变。

map(function, iterable, /, *iterables, strict=False)

返回一个迭代器,它将 function 应用于 iterable 的每个项目,并生成结果。如果传递了额外的 iterables 参数,function 必须接受相同数量的参数,并并行应用于所有可迭代对象的项目。对于多个可迭代对象,当最短的可迭代对象耗尽时,迭代器停止。如果 strictTrue 并且其中一个可迭代对象在其他可迭代对象之前耗尽,则会引发 ValueError。对于函数输入已排列成参数元组的情况,请参阅 itertools.starmap()

3.14 版本新增: 添加了 strict 参数。

max(iterable, /, *, key=None) max(iterable, /, *, default, key=None) max(arg1, arg2, /, *args, key=None)

返回可迭代对象中的最大项,或两个或更多参数中的最大值。

如果提供了一个位置参数,它应该是一个 可迭代对象。返回可迭代对象中最大的项。如果提供了两个或更多位置参数,则返回位置参数中最大的项。

有两个可选的仅限关键字参数。key 参数指定一个单参数排序函数,类似于 list.sort() 所使用的那种。default 参数指定当提供的可迭代对象为空时要返回的对象。如果可迭代对象为空且未提供 default,则会引发 ValueError

如果有多个项目是最大的,函数返回遇到的第一个。这与其它保持排序稳定性的工具一致,例如 sorted(iterable, key=keyfunc, reverse=True)[0]heapq.nlargest(1, iterable, key=keyfunc)

3.4 版本新增: 添加了 default 仅限关键字参数。

3.8 版本新增: key 可以是 None

class memoryview(object)

返回从给定参数创建的“内存视图”对象。有关更多信息,请参阅 内存视图

min(iterable, /, *, key=None) min(iterable, /, *, default, key=None) min(arg1, arg2, /, *args, key=None)

返回可迭代对象中的最小项,或两个或更多参数中的最小值。

如果提供了一个位置参数,它应该是一个 可迭代对象。返回可迭代对象中最小的项。如果提供了两个或更多位置参数,则返回位置参数中最小的项。

有两个可选的仅限关键字参数。key 参数指定一个单参数排序函数,类似于 list.sort() 所使用的那种。default 参数指定当提供的可迭代对象为空时要返回的对象。如果可迭代对象为空且未提供 default,则会引发 ValueError

如果有多个项目是最小的,函数返回遇到的第一个。这与其它保持排序稳定性的工具一致,例如 sorted(iterable, key=keyfunc)[0]heapq.nsmallest(1, iterable, key=keyfunc)

3.4 版本新增: 添加了 default 仅限关键字参数。

3.8 版本新增: key 可以是 None

next(iterator, /) next(iterator, default, /)

通过调用 __next__() 方法从 迭代器 中检索下一项。如果给定了 default,则在迭代器耗尽时返回 default,否则引发 StopIteration

class object

这是所有其他类的终极基类。它具有所有 Python 类实例共有的方法。当调用构造函数时,它会返回一个新的无特征对象。构造函数不接受任何参数。

备注

object 实例 具有 __dict__ 属性,因此你不能为 object 的实例分配任意属性。

oct(integer, /)

将整数转换为以“0o”为前缀的八进制字符串。结果是有效的 Python 表达式。如果 integer 不是 Python int 对象,它必须定义一个返回整数的 __index__() 方法。例如

>>> oct(8) '0o10' >>> oct(-56) '-0o70'

如果你想将整数转换为带或不带前缀“0o”的八进制字符串,你可以使用以下任一方式。

>>> '%#o' % 10, '%o' % 10 ('0o12', '12') >>> format(10, '#o'), format(10, 'o') ('0o12', '12') >>> f'{10:#o}', f'{10:o}' ('0o12', '12')

有关更多信息,请参阅 format()

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

打开 file 并返回相应的 文件对象。如果文件无法打开,则会引发 OSError。有关如何使用此函数的更多示例,请参阅 读写文件

file 是一个 类路径对象,给出要打开文件的路径名(绝对路径或相对于当前工作目录的路径),或者是包装文件的整数文件描述符。(如果给出了文件描述符,则在关闭返回的 I/O 对象时关闭它,除非 closefd 设置为 False。)

mode 是一个可选字符串,用于指定文件打开的模式。它默认为 'r',表示以文本模式读取。其他常见值包括 'w' 用于写入(如果文件已存在则截断文件)、'x' 用于独占创建,以及 'a' 用于追加(在 某些 Unix 系统上,这意味着 所有 写入都追加到文件末尾,无论当前查找位置如何)。在文本模式下,如果未指定 encoding,则使用的编码是平台相关的:调用 locale.getencoding() 以获取当前区域设置编码。(为了读写原始字节,请使用二进制模式并省略 encoding。)可用模式包括

字符

含义

'r'

以读模式打开(默认)

'w'

以写模式打开,首先截断文件

'x'

以独占创建模式打开,如果文件已存在则失败

'a'

以写入模式打开,如果文件存在则追加到文件末尾

'b'

二进制模式

't'

文本模式(默认)

'+'

以更新模式打开(读写)

默认模式为 'r' (以文本模式读取,与 'rt' 同义)。模式 'w+''w+b' 打开并截断文件。模式 'r+''r+b' 打开文件时不截断。

概述 中所述,Python 区分二进制 I/O 和文本 I/O。以二进制模式打开的文件(包括 mode 参数中的 'b')返回的内容为 bytes 对象,不进行任何解码。在文本模式下(默认模式,或当 mode 参数中包含 't' 时),文件内容作为 str 返回,字节首先使用平台相关的编码进行解码,或者如果给出 encoding 则使用指定的编码进行解码。

备注

Python 不依赖于底层操作系统对文本文件的概念;所有处理都由 Python 自己完成,因此是平台独立的。

buffering 是一个可选整数,用于设置缓冲策略。传递 0 关闭缓冲(仅允许在二进制模式下),传递 1 选择行缓冲(仅在文本模式下写入时可用),传递大于 1 的整数表示固定大小块缓冲区的字节大小。请注意,以这种方式指定缓冲区大小适用于二进制缓冲 I/O,但 TextIOWrapper(即,以 mode='r+' 打开的文件)会有另一个缓冲。要禁用 TextIOWrapper 中的缓冲,请考虑对 io.TextIOWrapper.reconfigure() 使用 write_through 标志。如果没有给出 buffering 参数,默认缓冲策略如下

  • 二进制文件以固定大小的块进行缓冲;当设备块大小可用时,缓冲区大小为 max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE)。在大多数系统上,缓冲区通常为 128 千字节。

  • “交互式”文本文件(isatty() 返回 True 的文件)使用行缓冲。其他文本文件使用上述二进制文件的策略。

encoding 是用于解码或编码文件的编码名称。这应该只在文本模式下使用。默认编码是平台相关的(locale.getencoding() 返回的任何内容),但可以使用 Python 支持的任何 文本编码。有关支持的编码列表,请参阅 codecs 模块。

errors 是一个可选字符串,指定如何处理编码和解码错误——这不能在二进制模式下使用。有多种标准错误处理程序可用(列在 错误处理程序 下),尽管任何已通过 codecs.register_error() 注册的错误处理程序名称也是有效的。标准名称包括

  • 'strict' 在编码错误时引发 ValueError 异常。默认值 None 具有相同的效果。

  • 'ignore' 忽略错误。请注意,忽略编码错误可能导致数据丢失。

  • 'replace' 导致在数据格式错误的地方插入一个替换标记(例如 '?')。

  • 'surrogateescape' 将任何不正确的字节表示为 U+DC80 到 U+DCFF 范围内的低位替代码点。当写入数据时使用 surrogateescape 错误处理程序时,这些替代码点将再次转换回相同的字节。这对于处理未知编码的文件很有用。

  • 'xmlcharrefreplace' 仅在写入文件时支持。编码不支持的字符将替换为相应的 XML 字符引用 &#nnn;

  • 'backslashreplace' 将格式错误的数据替换为 Python 的反斜杠转义序列。

  • 'namereplace'(同样仅在写入时支持)将不支持的字符替换为 \N{...} 转义序列。

newline 决定如何解析流中的换行符。它可以是 None'''\n''\r''\r\n'。它的工作方式如下

  • 从流中读取输入时,如果 newlineNone,则启用通用换行符模式。输入中的行可以以 '\n''\r''\r\n' 结尾,并且这些在返回给调用者之前会转换为 '\n'。如果为 '',则启用通用换行符模式,但行尾会未经转换地返回给调用者。如果它具有任何其他合法值,则输入行仅由给定字符串终止,并且行尾会未经转换地返回给调用者。

  • 当向流写入输出时,如果 newlineNone,则写入的任何 '\n' 字符都会转换为系统默认的行分隔符 os.linesep。如果 newline'''\n',则不进行转换。如果 newline 是任何其他合法值,则写入的任何 '\n' 字符都会转换为给定字符串。

如果 closefdFalse 且给出了文件描述符而非文件名,则在文件关闭时,底层文件描述符将保持打开状态。如果给出了文件名,closefd 必须为 True(默认值);否则,将引发错误。

可以通过将可调用对象作为 opener 传递来使用自定义的打开器。然后通过使用 (file, flags) 调用 opener 来获取文件对象的底层文件描述符。opener 必须返回一个打开的文件描述符(将 os.open 作为 opener 传递会导致类似于传递 None 的功能)。

新创建的文件是 不可继承的

以下示例使用 os.open() 函数的 dir_fd 参数来打开相对于给定目录的文件

>>> import os >>> dir_fd = os.open('somedir', os.O_RDONLY) >>> def opener(path, flags): ... return os.open(path, flags, dir_fd=dir_fd) ... >>> with open('spamspam.txt', 'w', opener=opener) as f: ... print('This will be written to somedir/spamspam.txt', file=f) ... >>> os.close(dir_fd) # don't leak a file descriptor

open() 函数返回的 文件对象 类型取决于模式。当 open() 用于以文本模式('w''r''wt''rt' 等)打开文件时,它返回 io.TextIOBase 的子类(具体是 io.TextIOWrapper)。当用于以二进制模式且带缓冲打开文件时,返回的类是 io.BufferedIOBase 的子类。具体类有所不同:在读取二进制模式下,它返回一个 io.BufferedReader;在写入二进制和追加二进制模式下,它返回一个 io.BufferedWriter,在读/写模式下,它返回一个 io.BufferedRandom。当禁用缓冲时,返回原始流,它是 io.RawIOBase 的子类 io.FileIO

另请参阅文件处理模块,例如 fileinputio(其中声明了 open())、osos.pathtempfileshutil

引发 审计事件 open,参数为 pathmodeflags

modeflags 参数可能已根据原始调用进行了修改或推断。

3.3 版本中的变化

  • 添加了 opener 参数。

  • 添加了 'x' 模式。

  • IOError 以前会被引发,现在它是 OSError 的别名。

  • 现在,如果文件以独占创建模式 ('x') 打开时已存在,则会引发 FileExistsError

3.4 版本中的变化

  • 文件现在不可继承。

3.5 版本中的变化

  • 如果系统调用被中断并且信号处理程序没有引发异常,则函数现在会重试系统调用,而不是引发 InterruptedError 异常(有关原因,请参阅 PEP 475)。

  • 添加了 'namereplace' 错误处理程序。

3.6 版本中的变化

  • 添加了对实现 os.PathLike 的对象的支持。

  • 在 Windows 上,打开控制台缓冲区可能会返回 io.RawIOBase 的子类,而不是 io.FileIO

3.11 版本中的变化: 'U' 模式已移除。

ord(character, /)

返回字符的序数值。

如果参数是一个单字符字符串,则返回该字符的 Unicode 码点。例如,ord('a') 返回整数 97ord('€')(欧元符号)返回 8364。这与 chr() 相反。

如果参数是长度为 1 的 bytesbytearray 对象,则返回其单个字节值。例如,ord(b'a') 返回整数 97

pow(base, exp, mod=None)

返回 baseexp 次幂;如果存在 mod,则返回 baseexp 次幂,然后取模 mod(比 pow(base, exp) % mod 更高效)。两参数形式 pow(base, exp) 等价于使用幂运算符:base**exp

当参数是内置数值类型且包含混合操作数类型时,适用于二进制算术运算符的强制转换规则。对于 int 操作数,结果类型与操作数类型相同(强制转换后),除非第二个参数为负;在这种情况下,所有参数都将转换为浮点数并返回浮点数结果。例如,pow(10, 2) 返回 100,但 pow(10, -2) 返回 0.01。对于 intfloat 类型的负基数和非整数指数,将返回复数结果。例如,pow(-9, 0.5) 返回一个接近 3j 的值。然而,对于 intfloat 类型的负基数和整数指数,将返回浮点数结果。例如,pow(-9, 2.0) 返回 81.0

对于 int 操作数 baseexp,如果 mod 存在,mod 也必须是整数类型且 mod 必须为非零。如果 mod 存在且 exp 为负,则 base 必须与 mod 互质。在这种情况下,返回 pow(inv_base, -exp, mod),其中 inv_basebasemod 的逆。

这是一个计算 3897 的逆的示例

>>> pow(38, -1, mod=97) 23 >>> 23 * 38 % 97 == 1 True

3.8 版本发生变更: 对于 int 操作数,pow 的三参数形式现在允许第二个参数为负数,从而可以计算模逆。

3.8 版本发生变更: 允许关键字参数。以前只支持位置参数。

print(*objects, sep=' ', end='\n', file=None, flush=False)

objects 打印到文本流 file,由 sep 分隔并以 end 结尾。如果存在 sependfileflush,则必须将其作为关键字参数给出。

所有非关键字参数都将像 str() 一样转换为字符串,并写入流中,由 sep 分隔并以 end 结尾。sepend 都必须是字符串;它们也可以是 None,这意味着使用默认值。如果没有给出 objectsprint() 将只写入 end

file 参数必须是一个具有 write(string) 方法的对象;如果它不存在或为 None,则将使用 sys.stdout。由于打印的参数被转换为文本字符串,因此 print() 不能与二进制模式的文件对象一起使用。对于这些对象,请改用 file.write(...)

输出缓冲通常由 file 决定。但是,如果 flush 为 True,则流将被强制刷新。

3.3 版本发生变更: 添加了 flush 关键字参数。

class property(fget=None, fset=None, fdel=None, doc=None)

返回一个属性。

fget 是用于获取属性值的函数。fset 是用于设置属性值的函数。fdel 是用于删除属性值的函数。doc 为属性创建文档字符串。

典型用法是定义一个托管属性 x

class C: def __init__(self): self._x = None def getx(self): return self._x def setx(self, value): self._x = value def delx(self): del self._x x = property(getx, setx, delx, "I'm the 'x' property.")

如果 cC 的实例,c.x 将调用 getter,c.x = value 将调用 setter,del c.x 将调用 deleter。

如果给出 doc,它将成为属性的文档字符串。否则,该属性将复制 fget 的文档字符串(如果存在)。这使得使用 property() 作为装饰器可以轻松创建只读属性

class Parrot: def __init__(self): self._voltage = 100000 @property def voltage(self): """Get the current voltage.""" return self._voltage

@property 装饰器将 voltage() 方法转换为同名只读属性的“getter”,并将其文档字符串设置为“Get the current voltage.”

@getter @setter @deleter

property 对象具有 gettersetterdeleter 方法,可用作装饰器,它们会创建属性的副本,并将相应的访问器函数设置为被装饰的函数。这最好通过示例解释

class C: def __init__(self): self._x = None @property def x(self): """I'm the 'x' property.""" return self._x @x.setter def x(self, value): self._x = value @x.deleter def x(self): del self._x

此代码与第一个示例完全等效。请务必为附加函数提供与原始属性相同的名称(在本例中为 x)。

返回的属性对象还具有与构造函数参数对应的属性 fgetfsetfdel

3.5 版本发生变更: 属性对象的文档字符串现在是可写入的。

__name__

保存属性名称的属性。属性的名称可以在运行时更改。

在 3.13 版本加入。

class range(stop, /) class range(start, stop, step=1, /)

range 实际上不是一个函数,而是一个不可变序列类型,如 区间序列类型 — list、tuple、range 中所述。

repr(object, /)

返回一个包含对象可打印表示形式的字符串。对于许多类型,此函数会尝试返回一个字符串,该字符串在传递给 eval() 时将生成具有相同值的对象;否则,表示形式是一个用尖括号括起来的字符串,其中包含对象的类型名称以及通常包括对象名称和地址的其他信息。类可以通过定义 __repr__() 方法来控制此函数为其实例返回的内容。如果无法访问 sys.displayhook(),此函数将引发 RuntimeError

这个类有一个自定义表示形式,可以进行评估

class Person: def __init__(self, name, age): self.name = name self.age = age def __repr__(self): return f"Person('{self.name}', {self.age})"
reversed(object, /)

返回一个逆向迭代器。参数必须是具有 __reversed__() 方法或支持序列协议(__len__() 方法和从 0 开始的整数参数的 __getitem__() 方法)的对象。

round(number, ndigits=None)

返回 number 在小数点后精确到 ndigits 位的四舍五入值。如果 ndigits 被省略或为 None,它将返回最接近其输入的整数。

对于支持 round() 的内置类型,值将四舍五入到最接近 10 的幂减去 ndigits 的倍数;如果两个倍数同样接近,则向偶数方向四舍五入(例如,round(0.5)round(-0.5) 都是 0round(1.5)2)。任何整数值对于 ndigits 都是有效的(正数、零或负数)。如果 ndigits 被省略或为 None,则返回值为整数。否则,返回值的类型与 number 相同。

对于一般的 Python 对象 numberround 会委托给 number.__round__

备注

round() 对于浮点数的行为可能会令人惊讶:例如,round(2.675, 2) 给出 2.67 而不是预期的 2.68。这不是一个 bug:这是因为大多数十进制分数不能精确地表示为浮点数。有关更多信息,请参阅 浮点数算术:问题和限制

class set(iterable=(), /)

返回一个新的 set 对象,可选地包含来自 iterable 的元素。set 是一个内置类。有关此类的文档,请参阅 set集合类型 — set、frozenset

有关其他容器,请参阅内置的 frozensetlisttupledict 类,以及 collections 模块。

setattr(object, name, value, /)

这是 getattr() 的对应函数。参数是一个对象、一个字符串和一个任意值。该字符串可以命名一个现有属性或一个新属性。该函数将值赋给该属性,前提是对象允许。例如,setattr(x, 'foobar', 123) 等同于 x.foobar = 123

除非对象选择强制执行此操作(例如在自定义 __getattribute__() 中或通过 __slots__),否则 name 不需要是 名称(标识符和关键字) 中定义的 Python 标识符。名称不是标识符的属性将无法使用点表示法访问,但可以通过 getattr() 等访问。

备注

由于 私有名称重整 在编译时发生,因此必须手动重整私有属性(具有两个前导下划线的属性)的名称才能使用 setattr() 设置它。

class slice(stop, /) class slice(start, stop, step=None, /)

返回一个 切片 对象,表示由 range(start, stop, step) 指定的索引集。startstep 参数默认为 None

切片对象具有只读数据属性 startstopstep,它们仅返回参数值(或其默认值)。它们没有其他明确的功能;但是,它们被 NumPy 和其他第三方包使用。

start stop step

当使用扩展索引语法时也会生成切片对象。例如:a[start:stop:step]a[start:stop, i]。有关返回 迭代器 的替代版本,请参阅 itertools.islice()

3.12 版本发生变更: 切片对象现在是可哈希的(前提是 startstopstep 都是可哈希的)。

sorted(iterable, /, *, key=None, reverse=False)

iterable 中的项返回一个新的已排序列表。

有两个可选参数,必须指定为关键字参数。

key 指定一个接受一个参数的函数,用于从 iterable 中的每个元素中提取比较键(例如,key=str.lower)。默认值为 None(直接比较元素)。

reverse 是一个布尔值。如果设置为 True,则列表元素将按每个比较被反转的方式排序。

使用 functools.cmp_to_key() 将旧式的 cmp 函数转换为 key 函数。

内置的 sorted() 函数保证是稳定的。如果排序保证不改变比较相等的元素的相对顺序,则它是稳定的——这对于多次排序很有帮助(例如,按部门排序,然后按工资等级排序)。

排序算法仅使用项目之间的 < 比较。虽然定义 __lt__() 方法足以进行排序,但 PEP 8 建议实现所有六个富比较。这将有助于在使用相同数据和依赖不同底层方法的其他排序工具(例如 max())时避免错误。实现所有六个比较还有助于避免混合类型比较的混淆,因为混合类型比较可以调用反射的 __gt__() 方法。

有关排序示例和简短的排序教程,请参阅排序技术

@staticmethod

将方法转换为静态方法。

静态方法不接收隐式的第一个参数。要声明静态方法,请使用此惯用法

class C: @staticmethod def f(arg1, arg2, argN): ...

@staticmethod 形式是一个函数装饰器——有关详细信息,请参见函数定义

静态方法可以在类上调用(例如 C.f())或在实例上调用(例如 C().f())。此外,静态方法描述符也是可调用的,因此可以在类定义中使用(例如 f())。

Python 中的静态方法与 Java 或 C++ 中的静态方法类似。另外,请参阅 classmethod(),它是一个变体,可用于创建替代类构造函数。

与所有装饰器一样,也可以将 staticmethod 作为普通函数调用并对其结果进行处理。在某些情况下,您需要从类体中引用函数并希望避免自动转换为实例方法时,需要这样做。对于这些情况,请使用此惯用法

def regular_function(): ... class C: method = staticmethod(regular_function)

有关静态方法的更多信息,请参见 标准类型层次结构

3.10 版本发生变更: 静态方法现在继承方法属性(__module____name____qualname____doc____annotations__),拥有一个新的 __wrapped__ 属性,并且现在可以作为普通函数调用。

class str(*, encoding='utf-8', errors='strict') class str(object) class str(object, encoding, errors='strict') class str(object, *, errors)

返回 objectstr 版本。有关详细信息,请参阅 str()

str 是内置的字符串。有关字符串的通用信息,请参阅文本序列类型 — str

sum(iterable, /, start=0)

从左到右将 startiterable 的项目相加,并返回总和。iterable 的项目通常是数字,并且起始值不允许是字符串。

对于某些用例,sum() 有很好的替代方案。连接字符串序列的首选、快速方法是调用 ''.join(sequence)。要以扩展精度添加浮点值,请参阅 math.fsum()。要连接一系列可迭代对象,请考虑使用 itertools.chain()

3.8 版本发生变更: start 参数可以指定为关键字参数。

3.12 版本发生变更: 浮点数求和改为使用在大多数构建中提供更高精度和更好可交换性的算法。

3.14 版本发生变更: 添加了复数求和的专门化,使用与浮点数求和相同的算法。

class super class super(type, object_or_type=None, /)

返回一个代理对象,该对象将方法调用委托给 type 的父类或兄弟类。这对于访问在类中被覆盖的继承方法很有用。

object_or_type 决定要搜索的方法解析顺序。搜索从 type 右侧的类开始。

例如,如果 object_or_type__mro__D -> B -> C -> A -> object,并且 type 的值是 B,那么 super() 会搜索 C -> A -> object

对应于 object_or_type 的类的 __mro__ 属性列出了 getattr()super() 使用的方法解析搜索顺序。该属性是动态的,并且可以在继承层次结构更新时更改。

如果省略第二个参数,则返回的超对象是未绑定的。如果第二个参数是一个对象,则 isinstance(obj, type) 必须为 True。如果第二个参数是一个类型,则 issubclass(type2, type) 必须为 True(这对于类方法很有用)。

在类的普通方法中直接调用时,两个参数都可以省略(“零参数 super()”)。在这种情况下,type 将是封闭类,obj 将是紧邻封闭函数的第一个参数(通常是 self)。(这意味着零参数 super() 在嵌套函数(包括生成器表达式,它们隐式创建嵌套函数)中将无法按预期工作。)

super 有两种典型的用例。在单一继承的类层次结构中,super 可以用于在不明确命名父类的情况下引用它们,从而使代码更易于维护。这种用法与 super 在其他编程语言中的用法非常相似。

第二种用例是在动态执行环境中支持协作多重继承。此用例是 Python 独有的,在静态编译语言或仅支持单一继承的语言中找不到。这使得实现“菱形图”成为可能,其中多个基类实现相同的方法。良好的设计要求此类实现(在所有情况下)具有相同的调用签名(因为调用顺序在运行时确定,因为该顺序适应类层次结构中的更改,并且因为该顺序可以包括在运行时之前未知的兄弟类)。

对于这两种用例,典型的超类调用如下所示

class C(B): def method(self, arg): super().method(arg) # This does the same thing as: # super(C, self).method(arg)

除了方法查找,super() 也适用于属性查找。一个可能的用例是在父类或兄弟类中调用描述符

请注意,super() 作为显式点属性查找(例如 super().__getitem__(name))的绑定过程的一部分实现。它通过实现自己的 __getattribute__() 方法来以可预测的顺序搜索类,从而支持协作多重继承。因此,super() 对于使用语句或运算符(例如 super()[name])进行的隐式查找是未定义的。

另请注意,除了零参数形式外,super() 并不限于在方法内部使用。两参数形式精确指定参数并进行适当的引用。零参数形式仅在类定义内部有效,因为编译器会填写必要的详细信息以正确检索正在定义的类,以及访问普通方法的当前实例。

有关如何使用 super() 设计协作类的实用建议,请参阅 guide to using super()

3.14 版本发生变更: super 对象现在是pickleablecopyable

class tuple(iterable=(), /)

tuple 实际上不是一个函数,而是一个不可变序列类型,如 元组序列类型 — list、tuple、range 中所述。

class type(object, /) class type(name, bases, dict, /, **kwargs)

使用一个参数时,返回 object 的类型。返回值是一个类型对象,通常与 object.__class__ 返回的对象相同。

建议使用内置函数 isinstance() 来测试对象的类型,因为它会考虑子类。

使用三个参数时,返回一个新的类型对象。这本质上是 class 语句的动态形式。name 字符串是类名,并成为 __name__ 属性。bases 元组包含基类,并成为 __bases__ 属性;如果为空,则添加 object,即所有类的最终基类。dict 字典包含类体的属性和方法定义;它可以在成为 __dict__ 属性之前被复制或包装。以下两个语句创建相同的 type 对象

>>> class X: ... a = 1 ... >>> X = type('X', (), dict(a=1))

参见

提供给三参数形式的关键字参数以与类定义中的关键字(除了 metaclass)相同的方式传递给适当的元类机制(通常是 __init_subclass__())。

另请参阅 自定义类的创建

3.6 版本发生变更: 不重写 type.__new__type 子类不能再使用单参数形式获取对象的类型。

vars() vars(object, /)

返回模块、类、实例或任何其他具有 __dict__ 属性的对象的 __dict__ 属性。

模块和实例等对象具有可更新的 __dict__ 属性;但是,其他对象可能对其 __dict__ 属性有写入限制(例如,类使用 types.MappingProxyType 来防止直接字典更新)。

如果没有参数,vars() 的行为与 locals() 类似。

如果指定了一个对象但它没有 __dict__ 属性(例如,如果它的类定义了 __slots__ 属性),则会引发 TypeError 异常。

3.13 版本发生变更: 不带参数调用此函数的结果已更新,如内置函数 locals() 所述。

zip(*iterables, strict=False)

并行迭代多个可迭代对象,生成包含每个对象中一个元素的元组。

示例

>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']): ... print(item) ... (1, 'sugar') (2, 'spice') (3, 'everything nice')

更正式地讲:zip() 返回一个元组迭代器,其中第 i 个元组包含每个参数可迭代对象的第 i 个元素。

另一种理解 zip() 的方式是它将行转换为列,将列转换为行。这类似于转置矩阵

zip() 是惰性的:元素直到可迭代对象被迭代才会被处理,例如通过 for 循环或包装在 list 中。

需要考虑的一点是,传递给 zip() 的可迭代对象可能具有不同的长度;有时是设计使然,有时是由于准备这些可迭代对象的代码中的 bug。Python 提供了三种不同的方法来处理这个问题

  • 默认情况下,zip() 在最短的可迭代对象耗尽时停止。它将忽略较长可迭代对象中剩余的项目,将结果截断为最短可迭代对象的长度

    >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'])) [(0, 'fee'), (1, 'fi'), (2, 'fo')]
  • zip() 通常用于假定可迭代对象长度相等的情况。在这种情况下,建议使用 strict=True 选项。它的输出与常规 zip() 相同

    >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True)) [('a', 1), ('b', 2), ('c', 3)]

    与默认行为不同,如果一个可迭代对象在其他对象之前耗尽,它会引发 ValueError

    >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True): ... print(item) ... (0, 'fee') (1, 'fi') (2, 'fo') Traceback (most recent call last): ... ValueError: zip() argument 2 is longer than argument 1

    如果没有 strict=True 参数,任何导致可迭代对象长度不同的错误都将被静默,可能在程序的另一部分表现为难以找到的错误。

  • 较短的可迭代对象可以用一个常量值填充,使所有可迭代对象具有相同的长度。这通过 itertools.zip_longest() 完成。

极端情况:只有一个可迭代参数时,zip() 返回一个由 1 元组组成的迭代器。没有参数时,它返回一个空迭代器。

提示和技巧

  • 可迭代对象的从左到右评估顺序是有保证的。这使得使用 zip(*[iter(s)]*n, strict=True) 将数据系列聚类为 n 长度组的惯用法成为可能。这会重复 相同 迭代器 n 次,以便每个输出元组都包含对迭代器的 n 次调用的结果。这具有将输入分成 n 长度块的效果。

  • zip() 结合 * 运算符可用于解压列表

    >>> x = [1, 2, 3] >>> y = [4, 5, 6] >>> list(zip(x, y)) [(1, 4), (2, 5), (3, 6)] >>> x2, y2 = zip(*zip(x, y)) >>> x == list(x2) and y == list(y2) True

3.10 版本发生变更: 添加了 strict 参数。

__import__(name, globals=None, locals=None, fromlist=(), level=0)

备注

这是一个高级函数,在日常 Python 编程中不需要,不像 importlib.import_module()

此函数由 import 语句调用。可以通过替换它(通过导入 builtins 模块并赋值给 builtins.__import__)来改变 import 语句的语义,但强烈不建议这样做,因为使用导入钩子(参见 PEP 302)通常更简单,并且不会导致代码假定使用默认导入实现的问题。也建议不要直接使用 __import__(),而应使用 importlib.import_module()

此函数导入模块 name,可能使用给定的 globalslocals 来确定如何在包上下文中解释该名称。fromlist 给出应从 name 指定的模块中导入的对象或子模块的名称。标准实现根本不使用其 locals 参数,并且仅使用其 globals 来确定 import 语句的包上下文。

level 指定是使用绝对导入还是相对导入。0(默认值)表示只执行绝对导入。level 的正值表示相对于调用 __import__() 的模块所在目录的父目录数(有关详细信息,请参阅 PEP 328)。

name 变量的形式为 package.module 时,通常返回的是顶级包(第一个点之前的名称),而不是由 name 命名的模块。但是,当给定非空的 fromlist 参数时,返回由 name 命名的模块。

例如,语句 import spam 产生类似于以下代码的字节码

spam = __import__('spam', globals(), locals(), [], 0)

语句 import spam.ham 导致此调用

spam = __import__('spam.ham', globals(), locals(), [], 0)

请注意,__import__() 如何在此处返回顶级模块,因为这是由 import 语句绑定到名称的对象。

另一方面,语句 from spam.ham import eggs, sausage as saus 导致

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0) eggs = _temp.eggs saus = _temp.sausage

在这里,spam.ham 模块是从 __import__() 返回的。从这个对象中,要导入的名称被检索并分配给它们各自的名称。

如果您只是想按名称导入模块(可能在包中),请使用 importlib.import_module()

3.3 版本发生变更: 不再支持 level 的负值(这也将默认值更改为 0)。

3.9 版本发生变更: 当使用命令行选项 -E-I 时,环境变量 PYTHONCASEOK 现在被忽略。

脚注

[1]

请注意,解析器只接受 Unix 风格的行尾约定。如果您从文件读取代码,请确保使用换行符转换模式来转换 Windows 或 Mac 风格的换行符。