Python v3.10


Python 基础教程

1. Python 解释器

调用解释器

Python 解释器在可用的机器上通常安装于 /usr/local/bin/python3.10 路径下;将 /usr/local/bin 加入你的 Unix 终端的搜索路径就可以通过键入以下命令来启动它:

python3.10

这样,就可以在 shell 中运行 Python 了。因为可以选择安装目录,解释器也有可能安装在别的位置;如果还不明白,就去问问身边的 Python 大神或系统管理员。(例如,常见备选路径还有 /usr/local/python。)

在 Windows 机器上当你从 Microsoft Store 安装 Python 之后,python3.10 命令将可使用。 如果你安装了 py.exe 启动器,你将可以使用 py 命令。

在主提示符中,输入文件结束符(Unix 里是 Control-D,Windows 里是 Control-Z),就会退出解释器,退出状态码为 0。如果不能退出,还可以输入这个命令:quit()

在支持 GNU Readline 库的系统中,解释器的行编辑功能包括交互式编辑、历史替换、代码补全等。检测是否支持命令行编辑最快速的方式是,在首次出现 Python 提示符时,输入 Control-P。听到“哔”提示音,说明支持行编辑;如果没有反应,或回显了 ^P,则说明不支持行编辑;只能用退格键删除当前行的字符。

解释器的操作方式类似 Unix Shell:用与 tty 设备关联的标准输入调用时,可以交互式地读取和执行命令;以文件名参数,或标准输入文件调用时,则读取并执行文件中的 脚本

启动解释器的另一种方式是 python -c command [arg] ...,这与 shell 的 -c 选项类似,其中,command 需换成要执行的语句。由于 Python 语句经常包含空格等被 shell 特殊对待的字符,一般情况下,建议用单引号标注整个 command

Python 模块也可以当作脚本使用。输入:python -m module [arg] ...,会执行 module 的源文件,这跟在命令行把路径写全了一样。

在交互模式下运行脚本文件,只要在脚本名称参数前,加上选项 -i 就可以了。

传入参数

解释器读取命令行参数,把脚本名与其他参数转化为字符串列表存到 sys 模块的 argv 变量里。执行 import sys,可以导入这个模块,并访问该列表。该列表最少有一个元素;未给定输入参数时,sys.argv[0] 是空字符串。给定脚本名是 '-' (标准输入)时,sys.argv[0]'-'。使用 -c command 时,sys.argv[0]'-c'。如果使用选项 -m module*,sys.argv[0] 就是包含目录的模块全名。解释器不处理 -c *command-m module 之后的选项,而是直接留在 sys.argv 中由命令或模块来处理。

交互模式

在终端(tty)输入并执行指令时,解释器在 交互模式(interactive mode) 中运行。在这种模式中,会显示 主提示符,提示输入下一条指令,主提示符通常用三个大于号(>>>)表示;输入连续行时,显示 次要提示符,默认是三个点(...)。进入解释器时,首先显示欢迎信息、版本信息、版权声明,然后才是提示符:

$ python3.10
Python 3.10 (default, June 4 2019, 09:25:04)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

输入多行架构的语句时,要用连续行。以 if 为例:

>>> the_world_is_flat = True
>>> if the_world_is_flat:
...     print("Be careful not to fall off!")
...
Be careful not to fall off!

解释器的运行环境

源文件的字符编码

默认情况下,Python 源码文件的编码是 UTF-8。这种编码支持世界上大多数语言的字符,可以用于字符串字面值、变量、函数名及注释 —— 尽管标准库只用常规的 ASCII 字符作为变量名或函数名,可移植代码都应遵守此约定。要正确显示这些字符,编辑器必须能识别 UTF-8 编码,而且必须使用支持文件中所有字符的字体。

如果不使用默认编码,则要声明文件的编码,文件的 第一 行要写成特殊注释。句法如下:

# -*- coding: encoding -*-

其中,encoding 可以是 Python 支持的任意一种 codecs

比如,声明使用 Windows-1252 编码,源码文件要写成:

# -*- coding: cp1252 -*-

第一行 的规则也有一种例外情况,源码以 UNIX “shebang” 行 开头。此时,编码声明要写在文件的第二行。例如:

#!/usr/bin/env python3
# -*- coding: cp1252 -*-

Unix 系统中,为了不与同时安装的 Python 2.x 冲突,Python 3.x 解释器默认安装的执行文件名不是 python

2. Python 速览

下面的例子以是否显示提示符(>>> 与 …)区分输入与输出:输入例子中的代码时,要键入以提示符开头的行中提示符后的所有内容;未以提示符开头的行是解释器的输出。注意,例子中的某行出现的第二个提示符是用来结束多行命令的,此时,要键入一个空白行。

本手册中的许多例子,甚至交互式命令都包含注释。Python 注释以 # 开头,直到该物理行结束。注释可以在行开头,或空白符与代码之后,但不能在字符串里面。字符串中的 # 号就是 # 号。注释用于阐明代码,Python 不解释注释,键入例子时,可以不输入注释。

示例如下:

# this is the first comment
spam = 1  # and this is the second comment
          # ... and now a third!
text = "# This is not a comment because it's inside quotes."

Python 用作计算器

现在,尝试一些简单的 Python 命令。启动解释器,等待主提示符(>>> )出现。

数字

解释器像一个简单的计算器:输入表达式,就会给出答案。表达式的语法很直接:运算符 +-*/ 的用法和其他大部分语言一样(比如,Pascal 或 C);括号 (()) 用来分组。例如:

>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5  # division always returns a floating point number
1.6

整数(如,2420 )的类型是 int,带小数(如,5.01.6 )的类型是 float。本教程后半部分将介绍更多数字类型。

除法运算(/)返回浮点数。用 // 运算符执行 floor division 的结果是整数(忽略小数);计算余数用 %

>>> 17 / 3  # classic division returns a float
5.666666666666667
>>>
>>> 17 // 3  # floor division discards the fractional part
5
>>> 17 % 3  # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2  # floored quotient * divisor + remainder
17

Python 用 ** 运算符计算乘方:

>>> 5 ** 2  # 5 squared
25
>>> 2 ** 7  # 2 to the power of 7
128

等号(=)用于给变量赋值。赋值后,下一个交互提示符的位置不显示任何结果:

>>> width = 20
>>> height = 5 * 9
>>> width * height
900

如果变量未定义(即,未赋值),使用该变量会提示错误:

>>> n  # try to access an undefined variable
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined

Python 全面支持浮点数;混合类型运算数的运算会把整数转换为浮点数:

>>> 4 * 3.75 - 1
14.0

交互模式下,上次输出的表达式会赋给变量 _。把 Python 当作计算器时,用该变量实现下一步计算更简单,例如:

>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06

最好把该变量当作只读类型。不要为它显式赋值,否则会创建一个同名独立局部变量,该变量会用它的魔法行为屏蔽内置变量。

除了 intfloat,Python 还支持其他数字类型,例如 DecimalFraction。Python 还内置支持 复数,后缀 jJ 用于表示虚数(例如 3+5j )。

字符串

除了数字,Python 还可以操作字符串。字符串有多种表现形式,用单引号('……')或双引号("……")标注的结果相同 2。反斜杠 \ 用于转义:

>>> 'spam eggs'  # single quotes
'spam eggs'
>>> 'doesn\'t'  # use \' to escape the single quote...
"doesn't"
>>> "doesn't"  # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'

交互式解释器会为输出的字符串加注引号,特殊字符使用反斜杠转义。虽然,有时输出的字符串看起来与输入的字符串不一样(外加的引号可能会改变),但两个字符串是相同的。如果字符串中有单引号而没有双引号,该字符串外将加注双引号,反之,则加注单引号。print() 函数输出的内容更简洁易读,它会省略两边的引号,并输出转义后的特殊字符:

>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
>>> print('"Isn\'t," they said.')
"Isn't," they said.
>>> s = 'First line.\nSecond line.'  # \n means newline
>>> s  # without print(), \n is included in the output
'First line.\nSecond line.'
>>> print(s)  # with print(), \n produces a new line
First line.
Second line.

如果不希望前置 \ 的字符转义成特殊字符,可以使用 原始字符串,在引号前添加 r 即可:

>>> print('C:\some\name')  # here \n means newline!
C:\some
ame
>>> print(r'C:\some\name')  # note the r before the quote
C:\some\name

字符串字面值可以实现跨行连续输入。实现方式是用三引号:"""..."""'''...''',字符串行尾会自动加上回车换行,如果不需要回车换行,在行尾添加 \ 即可。示例如下:

print("""\
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to
""")

输出如下(注意,第一行没有换行):

Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

字符串可以用 + 合并(粘到一起),也可以用 * 重复:

>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'

相邻的两个或多个 字符串字面值 (引号标注的字符)会自动合并:

>>> 'Py' 'thon'
'Python'

拆分长字符串时,这个功能特别实用:

>>> text = ('Put several strings within parentheses '
...         'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'

这项功能只能用于两个字面值,不能用于变量或表达式:

>>> prefix = 'Py'
>>> prefix 'thon'  # can't concatenate a variable and a string literal
  File "<stdin>", line 1
    prefix 'thon'
                ^
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
  File "<stdin>", line 1
    ('un' * 3) 'ium'
                   ^
SyntaxError: invalid syntax

合并多个变量,或合并变量与字面值,要用 +

>>> prefix + 'thon'
'Python'

字符串支持 索引 (下标访问),第一个字符的索引是 0。单字符没有专用的类型,就是长度为一的字符串:

>>> word = 'Python'
>>> word[0]  # character in position 0
'P'
>>> word[5]  # character in position 5
'n'

索引还支持负数,用负数索引时,从右边开始计数:

>>> word[-1]  # last character
'n'
>>> word[-2]  # second-last character
'o'
>>> word[-6]
'P'

注意,-0 和 0 一样,因此,负数索引从 -1 开始。

除了索引,字符串还支持 切片。索引可以提取单个字符,切片 则提取子字符串:

>>> word[0:2]  # characters from position 0 (included) to 2 (excluded)
'Py'
>>> word[2:5]  # characters from position 2 (included) to 5 (excluded)
'tho'

切片索引的默认值很有用;省略开始索引时,默认值为 0,省略结束索引时,默认为到字符串的结尾:

>>> word[:2]   # character from the beginning to position 2 (excluded)
'Py'
>>> word[4:]   # characters from position 4 (included) to the end
'on'
>>> word[-2:]  # characters from the second-last (included) to the end
'on'

注意,输出结果包含切片开始,但不包含切片结束。因此,s[:i] + s[i:] 总是等于 s

>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'

还可以这样理解切片,索引指向的是字符 之间 ,第一个字符的左侧标为 0,最后一个字符的右侧标为 nn 是字符串长度。例如:

 +---+---+---+---+---+---+
 | P | y | t | h | o | n |
 +---+---+---+---+---+---+
 0   1   2   3   4   5   6
-6  -5  -4  -3  -2  -1

第一行数字是字符串中索引 0…6 的位置,第二行数字是对应的负数索引位置。ij 的切片由 ij 之间所有对应的字符组成。

对于使用非负索引的切片,如果两个索引都不越界,切片长度就是起止索引之差。例如, word[1:3] 的长度是 2。

索引越界会报错:

>>> word[42]  # the word only has 6 characters
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: string index out of range

但是,切片会自动处理越界索引:

>>> word[4:42]
'on'
>>> word[42:]
''

Python 字符串不能修改,是 immutable 的。因此,为字符串中某个索引位置赋值会报错:

>>> word[0] = 'J'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment

要生成不同的字符串,应新建一个字符串:

>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'

内置函数 len() 返回字符串的长度:

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34

列表

Python 支持多种 复合 数据类型,可将不同值组合在一起。最常用的 列表 ,是用方括号标注,逗号分隔的一组值。列表 可以包含不同类型的元素,但一般情况下,各个元素的类型相同:

>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]

和字符串(及其他内置 sequence 类型)一样,列表也支持索引和切片:

>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]

切片操作返回包含请求元素的新列表。以下切片操作会返回列表的 浅拷贝:

>>> squares[:]
[1, 4, 9, 16, 25]

列表还支持合并操作:

>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

与 immutable 字符串不同, 列表是 mutable 类型,其内容可以改变:

>>> cubes = [1, 8, 27, 65, 125]  # something's wrong here
>>> 4 ** 3  # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64  # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]

append() 方法 可以在列表结尾添加新元素(详见后文):

>>> cubes.append(216)  # add the cube of 6
>>> cubes.append(7 ** 3)  # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]

为切片赋值可以改变列表大小,甚至清空整个列表:

>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty list
>>> letters[:] = []
>>> letters
[]

内置函数 len() 也支持列表:

>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4

还可以嵌套列表(创建包含其他列表的列表),例如:

>>> a = ['a', 'b', 'c']
>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'

走向编程的第一步

当然,Python 还可以完成比二加二更复杂的任务。 例如,可以编写 斐波那契数列 的初始子序列,如下所示:

>>> # Fibonacci series:
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while a < 10:
...     print(a)
...     a, b = b, a+b
...
0
1
1
2
3
5
8

本例引入了几个新功能。

  • 第一行中的 多重赋值:变量 ab 同时获得新值 0 和 1。最后一行又用了一次多重赋值,这体现在右表达式在赋值前就已经求值了。右表达式求值顺序为从左到右。

  • while 循环只要条件(这里指:a < 10)保持为真就会一直执行。Python 和 C 一样,任何非零整数都为真,零为假。这个条件也可以是字符串或列表的值,事实上,任何序列都可以;长度非零就为真,空序列则为假。示例中的判断只是最简单的比较。比较操作符的标准写法和 C 语言一样: < (小于)、 > (大于)、 == (等于)、 <= (小于等于)、 >= (大于等于)及 != (不等于)。

  • 循环体缩进的 :缩进是 Python 组织语句的方式。在交互式命令行里,得为每个缩输入制表符或空格。使用文本编辑器可以实现更复杂的输入方式;所有像样的文本编辑器都支持自动缩进。交互式输入复合语句时, 要在最后输入空白行表示结束(因为解析器不知道哪一行代码是最后一行)。注意,同一块语句的每一行的缩进相同。

  • print() 函数输出给定参数的值。与表达式不同(比如,之前计算器的例子),它能处理多个参数,包括浮点数与字符串。它输出的字符串不带引号,且各参数项之间会插入一个空格,这样可以实现更好的格式化操作:

    >>> i = 256*256
    >>> print('The value of i is', i)
    The value of i is 65536

    关键字参数 end 可以取消输出后面的换行, 或用另一个字符串结尾:

    >>> a, b = 0, 1
    >>> while a < 1000:
    ...     print(a, end=',')
    ...     a, b = b, a+b
    ...
    0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,

注:

  • **- 的优先级更高, 所以 -3**2 会被解释成 -(3**2) ,因此,结果是 -9。要避免这个问题,并且得到 9, 可以用 (-3)**2
  • 和其他语言不一样,特殊字符如 \n 在单引号('...')和双引号("...")里的意义一样。这两种引号唯一的区别是,不需要在单引号里转义双引号 ",但必须把单引号转义成 \',反之亦然。

3. 流程控制工具

if 语句

最让人耳熟能详的应该是 if 语句。例如:

>>> x = int(input("Please enter an integer: "))
Please enter an integer: 42
>>> if x < 0:
...     x = 0
...     print('Negative changed to zero')
... elif x == 0:
...     print('Zero')
... elif x == 1:
...     print('Single')
... else:
...     print('More')
...
More

if 语句包含零个或多个 elif 子句,及可选的 else 子句。关键字 ‘elif‘ 是 ‘else if’ 的缩写,适用于避免过多的缩进。可以把 ifelifelif … 序列看作是其他语言中 switchcase 语句的替代品。

如果你要将同一个值与多个常量进行比较,或是要检查特定类型或属性,你可能会发现 match 语句是很有用的。

for 语句

Python 的 for 语句与 C 或 Pascal 中的不同。Python 的 for 语句不迭代算术递增数值(如 Pascal),或是给予用户定义迭代步骤和暂停条件的能力(如 C),而是迭代列表或字符串等任意序列,元素的迭代顺序与在序列中出现的顺序一致。 例如:

>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

遍历某个集合的同时修改该集合的内容,很难获取想要的结果。要在遍历时修改集合的内容,应该遍历该集合的副本或创建新的集合:

# Create a sample collection
users = {'Hans': 'active', 'Éléonore': 'inactive', '景太郎': 'active'}
# Strategy:  Iterate over a copy
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]
# Strategy:  Create a new collection
active_users = {}
for user, status in users.items():
    if status == 'active':
        active_users[user] = status

range() 函数

内置函数 range() 常用于遍历数字序列,该函数可以生成算术级数:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

生成的序列不包含给定的终止数值;range(10) 生成 10 个值,这是一个长度为 10 的序列,其中的元素索引都是合法的。range 可以不从 0 开始,还可以按指定幅度递增(递增幅度称为 ‘步进’,支持负数):

>>> list(range(5, 10))
[5, 6, 7, 8, 9]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(-10, -100, -30))
[-10, -40, -70]

range()len() 组合在一起,可以按索引迭代序列:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

不过,大多数情况下,enumerate() 函数更便捷 。

如果只输出 range,会出现意想不到的结果:

>>> range(10)
range(0, 10)

range() 返回对象的操作和列表很像,但其实这两种对象不是一回事。迭代时,该对象基于所需序列返回连续项,并没有生成真正的列表,从而节省了空间。

这种对象称为可迭代对象 iterable,函数或程序结构可通过该对象获取连续项,直到所有元素全部迭代完毕。for 语句就是这样的架构,sum() 是一种把可迭代对象作为参数的函数:

>>> sum(range(4))  # 0 + 1 + 2 + 3
6

下文将介绍更多返回可迭代对象或把可迭代对象当作参数的函数。

循环中的 breakcontinue 语句及 else 子句

break 语句和 C 中的类似,用于跳出最近的 forwhile 循环。

循环语句支持 else 子句;for 循环中,可迭代对象中的元素全部循环完毕时,或 while 循环的条件为假时,执行该子句;break 语句终止循环时,不执行该子句。 请看下面这个查找素数的循环示例:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # loop fell through without finding a factor
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(没错,这段代码就是这么写。仔细看:else 子句属于 for 循环,不属于 if 语句。)

if 语句相比,循环的 else 子句更像 tryelse 子句: tryelse 子句在未触发异常时执行,循环的 else 子句则在未运行 break 时执行。

continue 语句也借鉴自 C 语言,表示继续执行循环的下一次迭代:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("Found an odd number", num)
...
Found an even number 2
Found an odd number 3
Found an even number 4
Found an odd number 5
Found an even number 6
Found an odd number 7
Found an even number 8
Found an odd number 9

pass 语句

pass 语句不执行任何操作。语法上需要一个语句,但程序不实际执行任何动作时,可以使用该语句。例如:

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

下面这段代码创建了一个最小的类:

>>> class MyEmptyClass:
...     pass
...

pass 还可以用作函数或条件子句的占位符,让开发者聚焦更抽象的层次。此时,程序直接忽略 pass

>>> def initlog(*args):
...     pass   # Remember to implement this!
...

match 语句

match 语句接受一个表达式并将它的值与以一个或多个 case 语句块形式给出的一系列模式进行比较。 这在表面上很类似 C, Java 或 JavaScript (以及许多其他语言) 中的 switch 语句,但它还能够从值中提取子部分 (序列元素或对象属性) 并赋值给变量。

最简单的形式是将一个目标值与一个或多个字面值进行比较:

def http_error(status):
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"
        case _:
            return "Something's wrong with the internet"

请注意最后一个代码块: “变量名” _ 被作为 通配符 并必定会匹配成功。 如果没有任何 case 语句匹配成功,则任何分支都不会被执行。

你可以使用 | (“ or ”)在一个模式中组合几个字面值:

case 401 | 403 | 404:
    return "Not allowed"

模式的形式可以类似于解包赋值,并可被用于绑定变量:

# point is an (x, y) tuple
match point:
    case (0, 0):
        print("Origin")
    case (0, y):
        print(f"Y={y}")
    case (x, 0):
        print(f"X={x}")
    case (x, y):
        print(f"X={x}, Y={y}")
    case _:
        raise ValueError("Not a point")

请仔细研究此代码! 第一个模式有两个字面值,可以看作是上面所示字面值模式的扩展。 但接下来的两个模式结合了一个字面值和一个变量,而变量 绑定 了一个来自目标的值 (point)。 第四个模式捕获了两个值,这使得它在概念上类似于解包赋值 (x, y) = point

如果你使用类来结构化你的数据,你可以使用类名之后跟一个类似于构造器的参数列表,这样能够捕获属性放入到变量中:

class Point:
    x: int
    y: int
def where_is(point):
    match point:
        case Point(x=0, y=0):
            print("Origin")
        case Point(x=0, y=y):
            print(f"Y={y}")
        case Point(x=x, y=0):
            print(f"X={x}")
        case Point():
            print("Somewhere else")
        case _:
            print("Not a point")

你可以在某些为其属性提供了排序的内置类(例如 dataclass)中使用位置参数。 你也可以通过在你的类中设置 __match_args__ 特殊属性来为模式中的属性定义一个专门的位置。 如果它被设为 (“x”, “y”),则以下模式均为等价的(并且都是将 y 属性绑定到 var 变量):

Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)

读取模式的推荐方式是将它们看做是你会在赋值操作左侧放置的内容的扩展形式,以便理解各个变量将会被设置的值。 只有单独的名称 (例如上面的 var) 会被 match 语句所赋值。 带点号的名称 (例如 foo.bar)、属性名称 (例如上面的 x=y=) 或类名称 (通过其后的 “(…)” 来识别,例如上面的 Point) 都绝不会被赋值。

模式可以任意地嵌套。 例如,如果我们有一个由点组成的短列表,则可以这样匹配它:

match points:
    case []:
        print("No points")
    case [Point(0, 0)]:
        print("The origin")
    case [Point(x, y)]:
        print(f"Single point {x}, {y}")
    case [Point(0, y1), Point(0, y2)]:
        print(f"Two on the Y axis at {y1}, {y2}")
    case _:
        print("Something else")

我们可以向一个模式添加 if 子句,称为“守护项”。 如果守护项为假值,则 match 将继续尝试下一个 case 语句块。 请注意值的捕获发生在守护项被求值之前。:

match point:
    case Point(x, y) if x == y:
        print(f"Y=X at {x}")
    case Point(x, y):
        print(f"Not on the diagonal")

此语句的一些其他关键特性:

  • 类似于解包赋值,元组和列表模式具有完全相同的含义并且实际上能匹配任意序列。 一个重要的例外是它们不能匹配迭代器或字符串。

  • 序列模式支持扩展解包操作: [x, y, *rest](x, y, *rest) 的作用类似于解包赋值。 在 * 之后的名称也可以为 _,因此 (x, y, *_) 可以匹配包含至少两个条目的序列而不必绑定其余的条目。

  • 映射模式: {"bandwidth": b, "latency": l} 会从一个字典中捕获 "bandwidth""latency" 的值。 与序列模式不同,额外的键会被忽略。 解包操作例如 **rest 也受到支持。 (但 **_ 是冗余的,因而不被允许。)

  • 子模式可使用 as 关键字来捕获:

    case (Point(x1, y1), Point(x2, y2) as p2): ...

    将把输入的第二个元素捕获为 p2 (只要输入是包含两个点的序列)

  • 大多数字面值是按相等性比较的,但是单例对象 True, FalseNone 则是按标识号比较的。

  • 模式可以使用命名常量。 这些命名常量必须为带点号的名称以防止它们被解读为捕获变量:

    from enum import Enum
    class Color(Enum):
        RED = 0
        GREEN = 1
        BLUE = 2
    match color:
        case Color.RED:
            print("I see red!")
        case Color.GREEN:
            print("Grass is green")
        case Color.BLUE:
            print("I'm feeling the blues :(")

定义函数

下列代码创建一个可以输出限定数值内的斐波那契数列函数:

>>> def fib(n):    # write Fibonacci series up to n
...     """Print a Fibonacci series up to n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

定义 函数使用关键字 def,后跟函数名与括号内的形参列表。函数语句从下一行开始,并且必须缩进。

函数内的第一条语句是字符串时,该字符串就是文档字符串,也称为 docstring。利用文档字符串可以自动生成在线文档或打印版文档,还可以让开发者在浏览代码时直接查阅文档;Python 开发者最好养成在代码中加入文档字符串的好习惯。

函数在 执行 时使用函数局部变量符号表,所有函数变量赋值都存在局部符号表中;引用变量时,首先,在局部符号表里查找变量,然后,是外层函数局部符号表,再是全局符号表,最后是内置名称符号表。因此,尽管可以引用全局变量和外层函数的变量,但最好不要在函数内直接赋值(除非是 global 语句定义的全局变量,或 nonlocal 语句定义的外层函数变量)。

在调用函数时会将实际参数(实参)引入到被调用函数的局部符号表中;因此,实参是使用 按值调用 来传递的(其中的 始终是对象的 引用 而不是对象的值)。 1 当一个函数调用另外一个函数时,会为该调用创建一个新的局部符号表。

函数定义在当前符号表中把函数名与函数对象关联在一起。解释器把函数名指向的对象作为用户自定义函数。还可以使用其他名称指向同一个函数对象,并访问访该函数:

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

fib 不返回值,因此,其他语言不把它当作函数,而是当作过程。事实上,没有 return 语句的函数也返回值,只不过这个值比较是 None (是一个内置名称)。一般来说,解释器不会输出单独的返回值 None ,如需查看该值,可以使用 print()

>>> fib(0)
>>> print(fib(0))
None

编写不直接输出斐波那契数列运算结果,而是返回运算结果列表的函数也非常简单:

>>> def fib2(n):  # return Fibonacci series up to n
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # see below
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # call it
>>> f100                # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

本例也新引入了一些 Python 功能:

  • return 语句返回函数的值。return 语句不带表达式参数时,返回 None。函数执行完毕退出也返回 None
  • result.append(a) 语句调用了列表对象 result方法 。方法是“从属于”对象的函数,命名为 obj.methodnameobj 是对象(也可以是表达式),methodname 是对象类型定义的方法名。不同类型定义不同的方法,不同类型的方法名可以相同,且不会引起歧义。示例中的方法 append() 是为列表对象定义的,用于在列表末尾添加新元素。本例中,该方法相当于 result = result + [a] ,但更有效。

函数定义详解

函数定义支持可变数量的参数。这里列出三种可以组合使用的形式。

默认值参数

为参数指定默认值是非常有用的方式。调用函数时,可以使用比定义时更少的参数,例如:

def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        ok = input(prompt)
        if ok in ('y', 'ye', 'yes'):
            return True
        if ok in ('n', 'no', 'nop', 'nope'):
            return False
        retries = retries - 1
        if retries < 0:
            raise ValueError('invalid user response')
        print(reminder)

该函数可以用以下方式调用:

  • 只给出必选实参:ask_ok('Do you really want to quit?')
  • 给出一个可选实参:ask_ok('OK to overwrite the file?', 2)
  • 给出所有实参:ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')

本例还使用了关键字 in ,用于确认序列中是否包含某个值。

默认值在 定义 作用域里的函数定义中求值,所以:

i = 5
def f(arg=i):
    print(arg)
i = 6
f()

上例输出的是 5

重要警告: 默认值只计算一次。默认值为列表、字典或类实例等可变对象时,会产生与该规则不同的结果。例如,下面的函数会累积后续调用时传递的参数:

def f(a, L=[]):
    L.append(a)
    return L
print(f(1))
print(f(2))
print(f(3))

输出结果如下:

[1]
[1, 2]
[1, 2, 3]

不想在后续调用之间共享默认值时,应以如下方式编写函数:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

关键字参数

kwarg=value 形式的 关键字参数 也可以用于调用函数。函数示例如下:

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print("-- This parrot wouldn't", action, end=' ')
    print("if you put", voltage, "volts through it.")
    print("-- Lovely plumage, the", type)
    print("-- It's", state, "!")

该函数接受一个必选参数(voltage)和三个可选参数(state, actiontype)。该函数可用下列方式调用:

parrot(1000)                                          # 1 positional argument
parrot(voltage=1000)                                  # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword

以下调用函数的方式都无效:

parrot()                     # required argument missing
parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
parrot(110, voltage=220)     # duplicate value for the same argument
parrot(actor='John Cleese')  # unknown keyword argument

函数调用时,关键字参数必须跟在位置参数后面。所有传递的关键字参数都必须匹配一个函数接受的参数(比如,actor 不是函数 parrot 的有效参数),关键字参数的顺序并不重要。这也包括必选参数,(比如,parrot(voltage=1000) 也有效)。不能对同一个参数多次赋值,下面就是一个因此限制而失败的例子:

>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for argument 'a'

最后一个形参为 **name 形式时,接收一个字典,该字典包含与函数中已定义形参对应之外的所有关键字参数。**name 形参可以与 *name 形参组合使用(*name 必须在 **name 前面), *name 形参接收一个 元组,该元组包含形参列表之外的位置参数。例如,可以定义下面这样的函数:

def cheeseshop(kind, *arguments, **keywords):
    print("-- Do you have any", kind, "?")
    print("-- I'm sorry, we're all out of", kind)
    for arg in arguments:
        print(arg)
    print("-" * 40)
    for kw in keywords:
        print(kw, ":", keywords[kw])

该函数可以用如下方式调用:

cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")

输出结果如下:

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch

注意,关键字参数在输出结果中的顺序与调用函数时的顺序一致。

特殊参数

默认情况下,参数可以按位置或显式关键字传递给 Python 函数。为了让代码易读、高效,最好限制参数的传递方式,这样,开发者只需查看函数定义,即可确定参数项是仅按位置、按位置或关键字,还是仅按关键字传递。

函数定义如下:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only

/* 是可选的。这些符号表明形参如何把参数值传递给函数:位置、位置或关键字、关键字。关键字形参也叫作命名形参。

位置或关键字参数

函数定义中未使用 /* 时,参数可以按位置或关键字传递给函数。

仅位置参数

此处再介绍一些细节,特定形参可以标记为 仅限位置仅限位置 时,形参的顺序很重要,且这些形参不能用关键字传递。仅限位置形参应放在 / (正斜杠)前。/ 用于在逻辑上分割仅限位置形参与其它形参。如果函数定义中没有 /,则表示没有仅限位置形参。

/ 后可以是 位置或关键字仅限关键字 形参。

仅限关键字参数

把形参标记为 仅限关键字*,表明必须以关键字参数形式传递该形参,应在参数列表中第一个 *仅限关键字 形参前添加 *

函数示例

请看下面的函数定义示例,注意 /* 标记:

>>> def standard_arg(arg):
...     print(arg)
...
>>> def pos_only_arg(arg, /):
...     print(arg)
...
>>> def kwd_only_arg(*, arg):
...     print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
...     print(pos_only, standard, kwd_only)

第一个函数定义 standard_arg 是最常见的形式,对调用方式没有任何限制,可以按位置也可以按关键字传递参数:

>>> standard_arg(2)
2
>>> standard_arg(arg=2)
2

第二个函数 pos_only_arg 的函数定义中有 /,仅限使用位置形参:

>>> pos_only_arg(1)
1
>>> pos_only_arg(arg=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got some positional-only arguments passed as keyword arguments: 'arg'

第三个函数 kwd_only_args 的函数定义通过 * 表明仅限关键字参数:

>>> kwd_only_arg(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given
>>> kwd_only_arg(arg=3)
3

最后一个函数在同一个函数定义中,使用了全部三种调用惯例:

>>> combined_example(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given
>>> combined_example(1, 2, kwd_only=3)
1 2 3
>>> combined_example(1, standard=2, kwd_only=3)
1 2 3
>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() got some positional-only arguments passed as keyword arguments: 'pos_only'

下面的函数定义中,kwdsname 当作键,因此,可能与位置参数 name 产生潜在冲突:

def foo(name, **kwds):
    return 'name' in kwds

调用该函数不可能返回 True,因为关键字 'name' 总与第一个形参绑定。例如:

>>> foo(1, **{'name': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>

加上 / (仅限位置参数)后,就可以了。此时,函数定义把 name 当作位置参数,'name' 也可以作为关键字参数的键:

def foo(name, /, **kwds):
    return 'name' in kwds
>>> foo(1, **{'name': 2})
True

换句话说,仅限位置形参的名称可以在 **kwds 中使用,而不产生歧义。

小结

以下用例决定哪些形参可以用于函数定义:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

说明:

  • 使用仅限位置形参,可以让用户无法使用形参名。形参名没有实际意义时,强制调用函数的实参顺序时,或同时接收位置形参和关键字时,这种方式很有用。
  • 当形参名有实际意义,且显式名称可以让函数定义更易理解时,阻止用户依赖传递实参的位置时,才使用关键字。
  • 对于 API,使用仅限位置形参,可以防止未来修改形参名时造成破坏性的 API 变动。

任意实参列表

调用函数时,使用任意数量的实参是最少见的选项。这些实参包含在元组中。在可变数量的实参之前,可能有若干个普通参数:

def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))

variadic 实参用于采集传递给函数的所有剩余实参,因此,它们通常在形参列表的末尾。*args 形参后的任何形式参数只能是仅限关键字参数,即只能用作关键字参数,不能用作位置参数:

>>> def concat(*args, sep="/"):
...     return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

解包实参列表

函数调用要求独立的位置参数,但实参在列表或元组里时,要执行相反的操作。例如,内置的 range() 函数要求独立的 startstop 实参。如果这些参数不是独立的,则要在调用函数时,用 * 操作符把实参从列表或元组解包出来:

>>> list(range(3, 6))            # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # call with arguments unpacked from a list
[3, 4, 5]

同样,字典可以用 ** 操作符传递关键字参数:

>>> def parrot(voltage, state='a stiff', action='voom'):
...     print("-- This parrot wouldn't", action, end=' ')
...     print("if you put", voltage, "volts through it.", end=' ')
...     print("E's", state, "!")
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !

Lambda 表达式

lambda 关键字用于创建小巧的匿名函数。lambda a, b: a+b 函数返回两个参数的和。Lambda 函数可用于任何需要函数对象的地方。在语法上,匿名函数只能是单个表达式。在语义上,它只是常规函数定义的语法糖。与嵌套函数定义一样,lambda 函数可以引用包含作用域中的变量:

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

上例用 lambda 表达式返回函数。还可以把匿名函数用作传递的实参:

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

文档字符串

以下是文档字符串内容和格式的约定。

第一行应为对象用途的简短摘要。为保持简洁,不要在这里显式说明对象名或类型,因为可通过其他方式获取这些信息(除非该名称碰巧是描述函数操作的动词)。这一行应以大写字母开头,以句点结尾。

文档字符串为多行时,第二行应为空白行,在视觉上将摘要与其余描述分开。后面的行可包含若干段落,描述对象的调用约定、副作用等。

Python 解析器不会删除 Python 中多行字符串字面值的缩进,因此,文档处理工具应在必要时删除缩进。这项操作遵循以下约定:文档字符串第一行 之后 的第一个非空行决定了整个文档字符串的缩进量(第一行通常与字符串开头的引号相邻,其缩进在字符串中并不明显,因此,不能用第一行的缩进),然后,删除字符串中所有行开头处与此缩进“等价”的空白符。不能有比此缩进更少的行,但如果出现了缩进更少的行,应删除这些行的所有前导空白符。转化制表符后(通常为 8 个空格),应测试空白符的等效性。

下面是多行文档字符串的一个例子:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.
    No, really, it doesn't do anything.

函数注解

函数注解 是可选的用户自定义函数类型的元数据完整信息。

标注 以字典的形式存放在函数的 __annotations__ 属性中,并且不会影响函数的任何其他部分。 形参标注的定义方式是在形参名后加冒号,后面跟一个表达式,该表达式会被求值为标注的值。 返回值标注的定义方式是加组合符号 ->,后面跟一个表达式,该标注位于形参列表和表示 def 语句结束的冒号之间。 下面的示例有一个必须的参数,一个可选的关键字参数以及返回值都带有相应的标注:

>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

编码风格

现在你将要写更长,更复杂的 Python 代码,是时候讨论一下 代码风格 了。 大多数语言都能以不同的风格被编写(或更准确地说,被格式化);有些比其他的更具有可读性。 能让其他人轻松阅读你的代码总是一个好主意,采用一种好的编码风格对此有很大帮助。

Python 项目大多都遵循 PEP 8 的风格指南;它推行的编码风格易于阅读、赏心悦目。Python 开发者均应抽时间悉心研读;以下是该提案中的核心要点:

  • 缩进,用 4 个空格,不要用制表符。

    4 个空格是小缩进(更深嵌套)和大缩进(更易阅读)之间的折中方案。制表符会引起混乱,最好别用。

  • 换行,一行不超过 79 个字符。

    这样换行的小屏阅读体验更好,还便于在大屏显示器上并排阅读多个代码文件。

  • 用空行分隔函数和类,及函数内较大的代码块。

  • 最好把注释放到单独一行。

  • 使用文档字符串。

  • 运算符前后、逗号后要用空格,但不要直接在括号内使用: a = f(1, 2) + g(3, 4)

  • 类和函数的命名要一致;按惯例,命名类用 UpperCamelCase,命名函数与方法用 lowercase_with_underscores。命名方法中第一个参数总是用 self

  • 编写用于国际多语环境的代码时,不要用生僻的编码。Python 默认的 UTF-8 或纯 ASCII 可以胜任各种情况。

  • 同理,就算多语阅读、维护代码的可能再小,也不要在标识符中使用非 ASCII 字符。

4. 数据结构

列表详解

列表数据类型支持很多方法,列表对象的所有方法所示如下:

list.append(x)

在列表末尾添加一个元素,相当于 a[len(a):] = [x]

list.extend(iterable)

用可迭代对象的元素扩展列表。相当于 a[len(a):] = iterable

list.insert(i, x)

在指定位置插入元素。第一个参数是插入元素的索引,因此,a.insert(0, x) 在列表开头插入元素, a.insert(len(a), x) 等同于 a.append(x)

list.remove(x)

从列表中删除第一个值为 x 的元素。未找到指定元素时,触发 ValueError 异常。

list.pop([i])

删除列表中指定位置的元素,并返回被删除的元素。未指定位置时,a.pop() 删除并返回列表的最后一个元素。(方法签名中 i 两边的方括号表示该参数是可选的,不是要求输入方括号。这种表示法常见于 Python 参考库)。

list.clear()

删除列表里的所有元素,相当于 del a[:]

list.index(x[, start[, end]])

返回列表中第一个值为 x 的元素的零基索引。未找到指定元素时,触发 ValueError 异常。

可选参数 startend 是切片符号,用于将搜索限制为列表的特定子序列。返回的索引是相对于整个序列的开始计算的,而不是 start 参数。

list.count(x)

返回列表中元素 x 出现的次数。

list.sort(**, key=None, reverse=False*)

就地排序列表中的元素(要了解自定义排序参数,详见 sorted())。

list.reverse()

翻转列表中的元素。

list.copy()

返回列表的浅拷贝。相当于 a[:]

多数列表方法示例:

>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi', 'apple', 'banana']
>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4)  # Find next banana starting a position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange', 'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange', 'pear']
>>> fruits.pop()
'pear'

insertremovesort 等方法只修改列表,不输出返回值——返回的默认值为 None 。这是所有 Python 可变数据结构的设计原则。

还有,不是所有数据都可以排序或比较。例如,[None, 'hello', 10] 就不可排序,因为整数不能与字符串对比,而 None 不能与其他类型对比。有些类型根本就没有定义顺序关系,例如,3+4j < 5+7j 这种对比操作就是无效的。

用列表实现堆栈

使用列表方法实现堆栈非常容易,最后插入的最先取出(“后进先出”)。把元素添加到堆栈的顶端,使用 append() 。从堆栈顶部取出元素,使用 pop() ,不用指定索引。例如:

>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]

用列表实现队列

列表也可以用作队列,最先加入的元素,最先取出(“先进先出”);然而,列表作为队列的效率很低。因为,在列表末尾添加和删除元素非常快,但在列表开头插入或移除元素却很慢(因为所有其他元素都必须移动一位)。

实现队列最好用 collections.deque,可以快速从两端添加或删除元素。例如:

>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry")           # Terry arrives
>>> queue.append("Graham")          # Graham arrives
>>> queue.popleft()                 # The first to arrive now leaves
'Eric'
>>> queue.popleft()                 # The second to arrive now leaves
'John'
>>> queue                           # Remaining queue in order of arrival
deque(['Michael', 'Terry', 'Graham'])

列表推导式

列表推导式创建列表的方式更简洁。常见的用法为,对序列或可迭代对象中的每个元素应用某种操作,用生成的结果创建新的列表;或用满足特定条件的元素创建子序列。

例如,创建平方值的列表:

>>> squares = []
>>> for x in range(10):
...     squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

注意,这段代码创建(或覆盖)变量 x,该变量在循环结束后仍然存在。下述方法可以无副作用地计算平方列表:

squares = list(map(lambda x: x**2, range(10)))

或等价于:

squares = [x**2 for x in range(10)]

上面这种写法更简洁、易读。

列表推导式的方括号内包含以下内容:一个表达式,后面为一个 for 子句,然后,是零个或多个 forif 子句。结果是由表达式依据 forif 子句求值计算而得出一个新列表。 举例来说,以下列表推导式将两个列表中不相等的元素组合起来:

>>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

等价于:

>>> combs = []
>>> for x in [1,2,3]:
...     for y in [3,1,4]:
...         if x != y:
...             combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]

注意,上面两段代码中,forif 的顺序相同。

表达式是元组(例如上例的 (x, y))时,必须加上括号:

>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
  File "<stdin>", line 1, in <module>
    [x, x**2 for x in range(6)]
               ^
SyntaxError: invalid syntax
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

列表推导式可以使用复杂的表达式和嵌套函数:

>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']

嵌套的列表推导式

列表推导式中的初始表达式可以是任何表达式,甚至可以是另一个列表推导式。

下面这个 3x4 矩阵,由 3 个长度为 4 的列表组成:

>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]

下面的列表推导式可以转置行列:

>>> [[row[i] for row in matrix] for i in range(4)]
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

如上节所示,嵌套的列表推导式基于其后的 for 求值,所以这个例子等价于:

>>> transposed = []
>>> for i in range(4):
...     transposed.append([row[i] for row in matrix])
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

反过来说,也等价于:

>>> transposed = []
>>> for i in range(4):
...     # the following 3 lines implement the nested listcomp
...     transposed_row = []
...     for row in matrix:
...         transposed_row.append(row[i])
...     transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]

实际应用中,最好用内置函数替代复杂的流程语句。此时,zip() 函数更好用:

>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]

del 语句

del 语句按索引,而不是值从列表中移除元素。与返回值的 pop() 方法不同, del 语句也可以从列表中移除切片,或清空整个列表(之前是将空列表赋值给切片)。 例如:

>>> a = [-1, 1, 66.25, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.25, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.25, 1234.5]
>>> del a[:]
>>> a
[]

del 也可以用来删除整个变量:

>>> del a

此后,再引用 a 就会报错(直到为它赋与另一个值)。后文会介绍 del 的其他用法。

元组和序列

列表和字符串有很多共性,例如,索引和切片操作。这两种数据类型是 序列 (参见 序列类型 —- list, tuple, range)。随着 Python 语言的发展,其他的序列类型也被加入其中。本节介绍另一种标准序列类型:元组

元组由多个用逗号隔开的值组成,例如:

>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])

输出时,元组都要由圆括号标注,这样才能正确地解释嵌套元组。输入时,圆括号可有可无,不过经常是必须的(如果元组是更大的表达式的一部分)。不允许为元组中的单个元素赋值,当然,可以创建含列表等可变对象的元组。

虽然,元组与列表很像,但使用场景不同,用途也不同。元组是 immutable (不可变的),一般可包含异质元素序列,通过解包(见本节下文)或索引访问(如果是 namedtuples,可以属性访问)。列表是 mutable (可变的),列表元素一般为同质类型,可迭代访问。

构造 0 个或 1 个元素的元组比较特殊:为了适应这种情况,对句法有一些额外的改变。用一对空圆括号就可以创建空元组;只有一个元素的元组可以通过在这个元素后添加逗号来构建(圆括号里只有一个值的话不够明确)。丑陋,但是有效。例如:

>>> empty = ()
>>> singleton = 'hello',    # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)

语句 t = 12345, 54321, 'hello!'元组打包 的例子:值 12345, 54321'hello!' 一起被打包进元组。逆操作也可以:

>>> x, y, z = t

称之为 序列解包 也是妥妥的,适用于右侧的任何序列。序列解包时,左侧变量与右侧序列元素的数量应相等。注意,多重赋值其实只是元组打包和序列解包的组合。

集合

Python 还支持 集合 这种数据类型。集合是由不重复元素组成的无序容器。基本用法包括成员检测、消除重复元素。集合对象支持合集、交集、差集、对称差分等数学运算。

创建集合用花括号或 set() 函数。注意,创建空集合只能用 set(),不能用 {}{} 创建的是空字典。

以下是一些简单的示例

>>> basket = {'apple', 'orange', 'apple', 'pear', 'orange', 'banana'}
>>> print(basket)                      # show that duplicates have been removed
{'orange', 'banana', 'pear', 'apple'}
>>> 'orange' in basket                 # fast membership testing
True
>>> 'crabgrass' in basket
False
>>> # Demonstrate set operations on unique letters from two words
...
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a                                  # unique letters in a
{'a', 'r', 'b', 'c', 'd'}
>>> a - b                              # letters in a but not in b
{'r', 'd', 'b'}
>>> a | b                              # letters in a or b or both
{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'}
>>> a & b                              # letters in both a and b
{'a', 'c'}
>>> a ^ b                              # letters in a or b but not both
{'r', 'd', 'b', 'm', 'z', 'l'}

与 列表推导式 类似,集合也支持推导式:

>>> a = {x for x in 'abracadabra' if x not in 'abc'}
>>> a
{'r', 'd'}

字典

字典 也是一种常用的 Python 內置数据类型。其他语言可能把字典称为 联合内存联合数组*。与以连续整数为索引的序列不同,字典以 *关键字 为索引,关键字通常是字符串或数字,也可以是其他任意不可变类型。只包含字符串、数字、元组的元组,也可以用作关键字。但如果元组直接或间接地包含了可变对象,就不能用作关键字。列表不能当关键字,因为列表可以用索引、切片、append()extend() 等方法修改。

可以把字典理解为 键值对 的集合,但字典的键必须是唯一的。花括号 {} 用于创建空字典。另一种初始化字典的方式是,在花括号里输入逗号分隔的键值对,这也是字典的输出方式。

字典的主要用途是通过关键字存储、提取值。用 del 可以删除键值对。用已存在的关键字存储值,与该关键字关联的旧值会被取代。通过不存在的键提取值,则会报错。

对字典执行 list(d) 操作,返回该字典中所有键的列表,按插入次序排列(如需排序,请使用 sorted(d))。检查字典里是否存在某个键,使用关键字 in

以下是一些字典的简单示例:

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'jack': 4098, 'sape': 4139, 'guido': 4127}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'jack': 4098, 'guido': 4127, 'irv': 4127}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False

dict() 构造函数可以直接用键值对序列创建字典:

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'guido': 4127, 'jack': 4098}

字典推导式可以用任意键值表达式创建字典:

>>> {x: x**2 for x in (2, 4, 6)}
{2: 4, 4: 16, 6: 36}

关键字是比较简单的字符串时,直接用关键字参数指定键值对更便捷:

>>> dict(sape=4139, guido=4127, jack=4098)
{'sape': 4139, 'guido': 4127, 'jack': 4098}

循环的技巧

在字典中循环时,用 items() 方法可同时取出键和对应的值:

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.items():
...     print(k, v)
...
gallahad the pure
robin the brave

在序列中循环时,用 enumerate() 函数可以同时取出位置索引和对应的值:

>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe

同时循环两个或多个序列时,用 zip() 函数可以将其内的元素一一匹配:

>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
...     print('What is your {0}?  It is {1}.'.format(q, a))
...
What is your name?  It is lancelot.
What is your quest?  It is the holy grail.
What is your favorite color?  It is blue.

逆向循环序列时,先正向定位序列,然后调用 reversed() 函数:

>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1

按指定顺序循环序列,可以用 sorted() 函数,在不改动原序列的基础上,返回一个重新的序列:

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear

使用 set() 去除序列中的重复元素。使用 sorted()set() 则按排序后的顺序,循环遍历序列中的唯一元素:

>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear

一般来说,在循环中修改列表的内容时,创建新列表比较简单,且安全:

>>> import math
>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
...     if not math.isnan(value):
...         filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]

深入条件控制

whileif 条件句不只可以进行比较,还可以使用任意运算符。

比较运算符 innot in 校验序列里是否存在某个值。运算符 isis not 比较两个对象是否为同一个对象。所有比较运算符的优先级都一样,且低于数值运算符。

比较操作支持链式操作。例如,a < b == c 校验 a 是否小于 b,且 b 是否等于 c

比较操作可以用布尔运算符 andor 组合,并且,比较操作(或其他布尔运算)的结果都可以用 not 取反。这些操作符的优先级低于比较操作符;not 的优先级最高, or 的优先级最低,因此,A and not B or C 等价于 (A and (not B)) or C。与其他运算符操作一样,此处也可以用圆括号表示想要的组合。

布尔运算符 andor 也称为 短路 运算符:其参数从左至右解析,一旦可以确定结果,解析就会停止。例如,如果 AC 为真,B 为假,那么 A and B and C 不会解析 C。用作普通值而不是布尔值时,短路操作符返回的值通常是最后一个变量。

还可以把比较操作或逻辑表达式的结果赋值给变量,例如:

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'

注意,Python 与 C 不同,在表达式内部赋值必须显式使用 海象运算符 :=。 这避免了 C 程序中常见的问题:要在表达式中写 == 时,却写成了 =

序列和其他类型的比较

序列对象可以与相同序列类型的其他对象比较。这种比较使用 字典式 顺序:首先,比较前两个对应元素,如果不相等,则可确定比较结果;如果相等,则比较之后的两个元素,以此类推,直到其中一个序列结束。如果要比较的两个元素本身是相同类型的序列,则递归地执行字典式顺序比较。如果两个序列中所有的对应元素都相等,则两个序列相等。如果一个序列是另一个的初始子序列,则较短的序列可被视为较小(较少)的序列。 对于字符串来说,字典式顺序使用 Unicode 码位序号排序单个字符。下面列出了一些比较相同类型序列的例子:

(1, 2, 3)              < (1, 2, 4)
[1, 2, 3]              < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4)           < (1, 2, 4)
(1, 2)                 < (1, 2, -1)
(1, 2, 3)             == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab'))   < (1, 2, ('abc', 'a'), 4)

注意,对不同类型的对象来说,只要待比较的对象提供了合适的比较方法,就可以使用 <> 进行比较。例如,混合数值类型通过数值进行比较,所以,0 等于 0.0,等等。否则,解释器不会随便给出一个对比结果,而是触发 TypeError 异常。

注:

  • 别的语言可能会返回可变对象,允许方法连续执行,例如,d->insert("a")->remove("b")->sort();

5. 模块

退出 Python 解释器后,再次进入时,之前在 Python 解释器中定义的函数和变量就丢失了。因此,编写较长程序时,建议用文本编辑器代替解释器,执行文件中的输入内容,这就是编写 脚本 。随着程序越来越长,为了方便维护,最好把脚本拆分成多个文件。编写脚本还一个好处,不同程序调用同一个函数时,不用每次把函数复制到各个程序。

为实现这些需求,Python 把各种定义存入一个文件,在脚本或解释器的交互式实例中使用。这个文件就是 模块 ;模块中的定义可以 导入 到其他模块或 模块(在顶层和计算器模式下,执行脚本中可访问的变量集)。

模块是包含 Python 定义和语句的文件。其文件名是模块名加后缀名 .py 。在模块内部,通过全局变量 __name__ 可以获取模块名(即字符串)。例如,用文本编辑器在当前目录下创建 fibo.py 文件,输入以下内容:

# Fibonacci numbers module
def fib(n):    # write Fibonacci series up to n
    a, b = 0, 1
    while a < n:
        print(a, end=' ')
        a, b = b, a+b
    print()
def fib2(n):   # return Fibonacci series up to n
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result

现在,进入 Python 解释器,用以下命令导入该模块:

>>> import fibo

这项操作不直接把 fibo 函数定义的名称导入到当前符号表,只导入模块名 fibo 。要使用模块名访问函数:

>>> fibo.fib(1000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'

如果经常使用某个函数,可以把它赋值给局部变量:

>>> fib = fibo.fib
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

模块详解

模块包含可执行语句及函数定义。这些语句用于初始化模块,且仅在 import 语句 第一次 遇到模块名时执行。1 (文件作为脚本运行时,也会执行这些语句。)

模块有自己的私有符号表,用作模块中所有函数的全局符号表。因此,在模块内使用全局变量时,不用担心与用户定义的全局变量发生冲突。另一方面,可以用与访问模块函数一样的标记法,访问模块的全局变量,modname.itemname

可以把其他模块导入模块。按惯例,所有 import 语句都放在模块(或脚本)开头,但这不是必须的。导入的模块名存在导入模块的全局符号表里。

import 语句有一个变体,可以直接把模块里的名称导入到另一个模块的符号表。例如:

>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

这段代码不会把模块名导入到局部符号表里(因此,本例没有定义 fibo)。

还有一种变体可以导入模块内定义的所有名称:

>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

这种方式会导入所有不以下划线(_)开头的名称。大多数情况下,不要用这个功能,这种方式向解释器导入了一批未知的名称,可能会覆盖已经定义的名称。

注意,一般情况下,不建议从模块或包内导入 *, 因为,这项操作经常让代码变得难以理解。不过,为了在交互式编译器中少打几个字,这么用也没问题。

模块名后使用 as 时,直接把 as 后的名称与导入模块绑定。

>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

import fibo 一样,这种方式也可以有效地导入模块,唯一的区别是,导入的名称是 fib

from 中也可以使用这种方式,效果类似:

>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

注解

为了保证运行效率,每次解释器会话只导入一次模块。如果更改了模块内容,必须重启解释器;仅交互测试一个模块时,也可以使用 importlib.reload(),例如 import importlib; importlib.reload(modulename)

以脚本方式执行模块

可以用以下方式运行 Python 模块:

python fibo.py <arguments>

这项操作将执行模块里的代码,和导入模块一样,但会把 __name__ 赋值为 "__main__"。 也就是把下列代码添加到模块末尾:

if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))

既可以把这个文件当脚本使用,也可以用作导入的模块, 因为,解析命令行的代码只有在模块以 “main” 文件执行时才会运行:

$ python fibo.py 500 
1 1 2 3 5 8 13 21 34

导入模块时,不运行这些代码:

>>> import fibo
>>>

这种操作常用于为模块提供便捷用户接口,或用于测试(把模块当作执行测试套件的脚本运行)。

模块搜索路径

导入 spam 模块时,解释器首先查找名为 spam 的内置模块。如果没找到,解释器再从 sys.path 变量中的目录列表里查找 spam.py 文件。sys.path 初始化时包含以下位置:

  • 输入脚本的目录(或未指定文件时的当前目录)。
  • PYTHONPATH (目录列表,与 shell 变量 PATH 的语法一样)。
  • The installation-dependent default (by convention including a site-packages directory, handled by the site module).

注解

在支持 symlink 的文件系统中,输入脚本目录是在追加 symlink 后计算出来的。换句话说,包含 symlink 的目录并 没有 添加至模块搜索路径。

初始化后,Python 程序可以更改 sys.path。运行脚本的目录在标准库路径之前,置于搜索路径的开头。即,加载的是该目录里的脚本,而不是标准库的同名模块。 除非刻意替换,否则会报错。

“已编译的” Python 文件

为了快速加载模块,Python 把模块的编译版缓存在 __pycache__ 目录中,文件名为 module.*version*.pyc,version 对编译文件格式进行编码,一般是 Python 的版本号。例如,CPython 的 3.3 发行版中,spam.py 的编译版本缓存为 __pycache__/spam.cpython-33.pyc。使用这种命名惯例,可以让不同 Python 发行版及不同版本的已编译模块共存。

Python 对比编译版本与源码的修改日期,查看它是否已过期,是否要重新编译,此过程完全自动化。此外,编译模块与平台无关,因此,可在不同架构系统之间共享相同的支持库。

Python 在两种情况下不检查缓存。其一,从命令行直接载入模块,只重新编译,不存储编译结果;其二,没有源模块,就不会检查缓存。为了支持无源文件(仅编译)发行版本, 编译模块必须在源目录下,并且绝不能有源模块。

给专业人士的一些小建议:

  • 在 Python 命令中使用 -O-OO 开关,可以减小编译模块的大小。-O 去除断言语句,-OO 去除断言语句和 doc 字符串。有些程序可能依赖于这些内容,因此,没有十足的把握,不要使用这两个选项。“优化过的”模块带有 opt- 标签,并且文件通常会一小些。将来的发行版或许会改进优化的效果。
  • .pyc 文件读取的程序不比从 .py 读取的执行速度快,.pyc 文件只是加载速度更快。
  • compileall 模块可以为一个目录下的所有模块创建 .pyc 文件。
  • 本过程的细节及决策流程图,详见 PEP 3147

标准模块

Python 自带一个标准模块的库,它在 Python 库参考(此处以下称为”库参考” )里另外描述。 一些模块是内嵌到编译器里面的, 它们给一些虽并非语言核心但却内嵌的操作提供接口,要么是为了效率,要么是给操作系统基础操作例如系统调入提供接口。 这些模块集是一个配置选项, 并且还依赖于底层的操作系统。 例如,winreg 模块只在 Windows 系统上提供。一个特别值得注意的模块 sys,它被内嵌到每一个 Python 编译器中。sys.ps1sys.ps2 变量定义了一些字符,它们可以用作主提示符和辅助提示符:

>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>

只有解释器用于交互模式时,才定义这两个变量。

变量 sys.path 是字符串列表,用于确定解释器的模块搜索路径。该变量以环境变量 PYTHONPATH 提取的默认路径进行初始化,如未设置 PYTHONPATH,则使用内置的默认路径。可以用标准列表操作修改该变量:

>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')

dir() 函数

内置函数 dir() 用于查找模块定义的名称。返回结果是经过排序的字符串列表:

>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)  
['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',
 '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',
 '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',
 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',
 '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',
 'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',
 'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',
 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
 'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',
 'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',
 'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',
 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
 'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',
 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',
 'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',
 'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',
 'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',
 'warnoptions']

没有参数时,dir() 列出当前定义的名称:

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

注意,该函数列出所有类型的名称:变量、模块、函数等。

dir() 不会列出内置函数和变量的名称。这些内容的定义在标准模块 builtins 里:

>>> import builtins
>>> dir(builtins)  
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError',
 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
 'zip']

包是一种用“点式模块名”构造 Python 模块命名空间的方法。例如,模块名 A.B 表示包 A 中名为 B 的子模块。正如模块可以区分不同模块之间的全局变量名称一样,点式模块名可以区分 NumPy 或 Pillow 等不同多模块包之间的模块名称。

假设要为统一处理声音文件与声音数据设计一个模块集(“包”)。声音文件的格式很多(通常以扩展名来识别,例如:.wav.aiff.au),因此,为了不同文件格式之间的转换,需要创建和维护一个不断增长的模块集合。为了实现对声音数据的不同处理(例如,混声、添加回声、均衡器功能、创造人工立体声效果),还要编写无穷无尽的模块流。下面这个分级文件树展示了这个包的架构:

sound/                          Top-level package
      __init__.py               Initialize the sound package
      formats/                  Subpackage for file format conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Subpackage for sound effects
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      filters/                  Subpackage for filters
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...

导入包时,Python 搜索 sys.path 里的目录,查找包的子目录。

Python 只把含 __init__.py 文件的目录当成包。这样可以防止以 string 等通用名称命名的目录,无意中屏蔽出现在后方模块搜索路径中的有效模块。 最简情况下,__init__.py 只是一个空文件,但该文件也可以执行包的初始化代码,或设置 __all__ 变量,详见下文。

还可以从包中导入单个模块,例如:

import sound.effects.echo

这段代码加载子模块 sound.effects.echo ,但引用时必须使用子模块的全名:

sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

另一种导入子模块的方法是 :

from sound.effects import echo

这段代码还可以加载子模块 echo ,不加包前缀也可以使用。因此,可以按如下方式使用:

echo.echofilter(input, output, delay=0.7, atten=4)

Import 语句的另一种变体是直接导入所需的函数或变量:

from sound.effects.echo import echofilter

同样,这样也会加载子模块 echo,但可以直接使用函数 echofilter()

echofilter(input, output, delay=0.7, atten=4)

注意,使用 from package import item 时,item 可以是包的子模块(或子包),也可以是包中定义的函数、类或变量等其他名称。import 语句首先测试包中是否定义了 item;如果未在包中定义,则假定 item 是模块,并尝试加载。如果找不到 item,则触发 ImportError 异常。

相反,使用 import item.subitem.subsubitem 句法时,除最后一项外,每个 item 都必须是包;最后一项可以是模块或包,但不能是上一项中定义的类、函数或变量。

从包中导入 *

使用 from sound.effects import * 时会发生什么?理想情况下,该语句在文件系统查找并导入包的所有子模块。这项操作花费的时间较长,并且导入子模块可能会产生不必要的副作用,这种副作用只有在显式导入子模块时才会发生。

唯一的解决方案是提供包的显式索引。import 语句使用如下惯例:如果包的 __init__.py 代码定义了列表 __all__,运行 from package import * 时,它就是用于导入的模块名列表。发布包的新版本时,包的作者应更新此列表。如果包的作者认为没有必要在包中执行导入 * 操作,也可以不提供此列表。例如,sound/effects/__init__.py 文件包含以下代码:

__all__ = ["echo", "surround", "reverse"]

即,from sound.effects import * 将导入 sound 包中的这三个命名子模块。

如果没有定义 __all__from sound.effects import * 语句 不会 把包 sound.effects 中所有子模块都导入到当前命名空间;该语句只确保导入包 sound.effects (可能还会运行 __init__.py 中的初始化代码),然后,再导入包中定义的名称。这些名称包括 __init__.py 中定义的任何名称(以及显式加载的子模块),还包括之前 import 语句显式加载的包里的子模块。请看以下代码:

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

本例中,执行 from...import 语句时,将把 echosurround 模块导入至当前命名空间,因为,它们是在 sound.effects 包里定义的。(该导入操作在定义了 __all__ 时也有效。)

虽然,可以把模块设计为用 import * 时只导出遵循指定模式的名称,但仍不提倡在生产代码中使用这种做法。

记住,使用 from package import specific_submodule 没有任何问题! 实际上,除了导入模块使用不同包的同名子模块之外,这种方式是推荐用法。

子包参考

包中含有多个子包时(与示例中的 sound 包一样),可以使用绝对导入引用兄弟包中的子模块。例如,要在模块 sound.filters.vocoder 中使用 sound.effects 包的 echo 模块时,可以用 from sound.effects import echo 导入。

还可以用 import 语句的 from module import name 形式执行相对导入。这些导入语句使用前导句点表示相对导入中的当前包和父包。例如,相对于 surround 模块,可以使用:

from . import echo
from .. import formats
from ..filters import equalizer

注意,相对导入基于当前模块名。因为主模块名是 "__main__" ,所以 Python 程序的主模块必须始终使用绝对导入。

多目录中的包

包还支持特殊属性 __path__。该属性初始化为在包的 __init__.py 文件中的代码执行前所在的目录名列表。这个变量可以修改,但这样做会影响将来搜索包中模块和子包的操作。

这个功能虽然不常用,但可用于扩展包中的模块集。

注:

  • 实际上,函数定义也是“可执行”的“语句”;执行模块级函数定义时,函数名将被导入到模块的全局符号表。

6. 输入与输出

更复杂的输出格式

至此,我们已学习了两种写入值的方法:表达式语句print() 函数。第三种方法是使用文件对象的 write() 方法;标准输出文件称为 sys.stdout。详见标准库参考。

对输出格式的控制不只是打印空格分隔的值,还需要更多方式。格式化输出包括以下几种方法。

  • 使用 格式化字符串字面值 ,要在字符串开头的引号/三引号前添加 fF 。在这种字符串中,可以在 {} 字符之间输入引用的变量,或字面值的 Python 表达式。

    >>> year = 2016
    >>> event = 'Referendum'
    >>> f'Results of the {year} {event}'
    'Results of the 2016 Referendum'
  • 字符串的 str.format() 方法需要更多手动操作。该方法也用 {} 标记替换变量的位置,虽然这种方法支持详细的格式化指令,但需要提供格式化信息。

    >>> yes_votes = 42_572_654
    >>> no_votes = 43_132_495
    >>> percentage = yes_votes / (yes_votes + no_votes)
    >>> '{:-9} YES votes  {:2.2%}'.format(yes_votes, percentage)
    ' 42572654 YES votes  49.67%'
  • 最后,还可以用字符串切片和合并操作完成字符串处理操作,创建任何排版布局。字符串类型还支持将字符串按给定列宽进行填充,这些方法也很有用。

如果不需要花哨的输出,只想快速显示变量进行调试,可以用 repr()str() 函数把值转化为字符串。

str() 函数返回供人阅读的值,repr() 则生成适于解释器读取的值(如果没有等效的语法,则强制执行 SyntaxError)。对于没有支持供人阅读展示结果的对象, str() 返回与 repr() 相同的值。一般情况下,数字、列表或字典等结构的值,使用这两个函数输出的表现形式是一样的。字符串有两种不同的表现形式。

示例如下:

>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"

string 模块包含 Template 类,提供了将值替换为字符串的另一种方法。该类使用 $x 占位符,并用字典的值进行替换,但对格式控制的支持比较有限。

格式化字符串字面值

格式化字符串字面值 (简称为 f-字符串)在字符串前加前缀 fF,通过 {expression} 表达式,把 Python 表达式的值添加到字符串内。

格式说明符是可选的,写在表达式后面,可以更好地控制格式化值的方式。下例将 pi 舍入到小数点后三位:

>>> import math
>>> print(f'The value of pi is approximately {math.pi:.3f}.')
The value of pi is approximately 3.142.

':' 后传递整数,为该字段设置最小字符宽度,常用于列对齐:

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
...     print(f'{name:10} ==> {phone:10d}')
...
Sjoerd     ==>       4127
Jack       ==>       4098
Dcab       ==>       7678

还有一些修饰符可以在格式化前转换值。 '!a' 应用 ascii()'!s' 应用 str()'!r' 应用 repr()

>>> animals = 'eels'
>>> print(f'My hovercraft is full of {animals}.')
My hovercraft is full of eels.
>>> print(f'My hovercraft is full of {animals!r}.')
My hovercraft is full of 'eels'.

字符串 format() 方法

str.format() 方法的基本用法如下所示:

>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"

花括号及之内的字符(称为格式字段)被替换为传递给 str.format() 方法的对象。花括号中的数字表示传递给 str.format() 方法的对象所在的位置。

>>> print('{0} and {1}'.format('spam', 'eggs'))
spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam

str.format() 方法中使用关键字参数名引用值。

>>> print('This {food} is {adjective}.'.format(
...       food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.

位置参数和关键字参数可以任意组合:

>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
                                                       other='Georg'))
The story of Bill, Manfred, and Georg.

如果不想分拆较长的格式字符串,最好按名称引用变量进行格式化,不要按位置。这项操作可以通过传递字典,并用方括号 '[]' 访问键来完成。

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
...       'Dcab: {0[Dcab]:d}'.format(table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

也可以用 ‘**‘ 符号,把 table 当作传递的关键字参数。

>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678

与内置函数 vars() 结合使用时,这种方式非常实用,可以返回包含所有局部变量的字典。

例如,下面的代码生成一组整齐的列,包含给定整数及其平方与立方:

>>> for x in range(1, 11):
...     print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

手动格式化字符串

下面是使用手动格式化方式实现的同一个平方和立方的表:

>>> for x in range(1, 11):
...     print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
...     # Note use of 'end' on previous line
...     print(repr(x*x*x).rjust(4))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000

(注意,每列之间的空格是通过使用 print() 添加的:它总在其参数间添加空格。)

字符串对象的 str.rjust() 方法通过在左侧填充空格,对给定宽度字段中的字符串进行右对齐。同类方法还有 str.ljust()str.center() 。这些方法不写入任何内容,只返回一个新字符串,如果输入的字符串太长,它们不会截断字符串,而是原样返回;虽然这种方式会弄乱列布局,但也比另一种方法好,后者在显示值时可能不准确(如果真的想截断字符串,可以使用 x.ljust(n)[:n] 这样的切片操作 。)

另一种方法是 str.zfill() ,该方法在数字字符串左边填充零,且能识别正负号:

>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'

旧式字符串格式化方法

% 运算符(求余符)也可用于字符串格式化。给定 'string' % values,则 string 中的 % 实例会以零个或多个 values 元素替换。此操作被称为字符串插值。例如:

>>> import math
>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.

读写文件

open() 返回 file object,最常用的参数有两个: open(filename, mode)

>>> f = open('workfile', 'w')

第一个实参是文件名字符串。第二个实参是包含描述文件使用方式字符的字符串。mode 的值包括 'r' ,表示文件只能读取;'w' 表示只能写入(现有同名文件会被覆盖);'a' 表示打开文件并追加内容,任何写入的数据会自动添加到文件末尾。'r+' 表示打开文件进行读写。mode 实参是可选的,省略时的默认值为 'r'

通常,文件以 text mode 打开,即,从文件中读取或写入字符串时,都以指定编码方式进行编码。如未指定编码格式,默认值与平台相关 。在 mode 中追加的 'b' 则以 binary mode 打开文件:此时,数据以字节对象的形式进行读写。该模式用于所有不包含文本的文件。

在文本模式下读取文件时,默认把平台特定的行结束符(Unix 上为 \n, Windows 上为 \r\n)转换为 \n。在文本模式下写入数据时,默认把 \n 转换回平台特定结束符。这种操作方式在后台修改文件数据对文本文件来说没有问题,但会破坏 JPEGEXE 等二进制文件中的数据。注意,在读写此类文件时,一定要使用二进制模式。

在处理文件对象时,最好使用 with 关键字。优点是,子句体结束后,文件会正确关闭,即便触发异常也可以。而且,使用 with 相比等效的 try-finally 代码块要简短得多:

>>> with open('workfile') as f:
...     read_data = f.read()
>>> # We can check that the file has been automatically closed.
>>> f.closed
True

如果没有使用 with 关键字,则应调用 f.close() 关闭文件,即可释放文件占用的系统资源。

警告:

调用 f.write() 时,未使用 with 关键字,或未调用 f.close(),即使程序正常退出,也可能 导致 f.write() 的参数没有完全写入磁盘。

通过 with 语句,或调用 f.close() 关闭文件对象后,再次使用该文件对象将会失败。

>>> f.close()
>>> f.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file.

文件对象的方法

本节下文中的例子假定已创建 f 文件对象。

f.read(size) 可用于读取文件内容,它会读取一些数据,并返回字符串(文本模式),或字节串对象(在二进制模式下)。 size 是可选的数值参数。省略 sizesize 为负数时,读取并返回整个文件的内容;文件大小是内存的两倍时,会出现问题。size 取其他值时,读取并返回最多 size 个字符(文本模式)或 size 个字节(二进制模式)。如已到达文件末尾,f.read() 返回空字符串('')。

>>> f.read()
'This is the entire file.\n'
>>> f.read()
''

f.readline() 从文件中读取单行数据;字符串末尾保留换行符(\n),只有在文件不以换行符结尾时,文件的最后一行才会省略换行符。这种方式让返回值清晰明确;只要 f.readline() 返回空字符串,就表示已经到达了文件末尾,空行使用 '\n' 表示,该字符串只包含一个换行符。

>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''

从文件中读取多行时,可以用循环遍历整个文件对象。这种操作能高效利用内存,快速,且代码简单:

>>> for line in f:
...     print(line, end='')
...
This is the first line of the file.
Second line of the file

如需以列表形式读取文件中的所有行,可以用 list(f)f.readlines()

f.write(string)string 的内容写入文件,并返回写入的字符数。

>>> f.write('This is a test\n')
15

写入其他类型的对象前,要先把它们转化为字符串(文本模式)或字节对象(二进制模式):

>>> value = ('the answer', 42)
>>> s = str(value)  # convert the tuple to string
>>> f.write(s)
18

f.tell() 返回整数,给出文件对象在文件中的当前位置,表示为二进制模式下时从文件开始的字节数,以及文本模式下的意义不明的数字。

f.seek(offset, whence) 可以改变文件对象的位置。通过向参考点添加 offset 计算位置;参考点由 whence 参数指定。 whence 值为 0 时,表示从文件开头计算,1 表示使用当前文件位置,2 表示使用文件末尾作为参考点。省略 whence 时,其默认值为 0,即使用文件开头作为参考点。

>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5)      # Go to the 6th byte in the file
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2)  # Go to the 3rd byte before the end
13
>>> f.read(1)
b'd'

在文本文件(模式字符串未使用 b 时打开的文件)中,只允许相对于文件开头搜索(使用 seek(0, 2) 搜索到文件末尾是个例外),唯一有效的 offset 值是能从 f.tell() 中返回的,或 0。其他 offset 值都会产生未定义的行为。

文件对象还支持 isatty()truncate() 等方法,但不常用;文件对象的完整指南详见库参考。

使用 json 保存结构化数据

从文件写入或读取字符串很简单,数字则稍显麻烦,因为 read() 方法只返回字符串,这些字符串必须传递给 int() 这样的函数,接受 '123' 这样的字符串,并返回数字值 123。保存嵌套列表、字典等复杂数据类型时,手动解析和序列化的操作非常复杂。

Python 支持 JSON (JavaScript Object Notation) 这种流行数据交换格式,用户无需没完没了地编写、调试代码,才能把复杂的数据类型保存到文件。json 标准模块采用 Python 数据层次结构,并将之转换为字符串表示形式;这个过程称为 serializing (序列化)。从字符串表示中重建数据称为 deserializing (解序化)。在序列化和解序化之间,表示对象的字符串可能已经存储在文件或数据中,或通过网络连接发送到远方 的机器。

注解

JSON 格式通常用于现代应用程序的数据交换。程序员早已对它耳熟能详,可谓是交互操作的不二之选。

只需一行简单的代码即可查看某个对象的 JSON 字符串表现形式:

>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'

dumps() 函数还有一个变体, dump() ,它只将对象序列化为 text file 。因此,如果 f 是 text file 对象,可以这样做:

json.dump(x, f)

要再次解码对象,如果 f 是已打开、供读取的 text file 对象:

x = json.load(f)

这种简单的序列化技术可以处理列表和字典,但在 JSON 中序列化任意类的实例,则需要付出额外努力。json 模块的参考包含对此的解释。

注:

  • pickle - 封存模块:与 JSON 不同,pickle 是一种允许对复杂 Python 对象进行序列化的协议。因此,它为 Python 所特有,不能用于与其他语言编写的应用程序通信。默认情况下它也是不安全的:如果解序化的数据是由手段高明的攻击者精心设计的,这种不受信任来源的 pickle 数据可以执行任意代码。

7. 错误和异常

句法错误

句法错误又称解析错误,是学习 Python 时最常见的错误:

>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
                   ^
SyntaxError: invalid syntax

解析器会复现出现句法错误的代码行,并用小“箭头”指向行里检测到的第一个错误。错误是由箭头 上方 的 token 触发的(至少是在这里检测出的):本例中,在 print() 函数中检测到错误,因为,在它前面缺少冒号(':') 。错误信息还输出文件名与行号,在使用脚本文件时,就可以知道去哪里查错。

异常

即使语句或表达式使用了正确的语法,执行时仍可能触发错误。执行时检测到的错误称为 异常,异常不一定导致严重的后果:很快我们就能学会如何处理 Python 的异常。大多数异常不会被程序处理,而是显示下列错误信息:

>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "int") to str

错误信息的最后一行说明程序遇到了什么类型的错误。异常有不同的类型,而类型名称会作为错误信息的一部分中打印出来:上述示例中的异常类型依次是:ZeroDivisionErrorNameErrorTypeError。作为异常类型打印的字符串是发生的内置异常的名称。对于所有内置异常都是如此,但对于用户定义的异常则不一定如此(虽然这种规范很有用)。标准的异常类型是内置的标识符(不是保留关键字)。

此行其余部分根据异常类型,结合出错原因,说明错误细节。

错误信息开头用堆栈回溯形式展示发生异常的语境。一般会列出源代码行的堆栈回溯;但不会显示从标准输入读取的行。

内置异常 列出了内置异常及其含义。

异常的处理

可以编写程序处理选定的异常。下例会要求用户一直输入内容,直到输入有效的整数,但允许用户中断程序(使用 Control-C 或操作系统支持的其他操作);注意,用户中断程序会触发 KeyboardInterrupt 异常。

>>> while True:
...     try:
...         x = int(input("Please enter a number: "))
...         break
...     except ValueError:
...         print("Oops!  That was no valid number.  Try again...")
...

try 语句的工作原理如下:

  • 首先,执行 try 子句tryexcept 关键字之间的(多行)语句)。
  • 如果没有触发异常,则跳过 except 子句try 语句执行完毕。
  • 如果在执行 try 子句时发生了异常,则跳过该子句中剩下的部分。 如果异常的类型与 except 关键字后指定的异常相匹配,则会执行 except 子句,然后跳到 try/except 代码块之后继续执行。
  • 如果发生的异常与 except 子句 中指定的异常不匹配,则它会被传递到外部的 try 语句中;如果没有找到处理程序,则它是一个 未处理异常 且执行将终止并输出如上所示的消息。

try 语句可以有多个 except 子句 来为不同的异常指定处理程序。 但最多只有一个处理程序会被执行。 处理程序只处理对应的 try 子句 中发生的异常,而不处理同一 try 语句内其他处理程序中的异常。 except 子句 可以用带圆括号的元组来指定多个异常,例如:

... except (RuntimeError, TypeError, NameError):
...     pass

如果发生的异常与 except 子句中的类是同一个类或是它的基类时,则该类与该异常相兼容(反之则不成立 —- 列出派生类的 except 子句 与基类不兼容)。 例如,下面的代码将依次打印 B, C, D:

class B(Exception):
    pass
class C(B):
    pass
class D(C):
    pass
for cls in [B, C, D]:
    try:
        raise cls()
    except D:
        print("D")
    except C:
        print("C")
    except B:
        print("B")

请注意如果颠倒 except 子句 的顺序(把 except B 放在最前),则会输出 B, B, B —- 即触发了第一个匹配的 except 子句

所有异常都继承自 BaseException,因此它可被用作通配符。 但这种用法要非常谨慎小心,因为它很容易掩盖真正的编程错误! 它还可被用于打印错误消息然后重新引发异常(允许调用者再来处理该异常):

import sys
try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except OSError as err:
    print("OS error: {0}".format(err))
except ValueError:
    print("Could not convert data to an integer.")
except BaseException as err:
    print(f"Unexpected {err=}, {type(err)=}")
    raise

可以选择让最后一个 except 子句省略异常名称,但在此之后异常值必须从 sys.exc_info()[1] 获取。

tryexcept 语句具有可选的 else 子句*,该子句如果存在,它必须放在所有 *except 子句 之后。 它适用于 try 子句 没有引发异常但又必须要执行的代码。 例如:

for arg in sys.argv[1:]:
    try:
        f = open(arg, 'r')
    except OSError:
        print('cannot open', arg)
    else:
        print(arg, 'has', len(f.readlines()), 'lines')
        f.close()

使用 else 子句比向 try 子句添加额外的代码要好,可以避免意外捕获非 tryexcept 语句保护的代码触发的异常。

发生异常时,它可能具有关联值,即异常 参数 。是否需要参数,以及参数的类型取决于异常的类型。

except 子句 可以在异常名称后面指定一个变量。 这个变量会绑定到一个异常实例并将参数存储在 instance.args 中。 为了方便起见,该异常实例定义了 __str__() 以便能直接打印参数而无需引用 .args。 也可以在引发异常之前先实例化一个异常并根据需要向其添加任何属性。:

>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception instance
...     print(inst.args)     # arguments stored in .args
...     print(inst)          # __str__ allows args to be printed directly,
...                          # but may be overridden in exception subclasses
...     x, y = inst.args     # unpack args
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs

如果异常有参数,则它们将作为未处理异常的消息的最后一部分(’详细信息’)打印。

异常处理程序不仅会处理在 try 子句 中发生的异常,还会处理在 try 子句 中调用(包括间接调用)的函数。 例如:

>>> def this_fails():
...     x = 1/0
...
>>> try:
...     this_fails()
... except ZeroDivisionError as err:
...     print('Handling run-time error:', err)
...
Handling run-time error: division by zero

触发异常

raise 语句支持强制触发指定的异常。例如:

>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: HiThere

raise 唯一的参数就是要触发的异常。这个参数必须是异常实例或异常类(派生自 Exception 类)。如果传递的是异常类,将通过调用没有参数的构造函数来隐式实例化:

raise ValueError  # shorthand for 'raise ValueError()'

如果只想判断是否触发了异常,但并不打算处理该异常,则可以使用更简单的 raise 语句重新触发异常:

>>> try:
...     raise NameError('HiThere')
... except NameError:
...     print('An exception flew by!')
...     raise
...
An exception flew by!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
NameError: HiThere

异常链

raise 语句支持可选的 from 子句,该子句用于启用链式异常。 例如:

# exc must be exception instance or None.
raise RuntimeError from exc

转换异常时,这种方式很有用。例如:

>>> def func():
...     raise ConnectionError
...
>>> try:
...     func()
... except ConnectionError as exc:
...     raise RuntimeError('Failed to open database') from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
  File "<stdin>", line 2, in func
ConnectionError
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Failed to open database

异常链会在 exceptfinally 子句内部引发异常时自动生成。 这可以通过使用 from None 这样的写法来禁用:

>>> try:
...     open('database.sqlite')
... except OSError:
...     raise RuntimeError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError

用户自定义异常

程序可以通过创建新的异常类命名自己的异常。不论是以直接还是间接的方式,异常都应从 Exception 类派生。

异常类和其他类一样,可以执行任何操作。但通常会比较简单,只提供让处理异常的程序提取错误信息的一些属性。创建能触发多个不同错误的模块时,一般只为该模块定义异常基类,然后再根据不同的错误条件,创建指定异常类的子类:

class Error(Exception):
    """Base class for exceptions in this module."""
    pass
class InputError(Error):
    """Exception raised for errors in the input.
    Attributes:
        expression -- input expression in which the error occurred
        message -- explanation of the error
    """
    def __init__(self, expression, message):
        self.expression = expression
        self.message = message
class TransitionError(Error):
    """Raised when an operation attempts a state transition that's not
    allowed.
    Attributes:
        previous -- state at beginning of transition
        next -- attempted new state
        message -- explanation of why the specific transition is not allowed
    """
    def __init__(self, previous, next, message):
        self.previous = previous
        self.next = next
        self.message = message

大多数异常命名都以 “Error” 结尾,类似标准异常的命名。

许多标准模块都需要自定义异常,以报告由其定义的函数中出现的错误。

定义清理操作

try 语句还有一个可选子句,用于定义在所有情况下都必须要执行的清理操作。例如:

>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
KeyboardInterrupt
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>

如果存在 finally 子句,则 finally 子句是 try 语句结束前执行的最后一项任务。不论 try 语句是否触发异常,都会执行 finally 子句。以下内容介绍了几种比较复杂的触发异常情景:

  • 如果执行 try 子句期间触发了某个异常,则某个 except 子句应处理该异常。如果该异常没有 except 子句处理,在 finally 子句执行后会被重新触发。
  • exceptelse 子句执行期间也会触发异常。 同样,该异常会在 finally 子句执行之后被重新触发。
  • 如果 finally 子句中包含 breakcontinuereturn 等语句,异常将不会被重新引发。
  • 如果执行 try 语句时遇到 breakcontinuereturn 语句,则 finally 子句在执行 breakcontinuereturn 语句之前执行。
  • 如果 finally 子句中包含 return 语句,则返回值来自 finally 子句的某个 return 语句的返回值,而不是来自 try 子句的 return 语句的返回值。

例如:

>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False

这是一个比较复杂的例子:

>>> def divide(x, y):
...     try:
...         result = x / y
...     except ZeroDivisionError:
...         print("division by zero!")
...     else:
...         print("result is", result)
...     finally:
...         print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'

如上所示,任何情况下都会执行 finally 子句。except 子句不处理两个字符串相除触发的 TypeError,因此会在 finally 子句执行后被重新触发。

在实际应用程序中,finally 子句对于释放外部资源(例如文件或者网络连接)非常有用,无论是否成功使用资源。

预定义的清理操作

某些对象定义了不需要该对象时要执行的标准清理操作。无论使用该对象的操作是否成功,都会执行清理操作。比如,下例要打开一个文件,并输出文件内容:

for line in open("myfile.txt"):
    print(line, end="")

这个代码的问题在于,执行完代码后,文件在一段不确定的时间内处于打开状态。在简单脚本中这没有问题,但对于较大的应用程序来说可能会出问题。with 语句支持以及时、正确的清理的方式使用文件对象:

with open("myfile.txt") as f:
    for line in f:
        print(line, end="")

语句执行完毕后,即使在处理行时遇到问题,都会关闭文件 f。和文件一样,支持预定义清理操作的对象会在文档中指出这一点。

8. 类

类把数据与功能绑定在一起。创建新类就是创建新的对象 类型*,从而创建该类型的新 *实例 。类实例具有多种保持自身状态的属性。类实例还支持(由类定义的)修改自身状态的方法。

和其他编程语言相比,Python 只用了很少的新语法和语义就加入了类。Python 的类是 C++ 和 Modula-3 中类机制的结合体,而且支持所有面向对象编程(OOP)的标准特性:类继承机制支持多个基类,派生类可以覆盖基类的任何方法,类的方法可以调用基类中相同名称的方法。对象可以包含任意数量和类型的数据。和模块一样,类也拥有 Python 天然的动态特性:在运行时创建,创建后也可以修改。

在 C++ 术语中,通常类成员(包括数据成员)是 public ,所有成员函数都是 virtual。 与在 Modula-3 中一样,没有用于从对象的方法中引用对象成员的简写:方法函数在声明时,有一个显示的参数代表本对象,该参数由调用隐式提供。 与 Smalltalk 一样,类本身也是对象。 这为导入和重命名提供了语义。 与 C++ 和 Modula-3 不同,内置类型可以用作基类,供用户扩展。 此外,与 C++ 一样,大多数具有特殊语法(算术运算符,下标等)的内置运算符都可以为类实例而重新定义。

(由于缺乏关于类的公认术语,我会偶尔使用 Smalltalk、C++ 的术语,我还会使用 Modula-3 的术语,因为它的面向对象语义比 C++ 更接近 Python,但估计没几个读者听说过这门语言。)

名称和对象

对象之间相互独立,多个名称(在多个作用域内)可以绑定到同一个对象。 其他语言称之为别名。Python 初学者通常不容易理解这个概念,处理数字、字符串、元组等不可变基本类型时,可以不必理会。 但是,对涉及可变对象,如列表、字典等大多数其他类型的 Python 代码的语义,别名可能会产生意料之外的效果。这样做,通常是为了让程序受益,因为别名在某些方面就像指针。例如,传递对象的代价很小,因为实现只传递一个指针;如果函数修改了作为参数传递的对象,调用者就可以看到更改 —- 无需 Pascal 用两个不同参数的传递机制。

Python 作用域和命名空间

在介绍类之前,我首先要告诉你一些 Python 的作用域规则。类定义对命名空间有一些巧妙的技巧,你需要知道作用域和命名空间如何工作才能完全理解正在发生的事情。顺便说一下,关于这个主题的知识对任何高级 Python 程序员都很有用。

让我们从一些定义开始。

namespace (命名空间)是一个从名字到对象的映射。 当前大部分命名空间都由 Python 字典实现,但一般情况下基本不会去关注它们(除了要面对性能问题时),而且也有可能在将来更改。 下面是几个命名空间的例子:存放内置函数的集合(包含 abs() 这样的函数,和内建的异常等);模块中的全局名称;函数调用中的局部名称。 从某种意义上说,对象的属性集合也是一种命名空间的形式。 关于命名空间的重要一点是,不同命名空间中的名称之间绝对没有关系;例如,两个不同的模块都可以定义一个 maximize 函数而不会产生混淆 —- 模块的用户必须在其前面加上模块名称。

顺便说明一下,我把任何跟在一个点号之后的名称都称为 属性 —- 例如,在表达式 z.real 中,real 是对象 z 的一个属性。按严格的说法,对模块中名称的引用属于属性引用:在表达式 modname.funcname 中,modname 是一个模块对象而 funcname 是它的一个属性。在此情况下在模块的属性和模块中定义的全局名称之间正好存在一个直观的映射:它们共享相同的命名空间!

属性可以是只读或者可写的。如果为后者,那么对属性的赋值是可行的。模块属性是可写的,你可以写 modname.the_answer = 42 。可写的属性同样可以用 del 语句删除。例如, del modname.the_answer 将会从名为 modname 的对象中移除 the_answer 属性。

命名空间在不同时刻被创建,拥有不同的生存期。包含内置名称的命名空间是在 Python 解释器启动时创建的,永远不会被删除。模块的全局命名空间在模块定义被读入时创建;通常,模块命名空间也会持续到解释器退出。被解释器的顶层调用执行的语句,从一个脚本文件读取或交互式地读取,被认为是 __main__ 模块调用的一部分,因此它们拥有自己的全局命名空间。(内置名称实际上也存在于一个模块中;这个模块被称作 builtins 。)

一个函数的本地命名空间在这个函数被调用时创建,并在函数返回或抛出一个不在函数内部处理的错误时被删除。(事实上,比起描述到底发生了什么,忘掉它更好。)当然,每次递归调用都会有它自己的本地命名空间。

一个 作用域 是一个命名空间可直接访问的 Python 程序的文本区域。 这里的 “可直接访问” 意味着对名称的非限定引用会尝试在命名空间中查找名称。

虽然作用域是静态地确定的,但它们会被动态地使用。 在执行期间的任何时刻,会有 3 或 4 个命名空间可被直接访问的嵌套作用域:

  • 最先搜索的最内部作用域包含局部名称
  • 从最近的封闭作用域开始搜索的任何封闭函数的作用域包含非局部名称,也包括非全局名称
  • 倒数第二个作用域包含当前模块的全局名称
  • 最外面的作用域(最后搜索)是包含内置名称的命名空间

如果一个名称被声明为全局变量,则所有引用和赋值将直接指向包含该模块的全局名称的中间作用域。 要重新绑定在最内层作用域以外找到的变量,可以使用 nonlocal 语句声明为非本地变量。 如果没有被声明为非本地变量,这些变量将是只读的(尝试写入这样的变量只会在最内层作用域中创建一个 新的 局部变量,而同名的外部变量保持不变)。

通常,当前局部作用域将(按字面文本)引用当前函数的局部名称。 在函数以外,局部作用域将引用与全局作用域相一致的命名空间:模块的命名空间。 类定义将在局部命名空间内再放置另一个命名空间。

重要的是应该意识到作用域是按字面文本来确定的:在一个模块内定义的函数的全局作用域就是该模块的命名空间,无论该函数从什么地方或以什么别名被调用。 另一方面,实际的名称搜索是在运行时动态完成的 —- 但是,Python 正在朝着“编译时静态名称解析”的方向发展,因此不要过于依赖动态名称解析! (事实上,局部变量已经是被静态确定了。)

Python 的一个特殊规定是这样的 — 如果不存在生效的 globalnonlocal 语句 — 则对名称的赋值总是会进入最内层作用域。 赋值不会复制数据 —- 它们只是将名称绑定到对象。 删除也是如此:语句 del x 会从局部作用域所引用的命名空间中移除对 x 的绑定。 事实上,所有引入新名称的操作都是使用局部作用域:特别地,import 语句和函数定义会在局部作用域中绑定模块或函数名称。

global 语句可被用来表明特定变量生存于全局作用域并且应当在其中被重新绑定;nonlocal 语句表明特定变量生存于外层作用域中并且应当在其中被重新绑定。

作用域和命名空间示例

这个例子演示了如何引用不同作用域和名称空间,以及 globalnonlocal 会如何影响变量绑定:

def scope_test():
    def do_local():
        spam = "local spam"
    def do_nonlocal():
        nonlocal spam
        spam = "nonlocal spam"
    def do_global():
        global spam
        spam = "global spam"
    spam = "test spam"
    do_local()
    print("After local assignment:", spam)
    do_nonlocal()
    print("After nonlocal assignment:", spam)
    do_global()
    print("After global assignment:", spam)
scope_test()
print("In global scope:", spam)

示例代码的输出是:

After local assignment: test spam
After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam

请注意 局部 赋值(这是默认状态)不会改变 scope_testspam 的绑定。 nonlocal 赋值会改变 scope_testspam 的绑定,而 global 赋值会改变模块层级的绑定。

您还可以发现在 global 赋值之前没有 spam 的绑定。

初探类

类引入了一些新语法,三种新对象类型和一些新语义。

类定义语法

最简单的类定义看起来像这样:

class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>

类定义与函数定义 (def 语句) 一样必须被执行才会起作用。 (你可以尝试将类定义放在 if 语句的一个分支或是函数的内部。)

在实践中,类定义内的语句通常都是函数定义,但也允许有其他语句,有时还很有用 —- 我们会稍后再回来说明这个问题。 在类内部的函数定义通常具有一种特别形式的参数列表,这是方法调用的约定规范所指明的 —- 这个问题也将在稍后再说明。

当进入类定义时,将创建一个新的命名空间,并将其用作局部作用域 —- 因此,所有对局部变量的赋值都是在这个新命名空间之内。 特别的,函数定义会绑定到这里的新函数名称。

当(从结尾处)正常离开类定义时,将创建一个 类对象。 这基本上是一个包围在类定义所创建命名空间内容周围的包装器;我们将在下一节了解有关类对象的更多信息。 原始的(在进入类定义之前起作用的)局部作用域将重新生效,类对象将在这里被绑定到类定义头所给出的类名称 (在这个示例中为 ClassName)。

Class 对象

类对象支持两种操作:属性引用和实例化。

属性引用 使用 Python 中所有属性引用所使用的标准语法: obj.name。 有效的属性名称是类对象被创建时存在于类命名空间中的所有名称。 因此,如果类定义是这样的:

class MyClass:
    """A simple example class"""
    i = 12345
    def f(self):
        return 'hello world'

那么 MyClass.iMyClass.f 就是有效的属性引用,将分别返回一个整数和一个函数对象。 类属性也可以被赋值,因此可以通过赋值来更改 MyClass.i 的值。 __doc__ 也是一个有效的属性,将返回所属类的文档字符串: "A simple example class"

类的 实例化 使用函数表示法。 可以把类对象视为是返回该类的一个新实例的不带参数的函数。 举例来说(假设使用上述的类):

x = MyClass()

创建类的新 实例 并将此对象分配给局部变量 x

实例化操作(“调用”类对象)会创建一个空对象。 许多类喜欢创建带有特定初始状态的自定义实例。 为此类定义可能包含一个名为 __init__() 的特殊方法,就像这样:

def __init__(self):
    self.data = []

当一个类定义了 __init__() 方法时,类的实例化操作会自动为新创建的类实例发起调用 __init__()。 因此在这个示例中,可以通过以下语句获得一个经初始化的新实例:

x = MyClass()

当然,__init__() 方法还可以有额外参数以实现更高灵活性。 在这种情况下,提供给类实例化运算符的参数将被传递给 __init__()。 例如,:

>>> class Complex:
...     def __init__(self, realpart, imagpart):
...         self.r = realpart
...         self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)

实例对象

现在我们能用实例对象做什么? 实例对象所能理解的唯一操作是属性引用。 有两种有效的属性名称:数据属性和方法。

数据属性 对应于 Smalltalk 中的“实例变量”,以及 C++ 中的“数据成员”。 数据属性不需要声明;像局部变量一样,它们将在第一次被赋值时产生。 例如,如果 x 是上面创建的 MyClass 的实例,则以下代码段将打印数值 16,且不保留任何追踪信息:

x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print(x.counter)
del x.counter

另一类实例属性引用称为 方法。 方法是“从属于”对象的函数。 (在 Python 中,方法这个术语并不是类实例所特有的:其他对象也可以有方法。 例如,列表对象具有 append, insert, remove, sort 等方法。 然而,在以下讨论中,我们使用方法一词将专指类实例对象的方法,除非另外显式地说明。)

实例对象的有效方法名称依赖于其所属的类。 根据定义,一个类中所有是函数对象的属性都是定义了其实例的相应方法。 因此在我们的示例中,x.f 是有效的方法引用,因为 MyClass.f 是一个函数,而 x.i 不是方法,因为 MyClass.i 不是函数。 但是 x.fMyClass.f 并不是一回事 —- 它是一个 方法对象,不是函数对象。

方法对象

通常,方法在绑定后立即被调用:

x.f()

MyClass 示例中,这将返回字符串 'hello world'。 但是,立即调用一个方法并不是必须的: x.f 是一个方法对象,它可以被保存起来以后再调用。 例如:

xf = x.f
while True:
    print(xf())

将持续打印 hello world,直到结束。

当一个方法被调用时到底发生了什么? 你可能已经注意到上面调用 x.f() 时并没有带参数,虽然 f() 的函数定义指定了一个参数。 这个参数发生了什么事? 当不带参数地调用一个需要参数的函数时 Python 肯定会引发异常 —- 即使参数实际未被使用…

实际上,你可能已经猜到了答案:方法的特殊之处就在于实例对象会作为函数的第一个参数被传入。 在我们的示例中,调用 x.f() 其实就相当于 MyClass.f(x)。 总之,调用一个具有 n 个参数的方法就相当于调用再多一个参数的对应函数,这个参数值为方法所属实例对象,位置在其他参数之前。

如果你仍然无法理解方法的运作原理,那么查看实现细节可能会弄清楚问题。 当一个实例的非数据属性被引用时,将搜索实例所属的类。 如果被引用的属性名称表示一个有效的类属性中的函数对象,会通过打包(指向)查找到的实例对象和函数对象到一个抽象对象的方式来创建方法对象:这个抽象对象就是方法对象。 当附带参数列表调用方法对象时,将基于实例对象和参数列表构建一个新的参数列表,并使用这个新参数列表调用相应的函数对象。

类和实例变量

一般来说,实例变量用于每个实例的唯一数据,而类变量用于类的所有实例共享的属性和方法:

class Dog:
    kind = 'canine'         # class variable shared by all instances
    def __init__(self, name):
        self.name = name    # instance variable unique to each instance
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind                  # shared by all dogs
'canine'
>>> e.kind                  # shared by all dogs
'canine'
>>> d.name                  # unique to d
'Fido'
>>> e.name                  # unique to e
'Buddy'

正如 名称和对象 中已讨论过的,共享数据可能在涉及 mutable 对象例如列表和字典的时候导致令人惊讶的结果。 例如以下代码中的 tricks 列表不应该被用作类变量,因为所有的 Dog 实例将只共享一个单独的列表:

class Dog:
    tricks = []             # mistaken use of a class variable
    def __init__(self, name):
        self.name = name
    def add_trick(self, trick):
        self.tricks.append(trick)
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks                # unexpectedly shared by all dogs
['roll over', 'play dead']

正确的类设计应该使用实例变量:

class Dog:
    def __init__(self, name):
        self.name = name
        self.tricks = []    # creates a new empty list for each dog
    def add_trick(self, trick):
        self.tricks.append(trick)
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']

补充说明

如果同样的属性名称同时出现在实例和类中,则属性查找会优先选择实例:

>>> class Warehouse:
        purpose = 'storage'
        region = 'west'
>>> w1 = Warehouse()
>>> print(w1.purpose, w1.region)
storage west
>>> w2 = Warehouse()
>>> w2.region = 'east'
>>> print(w2.purpose, w2.region)
storage east

数据属性可以被方法以及一个对象的普通用户(“客户端”)所引用。 换句话说,类不能用于实现纯抽象数据类型。 实际上,在 Python 中没有任何东西能强制隐藏数据 —- 它是完全基于约定的。 (而在另一方面,用 C 语言编写的 Python 实现则可以完全隐藏实现细节,并在必要时控制对象的访问;此特性可以通过用 C 编写 Python 扩展来使用。)

客户端应当谨慎地使用数据属性 —- 客户端可能通过直接操作数据属性的方式破坏由方法所维护的固定变量。 请注意客户端可以向一个实例对象添加他们自己的数据属性而不会影响方法的可用性,只要保证避免名称冲突 —- 再次提醒,在此使用命名约定可以省去许多令人头痛的麻烦。

在方法内部引用数据属性(或其他方法!)并没有简便方式。 我发现这实际上提升了方法的可读性:当浏览一个方法代码时,不会存在混淆局部变量和实例变量的机会。

方法的第一个参数常常被命名为 self。 这也不过就是一个约定: self 这一名称在 Python 中绝对没有特殊含义。 但是要注意,不遵循此约定会使得你的代码对其他 Python 程序员来说缺乏可读性,而且也可以想像一个 类浏览器 程序的编写可能会依赖于这样的约定。

任何一个作为类属性的函数都为该类的实例定义了一个相应方法。 函数定义的文本并非必须包含于类定义之内:将一个函数对象赋值给一个局部变量也是可以的。 例如:

# Function defined outside the class
def f1(self, x, y):
    return min(x, x+y)
class C:
    f = f1
    def g(self):
        return 'hello world'
    h = g

现在 f, gh 都是 C 类的引用函数对象的属性,因而它们就都是 C 的实例的方法 —- 其中 h 完全等同于 g。 但请注意,本示例的做法通常只会令程序的阅读者感到迷惑。

方法可以通过使用 self 参数的方法属性调用其他方法:

class Bag:
    def __init__(self):
        self.data = []
    def add(self, x):
        self.data.append(x)
    def addtwice(self, x):
        self.add(x)
        self.add(x)

方法可以通过与普通函数相同的方式引用全局名称。 与方法相关联的全局作用域就是包含其定义的模块。 (类永远不会被作为全局作用域。) 虽然我们很少会有充分的理由在方法中使用全局作用域,但全局作用域存在许多合理的使用场景:举个例子,导入到全局作用域的函数和模块可以被方法所使用,在其中定义的函数和类也一样。 通常,包含该方法的类本身是在全局作用域中定义的,而在下一节中我们将会发现为何方法需要引用其所属类的很好的理由。

每个值都是一个对象,因此具有 (也称为 类型),并存储为 object.__class__

继承

当然,如果不支持继承,语言特性就不值得称为“类”。派生类定义的语法如下所示:

class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>

名称 BaseClassName 必须定义于包含派生类定义的作用域中。 也允许用其他任意表达式代替基类名称所在的位置。 这有时也可能会用得上,例如,当基类定义在另一个模块中的时候:

class DerivedClassName(modname.BaseClassName):

派生类定义的执行过程与基类相同。 当构造类对象时,基类会被记住。 此信息将被用来解析属性引用:如果请求的属性在类中找不到,搜索将转往基类中进行查找。 如果基类本身也派生自其他某个类,则此规则将被递归地应用。

派生类的实例化没有任何特殊之处: DerivedClassName() 会创建该类的一个新实例。 方法引用将按以下方式解析:搜索相应的类属性,如有必要将按基类继承链逐步向下查找,如果产生了一个函数对象则方法引用就生效。

派生类可能会重写其基类的方法。 因为方法在调用同一对象的其他方法时没有特殊权限,所以调用同一基类中定义的另一方法的基类方法最终可能会调用覆盖它的派生类的方法。 (对 C++ 程序员的提示:Python 中所有的方法实际上都是 virtual 方法。)

在派生类中的重载方法实际上可能想要扩展而非简单地替换同名的基类方法。 有一种方式可以简单地直接调用基类方法:即调用 BaseClassName.methodname(self, arguments)。 有时这对客户端来说也是有用的。 (请注意仅当此基类可在全局作用域中以 BaseClassName 的名称被访问时方可使用此方式。)

Python有两个内置函数可被用于继承机制:

  • 使用 isinstance() 来检查一个实例的类型: isinstance(obj, int) 仅会在 obj.__class__int 或某个派生自 int 的类时为 True
  • 使用 issubclass() 来检查类的继承关系: issubclass(bool, int)True,因为 boolint 的子类。 但是,issubclass(float, int)False,因为 float 不是 int 的子类。

多重继承

Python 也支持一种多重继承。 带有多个基类的类定义语句如下所示:

class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>

对于多数应用来说,在最简单的情况下,你可以认为搜索从父类所继承属性的操作是深度优先、从左至右的,当层次结构中存在重叠时不会在同一个类中搜索两次。 因此,如果某一属性在 DerivedClassName 中未找到,则会到 Base1 中搜索它,然后(递归地)到 Base1 的基类中搜索,如果在那里未找到,再到 Base2 中搜索,依此类推。

真实情况比这个更复杂一些;方法解析顺序会动态改变以支持对 super() 的协同调用。 这种方式在某些其他多重继承型语言中被称为后续方法调用,它比单继承型语言中的 super 调用更强大。

动态改变顺序是有必要的,因为所有多重继承的情况都会显示出一个或更多的菱形关联(即至少有一个父类可通过多条路径被最底层类所访问)。 例如,所有类都是继承自 object,因此任何多重继承的情况都提供了一条以上的路径可以通向 object。 为了确保基类不会被访问一次以上,动态算法会用一种特殊方式将搜索顺序线性化, 保留每个类所指定的从左至右的顺序,只调用每个父类一次,并且保持单调(即一个类可以被子类化而不影响其父类的优先顺序)。 总而言之,这些特性使得设计具有多重继承的可靠且可扩展的类成为可能。 要了解更多细节,请参阅 https://www.python.org/download/releases/2.3/mro/。

私有变量

那种仅限从一个对象内部访问的“私有”实例变量在 Python 中并不存在。 但是,大多数 Python 代码都遵循这样一个约定:带有一个下划线的名称 (例如 _spam) 应该被当作是 API 的非公有部分 (无论它是函数、方法或是数据成员)。 这应当被视为一个实现细节,可能不经通知即加以改变。

由于存在对于类私有成员的有效使用场景(例如避免名称与子类所定义的名称相冲突),因此存在对此种机制的有限支持,称为 名称改写。 任何形式为 __spam 的标识符(至少带有两个前缀下划线,至多一个后缀下划线)的文本将被替换为 _classname__spam,其中 classname 为去除了前缀下划线的当前类名称。 这种改写不考虑标识符的句法位置,只要它出现在类定义内部就会进行。

名称改写有助于让子类重载方法而不破坏类内方法调用。例如:

class Mapping:
    def __init__(self, iterable):
        self.items_list = []
        self.__update(iterable)
    def update(self, iterable):
        for item in iterable:
            self.items_list.append(item)
    __update = update   # private copy of original update() method
class MappingSubclass(Mapping):
    def update(self, keys, values):
        # provides new signature for update()
        # but does not break __init__()
        for item in zip(keys, values):
            self.items_list.append(item)

上面的示例即使在 MappingSubclass 引入了一个 __update 标识符的情况下也不会出错,因为它会在 Mapping 类中被替换为 _Mapping__update 而在 MappingSubclass 类中被替换为 _MappingSubclass__update

请注意,改写规则的设计主要是为了避免意外冲突;访问或修改被视为私有的变量仍然是可能的。这在特殊情况下甚至会很有用,例如在调试器中。

请注意传递给 exec()eval() 的代码不会将发起调用类的类名视作当前类;这类似于 global 语句的效果,因此这种效果仅限于同时经过字节码编译的代码。 同样的限制也适用于 getattr(), setattr()delattr(),以及对于 __dict__ 的直接引用。

杂项说明

有时会需要使用类似于 Pascal 的“record”或 C 的“struct”这样的数据类型,将一些命名数据项捆绑在一起。 这种情况适合定义一个空类:

class Employee:
    pass
john = Employee()  # Create an empty employee record
# Fill the fields of the record
john.name = 'John Doe'
john.dept = 'computer lab'
john.salary = 1000

一段需要特定抽象数据类型的 Python 代码往往可以被传入一个模拟了该数据类型的方法的类作为替代。 例如,如果你有一个基于文件对象来格式化某些数据的函数,你可以定义一个带有 read()readline() 方法从字符串缓存获取数据的类,并将其作为参数传入。

实例方法对象也具有属性: m.__self__ 就是带有 m() 方法的实例对象,而 m.__func__ 则是该方法所对应的函数对象。

迭代器

到目前为止,您可能已经注意到大多数容器对象都可以使用 for 语句:

for element in [1, 2, 3]:
    print(element)
for element in (1, 2, 3):
    print(element)
for key in {'one':1, 'two':2}:
    print(key)
for char in "123":
    print(char)
for line in open("myfile.txt"):
    print(line, end='')

这种访问风格清晰、简洁又方便。 迭代器的使用非常普遍并使得 Python 成为一个统一的整体。 在幕后,for 语句会在容器对象上调用 iter()。 该函数返回一个定义了 __next__() 方法的迭代器对象,此方法将逐一访问容器中的元素。 当元素用尽时,__next__() 将引发 StopIteration 异常来通知终止 for 循环。 你可以使用 next() 内置函数来调用 __next__() 方法;这个例子显示了它的运作方式:

>>> s = 'abc'
>>> it = iter(s)
>>> it
<iterator object at 0x00A1DB50>
>>> next(it)
'a'
>>> next(it)
'b'
>>> next(it)
'c'
>>> next(it)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    next(it)
StopIteration

看过迭代器协议的幕后机制,给你的类添加迭代器行为就很容易了。 定义一个 __iter__() 方法来返回一个带有 __next__() 方法的对象。 如果类已定义了 __next__(),则 __iter__() 可以简单地返回 self:

class Reverse:
    """Iterator for looping over a sequence backwards."""
    def __init__(self, data):
        self.data = data
        self.index = len(data)
    def __iter__(self):
        return self
    def __next__(self):
        if self.index == 0:
            raise StopIteration
        self.index = self.index - 1
        return self.data[self.index]
>>> rev = Reverse('spam')
>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
...     print(char)
...
m
a
p
s

生成器

生成器 是一个用于创建迭代器的简单而强大的工具。 它们的写法类似于标准的函数,但当它们要返回数据时会使用 yield 语句。 每次在生成器上调用 next() 时,它会从上次离开的位置恢复执行(它会记住上次执行语句时的所有数据值)。 一个显示如何非常容易地创建生成器的示例如下:

def reverse(data):
    for index in range(len(data)-1, -1, -1):
        yield data[index]
>>> for char in reverse('golf'):
...     print(char)
...
f
l
o
g

可以用生成器来完成的操作同样可以用前一节所描述的基于类的迭代器来完成。 但生成器的写法更为紧凑,因为它会自动创建 __iter__()__next__() 方法。

另一个关键特性在于局部变量和执行状态会在每次调用之间自动保存。 这使得该函数相比使用 self.indexself.data 这种实例变量的方式更易编写且更为清晰。

除了会自动创建方法和保存程序状态,当生成器终结时,它们还会自动引发 StopIteration。 这些特性结合在一起,使得创建迭代器能与编写常规函数一样容易。

生成器表达式

某些简单的生成器可以写成简洁的表达式代码,所用语法类似列表推导式,但外层为圆括号而非方括号。 这种表达式被设计用于生成器将立即被外层函数所使用的情况。 生成器表达式相比完整的生成器更紧凑但较不灵活,相比等效的列表推导式则更为节省内存。

示例:

>>> sum(i*i for i in range(10))                 # sum of squares
285
>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec))         # dot product
260
>>> unique_words = set(word for line in page  for word in line.split())
>>> valedictorian = max((student.gpa, student.name) for student in graduates)
>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']

注:

  • 存在一个例外。 模块对象有一个秘密的只读属性 __dict__,它返回用于实现模块命名空间的字典;__dict__ 是属性但不是全局名称。 显然,使用这个将违反命名空间实现的抽象,应当仅被用于事后调试器之类的场合。

9. 标准库简介

操作系统接口

os 模块提供了许多与操作系统交互的函数:

>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python310'
>>> os.chdir('/server/accesslogs')   # Change current working directory
>>> os.system('mkdir today')   # Run the command mkdir in the system shell
0

一定要使用 import os 而不是 from os import * 。这将避免内建的 open() 函数被 os.open() 隐式替换掉,因为它们的使用方式大不相同。

内置的 dir()help() 函数可用作交互式辅助工具,用于处理大型模块,如 os:

>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>

对于日常文件和目录管理任务, shutil 模块提供了更易于使用的更高级别的接口:

>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'

文件通配符

glob 模块提供了一个在目录中使用通配符搜索创建文件列表的函数:

>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']

命令行参数

通用实用程序脚本通常需要处理命令行参数。这些参数作为列表存储在 sys 模块的 argv 属性中。例如,以下输出来自在命令行运行 python demo.py one two three

>>> import sys
>>> print(sys.argv)
['demo.py', 'one', 'two', 'three']

argparse 模块提供了一种更复杂的机制来处理命令行参数。 以下脚本可提取一个或多个文件名,并可选择要显示的行数:

import argparse
parser = argparse.ArgumentParser(prog = 'top',
    description = 'Show top lines from each file')
parser.add_argument('filenames', nargs='+')
parser.add_argument('-l', '--lines', type=int, default=10)
args = parser.parse_args()
print(args)

当在通过 python top.py --lines=5 alpha.txt beta.txt 在命令行运行时,该脚本会将 args.lines 设为 5 并将 args.filenames 设为 ['alpha.txt', 'beta.txt']

错误输出重定向和程序终止

sys 模块还具有 stdinstdoutstderr 的属性。后者对于发出警告和错误消息非常有用,即使在 stdout 被重定向后也可以看到它们:

>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one

终止脚本的最直接方法是使用 sys.exit()

字符串模式匹配

re 模块为高级字符串处理提供正则表达式工具。对于复杂的匹配和操作,正则表达式提供简洁,优化的解决方案:

>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'

当只需要简单的功能时,首选字符串方法因为它们更容易阅读和调试:

>>> 'tea for too'.replace('too', 'two')
'tea for two'

数学

math 模块提供对浮点数学的底层C库函数的访问:

>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0

random 模块提供了进行随机选择的工具:

>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10)   # sampling without replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # random float
0.17970987693706186
>>> random.randrange(6)    # random integer chosen from range(6)
4

statistics 模块计算数值数据的基本统计属性(均值,中位数,方差等):

>>> import statistics
>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> statistics.mean(data)
1.6071428571428572
>>> statistics.median(data)
1.25
>>> statistics.variance(data)
1.3720238095238095

SciPy项目 https://scipy.org有许多其他模块用于数值计算。

互联网访问

有许多模块可用于访问互联网和处理互联网协议。其中两个最简单的 urllib.request 用于从URL检索数据,以及 smtplib 用于发送邮件:

>>> from urllib.request import urlopen
>>> with urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl') as response:
...     for line in response:
...         line = line.decode('utf-8')  # Decoding the binary data to text.
...         if 'EST' in line or 'EDT' in line:  # look for Eastern Time
...             print(line)
<BR>Nov. 25, 09:43:32 PM EST
>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
... """To: jcaesar@example.org
... From: soothsayer@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()

(请注意,第二个示例需要在localhost上运行的邮件服务器。)

日期和时间

datetime 模块提供了以简单和复杂的方式操作日期和时间的类。虽然支持日期和时间算法,但实现的重点是有效的成员提取以进行输出格式化和操作。该模块还支持可感知时区的对象。

>>> # dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
>>> # dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368

数据压缩

常见的数据存档和压缩格式由模块直接支持,包括:zlib, gzip, bz2, lzma, zipfiletarfile。:

>>> import zlib
>>> s = b'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
b'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979

性能测量

一些Python用户对了解同一问题的不同方法的相对性能产生了浓厚的兴趣。 Python提供了一种可以立即回答这些问题的测量工具。

例如,元组封包和拆包功能相比传统的交换参数可能更具吸引力。timeit 模块可以快速演示在运行效率方面一定的优势:

>>> from timeit import Timer
>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791

timeit 的精细粒度级别相反, profilepstats 模块提供了用于在较大的代码块中识别时间关键部分的工具。

质量控制

开发高质量软件的一种方法是在开发过程中为每个函数编写测试,并在开发过程中经常运行这些测试。

doctest 模块提供了一个工具,用于扫描模块并验证程序文档字符串中嵌入的测试。测试构造就像将典型调用及其结果剪切并粘贴到文档字符串一样简单。这通过向用户提供示例来改进文档,并且它允许doctest模块确保代码保持对文档的真实:

def average(values):
    """Computes the arithmetic mean of a list of numbers.
    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)
import doctest
doctest.testmod()   # automatically validate the embedded tests

unittest 模块不像 doctest 模块那样易于使用,但它允许在一个单独的文件中维护更全面的测试集:

import unittest
class TestStatisticalFunctions(unittest.TestCase):
    def test_average(self):
        self.assertEqual(average([20, 30, 70]), 40.0)
        self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
        with self.assertRaises(ZeroDivisionError):
            average([])
        with self.assertRaises(TypeError):
            average(20, 30, 70)
unittest.main()  # Calling from the command line invokes all tests

自带电池

Python有“自带电池”的理念。通过其包的复杂和强大功能可以最好地看到这一点。例如:

  • xmlrpc.clientxmlrpc.server 模块使得实现远程过程调用变成了小菜一碟。 尽管存在于模块名称中,但用户不需要直接了解或处理 XML。
  • email 包是一个用于管理电子邮件的库,包括MIME和其他符合 RFC 2822 规范的邮件文档。与 smtplibpoplib 不同(它们实际上做的是发送和接收消息),电子邮件包提供完整的工具集,用于构建或解码复杂的消息结构(包括附件)以及实现互联网编码和标头协议。
  • json 包为解析这种流行的数据交换格式提供了强大的支持。 csv 模块支持以逗号分隔值格式直接读取和写入文件,这种格式通常为数据库和电子表格所支持。 XML 处理由 xml.etree.ElementTreexml.domxml.sax 包支持。这些模块和软件包共同大大简化了 Python 应用程序和其他工具之间的数据交换。
  • sqlite3 模块是 SQLite 数据库库的包装器,提供了一个可以使用稍微非标准的 SQL 语法更新和访问的持久数据库。
  • 国际化由许多模块支持,包括 gettextlocale ,以及 codecs 包。

格式化输出

reprlib 模块提供了一个定制化版本的 repr() 函数,用于缩略显示大型或深层嵌套的容器对象:

>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"{'a', 'c', 'd', 'e', 'f', 'g', ...}"

pprint 模块提供了更加复杂的打印控制,其输出的内置对象和用户自定义对象能够被解释器直接读取。当输出结果过长而需要折行时,“美化输出机制”会添加换行符和缩进,以更清楚地展示数据结构:

>>> import pprint
>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
...     'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
   'white',
   ['green', 'red']],
  [['magenta', 'yellow'],
   'blue']]]

textwrap 模块能够格式化文本段落,以适应给定的屏幕宽度:

>>> import textwrap
>>> doc = """The wrap() method is just like fill() except that it returns
... a list of strings instead of one big string with newlines to separate
... the wrapped lines."""
...
>>> print(textwrap.fill(doc, width=40))
The wrap() method is just like fill()
except that it returns a list of strings
instead of one big string with newlines
to separate the wrapped lines.

locale 模块处理与特定地域文化相关的数据格式。locale 模块的 format 函数包含一个 grouping 属性,可直接将数字格式化为带有组分隔符的样式:

>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv()          # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
...                      conv['frac_digits'], x), grouping=True)
'$1,234,567.80'

模板

string 模块包含一个通用的 Template 类,具有适用于最终用户的简化语法。它允许用户在不更改应用逻辑的情况下定制自己的应用。

上述格式化操作是通过占位符实现的,占位符由 $ 加上合法的 Python 标识符(只能包含字母、数字和下划线)构成。一旦使用花括号将占位符括起来,就可以在后面直接跟上更多的字母和数字而无需空格分割。$$ 将被转义成单个字符 $:

>>> from string import Template
>>> t = Template('${village}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'

如果在字典或关键字参数中未提供某个占位符的值,那么 substitute() 方法将抛出 KeyError。对于邮件合并类型的应用,用户提供的数据有可能是不完整的,此时使用 safe_substitute() 方法更加合适 —— 如果数据缺失,它会直接将占位符原样保留。

>>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
  ...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'

Template 的子类可以自定义分隔符。例如,以下是某个照片浏览器的批量重命名功能,采用了百分号作为日期、照片序号和照片格式的占位符:

>>> import time, os.path
>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
...     delimiter = '%'
>>> fmt = input('Enter rename style (%d-date %n-seqnum %f-format):  ')
Enter rename style (%d-date %n-seqnum %f-format):  Ashley_%n%f
>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
...     base, ext = os.path.splitext(filename)
...     newname = t.substitute(d=date, n=i, f=ext)
...     print('{0} --> {1}'.format(filename, newname))
img_1074.jpg --> Ashley_0.jpg
img_1076.jpg --> Ashley_1.jpg
img_1077.jpg --> Ashley_2.jpg

模板的另一个应用是将程序逻辑与多样的格式化输出细节分离开来。这使得对 XML 文件、纯文本报表和 HTML 网络报表使用自定义模板成为可能。

使用二进制数据记录格式

struct 模块提供了 pack()unpack() 函数,用于处理不定长度的二进制记录格式。下面的例子展示了在不使用 zipfile 模块的情况下,如何循环遍历一个 ZIP 文件的所有头信息。Pack 代码 "H""I" 分别代表两字节和四字节无符号整数。"<" 代表它们是标准尺寸的小端字节序:

import struct
with open('myfile.zip', 'rb') as f:
    data = f.read()
start = 0
for i in range(3):                      # show the first 3 file headers
    start += 14
    fields = struct.unpack('<IIIHH', data[start:start+16])
    crc32, comp_size, uncomp_size, filenamesize, extra_size = fields
    start += 16
    filename = data[start:start+filenamesize]
    start += filenamesize
    extra = data[start:start+extra_size]
    print(filename, hex(crc32), comp_size, uncomp_size)
    start += extra_size + comp_size     # skip to the next header

多线程

线程是一种对于非顺序依赖的多个任务进行解耦的技术。多线程可以提高应用的响应效率,当接收用户输入的同时,保持其他任务在后台运行。一个有关的应用场景是,将 I/O 和计算运行在两个并行的线程中。

以下代码展示了高阶的 threading 模块如何在后台运行任务,且不影响主程序的继续运行:

import threading, zipfile
class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        threading.Thread.__init__(self)
        self.infile = infile
        self.outfile = outfile
    def run(self):
        f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
        f.write(self.infile)
        f.close()
        print('Finished background zip of:', self.infile)
background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print('The main program continues to run in foreground.')
background.join()    # Wait for the background task to finish
print('Main program waited until background was done.')

多线程应用面临的主要挑战是,相互协调的多个线程之间需要共享数据或其他资源。为此,threading 模块提供了多个同步操作原语,包括线程锁、事件、条件变量和信号量。

尽管这些工具非常强大,但微小的设计错误却可以导致一些难以复现的问题。因此,实现多任务协作的首选方法是将所有对资源的请求集中到一个线程中,然后使用 queue 模块向该线程供应来自其他线程的请求。 应用程序使用 Queue 对象进行线程间通信和协调,更易于设计,更易读,更可靠。

日志记录

logging 模块提供功能齐全且灵活的日志记录系统。在最简单的情况下,日志消息被发送到文件或 sys.stderr

import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')

这会产生以下输出:

WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down

默认情况下,informational 和 debugging 消息被压制,输出会发送到标准错误流。其他输出选项包括将消息转发到电子邮件,数据报,套接字或 HTTP 服务器。新的过滤器可以根据消息优先级选择不同的路由方式:DEBUGINFOWARNINGERROR,和 CRITICAL

日志系统可以直接从 Python 配置,也可以从用户配置文件加载,以便自定义日志记录而无需更改应用程序。

弱引用

Python 会自动进行内存管理(对大多数对象进行引用计数并使用 garbage collection 来清除循环引用)。 当某个对象的最后一个引用被移除后不久就会释放其所占用的内存。

此方式对大多数应用来说都适用,但偶尔也必须在对象持续被其他对象所使用时跟踪它们。 不幸的是,跟踪它们将创建一个会令其永久化的引用。 weakref 模块提供的工具可以不必创建引用就能跟踪对象。 当对象不再需要时,它将自动从一个弱引用表中被移除,并为弱引用对象触发一个回调。 典型应用包括对创建开销较大的对象进行缓存:

>>> import weakref, gc
>>> class A:
...     def __init__(self, value):
...         self.value = value
...     def __repr__(self):
...         return str(self.value)
...
>>> a = A(10)                   # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a            # does not create a reference
>>> d['primary']                # fetch the object if it is still alive
10
>>> del a                       # remove the one reference
>>> gc.collect()                # run garbage collection right away
0
>>> d['primary']                # entry was automatically removed
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    d['primary']                # entry was automatically removed
  File "C:/python310/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'

用于操作列表的工具

许多对于数据结构的需求可以通过内置列表类型来满足。 但是,有时也会需要具有不同效费比的替代实现。

array 模块提供了一种 array() 对象,它类似于列表,但只能存储类型一致的数据且存储密集更高。 下面的例子演示了一个以两个字节为存储单元的无符号二进制数值的数组 (类型码为 "H"),而对于普通列表来说,每个条目存储为标准 Python 的 int 对象通常要占用16 个字节:

>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])

collections 模块提供了一种 deque() 对象,它类似于列表,但从左端添加和弹出的速度较快,而在中间查找的速度较慢。 此种对象适用于实现队列和广度优先树搜索:

>>> from collections import deque
>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1

unsearched = deque([starting_node])
def breadth_first_search(unsearched):
    node = unsearched.popleft()
    for m in gen_moves(node):
        if is_goal(m):
            return m
        unsearched.append(m)

在替代的列表实现以外,标准库也提供了其他工具,例如 bisect 模块具有用于操作有序列表的函数:

>>> import bisect
>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]

heapq 模块提供了基于常规列表来实现堆的函数。 最小值的条目总是保持在位置零。 这对于需要重复访问最小元素而不希望运行完整列表排序的应用来说非常有用:

>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data)                      # rearrange the list into heap order
>>> heappush(data, -5)                 # add a new entry
>>> [heappop(data) for i in range(3)]  # fetch the three smallest entries
[-5, 0, 1]

十进制浮点运算

decimal 模块提供了一种 Decimal 数据类型用于十进制浮点运算。 相比内置的 float 二进制浮点实现,该类特别适用于

  • 财务应用和其他需要精确十进制表示的用途,
  • 控制精度,
  • 控制四舍五入以满足法律或监管要求,
  • 跟踪有效小数位,或
  • 用户期望结果与手工完成的计算相匹配的应用程序。

例如,使用十进制浮点和二进制浮点数计算70美分手机和5%税的总费用,会产生的不同结果。如果结果四舍五入到最接近的分数差异会更大:

>>> from decimal import *
>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73

Decimal 表示的结果会保留尾部的零,并根据具有两个有效位的被乘数自动推出四个有效位。 Decimal 可以模拟手工运算来避免当二进制浮点数无法精确表示十进制数时会导致的问题。

精确表示特性使得 Decimal 类能够执行对于二进制浮点数来说不适用的模运算和相等性检测:

>>> Decimal('1.00') % Decimal('.10')
Decimal('0.00')
>>> 1.00 % 0.10
0.09999999999999995
>>> sum([Decimal('0.1')]*10) == Decimal('1.0')
True
>>> sum([0.1]*10) == 1.0
False

decimal 模块提供了运算所需要的足够精度:

>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')

10. 虚拟环境和包

概述

Python应用程序通常会使用不在标准库内的软件包和模块。应用程序有时需要特定版本的库,因为应用程序可能需要修复特定的错误,或者可以使用库的过时版本的接口编写应用程序。

这意味着一个Python安装可能无法满足每个应用程序的要求。如果应用程序A需要特定模块的1.0版本但应用程序B需要2.0版本,则需求存在冲突,安装版本1.0或2.0将导致某一个应用程序无法运行。

这个问题的解决方案是创建一个 virtual environment,一个目录树,其中安装有特定Python版本,以及许多其他包。

然后,不同的应用将可以使用不同的虚拟环境。 要解决先前需求相冲突的例子,应用程序 A 可以拥有自己的 安装了 1.0 版本的虚拟环境,而应用程序 B 则拥有安装了 2.0 版本的另一个虚拟环境。 如果应用程序 B 要求将某个库升级到 3.0 版本,也不会影响应用程序 A 的环境。

创建虚拟环境

用于创建和管理虚拟环境的模块称为 venvvenv 通常会安装你可用的最新版本的 Python。如果您的系统上有多个版本的 Python,您可以通过运行 python3 或您想要的任何版本来选择特定的Python版本。

要创建虚拟环境,请确定要放置它的目录,并将 venv 模块作为脚本运行目录路径:

python3 -m venv tutorial-env

这将创建 tutorial-env 目录,如果它不存在的话,并在其中创建包含 Python 解释器副本和各种支持文件的目录。

虚拟环境的常用目录位置是 .venv。 这个名称通常会令该目录在你的终端中保持隐藏,从而避免需要对所在目录进行额外解释的一般名称。 它还能防止与某些工具所支持的 .env 环境变量定义文件发生冲突。

创建虚拟环境后,您可以激活它。

在Windows上,运行:

tutorial-env\Scripts\activate.bat

在Unix或MacOS上,运行:

source tutorial-env/bin/activate

(这个脚本是为bash shell编写的。如果你使用 cshfish shell,你应该改用 activate.cshactivate.fish 脚本。)

激活虚拟环境将改变你所用终端的提示符,以显示你正在使用的虚拟环境,并修改环境以使 python 命令所运行的将是已安装的特定 Python 版本。 例如:

$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
>>> import sys
>>> sys.path
['', '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>

使用pip管理包

你可以使用一个名为 pip 的程序来安装、升级和移除软件包。 默认情况下 pip 将从 Python Package Index https://pypi.org安装软件包。 你可以在你的 web 浏览器中查看 Python Package Index。

pip 有许多子命令: “install”, “uninstall”, “freeze” 等等。

您可以通过指定包的名称来安装最新版本的包:

(tutorial-env) $ python -m pip install novas
Collecting novas
  Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
  Running setup.py install for novas
Successfully installed novas-3.1.1.3

您还可以通过提供包名称后跟 == 和版本号来安装特定版本的包:

(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
  Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0

如果你重新运行这个命令,pip 会注意到已经安装了所请求的版本并且什么都不做。您可以提供不同的版本号来获取该版本,或者您可以运行 pip install --upgrade 将软件包升级到最新版本:

(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
  Found existing installation: requests 2.6.0
    Uninstalling requests-2.6.0:
      Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0

pip uninstall 后跟一个或多个包名称将从虚拟环境中删除包。

pip show 将显示有关特定包的信息:

(tutorial-env) $ pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:

pip list 将显示虚拟环境中安装的所有软件包:

(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)

pip freeze 将生成一个类似的已安装包列表,但输出使用 pip install 期望的格式。一个常见的约定是将此列表放在 requirements.txt 文件中:

(tutorial-env) $ pip freeze > requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0

然后可以将 requirements.txt 提交给版本控制并作为应用程序的一部分提供。然后用户可以使用 install -r 安装所有必需的包:

(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
  ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
  ...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
  ...
Installing collected packages: novas, numpy, requests
  Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0

11. 交互式编辑和编辑历史

某些版本的 Python 解释器支持编辑当前输入行和编辑历史记录,类似 Korn shell 和 GNU Bash shell 的功能 。这个功能使用了 GNU Readline 来实现,一个支持多种编辑方式的库。这个库有它自己的文档,在这里我们就不重复说明了。

Tab 补全和编辑历史

在解释器启动的时候,补全变量和模块名的功能将 自动打开,以便在按下 Tab 键的时候调用补全函数。它会查看 Python 语句名称,当前局部变量和可用的模块名称。处理像 string.a 的表达式,它会求值在最后一个 '.' 之前的表达式,接着根据求值结果对象的属性给出补全建议。如果拥有 __getattr__() 方法的对象是表达式的一部分,注意这可能会执行程序定义的代码。默认配置下会把编辑历史记录保存在用户目录下名为 .python_history 的文件。在下一次 Python 解释器会话期间,编辑历史记录仍旧可用。

默认交互式解释器的替代品

Python 解释器与早期版本的相比,向前迈进了一大步;无论怎样,还有些希望的功能:如果能在编辑连续行时建议缩进(解析器知道接下来是否需要缩进符号),那将很棒。补全机制可以使用解释器的符号表。有命令去检查(甚至建议)括号,引号以及其他符号是否匹配。

一个可选的增强型交互式解释器是 IPython,它已经存在了有一段时间,它具有 tab 补全,探索对象和高级历史记录管理功能。它还可以彻底定制并嵌入到其他应用程序中。另一个相似的增强型交互式环境是 bpython

12. 浮点算术:争议和限制

浮点数在计算机硬件中表示为以 2 为基数(二进制)的小数。举例而言,十进制的小数

0.125

等于 1/10 + 2/100 + 5/1000 ,同理,二进制的小数

0.001

等于0/2 + 0/4 + 1/8。这两个小数具有相同的值,唯一真正的区别是第一个是以 10 为基数的小数表示法,第二个则是 2 为基数。

不幸的是,大多数的十进制小数都不能精确地表示为二进制小数。这导致在大多数情况下,你输入的十进制浮点数都只能近似地以二进制浮点数形式储存在计算机中。

用十进制来理解这个问题显得更加容易一些。考虑分数 1/3 。我们可以得到它在十进制下的一个近似值

0.3

或者,更近似的,:

0.33

或者,更近似的,:

0.333

以此类推。结果是无论你写下多少的数字,它都永远不会等于 1/3 ,只是更加更加地接近 1/3 。

同样的道理,无论你使用多少位以 2 为基数的数码,十进制的 0.1 都无法精确地表示为一个以 2 为基数的小数。 在以 2 为基数的情况下, 1/10 是一个无限循环小数

0.0001100110011001100110011001100110011001100110011...

在任何一个位置停下,你都只能得到一个近似值。因此,在今天的大部分架构上,浮点数都只能近似地使用二进制小数表示,对应分数的分子使用每 8 字节的前 53 位表示,分母则表示为 2 的幂次。在 1/10 这个例子中,相应的二进制分数是 3602879701896397 / 2 ** 55 ,它很接近 1/10 ,但并不是 1/10 。

大部分用户都不会意识到这个差异的存在,因为 Python 只会打印计算机中存储的二进制值的十进制近似值。在大部分计算机中,如果 Python 想把 0.1 的二进制对应的精确十进制打印出来,将会变成这样

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625

这比大多数人认为有用的数字更多,因此Python通过显示舍入值来保持可管理的位数

>>> 1 / 10
0.1

牢记,即使输出的结果看起来好像就是 1/10 的精确值,实际储存的值只是最接近 1/10 的计算机可表示的二进制分数。

有趣的是,有许多不同的十进制数共享相同的最接近的近似二进制小数。例如, 0.10.100000000000000010.1000000000000000055511151231257827021181583404541015625 全都近似于 3602879701896397 / 2 ** 55 。由于所有这些十进制值都具有相同的近似值,因此可以显示其中任何一个,同时仍然保留不变的 eval(repr(x)) == x

在历史上,Python 提示符和内置的 repr() 函数会选择具有 17 位有效数字的来显示,即 0.10000000000000001。 从 Python 3.1 开始,Python(在大多数系统上)现在能够选择这些表示中最短的并简单地显示 0.1

请注意这种情况是二进制浮点数的本质特性:它不是 Python 的错误,也不是你代码中的错误。 你会在所有支持你的硬件中的浮点运算的语言中发现同样的情况(虽然某些语言在默认状态或所有输出模块下都不会 显示 这种差异)。

想要更美观的输出,你可能会希望使用字符串格式化来产生限定长度的有效位数:

>>> format(math.pi, '.12g')  # give 12 significant digits
'3.14159265359'
>>> format(math.pi, '.2f')   # give 2 digits after the point
'3.14'
>>> repr(math.pi)
'3.141592653589793'

必须重点了解的是,这在实际上只是一个假象:你只是将真正的机器码值进行了舍入操作再 显示 而已。

一个假象还可能导致另一个假象。 例如,由于这个 0.1 并非真正的 1/10,将三个 0.1 的值相加也不一定能恰好得到 0.3:

>>> .1 + .1 + .1 == .3
False

而且,由于这个 0.1 无法精确表示 1/10 的值而这个 0.3 也无法精确表示 3/10 的值,使用 round() 函数进行预先舍入也是没用的:

>>> round(.1, 1) + round(.1, 1) + round(.1, 1) == round(.3, 1)
False

虽然这些小数无法精确表示其所要代表的实际值,round() 函数还是可以用来“事后舍入”,使得实际的结果值可以做相互比较:

>>> round(.1 + .1 + .1, 10) == round(.3, 10)
True

二进制浮点运算会造成许多这样的“意外”。

正如那篇文章的结尾所言,“对此问题并无简单的答案。” 但是也不必过于担心浮点数的问题! Python 浮点运算中的错误是从浮点运算硬件继承而来,而在大多数机器上每次浮点运算得到的 2**53 数码位都会被作为 1 个整体来处理。 这对大多数任务来说都已足够,但你确实需要记住它并非十进制算术,且每次浮点运算都可能会导致新的舍入错误。

虽然病态的情况确实存在,但对于大多数正常的浮点运算使用来说,你只需简单地将最终显示的结果舍入为你期望的十进制数值即可得到你期望的结果。 str() 通常已足够。

对于需要精确十进制表示的使用场景,请尝试使用 decimal 模块,该模块实现了适合会计应用和高精度应用的十进制运算。

另一种形式的精确运算由 fractions 模块提供支持,该模块实现了基于有理数的算术运算(因此可以精确表示像 1/3 这样的数值)。

如果你是浮点运算的重度用户则你应当了解一下 NumPy 包以及由 SciPy 项目所提供的许多其他数字和统计运算包。 参见 https://scipy.org

Python 也提供了一些工具,可以在你真的 想要 知道一个浮点数精确值的少数情况下提供帮助。 例如 float.as_integer_ratio() 方法会将浮点数表示为一个分数:

>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)

由于这是一个精确的比值,它可以被用来无损地重建原始值:

>>> x == 3537115888337719 / 1125899906842624
True

float.hex() 方法会以十六进制(以 16 为基数)来表示浮点数,同样能给出保存在你的计算机中的精确值:

>>> x.hex()
'0x1.921f9f01b866ep+1'

这种精确的十六进制表示法可被用来精确地重建浮点值:

>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True

由于这种表示法是精确的,它适用于跨越不同版本(平台无关)的 Python 移植数值,以及与支持相同格式的其他语言(例如 Java 和 C99)交换数据.

另一个有用的工具是 math.fsum() 函数,它有助于减少求和过程中的精度损失。 它会在数值被添加到总计值的时候跟踪“丢失的位”。 这可以很好地保持总计值的精确度, 使得错误不会积累到能影响结果总数的程度:

>>> sum([0.1] * 10) == 1.0
False
>>> math.fsum([0.1] * 10) == 1.0
True

表示性错误

本小节将详细解释 “0.1” 的例子,并说明你可以怎样亲自对此类情况进行精确分析。 假定前提是已基本熟悉二进制浮点表示法。

表示性错误 是指某些(其实是大多数)十进制小数无法以二进制(以 2 为基数的计数制)精确表示这一事实造成的错误。 这就是为什么 Python(或者 Perl、C、C++、Java、Fortran 以及许多其他语言)经常不会显示你所期待的精确十进制数值的主要原因。

为什么会这样? 1/10 是无法用二进制小数精确表示的。 目前(2000年11月)几乎所有使用 IEEE-754 浮点运算标准的机器以及几乎所有系统平台都会将 Python 浮点数映射为 IEEE-754 “双精度类型”。 754 双精度类型包含 53 位精度,因此在输入时,计算会尽量将 0.1 转换为以 J/2**N 形式所能表示的最接近分数,其中 J 为恰好包含 53 个二进制位的整数。 重新将

1 / 10 ~= J / (2**N)

写为

J ~= 2**N / 10

并且由于 J 恰好有 53 位 (即 >= 2**52< 2**53),N 的最佳值为 56:

>>> 2**52 <=  2**56 // 10  < 2**53
True

也就是说,56 是唯一的 N 值能令 J 恰好有 53 位。 这样 J 的最佳可能值就是经过舍入的商:

>>> q, r = divmod(2**56, 10)
>>> r
6

由于余数超过 10 的一半,最佳近似值可通过四舍五入获得:

>>> q+1
7205759403792794

这样在 754 双精度下 1/10 的最佳近似值为:

7205759403792794 / 2 ** 56

分子和分母都除以二则结果小数为:

3602879701896397 / 2 ** 55

请注意由于我们做了向上舍入,这个结果实际上略大于 1/10;如果我们没有向上舍入,则商将会略小于 1/10。 但无论如何它都不会是 精确的 1/10!

因此计算永远不会“看到”1/10:它实际看到的就是上面所给出的小数,它所能达到的最佳 754 双精度近似值:

>>> 0.1 * 2 ** 55
3602879701896397.0

如果我们将该小数乘以 10**55,我们可以看到该值输出为 55 位的十进制数:

>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625

这意味着存储在计算机中的确切数值等于十进制数值 0.1000000000000000055511151231257827021181583404541015625。 许多语言(包括较旧版本的 Python)都不会显示这个完整的十进制数值,而是将结果舍入为 17 位有效数字:

>>> format(0.1, '.17f')
'0.10000000000000001'

fractionsdecimal 模块可令进行此类计算更加容易:

>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Fraction.from_float(0.1)
Fraction(3602879701896397, 36028797018963968)
>>> (0.1).as_integer_ratio()
(3602879701896397, 36028797018963968)
>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> format(Decimal.from_float(0.1), '.17')
'0.10000000000000001'

13. 交互模式

错误处理

当发生错误时,解释器会打印错误信息和错误堆栈。在交互模式下,将返回到主命令提示符;如果输入内容来自文件,在打印错误堆栈之后,程序会以非零状态退出。(这里所说的错误不包括 try 语句中由 except 所捕获的异常。)有些错误是无条件致命的,会导致程序以非零状态退出;比如内部逻辑矛盾或内存耗尽。所有错误信息都会被写入标准错误流;而命令的正常输出则被写入标准输出流。

将中断字符(通常为 Control-C 或 Delete )键入主要或辅助提示会取消输入并返回主提示符。 在执行命令时键入中断引发的 KeyboardInterrupt 异常,可以由 try 语句处理。

可执行的Python脚本

在BSD等类Unix系统上,Python脚本可以直接执行,就像shell脚本一样,第一行添加:

#!/usr/bin/env python3.5

(假设解释器位于用户的 PATH )脚本的开头,并将文件设置为可执行。 #! 必须是文件的前两个字符。在某些平台上,第一行必须以Unix样式的行结尾('\n')结束,而不是以Windows('\r\n')行结尾。请注意,散列或磅字符 '#' 在Python中代表注释开始。

可以使用 chmod 命令为脚本提供可执行模式或权限。

$ chmod +x myscript.py

在Windows系统上,没有“可执行模式”的概念。 Python安装程序自动将 .py 文件与 python.exe 相关联,这样双击Python文件就会将其作为脚本运行。扩展也可以是 .pyw ,在这种情况下,会隐藏通常出现的控制台窗口。

交互式启动文件

当您以交互方式使用Python时,每次启动解释器时都会执行一些标准命令,这通常很方便。您可以通过将名为 PYTHONSTARTUP 的环境变量设置为包含启动命令的文件名来实现。这类似于Unix shell的 .profile 功能。

此文件只会在交互式会话时读取,而非在 Python 从脚本读取指令或是在给定 /dev/tty 为指令的明确来源时(后者反而表现得像是一个交互式会话)。 该文件执行时所在的命名空间与交互式指令相同,所以它定义或导入的对象可以在交互式会话中直接使用。 你也可以在该文件中更改提示符 sys.ps1sys.ps2

如果你想从当前目录中读取一个额外的启动文件,你可以使用像 if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read()) 这样的代码在全局启动文件中对它进行编程。如果要在脚本中使用启动文件,则必须在脚本中显式执行此操作:

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
    with open(filename) as fobj:
        startup_file = fobj.read()
    exec(startup_file)

定制模块

Python提供了两个钩子来让你自定义它:sitecustomizeusercustomize。要查看其工作原理,首先需要找到用户site-packages目录的位置。启动Python并运行此代码:

>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.5/site-packages'

现在,您可以在该目录中创建一个名为 usercustomize.py 的文件,并将所需内容放入其中。它会影响Python的每次启动,除非它以 -s 选项启动,以禁用自动导入。

sitecustomize 以相同的方式工作,但通常由计算机管理员在全局 site-packages 目录中创建,并在 usercustomize 之前被导入。

Python 语言参考手册

1. 概述

我希望尽可能地保证内容精确无误,但还是选择使用自然词句进行描述,正式的规格定义仅用于句法和词法解析。这样应该能使文档对于普通人来说更易理解,但也可能导致一些歧义。因此,如果你是来自火星并且想凭借这份文档把 Python 重新实现一遍,也许有时需要自行猜测,实际上最终大概会得到一个十分不同的语言。而在另一方面,如果你正在使用 Python 并且想了解有关该语言特定领域的精确规则,你应该能够在这里找到它们。如果你希望查看对该语言更正式的定义,也许你可以花些时间自己写上一份 —- 或者发明一台克隆机器 :-)

在语言参考文档里加入过多的实现细节是很危险的 —- 具体实现可能发生改变,对同一语言的其他实现可能使用不同的方式。而在另一方面,CPython 是得到广泛使用的 Python 实现 (然而其他一些实现的拥护者也在增加),其中的特殊细节有时也值得一提,特别是当其实现方式导致额外的限制时。因此,你会发现在正文里不时会跳出来一些简短的 “实现注释”。

每种 Python 实现都带有一些内置和标准的模块。少数内置模块也会在此提及,如果它们同语言描述存在明显的关联。

1.1. 其他实现

虽然官方 Python 实现差不多得到最广泛的欢迎,但也有一些其他实现对特定领域的用户来说更具吸引力。

知名的实现包括:

CPython

这是最早出现并持续维护的 Python 实现,以 C 语言编写。新的语言特性通常在此率先添加。

Jython

以 Java 语言编写的 Python 实现。此实现可以作为 Java 应用的一个脚本语言,或者可以用来创建需要 Java 类库支持的应用。想了解更多信息可访问 Jython 网站

Python for .NET

此实现实际上使用了 CPython 实现,但是属于 .NET 托管应用并且可以引入 .NET 类库。它的创造者是 Brian Lloyd。想了解详情可访问 Python for .NET 主页

IronPython

另一个 .NET 的 Python 实现,与 Python.NET 不同点在于它是生成 IL 的完全 Python 实现,并且将 Python 代码直接编译为 .NET 程序集。它的创造者就是当初创造 Jython 的 Jim Hugunin。想了解详情可访问 IronPython 网站

PyPy

完全使用 Python 语言编写的 Python 实现。它支持多个其他实现所没有的高级特性,例如非栈式支持和 JIT 编译器等。此项目的目标之一是通过允许方便地修改解释器 (因为它是用 Python 编写的),鼓励该对语言本身进行试验。想了解详情可访问 PyPy 项目主页

以上这些实现都可能在某些方面与此参考文档手册的描述有所差异,或是引入了超出标准 Python 文档范围的特定信息。请参考它们各自的专门文档,以确定你正在使用的这个实现有哪些你需要了解的东西。

1.2. 标注

句法和词法解析的描述采用经过改进的 BNF 语法标注。这包含以下定义样式:

name      ::=  lc_letter (lc_letter | "_")*
lc_letter ::=  "a"..."z"

第一行表示 namelc_letter 之后跟零个或多个 lc_letter 和下划线。而 lc_letter 则是任意单个 'a''z' 字符。(实际上在本文档中始终采用此规则来定义词法和语法规则的名称。)

每条规则的开头是一个名称 (即该规则所定义的名称) 加上 ::=。 竖线 (|) 被用来分隔可选项,它是此标注中绑定程度最低的操作符。 星号 (*) 表示前一项的零次或多次重复,类似地,加号 (+) 表示一次或多次重复,而由方括号括起的内容 ([ ]) 表示出现零次或一次 (或者说,这部分内容是可选的)。 *+ 操作符的绑定是最紧密的,圆括号用于分组。 字符串字面值包含在引号内。 空格的作用仅限于分隔形符。 每条规则通常为一行,有许多个可选项的规则可能会以竖线为界分为多行。

在词法定义中 (如上述示例),还额外使用了两个约定: 由三个点号分隔的两个字符字面值表示在指定 (闭) 区间范围内的任意单个 ASCII 字符。由尖括号 (<...>) 括起来的内容是对于所定义符号的非正式描述;即可以在必要时用来说明 ‘控制字符’ 的意图。

虽然所用的标注方式几乎相同,但是词法定义和句法定义是存在很大区别的: 词法定义作用于输入源中单独的字符,而句法定义则作用于由词法分析所生成的形符流。在下一章节 (“词法分析”) 中使用的 BNF 全部都是词法定义;在之后的章节中使用的则是句法定义。

2. 词法分析

Python 程序由 解析器 读取,输入解析器的是 词法分析器 生成的 形符 流。本章介绍词法分析器怎样把文件拆成形符。

Python 将读取的程序文本转为 Unicode 代码点;编码声明用于指定源文件的编码,默认为 UTF-8,详见 PEP 3120。源文件不能解码时,触发 SyntaxError

2.1. 行结构

Python 程序可以拆分为多个 逻辑行

2.1.1. 逻辑行

NEWLINE 形符表示结束逻辑行。语句不能超出逻辑行的边界,除非句法支持 NEWLINE (例如,复合语句中的多行子语句)。根据显式或隐式 行拼接 规则,一个或多个 物理行 可组成逻辑行。

2.1.2. 物理行

物理行是一序列字符,由行尾序列终止。源文件和字符串可使用任意标准平台行终止序列 - Unix ASCII 字符 LF (换行)、 Windows ASCII 字符序列 CR LF (回车换行)、或老式 Macintosh ASCII 字符 CR (回车)。不管在哪个平台,这些形式均可等价使用。输入结束也可以用作最终物理行的隐式终止符。

嵌入 Python 时,传入 Python API 的源码字符串应使用 C 标准惯例换行符(\n,代表 ASCII 字符 LF, 行终止符)。

2.1.3. 注释

注释以井号 (#) 开头,在物理行末尾截止。注意,井号不是字符串字面值。除非应用隐式行拼接规则,否则,注释代表逻辑行结束。句法不解析注释。

2.1.4. 编码声明

Python 脚本第一或第二行的注释匹配正则表达式 coding[=:]\s*([-\w.]+) 时,该注释会被当作编码声明;这个表达式的第一组指定了源码文件的编码。编码声明必须独占一行,在第二行时,则第一行必须也是注释。编码表达式的形式如下:

# -*- coding: <encoding-name> -*-

这也是 GNU Emacs 认可的形式,此外,还支持如下形式:

# vim:fileencoding=<encoding-name>

这是 Bram Moolenaar 的 VIM 认可的形式。

没有编码声明时,默认编码为 UTF-8。此外,如果文件的首字节为 UTF-8 字节顺序标志(b'\xef\xbb\xbf'),文件编码也声明为 UTF-8(这是 Microsoft 的 notepad 等软件支持的形式)。

声明的编码名称必须是 Python 能识别的。语义字符串、注释和标识符等词法分析都使用此编码。

2.1.5. 显式拼接行

两个及两个以上的物理行可用反斜杠(\)拼接为一个逻辑行,规则如下:以不在字符串或注释内的反斜杠结尾时,物理行将与下一行拼接成一个逻辑行,并删除反斜杠及其后的换行符。例如:

if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1

以反斜杠结尾的行,不能加注释;反斜杠也不能拼接注释。除字符串字面值外,反斜杠不能拼接形符(如,除字符串字面值外,不能用反斜杠把形符切分至两个物理行)。反斜杠只能在代码的字符串字面值里,在其他任何位置都是非法的。

2.1.6. 隐式拼接行

圆括号、方括号、花括号内的表达式可以分成多个物理行,不必使用反斜杠。例如:

month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year

隐式行拼接可含注释;后续行的缩进并不重要;还支持空的后续行。隐式拼接行之间没有 NEWLINE 形符。三引号字符串支持隐式拼接行(见下文),但不支持注释。

2.1.7. 空白行

只包含空格符、制表符、换页符、注释的逻辑行会被忽略(即不生成 NEWLINE 形符)。交互模式输入语句时,空白行的处理方式可能因读取 - 求值 - 打印循环(REPL)的具体实现方式而不同。标准交互模式解释器中,完全空白的逻辑行(即连空格或注释都没有)将结束多行复合语句。

2.1.8. 缩进

逻辑行开头的空白符(空格符和制表符)用于计算该行的缩进层级,决定语句组块。

制表符(从左至右)被替换为一至八个空格,缩进空格的总数是八的倍数(与 Unix 的规则保持一致)。首个非空字符前的空格数决定了该行的缩进层次。缩进不能用反斜杠进行多行拼接;首个反斜杠之前的空白符决定了缩进的层次。

源文件混用制表符和空格符缩进时,因空格数量与制表符相关,由此产生的不一致将导致不能正常识别缩进层次,从而触发 TabError

跨平台兼容性说明: 鉴于非 UNIX 平台文本编辑器本身的特性,请勿在源文件中混用制表符和空格符。另外也请注意,不同平台有可能会显式限制最大缩进层级。

行首含换页符时,缩进计算将忽略该换页符。换页符在行首空白符内其他位置的效果未定义(例如,可能导致空格计数重置为零)。

连续行的缩进层级以堆栈形式生成 INDENT 和 DEDENT 形符,说明如下。

读取文件第一行前,先向栈推入一个零值,该零值不会被移除。推入栈的层级值从底至顶持续增加。每个逻辑行开头的行缩进层级将与栈顶行比较。如果相等,则不做处理。如果新行层级较高,则会被推入栈顶,并生成一个 INDENT 形符。如果新行层级较低,则 应当 是栈中的层级数值之一;栈中高于该层级的所有数值都将被移除,每移除一级数值生成一个 DEDENT 形符。文件末尾,栈中剩余的每个大于零的数值生成一个 DEDENT 形符。

下面的 Python 代码缩进示例虽然正确,但含混不清:

def perm(l):
        # Compute the list of all permutations of l
    if len(l) <= 1:
                  return [l]
    r = []
    for i in range(len(l)):
             s = l[:i] + l[i+1:]
             p = perm(s)
             for x in p:
              r.append(l[i:i+1] + x)
    return r

下例展示了多种缩进错误:

 def perm(l):                       # error: first line indented
for i in range(len(l)):             # error: not indented
    s = l[:i] + l[i+1:]
        p = perm(l[:i] + l[i+1:])   # error: unexpected indent
        for x in p:
                r.append(l[i:i+1] + x)
            return r                # error: inconsistent dedent

(实际上,解析器可以识别前三个错误;只有最后一个错误由词法分析器识别 —- return r 的缩进无法匹配从栈里移除的缩进层级。)

2.1.9. 形符间的空白字符

除非在逻辑行开头或字符串内,空格符、制表符、换页符等空白符都可以分隔形符。要把两个相连形符解读为不同形符,需要用空白符分隔(例如,ab 是一个形符,a b 则是两个形符)。

2.2. 其他形符

除 NEWLINE、INDENT、DEDENT 外,还有 标识符关键字字面值运算符分隔符 等形符。 空白符(前述的行终止符除外)不是形符,可用于分隔形符。存在二义性时,将从左至右,读取尽量长的字符串组成合法形符。

2.3. 标识符和关键字

标识符(也称为 名称)的词法定义说明如下。

Python 标识符的句法基于 Unicode 标准附件 UAX-31,并加入了下文定义的细化与修改;详见 PEP 3131

与 Python 2.x 一样,在 ASCII 范围内(U+0001..U+007F),有效标识符字符为: 大小写字母 AZ、下划线 _ 、数字 09,但不能以数字开头。

Python 3.0 引入了 ASCII 之外的更多字符(请参阅 PEP 3131)。这些字符的分类使用 unicodedata 模块中的 Unicode 字符数据库版本。

标识符的长度没有限制,但区分大小写。

identifier   ::=  xid_start xid_continue*
id_start     ::=  <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
id_continue  ::=  <all characters in id_start, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
xid_start    ::=  <all characters in id_start whose NFKC normalization is in "id_start xid_continue*">
xid_continue ::=  <all characters in id_continue whose NFKC normalization is in "id_continue*">

上述 Unicode 类别码的含义:

  • Lu - 大写字母
  • Ll - 小写字母
  • Lt - 词首大写字母
  • Lm - 修饰符字母
  • Lo - 其他字母
  • Nl - 字母数字
  • Mn - 非空白标识
  • Mc - 含空白标识
  • Nd - 十进制数字
  • Pc - 连接标点
  • Other_ID_Start - 由 PropList.txt 定义的显式字符列表,用于支持向后兼容
  • Other_ID_Continue - 同上

在解析时,所有标识符都会被转换为规范形式 NFKC;标识符的比较都是基于 NFKC。

Unicode 4.1 中所有可用的标识符字符详见此 HTML 文件 https://www.unicode.org/Public/13.0.0/ucd/DerivedCoreProperties.txt

2.3.1. 关键字

以下标识符为保留字,或称 关键字,不可用于普通标识符。关键字的拼写必须与这里列出的完全一致:

False      await      else       import     pass
None       break      except     in         raise
True       class      finally    is         return
and        continue   for        lambda     try
as         def        from       nonlocal   while
assert     del        global     not        with
async      elif       if         or         yield

2.3.2. 软关键字

3.10 新版功能.

某些标识符仅在特定上下文中被保留。 它们被称为 软关键字match, case_ 等标识符在模式匹配语句相关的上下文中具有相当于关键字的语义,但这种区分是在解析器层级完成,而不是在形符化的时候。

作为软关键字,它们能够与模式匹配一起使用,同时仍然保持与使用 match, case_ 作为标识符名称的现有代码的兼容性。

2.3.3. 保留的标识符类

某些标识符类(除了关键字)具有特殊含义。这些类的命名模式以下划线字符开头,并以下划线结尾:

_*

from module import * 时,不会导入。交互式解释器中,特殊标识符 _ 用于存储最近一次求值的结果;该标识符保存在 builtins 模块里。不处于交互模式时,_ 没有特殊含义,也没有预定义。

注解

_ 常用于连接国际化文本。

__*__

系统定义的名称,通常简称为 “dunder” 。这些名称由解释器及其实现(包括标准库)定义。Python 未来版本中还将定义更多此类名称。任何情况下,任何 不显式遵从 __*__ 名称的文档用法,都可能导致无警告提示的错误。

__*

类的私有名称。类定义时,此类名称以一种混合形式重写,以避免基类及派生类的 “私有” 属性之间产生名称冲突。

2.4. 字面值

字面值是内置类型常量值的表示法。

2.4.1. 字符串与字节串字面值

字符串字面值的词法定义如下:

stringliteral   ::=  [stringprefix](shortstring | longstring)
stringprefix    ::=  "r" | "u" | "R" | "U" | "f" | "F"
                     | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
shortstring     ::=  "'" shortstringitem* "'" | '"' shortstringitem* '"'
longstring      ::=  "'''" longstringitem* "'''" | '"""' longstringitem* '"""'
shortstringitem ::=  shortstringchar | stringescapeseq
longstringitem  ::=  longstringchar | stringescapeseq
shortstringchar ::=  <any source character except "\" or newline or the quote>
longstringchar  ::=  <any source character except "\">
stringescapeseq ::=  "\" <any source character>

bytesliteral   ::=  bytesprefix(shortbytes | longbytes)
bytesprefix    ::=  "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
shortbytes     ::=  "'" shortbytesitem* "'" | '"' shortbytesitem* '"'
longbytes      ::=  "'''" longbytesitem* "'''" | '"""' longbytesitem* '"""'
shortbytesitem ::=  shortbyteschar | bytesescapeseq
longbytesitem  ::=  longbyteschar | bytesescapeseq
shortbyteschar ::=  <any ASCII character except "\" or newline or the quote>
longbyteschar  ::=  <any ASCII character except "\">
bytesescapeseq ::=  "\" <any ASCII character>

上述产生式没有说明以下句法限制,stringprefixbytesprefix 与其他字面值之间不允许有空白符。源字符集由编码声明定义;源文件没有编码声明时,默认为 UTF-8。

通俗地说:两种字面值都可以用单引号(')或双引号(") 标注。也可以用三个单引号或双引号标注(俗称 三引号字符串)。反斜杠(\)用于转义特殊字符,例如,换行符、反斜杠本身、引号等。

字节串字面值要加前缀 'b''B';生成的是类型 bytes 的实例,不是类型 str 的实例;字节串只能包含 ASCII 字符;字节串数值大于等于 128 时,必须用转义表示。

字符串和字节串都可以加前缀 'r''R',称为 原始字符串,原始字符串把反斜杠当作原义字符,不执行转义操作。因此,原始字符串不转义 '\U''\u'。与 Python 2.x 的原始 unicode 字面值操作不同,Python 3.x 现已不支持 'ur' 句法。

3.3 新版功能: 新增原始字节串 'rb' 前缀,是 'br' 的同义词。

3.3 新版功能: 支持 unicode 字面值(u'value')遗留代码,简化 Python 2.x 和 3.x 并行代码库的维护工作。详见 PEP 414

前缀为 'f''F' 的字符串称为 格式字符串'f' 可与 'r' 连用,但不能与 'b''u' 连用,因此,可以使用原始格式字符串,但不能使用格式字节串字面值。

三引号字面值可以包含未转义的换行和引号(原样保留),除了连在一起的,用于终止字面值的,未经转义的三个引号。(”引号” 是启用字面值的字符,可以是 ',也可以是 "。)

如未标注 'r''R' 前缀,字符串和字节串字面值中,转义序列以类似 C 标准的规则进行解释。可用的转义序列如下:

转义序列 含意 备注
\newline 忽略反斜杠与换行符
\ 反斜杠(\
\’ 单引号(
\” 双引号(
\a ASCII 响铃(BEL)
\b ASCII 退格符(BS)
\f ASCII 换页符(FF)
\n ASCII 换行符(LF)
\r ASCII 回车符(CR)
\t ASCII 水平制表符(TAB)
\v ASCII 垂直制表符(VT)
\ooo 八进制数 ooo 字符 (1,3)
\xhh 十六进制数 hh 字符 (2,3)

字符串字面值专用的转义序列:

转义序列 含意 备注
\N{name} Unicode 数据库中名为 name 的字符 (4)
\uxxxx 16 位十六进制数 xxxx 码位的字符 (5)
\Uxxxxxxxx 32 位 16 进制数 xxxxxxxx 码位的字符 (6)

注释:

  1. 与 C 标准一致,接受最多三个八进制数字。
  2. 与 C 标准不同,必须为两个十六进制数字。
  3. 字节串 字面值中,十六进制数和八进制数的转义码以相应数值代表每个字节。字符串 字面值中,这些转义码以相应数值代表每个 Unicode 字符。
  4. 在 3.3 版更改: 加入了对别名的支持
  5. 必须为 4 个十六进制数码。
  6. 表示任意 Unicode 字符。必须为 8 个十六进制数码。

与 C 标准不同,无法识别的转义序列在字符串里原样保留,即,输出结果保留反斜杠。(调试时,这种方式很有用:输错转义序列时,更容易在输出结果中识别错误。)注意,在字节串字面值内,字符串字面值专用的转义序列属于无法识别的转义序列。

在 3.6 版更改: 无法识别的转义序列触发 DeprecationWarning。未来的 Python 发行版将改为触发 SyntaxWarning,最终会改为触发 SyntaxError

即使在原始字面值中,引号也可以用反斜杠转义,但反斜杠会保留在输出结果里;例如 r"\"" 是由两个字符组成的有效字符串字面值:反斜杠和双引号;r"\" 则不是有效字符串字面值(原始字符串也不能以奇数个反斜杠结尾)。尤其是,原始字面值不能以单个反斜杠结尾 (反斜杠会转义其后的引号)。还要注意,反斜杠加换行在字面值中被解释为两个字符,而 不是 连续行。

2.4.2. 字符串字面值合并

以空白符分隔的多个相邻字符串或字节串字面值,可用不同引号标注,等同于合并操作。因此,"hello" 'world' 等价于 "helloworld"。此功能不需要反斜杠,即可将长字符串分为多个物理行,还可以为不同部分的字符串添加注释,例如:

re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )

注意,此功能在句法层面定义,在编译时实现。在运行时,合并字符串表达式必须使用 ‘+’ 运算符。还要注意,字面值合并可以为每个部分应用不同的引号风格(甚至混用原始字符串和三引号字符串),格式字符串字面值也可以与纯字符串字面值合并。

2.4.3. 格式字符串字面值

3.6 新版功能.

格式字符串字面值 或称 f-string 是标注了 'f''F' 前缀的字符串字面值。这种字符串可包含替换字段,即以 {} 标注的表达式。其他字符串字面值只是常量,格式字符串字面值则是可在运行时求值的表达式。

除非字面值标记为原始字符串,否则,与在普通字符串字面值中一样,转义序列也会被解码。解码后,用于字符串内容的语法如下:

f_string          ::=  (literal_char | "{{" | "}}" | replacement_field)*
replacement_field ::=  "{" f_expression ["="] ["!" conversion] [":" format_spec] "}"
f_expression      ::=  (conditional_expression | "*" or_expr)
                         ("," conditional_expression | "," "*" or_expr)* [","]
                       | yield_expression
conversion        ::=  "s" | "r" | "a"
format_spec       ::=  (literal_char | NULL | replacement_field)*
literal_char      ::=  <any code point except "{", "}" or NULL>

双花括号 '` 或 `' 被替换为单花括号,花括号外的字符串仍按字面值处理。单左花括号 '{' 标记以 Python 表达式开头的替换字段。在表达式后加等于号 '=',可在求值后,同时显示表达式文本及其结果(用于调试)。 随后是用叹号 '!' 标记的转换字段。还可以在冒号 ':' 后附加格式说明符。替换字段以右花括号 '}' 为结尾。

格式字符串字面值中,表达式的处理与圆括号中的常规 Python 表达式基本一样,但也有一些不同的地方。不允许使用空表达式;lambda 和赋值表达式 := 必须显式用圆括号标注;替换表达式可以包含换行(例如,三引号字符串中),但不能包含注释;在格式字符串字面值语境内,按从左至右的顺序,为每个表达式求值。

在 3.7 版更改: Python 3.7 以前, 因为实现的问题,不允许在格式字符串字面值表达式中使用 await 表达式与包含 async for 子句的推导式。

表达式里含等号 '=' 时,输出内容包括表达式文本、'=' 、求值结果。输出内容可以保留表达式中左花括号 '{' 后,及 '=' 后的空格。没有指定格式时,'=' 默认调用表达式的 repr()。指定了格式时,默认调用表达式的 str(),除非声明了转换字段 '!r'

3.8 新版功能: 等号 '='

指定了转换符时,表达式求值的结果会先转换,再格式化。转换符 '!s' 调用 str() 转换求值结果,'!r' 调用 repr()'!a' 调用 ascii()

输出结果的格式化使用 format() 协议。格式说明符传入表达式或转换结果的 __format__() 方法。省略格式说明符,则传入空字符串。然后,格式化结果包含在整个字符串的最终值里。

顶层格式说明符可以包含嵌套替换字段。嵌套字段也可以包含自己的转换字段和 格式说明符,但不可再包含更深层嵌套的替换字段。格式说明符微语言 与 str.format() 方法使用的微语言相同。

格式化字符串字面值可以拼接,但是一个替换字段不能拆分到多个字面值。

格式字符串字面值示例如下:

>>> name = "Fred"
>>> f"He said his name is {name!r}."
"He said his name is 'Fred'."
>>> f"He said his name is {repr(name)}."  # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: {value:{width}.{precision}}"  # nested fields
'result:      12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"{today:%B %d, %Y}"  # using date format specifier
'January 27, 2017'
>>> f"{today=:%B %d, %Y}" # using date format specifier and debugging
'today=January 27, 2017'
>>> number = 1024
>>> f"{number:#0x}"  # using integer format specifier
'0x400'
>>> foo = "bar"
>>> f"{ foo = }" # preserves whitespace
" foo = 'bar'"
>>> line = "The mill's closed"
>>> f"{line = }"
'line = "The mill\'s closed"'
>>> f"{line = :20}"
"line = The mill's closed   "
>>> f"{line = !r:20}"
'line = "The mill\'s closed" '

与常规字符串字面值的语法一样,替换字段中的字符不能与外层格式字符串字面值的引号冲突:

f"abc {a["x"]} def"    # error: outer string literal ended prematurely
f"abc {a['x']} def"    # workaround: use different quoting

格式表达式中不能有反斜杠,否则会报错:

f"newline: {ord('\n')}"  # raises SyntaxError

要使用反斜杠转义的值,则需创建临时变量。

>>> newline = ord('\n')
>>> f"newline: {newline}"
'newline: 10'

即便未包含表达式,格式字符串字面值也不能用作文档字符串。

>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True

参阅 PEP 498,了解格式字符串字面值的提案,以及与格式字符串机制相关的 str.format()

2.4.4. 数值字面值

数值字面值有三种类型:整数、浮点数、虚数。没有复数字面值(复数由实数加虚数构成)。

注意,数值字面值不含正负号;实际上,-1 等负数是由一元运算符 ‘-‘ 和字面值 1 合成的。

2.4.5. 整数字面值

整数字面值词法定义如下:

integer      ::=  decinteger | bininteger | octinteger | hexinteger
decinteger   ::=  nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
bininteger   ::=  "0" ("b" | "B") (["_"] bindigit)+
octinteger   ::=  "0" ("o" | "O") (["_"] octdigit)+
hexinteger   ::=  "0" ("x" | "X") (["_"] hexdigit)+
nonzerodigit ::=  "1"..."9"
digit        ::=  "0"..."9"
bindigit     ::=  "0" | "1"
octdigit     ::=  "0"..."7"
hexdigit     ::=  digit | "a"..."f" | "A"..."F"

整数字面值的长度没有限制,能一直大到占满可用内存。

确定数值时,会忽略字面值中的下划线。下划线只是为了分组数字,让数字更易读。下划线可在数字之间,也可在 0x 等基数说明符后。

注意,除了 0 以外,十进制数字的开头不允许有零。以免与 Python 3.0 版之前使用的 C 样式八进制字面值混淆。

整数字面值示例如下:

7     2147483647                        0o177    0b100110111
3     79228162514264337593543950336     0o377    0xdeadbeef
      100_000_000_000                   0b_1110_0101

在 3.6 版更改: 现已支持在字面值中,用下划线分组数字。

2.4.6. 浮点数字面值

浮点数字面值词法定义如下:

floatnumber   ::=  pointfloat | exponentfloat
pointfloat    ::=  [digitpart] fraction | digitpart "."
exponentfloat ::=  (digitpart | pointfloat) exponent
digitpart     ::=  digit (["_"] digit)*
fraction      ::=  "." digitpart
exponent      ::=  ("e" | "E") ["+" | "-"] digitpart

注意,解析时,整数和指数部分总以 10 为基数。例如,077e010 是合法的,表示的数值与 77e10 相同。浮点数字面值的支持范围取决于具体实现。整数字面值支持用下划线分组数字。

浮点数字面值示例如下:

3.14    10.    .001    1e100    3.14e-10    0e0    3.14_15_93

在 3.6 版更改: 现已支持在字面值中,用下划线分组数字。

2.4.7. 虚数字面值

虚数字面值词法定义如下:

imagnumber ::=  (floatnumber | digitpart) ("j" | "J")

虚数字面值生成实部为 0.0 的复数。复数由一对浮点数表示,它们的取值范围相同。创建实部不为零的复数,则需添加浮点数,例如 (3+4j)。虚数字面值示例如下:

3.14j   10.j    10j     .001j   1e100j   3.14e-10j   3.14_15_93j

2.5. 运算符

运算符如下所示:

+       -       *       **      /       //      %      @
<<      >>      &       |       ^       ~       :=
<       >       <=      >=      ==      !=

2.6. 分隔符

以下形符在语法中为分隔符:

(       )       [       ]       {       }
,       :       .       ;       @       =       ->
+=      -=      *=      /=      //=     %=      @=
&=      |=      ^=      >>=     <<=     **=

句点也可以用于浮点数和虚数字面值。三个连续句点表示省略符。列表后半部分是增强赋值操作符,用作词法分隔符,但也可以执行运算。

以下 ASCII 字符具有特殊含义,对词法分析器有重要意义:

'       "       #       \

以下 ASCII 字符不用于 Python。在字符串字面值或注释外使用时,将直接报错:

$       ?       `

3. 数据模型

3.1. 对象、值与类型

对象 是 Python 中对数据的抽象。 Python 程序中的所有数据都是由对象或对象间关系来表示的。 (从某种意义上说,按照冯·诺依曼的“存储程序计算机”模型,代码本身也是由对象来表示的。)

每个对象都有各自的编号、类型和值。一个对象被创建后,它的 编号 就绝不会改变;你可以将其理解为该对象在内存中的地址。 ‘is‘ 运算符可以比较两个对象的编号是否相同;id() 函数能返回一个代表其编号的整型数。

CPython implementation detail: 在 CPython 中,id(x) 就是存放 x 的内存的地址。

对象的类型决定该对象所支持的操作 (例如 “对象是否有长度属性?”) 并且定义了该类型的对象可能的取值。type() 函数能返回一个对象的类型 (类型本身也是对象)。与编号一样,一个对象的 类型 也是不可改变的。

有些对象的 可以改变。值可以改变的对象被称为 可变的;值不可以改变的对象就被称为 不可变的。(一个不可变容器对象如果包含对可变对象的引用,当后者的值改变时,前者的值也会改变;但是该容器仍属于不可变对象,因为它所包含的对象集是不会改变的。因此,不可变并不严格等同于值不能改变,实际含义要更微妙。) 一个对象的可变性是由其类型决定的;例如,数字、字符串和元组是不可变的,而字典和列表是可变的。

对象绝不会被显式地销毁;然而,当无法访问时它们可能会被作为垃圾回收。允许具体的实现推迟垃圾回收或完全省略此机制 —- 如何实现垃圾回收是实现的质量问题,只要可访问的对象不会被回收即可。

CPython implementation detail: CPython 目前使用带有 (可选) 延迟检测循环链接垃圾的引用计数方案,会在对象不可访问时立即回收其中的大部分,但不保证回收包含循环引用的垃圾。请查看 gc 模块的文档了解如何控制循环垃圾的收集相关信息。其他实现会有不同的行为方式,CPython 现有方式也可能改变。不要依赖不可访问对象的立即终结机制 (所以你应当总是显式地关闭文件)。

注意:使用实现的跟踪或调试功能可能令正常情况下会被回收的对象继续存活。还要注意通过 ‘tryexcept‘ 语句捕捉异常也可能令对象保持存活。

有些对象包含对 “外部” 资源的引用,例如打开文件或窗口。当对象被作为垃圾回收时这些资源也应该会被释放,但由于垃圾回收并不确保发生,这些对象还提供了明确地释放外部资源的操作,通常为一个 close() 方法。强烈推荐在程序中显式关闭此类对象。’tryfinally‘ 语句和 ‘with‘ 语句提供了进行此种操作的更便捷方式。

有些对象包含对其他对象的引用;它们被称为 容器。容器的例子有元组、列表和字典等。这些引用是容器对象值的组成部分。在多数情况下,当谈论一个容器的值时,我们是指所包含对象的值而不是其编号;但是,当我们谈论一个容器的可变性时,则仅指其直接包含的对象的编号。因此,如果一个不可变容器 (例如元组) 包含对一个可变对象的引用,则当该可变对象被改变时容器的值也会改变。

类型会影响对象行为的几乎所有方面。甚至对象编号的重要性也在某种程度上受到影响: 对于不可变类型,会得出新值的运算实际上会返回对相同类型和取值的任一现有对象的引用,而对于可变类型来说这是不允许的。例如在 a = 1; b = 1 之后,ab 可能会也可能不会指向同一个值为一的对象,这取决于具体实现,但是在 c = []; d = [] 之后,cd 保证会指向两个不同、单独的新建空列表。(请注意 c = d = [] 则是将同一个对象赋值给 cd。)

3.2. 标准类型层级结构

以下是 Python 内置类型的列表。扩展模块 (具体实现会以 C, Java 或其他语言编写) 可以定义更多的类型。未来版本的 Python 可能会加入更多的类型 (例如有理数、高效存储的整型数组等等),不过新增类型往往都是通过标准库来提供的。

以下部分类型的描述中包含有 ‘特殊属性列表’ 段落。这些属性提供对具体实现的访问而非通常使用。它们的定义在未来可能会改变。

None

此类型只有一种取值。是一个具有此值的单独对象。此对象通过内置名称 None 访问。在许多情况下它被用来表示空值,例如未显式指明返回值的函数将返回 None。它的逻辑值为假。

NotImplemented

此类型只有一种取值。 是一个具有该值的单独对象。 此对象通过内置名称 NotImplemented 访问。 数值方法和丰富比较方法如未实现指定运算符表示的运算则应返回该值。 (解释器会根据具体运算符继续尝试反向运算或其他回退操作。) 它不应被解读为布尔值。

在 3.9 版更改: 作为布尔值来解读 NotImplemented 已被弃用。 虽然它目前会被解读为真值,但将同时发出 DeprecationWarning。 它将在未来的 Python 版本中引发 TypeError

Ellipsis

此类型只有一种取值。是一个具有此值的单独对象。此对象通过字面值 ... 或内置名称 Ellipsis 访问。它的逻辑值为真。

numbers.Number

此类对象由数字字面值创建,并会被作为算术运算符和算术内置函数的返回结果。数字对象是不可变的;一旦创建其值就不再改变。Python 中的数字当然非常类似数学中的数字,但也受限于计算机中的数字表示方法。

数字类的字符串表示形式,由 __repr__()__str__() 算出,具有以下属性:

  • 它们是有效的数字字面值,当被传给它们的类构造器时,将会产生具有原数字值的对象。
  • 表示形式会在可能的情况下采用 10 进制。
  • 开头的零,除小数点前可能存在的单个零之外,将不会被显示。
  • 末尾的零,除小数点后可能存在的单个零之外,将不会被显示。
  • 正负号仅在当数字为负值时会被显示。

Python 区分整型数、浮点型数和复数:

  • numbers.Integral

    此类对象表示数学中整数集合的成员 (包括正数和负数)。

    整型数可细分为两种类型:

    • 整型 (int)

      此类对象表示任意大小的数字,仅受限于可用的内存 (包括虚拟内存)。在变换和掩码运算中会以二进制表示,负数会以 2 的补码表示,看起来像是符号位向左延伸补满空位。

      布尔型 (bool)

      此类对象表示逻辑值 False 和 True。代表 FalseTrue 值的两个对象是唯二的布尔对象。布尔类型是整型的子类型,两个布尔值在各种场合的行为分别类似于数值 0 和 1,例外情况只有在转换为字符串时分别返回字符串 "False""True"

    整型数表示规则的目的是在涉及负整型数的变换和掩码运算时提供最为合理的解释。

    numbers.Real (float)

    此类对象表示机器级的双精度浮点数。其所接受的取值范围和溢出处理将受制于底层的机器架构 (以及 C 或 Java 实现)。Python 不支持单精度浮点数;支持后者通常的理由是节省处理器和内存消耗,但这点节省相对于在 Python 中使用对象的开销来说太过微不足道,因此没有理由包含两种浮点数而令该语言变得复杂。

    numbers.Complex (complex)

    此类对象以一对机器级的双精度浮点数来表示复数值。有关浮点数的附带规则对其同样有效。一个复数值 z 的实部和虚部可通过只读属性 z.realz.imag 来获取。

序列

此类对象表示以非负整数作为索引的有限有序集。内置函数 len() 可返回一个序列的条目数量。当一个序列的长度为 n 时,索引集包含数字 0, 1, …, n-1。序列 a 的条目 i 可通过 a[i] 选择。

序列还支持切片: a[i:j] 选择索引号为 k 的所有条目,i <= k < j。当用作表达式时,序列的切片就是一个与序列类型相同的新序列。新序列的索引还是从 0 开始。

有些序列还支持带有第三个 “step” 形参的 “扩展切片”: a[i:j:k] 选择 a 中索引号为 x 的所有条目,x = i + n*k, n >= 0i <= x < j

序列可根据其可变性来加以区分:

  • 不可变序列

    不可变序列类型的对象一旦创建就不能再改变。(如果对象包含对其他对象的引用,其中的可变对象就是可以改变的;但是,一个不可变对象所直接引用的对象集是不能改变的。)

    以下类型属于不可变对象:

    • 字符串

      字符串是由 Unicode 码位值组成的序列。范围在 U+0000 - U+10FFFF 之内的所有码位值都可在字符串中使用。Python 没有 char 类型;而是将字符串中的每个码位表示为一个长度为 1 的字符串对象。内置函数 ord() 可将一个码位由字符串形式转换成一个范围在 0 - 10FFFF 之内的整型数;chr() 可将一个范围在 0 - 10FFFF 之内的整型数转换为长度为 1 的对应字符串对象。str.encode() 可以使用指定的文本编码将 str 转换为 bytes,而 bytes.decode() 则可以实现反向的解码。

      元组

      一个元组中的条目可以是任意 Python 对象。包含两个或以上条目的元组由逗号分隔的表达式构成。只有一个条目的元组 (‘单项元组’) 可通过在表达式后加一个逗号来构成 (一个表达式本身不能创建为元组,因为圆括号要用来设置表达式分组)。一个空元组可通过一对内容为空的圆括号创建。

      字节串

      字节串对象是不可变的数组。其中每个条目都是一个 8 位字节,以取值范围 0 <= x < 256 的整型数表示。字节串字面值 (例如 b'abc') 和内置的 bytes() 构造器可被用来创建字节串对象。字节串对象还可以通过 decode() 方法解码为字符串。

  • 可变序列

    可变序列在被创建后仍可被改变。下标和切片标注可被用作赋值和 del (删除) 语句的目标。

    目前有两种内生可变序列类型:

    • 列表

      列表中的条目可以是任意 Python 对象。列表由用方括号括起并由逗号分隔的多个表达式构成。(注意创建长度为 0 或 1 的列表无需使用特殊规则。)

      字节数组

      字节数组对象属于可变数组。可以通过内置的 bytearray() 构造器来创建。除了是可变的 (因而也是不可哈希的),在其他方面字节数组提供的接口和功能都与不可变的 bytes 对象一致。

    扩展模块 array 提供了一个额外的可变序列类型示例,collections 模块也是如此。

集合类型

此类对象表示由不重复且不可变对象组成的无序且有限的集合。因此它们不能通过下标来索引。但是它们可被迭代,也可用内置函数 len() 返回集合中的条目数。集合常见的用处是快速成员检测,去除序列中的重复项,以及进行交、并、差和对称差等数学运算。

对于集合元素所采用的不可变规则与字典的键相同。注意数字类型遵循正常的数字比较规则: 如果两个数字相等 (例如 11.0),则同一集合中只能包含其中一个。

目前有两种内生集合类型:

  • 集合

    此类对象表示可变集合。它们可通过内置的 set() 构造器创建,并且创建之后可以通过方法进行修改,例如 add()

    冻结集合

    此类对象表示不可变集合。它们可通过内置的 frozenset() 构造器创建。由于 frozenset 对象不可变且 hashable,它可以被用作另一个集合的元素或是字典的键。

映射

此类对象表示由任意索引集合所索引的对象的集合。通过下标 a[k] 可在映射 a 中选择索引为 k 的条目;这可以在表达式中使用,也可作为赋值或 del 语句的目标。内置函数 len() 可返回一个映射中的条目数。

目前只有一种内生映射类型:

  • 字典

    此类对象表示由几乎任意值作为索引的有限个对象的集合。不可作为键的值类型只有包含列表或字典或其他可变类型,通过值而非对象编号进行比较的值,其原因在于高效的字典实现需要使用键的哈希值以保持一致性。用作键的数字类型遵循正常的数字比较规则: 如果两个数字相等 (例如 11.0) 则它们均可来用来索引同一个字典条目。

    字典会保留插入顺序,这意味着键将以它们被添加的顺序在字典中依次产生。 替换某个现有的键不会改变其顺序,但是移除某个键再重新插入则会将其添加到末尾而不会保留其原有位置。

    字典是可变的;它们可通过 {...} 标注来创建 。

    扩展模块 dbm.ndbmdbm.gnu 提供了额外的映射类型示例,collections 模块也是如此。

    在 3.7 版更改: 在 Python 3.6 版之前字典不会保留插入顺序。 在 CPython 3.6 中插入顺序会被保留,但这在当时被当作是一个实现细节而非确定的语言特性。

可调用类型

此类型可以被应用于函数调用操作 :

  • 用户定义函数

    用户定义函数对象可通过函数定义来创建 。它被调用时应附带一个参数列表,其中包含的条目应与函数所定义的形参列表一致。

    特殊属性:

    属性 含意
    doc 该函数的文档字符串,没有则为 None;不会被子类继承。 可写
    name 该函数的名称。 可写
    qualname 该函数的 qualified name。3.3 新版功能. 可写
    module 该函数所属模块的名称,没有则为 None 可写
    defaults 由具有默认值的参数的默认参数值组成的元组,如无任何参数具有默认值则为 None 可写
    code 表示编译后的函数体的代码对象。 可写
    globals 对存放该函数中全局变量的字典的引用 —- 函数所属模块的全局命名空间。 只读
    dict 命名空间支持的函数属性。 可写
    closure None 或包含该函数可用变量的绑定的单元的元组。有关 cell contents 属性的详情见下。 只读
    annotations 包含形参标注的字典。 字典的键是形参名,而如果提供了 ‘return’ 则是用于返回值标注。 可写
    _kwdefaults 仅包含关键字参数默认值的字典。 可写

    大部分标有 “Writable” 的属性均会检查赋值的类型。

    函数对象也支持获取和设置任意属性,例如这可以被用来给函数附加元数据。使用正规的属性点号标注获取和设置此类属性。注意当前实现仅支持用户定义函数属性。未来可能会增加支持内置函数属性。

    单元对象具有 cell_contents 属性。这可被用来获取以及设置单元的值。

    有关函数定义的额外信息可以从其代码对象中提取;参见下文对内部类型的描述。 cell 类型可以在 types 模块中访问。

    实例方法

    实例方法用于结合类、类实例和任何可调用对象 (通常为用户定义函数)。

    特殊的只读属性: __self__ 为类实例对象本身,__func__ 为函数对象;__doc__ 为方法的文档 (与 __func__.__doc__ 作用相同);__name__ 为方法名称 (与 __func__.__name__ 作用相同);__module__ 为方法所属模块的名称,没有则为 None

    方法还支持获取 (但不能设置) 下层函数对象的任意函数属性。

    用户定义方法对象可在获取一个类的属性时被创建 (也可能通过该类的一个实例),如果该属性为用户定义函数对象或类方法对象。

    当通过从类实例获取一个用户定义函数对象的方式创建一个实例方法对象时,类实例对象的 __self__ 属性即为该实例,并会绑定方法对象。该新建方法的 __func__ 属性就是原来的函数对象。

    当通过从类或实例获取一个类方法对象的方式创建一个实例对象时,实例对象的 __self__ 属性为该类本身,其 __func__ 属性为类方法对应的下层函数对象。

    当一个实例方法对象被调用时,会调用对应的下层函数 (__func__),并将类实例 (__self__) 插入参数列表的开头。例如,当 C 是一个包含了 f() 函数定义的类,而 xC 的一个实例,则调用 x.f(1) 就等同于调用 C.f(x, 1)

    当一个实例方法对象是衍生自一个类方法对象时,保存在 __self__ 中的 “类实例” 实际上会是该类本身,因此无论是调用 x.f(1) 还是 C.f(1) 都等同于调用 f(C,1),其中 f 为对应的下层函数。

    请注意从函数对象到实例方法对象的变换会在每一次从实例获取属性时发生。在某些情况下,一种高效的优化方式是将属性赋值给一个本地变量并调用该本地变量。还要注意这样的变换只发生于用户定义函数;其他可调用对象 (以及所有不可调用对象) 在被获取时都不会发生变换。还有一个需要关注的要点是作为一个类实例属性的用户定义函数不会被转换为绑定方法;这样的变换 仅当 函数是类属性时才会发生。

    生成器函数

    一个使用 yield 语句 的函数或方法被称作一个 生成器函数。 这样的函数在被调用时,总是返回一个可以执行函数体的迭代器对象:调用该迭代器的 iterator.__next__() 方法将会导致这个函数一直运行直到它使用 yield 语句提供了一个值为止。 当这个函数执行 return 语句或者执行到末尾时,将引发 StopIteration 异常并且这个迭代器将到达所返回的值集合的末尾。

    协程函数

    使用 async def 来定义的函数或方法就被称为 协程函数。这样的函数在被调用时会返回一个 coroutine 对象。它可能包含 await 表达式以及 async withasync for 语句。

    异步生成器函数

    使用 async def 来定义并包含 yield 语句的函数或方法就被称为 异步生成器函数。这样的函数在被调用时会返回一个异步迭代器对象,该对象可在 async for 语句中用来执行函数体。

    调用异步迭代器的 aiterator.__anext__() 方法将会返回一个 awaitable,此对象会在被等待时执行直到使用 yield 表达式输出一个值。当函数执行时到空的 return 语句或是最后一条语句时,将会引发 StopAsyncIteration 异常,异步迭代器也会到达要输出的值集合的末尾。

    内置函数

    内置函数对象是对于 C 函数的外部封装。内置函数的例子包括 len()math.sin() (math 是一个标准内置模块)。内置函数参数的数量和类型由 C 函数决定。特殊的只读属性: __doc__ 是函数的文档字符串,如果没有则为 None; __name__ 是函数的名称; __self__ 设定为 None (参见下一条目); __module__ 是函数所属模块的名称,如果没有则为 None

    内置方法

    此类型实际上是内置函数的另一种形式,只不过还包含了一个传入 C 函数的对象作为隐式的额外参数。内置方法的一个例子是 alist.append(),其中 alist 为一个列表对象。在此示例中,特殊的只读属性 __self__ 会被设为 alist 所标记的对象。

    类是可调用的。此种对象通常是作为“工厂”来创建自身的实例,类也可以有重载 __new__() 的变体类型。调用的参数会传给 __new__(),而且通常也会传给 __init__() 来初始化新的实例。

    类实例

    任意类的实例通过在所属类中定义 __call__() 方法即能成为可调用的对象。

模块

模块是 Python 代码的基本组织单元,由 导入系统 创建,由 import 语句发起调用,或者通过 importlib.import_module() 和内置的 __import__() 等函数发起调用。 模块对象具有由字典对象实现的命名空间(这是被模块中定义的函数的 __globals__ 属性引用的字典)。 属性引用被转换为该字典中的查找,例如 m.x 相当于 m.__dict__["x"]。 模块对象不包含用于初始化模块的代码对象(因为初始化完成后不需要它)。

属性赋值会更新模块的命名空间字典,例如 m.x = 1 等同于 m.__dict__["x"] = 1

预先定义的(可写)属性:

  • __name__

    模块的名称。

    __doc__

    模块的文档字符串,如果不可用则为 None

    __file__

    被加载模块所对应文件的路径名称,如果它是从文件加载的话。 对于某些类型的模块来说 __file__ 属性可能是缺失的,例如被静态链接到解释器中的 C 模块。 对于从共享库动态加载的扩展模块来说,它将是共享库文件的路径名称。

    __annotations__

    包含在模块体执行期间收集的 变量标注 的字典。

特殊的只读属性: __dict__ 为以字典对象表示的模块命名空间。

CPython implementation detail: 由于 CPython 清理模块字典的设定,当模块离开作用域时模块字典将会被清理,即使该字典还有活动的引用。想避免此问题,可复制该字典或保持模块状态以直接使用其字典。

自定义类

自定义类这种类型一般通过类定义来创建。每个类都有通过一个字典对象实现的独立命名空间。类属性引用会被转化为在此字典中查找,例如 C.x 会被转化为 C.__dict__["x"] (不过也存在一些钩子对象以允许其他定位属性的方式)。当未在其中发现某个属性名称时,会继续在基类中查找。这种基类查找使用 C3 方法解析顺序,即使存在 ‘钻石形’ 继承结构即有多条继承路径连到一个共同祖先也能保持正确的行为。有关 Python 使用的 C3 MRO 的详情可查看配合 2.3 版发布的文档 https://www.python.org/download/releases/2.3/mro/.

当一个类属性引用 (假设类名为 C) 会产生一个类方法对象时,它将转化为一个 __self__ 属性为 C 的实例方法对象。当其会产生一个静态方法对象时,它将转化为该静态方法对象所封装的对象。

类属性赋值会更新类的字典,但不会更新基类的字典。

类对象可被调用 (见上文) 以产生一个类实例 (见下文)。

特殊属性:

  • __name__

    类的名称。

    __module__

    类定义所在模块的名称。

    __dict__

    包含类命名空间的字典。

    __bases__

    包含基类的元组,按它们在基类列表中的出现先后排序。

    __doc__

    类的文档字符串,如果未定义则为 None

    __annotations__

    包含在类体执行期间收集的 变量标注 的字典。

类实例

类实例可通过调用类对象来创建 (见上文)。每个类实例都有通过一个字典对象实现的独立命名空间,属性引用会首先在此字典中查找。当未在其中发现某个属性,而实例对应的类中有该属性时,会继续在类属性中查找。如果找到的类属性为一个用户定义函数对象,它会被转化为实例方法对象,其 __self__ 属性即该实例。静态方法和类方法对象也会被转化;参见上文 “Classes” 一节。这样得到的属性可能与实际存放于类的 __dict__ 中的对象不同。如果未找到类属性,而对象对应的类具有 __getattr__() 方法,则会调用该方法来满足查找要求。

属性赋值和删除会更新实例的字典,但不会更新对应类的字典。如果类具有 __setattr__()__delattr__() 方法,则将调用方法而不再直接更新实例的字典。

如果类实例具有某些特殊名称的方法,就可以伪装为数字、序列或映射。

特殊属性: __dict__ 为属性字典; __class__ 为实例对应的类。

I/O 对象 (或称文件对象)

file object 表示一个打开的文件。有多种快捷方式可用来创建文件对象: open() 内置函数,以及 os.popen(), os.fdopen() 和 socket 对象的 makefile() 方法 (还可能使用某些扩展模块所提供的其他函数或方法)。

sys.stdin, sys.stdoutsys.stderr 会初始化为对应于解释器标准输入、输出和错误流的文件对象;它们都会以文本模式打开,因此都遵循 io.TextIOBase 抽象类所定义的接口。

内部类型

某些由解释器内部使用的类型也被暴露给用户。它们的定义可能随未来解释器版本的更新而变化,为内容完整起见在此处一并介绍。

  • 代码对象

    代码对象表示 编译为字节的 可执行 Python 代码,或称 bytecode。代码对象和函数对象的区别在于函数对象包含对函数全局对象 (函数所属的模块) 的显式引用,而代码对象不包含上下文;而且默认参数值会存放于函数对象而不是代码对象内 (因为它们表示在运行时算出的值)。与函数对象不同,代码对象不可变,也不包含对可变对象的引用 (不论是直接还是间接)。

    特殊的只读属性: co_name 给出了函数名; co_argcount 为位置参数的总数量 (包括仅限位置参数和带有默认值的参数); co_posonlyargcount 为仅限位置参数的数量 (包括带有默认值的参数); co_kwonlyargcount 为仅限关键字参数的数量 (包括带有默认值的参数); co_nlocals 为函数使用的局部变量的数量 (包括参数); co_varnames 为一个包含局部变量名称的元组 (参数名排在最前面); co_cellvars 为一个包含被嵌套函数所引用的局部变量名称的元组; co_freevars 为一个包含自由变量名称的元组; co_code 为一个表示字节码指令序列的字符口中; co_consts 为一个包含字节码所使用的字面值的元组; co_names 为一个包含字节码所使用的名称的元组; co_filename 为被编码代码所在的文件名; co_firstlineno 为函数首行的行号; co_lnotab 为一个字符串,其中编码了从字节码偏移量到行号的映射 (详情参见解释器的源代码); co_stacksize 为要求的栈大小; co_flags 为一个整数,其中编码了解释器所用的多个旗标。

    以下是可用于 co_flags 的标志位定义:如果函数使用 *arguments 语法来接受任意数量的位置参数,则 0x04 位被设置;如果函数使用 **keywords 语法来接受任意数量的关键字参数,则 0x08 位被设置;如果函数是一个生成器,则 0x20 位被设置。

    未来特性声明 (from __future__ import division) 也使用 co_flags 中的标志位来指明代码对象的编译是否启用特定的特性: 如果函数编译时启用未来除法特性则设置 0x2000 位; 在更早的 Python 版本中则使用 0x100x1000 位。

    co_flags 中的其他位被保留为内部使用。

    如果代码对象表示一个函数,co_consts 中的第一项将是函数的文档字符串,如果未定义则为 None

  • 帧对象

    帧对象表示执行帧。它们可能出现在回溯对象中 (见下文),还会被传递给注册跟踪函数。

    特殊的只读属性: f_back 为前一堆栈帧 (指向调用者),如是最底层堆栈帧则为 None; f_code 为此帧中所执行的代码对象; f_locals 为用于查找本地变量的字典; f_globals 则用于查找全局变量; f_builtins 用于查找内置 (固有) 名称; f_lasti 给出精确指令 (这是代码对象的字节码字符串的一个索引)。

    访问 f_code 会引发一个 审计事件 object.__getattr__,附带参数 obj"f_code"

    特殊的可写属性: f_trace,如果不为 None,则是在代码执行期间调用各类事件的函数 (由调试器使用)。通常每个新源码行会触发一个事件 - 这可以通过将 f_trace_lines 设为 False 来禁用。

    具体的实现 可能 会通过将 f_trace_opcodes 设为 True 来允许按操作码请求事件。请注意如果跟踪函数引发的异常逃逸到被跟踪的函数中,这可能会导致未定义的解释器行为。

    f_lineno 为帧的当前行号 —- 在这里写入从一个跟踪函数内部跳转的指定行 (仅用于最底层的帧)。调试器可以通过写入 f_lineno 实现一个 Jump 命令 (即设置下一语句)。

    帧对象支持一个方法:

    • frame.clear()

      此方法清除该帧持有的全部对本地变量的引用。而且如果该帧属于一个生成器,生成器会被完成。这有助于打破包含帧对象的循环引用 (例如当捕获一个异常并保存其回溯在之后使用)。

      如果该帧当前正在执行则会引发 RuntimeError

      3.4 新版功能.

  • 回溯对象

    回溯对象表示一个异常的栈跟踪记录。当异常发生时会隐式地创建一个回溯对象,也可能通过调用 types.TracebackType 显式地创建。

    对于隐式地创建的回溯对象,当查找异常句柄使得执行栈展开时,会在每个展开层级的当前回溯之前插入一个回溯对象。当进入一个异常句柄时,栈跟踪将对程序启用。 它可作为 sys.exc_info() 所返回的元组的第三项,以及所捕获异常的 __traceback__ 属性被获取。

    当程序不包含可用的句柄时,栈跟踪会 (以良好的格式) 写入标准错误流;如果解释器处于交互模式,它也可作为 sys.last_traceback 对用户启用。

    对于显式创建的回溯对象,则由回溯对象的创建者来决定应该如何链接 tb_next 属性来构成完整的栈跟踪。

    特殊的只读属性: tb_frame 指向当前层级的执行帧; tb_lineno 给出发生异常所在的行号; tb_lasti 标示具体指令。如果异常发生于没有匹配的 except 子句或有 finally 子句的 try 语句中,回溯对象中的行号和最后指令可能与相应帧对象中行号不同。

    访问 tb_frame 会引发一个 审计事件 object.__getattr__,附带参数 obj"tb_frame"

    特殊的可写属性: tb_next 为栈跟踪中的下一层级 (通往发生异常的帧),如果没有下一层级则为 None

    在 3.7 版更改: 回溯对象现在可以使用 Python 代码显式地实例化,现有实例的 tb_next 属性可以被更新。

    切片对象

    切片对象用来表示 __getitem__() 方法用到的切片。 该对象也可使用内置的 slice() 函数来创建。

    特殊的只读属性: start 为下界; stop 为上界; step 为步长值; 各值如省略则为 None。这些属性可具有任意类型。

    切片对象支持一个方法:

    • slice.indices(self, length)

      此方法接受一个整型参数 length 并计算在切片对象被应用到 length 指定长度的条目序列时切片的相关信息应如何描述。 其返回值为三个整型数组成的元组;这些数分别为切片的 startstop 索引号以及 step 步长值。索引号缺失或越界则按照与正规切片相一致的方式处理。

    静态方法对象

    静态方法对象提供了一种胜过上文所述将函数对象转换为方法对象的方式。 静态方法对象是对任意其他对象的包装器,通常用来包装用户自定义的方法对象。 当从类或类实例获取一个静态方法对象时,实际返回的是经过包装的对象,它不会被进一步转换。 静态方法对象也是可调用对象。 静态方法对象可通过内置的 staticmethod() 构造器来创建。

    类方法对象

    类方法对象和静态方法一样是对其他对象的封装,会改变从类或类实例获取该对象的方式。类方法对象在此类获取操作中的行为已在上文 “用户定义方法” 一节中描述。类方法对象可通过内置的 classmethod() 构造器来创建。

3.3. 特殊方法名称

一个类可以通过定义具有特殊名称的方法来实现由特殊语法所引发的特定操作 (例如算术运算或下标与切片)。这是 Python 实现 操作符重载 的方式,允许每个类自行定义基于操作符的特定行为。例如,如果一个类定义了名为 __getitem__() 的方法,并且 x 为该类的一个实例,则 x[i] 基本就等同于 type(x).__getitem__(x, i)。除非有说明例外情况,在没有定义适当方法的情况下尝试执行一种操作将引发一个异常 (通常为 AttributeErrorTypeError)。

将一个特殊方法设为 None 表示对应的操作不可用。例如,如果一个类将 __iter__() 设为 None,则该类就是不可迭代的,因此对其实例调用 iter() 将引发一个 TypeError (而不会回退至 __getitem__()).

在实现模拟任何内置类型的类时,很重要的一点是模拟的实现程度对于被模拟对象来说应当是有意义的。例如,提取单个元素的操作对于某些序列来说是适宜的,但提取切片可能就没有意义。(这种情况的一个实例是 W3C 的文档对象模型中的 NodeList 接口。)

3.3.1. 基本定制

object.__new__(cls[, ])

调用以创建一个 cls 类的新实例。__new__() 是一个静态方法 (因为是特例所以你不需要显式地声明),它会将所请求实例所属的类作为第一个参数。其余的参数会被传递给对象构造器表达式 (对类的调用)。__new__() 的返回值应为新对象实例 (通常是 cls 的实例)。

典型的实现会附带适宜的参数使用 super().__new__(cls[, ...]),通过超类的 __new__() 方法来创建一个类的新实例,然后根据需要修改新创建的实例再将其返回。

If __new__() is invoked during object construction and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor.

如果 __new__() 未返回一个 cls 的实例,则新实例的 __init__() 方法就不会被执行。

__new__() 的目的主要是允许不可变类型的子类 (例如 int, str 或 tuple) 定制实例创建过程。它也常会在自定义元类中被重载以便定制类创建过程。

object.__init__(self[, ])

在实例 (通过 __new__()) 被创建之后,返回调用者之前调用。其参数与传递给类构造器表达式的参数相同。一个基类如果有 __init__() 方法,则其所派生的类如果也有 __init__() 方法,就必须显式地调用它以确保实例基类部分的正确初始化;例如: super().__init__([args...]).

因为对象是由 __new__()__init__() 协作构造完成的 (由 __new__() 创建,并由 __init__() 定制),所以 __init__() 返回的值只能是 None,否则会在运行时引发 TypeError

object.__del__(self)

在实例将被销毁时调用。 这还被称为终结器或析构器(不适当)。 如果一个基类具有 __del__() 方法,则其所派生的类如果也有 __del__() 方法,就必须显式地调用它以确保实例基类部分的正确清除。

__del__() 方法可以 (但不推荐!) 通过创建一个该实例的新引用来推迟其销毁。这被称为对象 重生__del__() 是否会在重生的对象将被销毁时再次被调用是由具体实现决定的 ;当前的 CPython 实现只会调用一次。

当解释器退出时不会确保为仍然存在的对象调用 __del__() 方法。

注解

del x 并不直接调用 x.__del__() —- 前者会将 x 的引用计数减一,而后者仅会在 x 的引用计数变为零时被调用。

CPython implementation detail: It is possible for a reference cycle to prevent the reference count of an object from going to zero. In this case, the cycle will be later detected and deleted by the cyclic garbage collector. A common cause of reference cycles is when an exception has been caught in a local variable. The frame’s locals then reference the exception, which references its own traceback, which references the locals of all frames caught in the traceback.

警告

由于调用 __del__() 方法时周边状况已不确定,在其执行期间发生的异常将被忽略,改为打印一个警告到 sys.stderr。特别地:

  • __del__() 可在任意代码被执行时启用,包括来自任意线程的代码。如果 __del__() 需要接受锁或启用其他阻塞资源,可能会发生死锁,例如该资源已被为执行 __del__() 而中断的代码所获取。
  • __del__() 可以在解释器关闭阶段被执行。因此,它需要访问的全局变量(包含其他模块)可能已被删除或设为 None。Python 会保证先删除模块中名称以单个下划线打头的全局变量再删除其他全局变量;如果已不存在其他对此类全局变量的引用,这有助于确保导入的模块在 __del__() 方法被调用时仍然可用。

object.__repr__(self)

repr() 内置函数调用以输出一个对象的“官方”字符串表示。如果可能,这应类似一个有效的 Python 表达式,能被用来重建具有相同取值的对象(只要有适当的环境)。如果这不可能,则应返回形式如 <...some useful description...> 的字符串。返回值必须是一个字符串对象。如果一个类定义了 __repr__() 但未定义 __str__(),则在需要该类的实例的“非正式”字符串表示时也会使用 __repr__()

此方法通常被用于调试,因此确保其表示的内容包含丰富信息且无歧义是很重要的。

object.__str__(self)

通过 str(object) 以及内置函数 format()print() 调用以生成一个对象的“非正式”或格式良好的字符串表示。返回值必须为一个 字符串 对象。

此方法与 object.__repr__() 的不同点在于 __str__() 并不预期返回一个有效的 Python 表达式:可以使用更方便或更准确的描述信息。

内置类型 object 所定义的默认实现会调用 object.__repr__()

object.__bytes__(self)

通过 bytes 调用以生成一个对象的字节串表示。这应该返回一个 bytes 对象。

object.__format__(self, format_spec)

通过 format() 内置函数、扩展、格式化字符串字面值 的求值以及 str.format() 方法调用以生成一个对象的“格式化”字符串表示。 format_spec 参数为包含所需格式选项描述的字符串。 format_spec 参数的解读是由实现 __format__() 的类型决定的,不过大多数类或是将格式化委托给某个内置类型,或是使用相似的格式化选项语法。

返回值必须为一个字符串对象。

在 3.4 版更改: object 本身的 format 方法如果被传入任何非空字符,将会引发一个 TypeError

在 3.7 版更改: object.__format__(x, '') 现在等同于 str(x) 而不再是 format(str(x), '')

object.__lt__(self, other)

object.__le__(self, other)

object.__eq__(self, other)

object.__ne__(self, other)

object.__gt__(self, other)

object.__ge__(self, other)

以上这些被称为“富比较”方法。运算符号与方法名称的对应关系如下:x<y 调用 x.__lt__(y)x<=y 调用 x.__le__(y)x==y 调用 x.__eq__(y)x!=y 调用 x.__ne__(y)x>y 调用 x.__gt__(y)x>=y 调用 x.__ge__(y)

如果指定的参数对没有相应的实现,富比较方法可能会返回单例对象 NotImplemented。按照惯例,成功的比较会返回 FalseTrue。不过实际上这些方法可以返回任意值,因此如果比较运算符是要用于布尔值判断(例如作为 if 语句的条件),Python 会对返回值调用 bool() 以确定结果为真还是假。

在默认情况下,object 通过使用 is 来实现 __eq__(),并在比较结果为假值时返回 NotImplemented: True if x is y else NotImplemented。 对于 __ne__(),默认会委托给 __eq__() 并对结果取反,除非结果为 NotImplemented。 比较运算符之间没有其他隐含关系或默认实现;例如,(x<y or x==y) 为真并不意味着 x<=y

这些方法并没有对调参数版本(在左边参数不支持该操作但右边参数支持时使用);而是 __lt__()__gt__() 互为对方的反射, __le__()__ge__() 互为对方的反射,而 __eq__()__ne__() 则是它们自己的反射。如果两个操作数的类型不同,且右操作数类型是左操作数类型的直接或间接子类,则优先选择右操作数的反射方法,否则优先选择左操作数的方法。虚拟子类不会被考虑。

object.__hash__(self)

通过内置函数 hash() 调用以对哈希集的成员进行操作,属于哈希集的类型包括 setfrozenset 以及 dict__hash__() 应该返回一个整数。对象比较结果相同所需的唯一特征属性是其具有相同的哈希值;建议的做法是把参与比较的对象全部组件的哈希值混在一起,即将它们打包为一个元组并对该元组做哈希运算。例如:

def __hash__(self):    
    return hash((self.name, self.nick, self.color))

注解

hash() 会从一个对象自定义的 __hash__() 方法返回值中截断为 Py_ssize_t 的大小。通常对 64 位构建为 8 字节,对 32 位构建为 4 字节。如果一个对象的 __hash__() 必须在不同位大小的构建上进行互操作,请确保检查全部所支持构建的宽度。做到这一点的简单方法是使用 python -c "import sys; print(sys.hash_info.width)"

如果一个类没有定义 __eq__() 方法,那么也不应该定义 __hash__() 操作;如果它定义了 __eq__() 但没有定义 __hash__(),则其实例将不可被用作可哈希集的项。如果一个类定义了可变对象并实现了 __eq__() 方法,则不应该实现 __hash__(),因为可哈希集的实现要求键的哈希集是不可变的(如果对象的哈希值发生改变,它将处于错误的哈希桶中)。

用户定义的类默认带有 __eq__()__hash__() 方法;使用它们与任何对象(自己除外)比较必定不相等,并且 x.__hash__() 会返回一个恰当的值以确保 x == y 同时意味着 x is yhash(x) == hash(y)

一个类如果重载了 __eq__() 且没有定义 __hash__() 则会将其 __hash__() 隐式地设为 None。当一个类的 __hash__() 方法为 None 时,该类的实例将在一个程序尝试获取其哈希值时正确地引发 TypeError,并会在检测 isinstance(obj, collections.abc.Hashable) 时被正确地识别为不可哈希对象。

如果一个重载了 __eq__() 的类需要保留来自父类的 __hash__() 实现,则必须通过设置 __hash__ = <ParentClass>.__hash__ 来显式地告知解释器。

如果一个没有重载 __eq__() 的类需要去掉哈希支持,则应该在类定义中包含 __hash__ = None。一个自定义了 __hash__() 以显式地引发 TypeError 的类会被 isinstance(obj, collections.abc.Hashable) 调用错误地识别为可哈希对象。

注解

在默认情况下,str 和 bytes 对象的 __hash__() 值会使用一个不可预知的随机值“加盐”。 虽然它们在一个单独 Python 进程中会保持不变,但它们的值在重复运行的 Python 间是不可预测的。

This is intended to provide protection against a denial-of-service caused by carefully-chosen inputs that exploit the worst case performance of a dict insertion, O(n2) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

改变哈希值会影响集合的迭代次序。Python 也从不保证这个次序不会被改变(通常它在 32 位和 64 位构建上是不一致的)。

在 3.3 版更改: 默认启用哈希随机化。

object.__bool__(self)

调用此方法以实现真值检测以及内置的 bool() 操作;应该返回 FalseTrue。如果未定义此方法,则会查找并调用 __len__() 并在其返回非零值时视对象的逻辑值为真。如果一个类既未定义 __len__() 也未定义 __bool__() 则视其所有实例的逻辑值为真。

3.3.2. 自定义属性访问

可以定义下列方法来自定义对类实例属性访问(x.name 的使用、赋值或删除)的具体含义.

object.__getattr__(self, name)

当默认属性访问因引发 AttributeError 而失败时被调用 (可能是调用 __getattribute__() 时由于 name 不是一个实例属性或 self 的类关系树中的属性而引发了 AttributeError;或者是对 name 特性属性调用 __get__() 时引发了 AttributeError)。此方法应当返回(找到的)属性值或是引发一个 AttributeError 异常。

请注意如果属性是通过正常机制找到的,__getattr__() 就不会被调用。(这是在 __getattr__()__setattr__() 之间故意设置的不对称性。)这既是出于效率理由也是因为不这样设置的话 __getattr__() 将无法访问实例的其他属性。要注意至少对于实例变量来说,你不必在实例属性字典中插入任何值(而是通过插入到其他对象)就可以模拟对它的完全控制。请参阅下面的 __getattribute__() 方法了解真正获取对属性访问的完全控制权的办法。

object.__getattribute__(self, name)

此方法会无条件地被调用以实现对类实例属性的访问。如果类还定义了 __getattr__(),则后者不会被调用,除非 __getattribute__() 显式地调用它或是引发了 AttributeError。此方法应当返回(找到的)属性值或是引发一个 AttributeError 异常。为了避免此方法中的无限递归,其实现应该总是调用具有相同名称的基类方法来访问它所需要的任何属性,例如 object.__getattribute__(self, name)

注解

此方法在作为通过特定语法或内置函数隐式地调用的结果的情况下查找特殊方法时仍可能会被跳过。

引发一个 审计事件 object.__getattr__,附带参数 obj, name

object.__setattr__(self, name, value)

此方法在一个属性被尝试赋值时被调用。这个调用会取代正常机制(即将值保存到实例字典)。 name 为属性名称, value 为要赋给属性的值。

如果 __setattr__() 想要赋值给一个实例属性,它应该调用同名的基类方法,例如 object.__setattr__(self, name, value)

引发一个 审计事件 object.__setattr__,附带参数 obj, name, value

object.__delattr__(self, name)

类似于 __setattr__() 但其作用为删除而非赋值。此方法应该仅在 del obj.name 对于该对象有意义时才被实现。

引发一个 审计事件 object.__delattr__,附带参数 obj, name

object.__dir__(self)

此方法会在对相应对象调用 dir() 时被调用。返回值必须为一个序列。 dir() 会把返回的序列转换为列表并对其排序。

3.3.2.1. 自定义模块属性访问

特殊名称 __getattr____dir__ 还可被用来自定义对模块属性的访问。模块层级的 __getattr__ 函数应当接受一个参数,其名称为一个属性名,并返回计算结果值或引发一个 AttributeError。如果通过正常查找即 object.__getattribute__() 未在模块对象中找到某个属性,则 __getattr__ 会在模块的 __dict__ 中查找,未找到时会引发一个 AttributeError。如果找到,它会以属性名被调用并返回结果值。

__dir__ 函数应当不接受任何参数,并且返回一个表示模块中可访问名称的字符串序列。 此函数如果存在,将会重载一个模块中的标准 dir() 查找。

想要更细致地自定义模块的行为(设置属性和特性属性等待),可以将模块对象的 __class__ 属性设置为一个 types.ModuleType 的子类。例如:

import sys
from types import ModuleType
class VerboseModule(ModuleType):
    def __repr__(self):
        return f'Verbose {self.__name__}'
    def __setattr__(self, attr, value):
        print(f'Setting {attr}...')
        super().__setattr__(attr, value)
sys.modules[__name__].__class__ = VerboseModule

注解

定义模块的 __getattr__ 和设置模块的 __class__ 只会影响使用属性访问语法进行的查找 — 直接访问模块全局变量(不论是通过模块内的代码还是通过对模块全局字典的引用)是不受影响的。

在 3.5 版更改: __class__ 模块属性改为可写。

3.7 新版功能: __getattr____dir__ 模块属性。

参见

PEP 562 - 模块 getattrdir

描述用于模块的 __getattr____dir__ 函数。

3.3.2.2. 实现描述器

以下方法仅当一个包含该方法的类(称为 描述器 类)的实例出现于一个 所有者 类中的时候才会起作用(该描述器必须在所有者类或其某个上级类的字典中)。在以下示例中,“属性”指的是名称为所有者类 __dict__ 中的特征属性的键名的属性。

object.__get__(self, instance, owner=None)

调用此方法以获取所有者类的属性(类属性访问)或该类的实例的属性(实例属性访问)。 可选的 owner 参数是所有者类而 instance 是被用来访问属性的实例,如果通过 owner 来访问属性则返回 None

此方法应当返回计算得到的属性值或是引发 AttributeError 异常。

PEP 252 指明 __get__() 为带有一至二个参数的可调用对象。 Python 自身内置的描述器支持此规格定义;但是,某些第三方工具可能要求必须带两个参数。 Python 自身的 __getattribute__() 实现总是会传入两个参数,无论它们是否被要求提供。

object.__set__(self, instance, value)

调用此方法以设置 instance 指定的所有者类的实例的属性为新值 value

请注意,添加 __set__()__delete__() 会将描述器变成“数据描述器”。

object.__delete__(self, instance)

调用此方法以删除 instance 指定的所有者类的实例的属性。

属性 __objclass__ 会被 inspect 模块解读为指定此对象定义所在的类(正确设置此属性有助于动态类属性的运行时内省)。对于可调用对象来说,它可以指明预期或要求提供一个特定类型(或子类)的实例作为第一个位置参数(例如,CPython 会为实现于 C 中的未绑定方法设置此属性)。

3.3.2.3. 调用描述器

总的说来,描述器就是具有“绑定行为”的对象属性,其属性访问已被描述器协议中的方法所重载,包括 __get__(), __set__()__delete__()。如果一个对象定义了以上方法中的任意一个,它就被称为描述器。

属性访问的默认行为是从一个对象的字典中获取、设置或删除属性。例如,a.x 的查找顺序会从 a.__dict__['x'] 开始,然后是 type(a).__dict__['x'],接下来依次查找 type(a) 的上级基类,不包括元类。

但是,如果找到的值是定义了某个描述器方法的对象,则 Python 可能会重载默认行为并转而发起调用描述器方法。这具体发生在优先级链的哪个环节则要根据所定义的描述器方法及其被调用的方式来决定。

描述器发起调用的开始点是一个绑定 a.x。参数的组合方式依 a 而定:

直接调用

最简单但最不常见的调用方式是用户代码直接发起调用一个描述器方法: x.__get__(a)

实例绑定

如果绑定到一个对象实例,a.x 会被转换为调用: type(a).__dict__['x'].__get__(a, type(a))

类绑定

如果绑定到一个类,A.x 会被转换为调用: A.__dict__['x'].__get__(None, A)

超绑定

如果 asuper 的一个实例,则绑定 super(B, obj).m() 会在 obj.__class__.__mro__ 中搜索 B 的直接上级基类 A 然后通过以下调用发起调用描述器: A.__dict__['m'].__get__(obj, obj.__class__)

对于实例绑定,发起描述器调用的优先级取决于定义了哪些描述器方法。 一个描述器可以定义 __get__(), __set__()__delete__() 的任意组合。 如果它没有定义 __get__(),则访问属性将返回描述器对象自身,除非对象的实例字典中有相应属性值。 如果描述器定义了 __set__() 和/或 __delete__(),则它是一个数据描述器;如果以上两种都未定义,则它是一个非数据描述器。 通常,数据描述器会同时定义 __get__()__set__(),而非数据描述器则只有 __get__() 方法。 定义了 __get__()__set__() (和/或 __delete__()) 的数据描述器总是会重载实例字典中的定义。 与之相对地,非数据描述器则可被实例所重载。

Python 方法 (包括 staticmethod()classmethod()) 都是作为非数据描述器来实现的。 因此实例可以重定义并重载方法。 这允许单个实例获得与相同类的其他实例不一样的行为。

property() 函数是作为数据描述器来实现的。因此实例不能重载特性属性的行为。

3.3.2.4. slots

slots 允许我们显式地声明数据成员(例如特征属性)并禁止创建 dictweakref (除非是在 slots 中显式地声明或是在父类中可用。)

相比使用 dict 此方式可以显著地节省空间。 属性查找速度也可得到显著的提升。

object.__slots__

这个类变量可赋值为字符串、可迭代对象或由实例使用的变量名构成的字符串序列。 slots 会为已声明的变量保留空间,并阻止自动为每个实例创建 dictweakref

使用 slots 的注意事项

  • 当继承自一个未定义 slots 的类时,实例的 dictweakref 属性将总是可访问。
  • 没有 dict 变量,实例就不能给未在 slots 定义中列出的新变量赋值。尝试给一个未列出的变量名赋值将引发 AttributeError。新变量需要动态赋值,就要将 '__dict__' 加入到 slots 声明的字符串序列中。
  • 如果未给每个实例设置 weakref 变量,定义了 slots 的类就不支持对其实际的弱引用。如果需要弱引用支持,就要将 '__weakref__' 加入到 slots 声明的字符串序列中。
  • slots 是通过为每个变量名创建描述器 (实现描述器) 在类层级上实现的。因此,类属性不能被用来为通过 slots 定义的实例变量设置默认值;否则,类属性就会覆盖描述器赋值。
  • slots 声明的作用不只限于定义它的类。在父类中声明的 slots 在其子类中同样可用。不过,子类将会获得 dictweakref 除非它们也定义了 slots (其中应该仅包含对任何 额外 名称的声明位置)。
  • 如果一个类定义的位置在某个基类中也有定义,则由基类位置定义的实例变量将不可访问(除非通过直接从基类获取其描述器的方式)。这会使得程序的含义变成未定义。未来可能会添加一个防止此情况的检查。
  • 非空的 slots 不适用于派生自“可变长度”内置类型例如 intbytestuple 的派生类。
  • 任何非字符串可迭代对象都可以被赋值给 slots。映射也可以被使用;不过,未来可能会分别赋给每个键具有特殊含义的值。
  • class 赋值仅在两个类具有相同的 slots 时才会起作用。
  • 带有多个父类声明位置的多重继承也是可用的,但仅允许一个父类具有由声明位置创建的属性(其他基类必须具有空的位置布局) —— 违反规则将引发 TypeError
  • 如果为 slots 使用了一个迭代器,则会为迭代器的每个值创建描述器。 但是 slots 属性将为一个空迭代器。

3.3.3. 自定义类创建

当一个类继承其他类时,那个类的 init_subclass 会被调用。这样就可以编写能够改变子类行为的类。这与类装饰器有紧密的关联,但是类装饰器是影响它们所应用的特定类,而 __init_subclass__ 则只作用于定义了该方法的类所派生的子类。

classmethod object.__init_subclass__(cls)

当所在类派生子类时此方法就会被调用。cls 将指向新的子类。如果定义为一个普通实例方法,此方法将被隐式地转换为类方法。

传入一个新类的关键字参数会被传给父类的 __init_subclass__。为了与其他使用 __init_subclass__ 的类兼容,应当根据需要去掉部分关键字参数再将其余的传给基类,例如:

class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name
class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass

object.__init_subclass__ 的默认实现什么都不做,只在带任意参数调用时引发一个错误。

注解

元类提示 metaclass 将被其它类型机制消耗掉,并不会被传给 __init_subclass__ 的实现。实际的元类(而非显式的提示)可通过 type(cls) 访问。

3.6 新版功能.

When a class is created, type.__new__() scans the class variables and makes callbacks to those with a __set_name__() hook.

object.__set_name__(self, owner, name)

Automatically called at the time the owning class owner is created. The object has been assigned to name in that class:

class A:
    x = C()  # Automatically calls: x.__set_name__(A, 'x')

If the class variable is assigned after the class is created, __set_name__() will not be called automatically. If needed, __set_name__() can be called directly:

class A:
   pass
c = C()
A.x = c                  # The hook is not called
c.__set_name__(A, 'x')   # Manually invoke the hook

3.6 新版功能.

3.3.3.1. 元类

默认情况下,类是使用 type() 来构建的。类体会在一个新的命名空间内执行,类名会被局部绑定到 type(name, bases, namespace) 的结果。

类创建过程可通过在定义行传入 metaclass 关键字参数,或是通过继承一个包含此参数的现有类来进行定制。在以下示例中,MyClassMySubclass 都是 Meta 的实例:

class Meta(type):
    pass
class MyClass(metaclass=Meta):
    pass
class MySubclass(MyClass):
    pass

在类定义内指定的任何其他关键字参数都会在下面所描述的所有元类操作中进行传递。

当一个类定义被执行时,将发生以下步骤:

  • 解析 MRO 条目;
  • 确定适当的元类;
  • 准备类命名空间;
  • 执行类主体;
  • 创建类对象。
3.3.3.2. 解析 MRO 条目

如果在类定义中出现的基类不是 type 的实例,则使用 __mro_entries__ 方法对其进行搜索,当找到结果时,它会以原始基类元组做参数进行调用。此方法必须返回类的元组以替代此基类被使用。元组可以为空,在此情况下原始基类将被忽略。

参见

PEP 560 - 对 typing 模块和泛型类型的核心支持

3.3.3.3. 确定适当的元类

为一个类定义确定适当的元类是根据以下规则:

  • 如果没有基类且没有显式指定元类,则使用 type()
  • 如果给出一个显式元类而且 不是 type() 的实例,则其会被直接用作元类;
  • 如果给出一个 type() 的实例作为显式元类,或是定义了基类,则使用最近派生的元类。

最近派生的元类会从显式指定的元类(如果有)以及所有指定的基类的元类(即 type(cls))中选取。最近派生的元类应为 所有 这些候选元类的一个子类型。如果没有一个候选元类符合该条件,则类定义将失败并抛出 TypeError

3.3.3.4. 准备类命名空间

一旦确定了适当的元类,则将准备好类命名空间。 如果元类具有 __prepare__ 属性,它会以 namespace = metaclass.__prepare__(name, bases, **kwds) 的形式被调用(其中如果有任何额外的关键字参数,则应当来自类定义)。 __prepare__ 方法应该被实现为 classmethod()__prepare__ 所返回的命名空间会被传入 __new__,但是当最终的类对象被创建时,该命名空间会被拷贝到一个新的 dict 中。

如果元类没有 __prepare__ 属性,则类命名空间将初始化为一个空的有序映射。

参见

PEP 3115 - Python 3000 中的元类

引入 __prepare__ 命名空间钩子

3.3.3.5. 执行类主体

类主体会以(类似于) exec(body, globals(), namespace) 的形式被执行。普通调用与 exec() 的关键区别在于当类定义发生于函数内部时,词法作用域允许类主体(包括任何方法)引用来自当前和外部作用域的名称。

但是,即使当类定义发生于函数内部时,在类内部定义的方法仍然无法看到在类作用域层次上定义的名称。类变量必须通过实例的第一个形参或类方法来访问,或者是通过下一节中描述的隐式词法作用域的 __class__ 引用。

3.3.3.6. 创建类对象

一旦执行类主体完成填充类命名空间,将通过调用 metaclass(name, bases, namespace, **kwds) 创建类对象(此处的附加关键字参数与传入 __prepare__ 的相同)。

如果类主体中有任何方法引用了 __class__super,这个类对象会通过零参数形式的 super(). __class__ 所引用,这是由编译器所创建的隐式闭包引用。这使用零参数形式的 super() 能够正确标识正在基于词法作用域来定义的类,而被用于进行当前调用的类或实例则是基于传递给方法的第一个参数来标识的。

CPython implementation detail: 在 CPython 3.6 及之后的版本中,__class__ 单元会作为类命名空间中的 __classcell__ 条目被传给元类。 如果存在,它必须被向上传播给 type.__new__ 调用,以便能正确地初始化该类。 如果不这样做,在 Python 3.8 中将引发 RuntimeError

When using the default metaclass type, or any metaclass that ultimately calls type.__new__, the following additional customization steps are invoked after creating the class object:

  1. The type.__new__ method collects all of the attributes in the class namespace that define a __set_name__() method;
  2. Those __set_name__ methods are called with the class being defined and the assigned name of that particular attribute;
  3. The __init_subclass__() hook is called on the immediate parent of the new class in its method resolution order.

在类对象创建之后,它会被传给包含在类定义中的类装饰器(如果有的话),得到的对象将作为已定义的类绑定到局部命名空间。

当通过 type.__new__ 创建一个新类时,提供以作为命名空间形参的对象会被复制到一个新的有序映射并丢弃原对象。这个新副本包装于一个只读代理中,后者则成为类对象的 __dict__ 属性。

参见

PEP 3135 - 新的超类型

描述隐式的 __class__ 闭包引用

3.3.3.7. 元类的作用

元类的潜在作用非常广泛。已经过尝试的设想包括枚举、日志、接口检查、自动委托、自动特征属性创建、代理、框架以及自动资源锁定/同步等等。

3.3.4. 自定义实例及子类检查

以下方法被用来重载 isinstance()issubclass() 内置函数的默认行为。

特别地,元类 abc.ABCMeta 实现了这些方法以便允许将抽象基类(ABC)作为“虚拟基类”添加到任何类或类型(包括内置类型),包括其他 ABC 之中。

class.__instancecheck__(self, instance)

如果 instance 应被视为 class 的一个(直接或间接)实例则返回真值。如果定义了此方法,则会被调用以实现 isinstance(instance, class)

class.__subclasscheck__(self, subclass)

Return true 如果 subclass 应被视为 class 的一个(直接或间接)子类则返回真值。如果定义了此方法,则会被调用以实现 issubclass(subclass, class)

请注意这些方法的查找是基于类的类型(元类)。它们不能作为类方法在实际的类中被定义。这与基于实例被调用的特殊方法的查找是一致的,只有在此情况下实例本身被当作是类。

参见

PEP 3119 - 引入抽象基类

新增功能描述,通过 __instancecheck__()__subclasscheck__() 来定制 isinstance()issubclass() 行为,加入此功能的动机是出于向该语言添加抽象基类的内容。

3.3.5. 模拟泛型类型

通过定义一个特殊方法,可以实现由 PEP 484 所规定的泛型类语法 (例如 List[int]):

classmethod object.__class_getitem__(cls, key)

按照 key 参数指定的类型返回一个表示泛型类的专门化对象。

此方法的查找会基于对象自身,并且当定义于类体内部时,此方法将隐式地成为类方法。请注意,此机制主要是被保留用于静态类型提示,不鼓励在其他场合使用。

参见

PEP 560 - 对 typing 模块和泛型类型的核心支持

3.3.6. 模拟可调用对象

object.__call__(self[, args…])

此方法会在实例作为一个函数被“调用”时被调用;如果定义了此方法,则 x(arg1, arg2, ...) 就大致可以被改写为 type(x).__call__(x, arg1, ...)

3.3.7. 模拟容器类型

可以定义下列方法来实现容器对象。 容器通常属于序列(如列表或元组)或映射(如字典),但也存在其他形式的容器。 前几个方法集被用于模拟序列或是模拟映射;两者的不同之处在于序列允许的键应为整数 k0 <= k < N 其中 N 是序列或定义指定区间的项的切片对象的长度。 此外还建议让映射提供 keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy() 以及 update() 等方法,它们的行为应与 Python 标准字典对象的相应方法类似。 此外 collections.abc 模块提供了一个 MutableMapping 抽象基类以便根据由 __getitem__(), __setitem__(), __delitem__(), 和 keys() 组成的基本集来创建所需的方法。 可变序列还应像 Python 标准列表对象那样提供 append(), count(), index(), extend(), insert(), pop(), remove(), reverse()sort() 等方法。 最后,序列类型还应通过定义下文描述的 __add__(), __radd__(), __iadd__(), __mul__(), __rmul__()__imul__() 等方法来实现加法(指拼接)和乘法(指重复);它们不应定义其他数值运算符。 此外还建议映射和序列都实现 __contains__() 方法以允许高效地使用 in 运算符;对于映射,in 应该搜索映射的键;对于序列,则应搜索其中的值。 另外还建议映射和序列都实现 __iter__() 方法以允许高效地迭代容器中的条目;对于映射,__iter__() 应当迭代对象的键;对于序列,则应当迭代其中的值。

object.__len__(self)

调用此方法以实现内置函数 len()。应该返回对象的长度,以一个 >= 0 的整数表示。此外,如果一个对象未定义 __bool__() 方法而其 __len__() 方法返回值为零,则在布尔运算中会被视为假值。

CPython implementation detail: 在 CPython 中,要求长度最大为 sys.maxsize。如果长度大于 sys.maxsize 则某些特性 (例如 len()) 可能会引发 OverflowError。要通过真值检测来防止引发 OverflowError,对象必须定义 __bool__() 方法。

object.__length_hint__(self)

调用此方法以实现 operator.length_hint()。 应该返回对象长度的估计值(可能大于或小于实际长度)。 此长度应为一个 >= 0 的整数。 返回值也可以为 NotImplemented,这会被视作与 __length_hint__ 方法完全不存在时一样处理。 此方法纯粹是为了优化性能,并不要求正确无误。

3.4 新版功能.

注解

切片是通过下述三个专门方法完成的。以下形式的调用

a[1:2] = b

会为转写为

a[slice(1, 2, None)] = b

其他形式以此类推。略去的切片项总是以 None 补全。

object.__getitem__(self, key)

调用此方法以实现 self[key] 的求值。对于序列类型,接受的键应为整数和切片对象。请注意负数索引(如果类想要模拟序列类型)的特殊解读是取决于 __getitem__() 方法。如果 key 的类型不正确则会引发 TypeError 异常;如果为序列索引集范围以外的值(在进行任何负数索引的特殊解读之后)则应引发 IndexError 异常。对于映射类型,如果 key 找不到(不在容器中)则应引发 KeyError 异常。

注解

for 循环在有不合法索引时会期待捕获 IndexError 以便正确地检测到序列的结束。

object.__setitem__(self, key, value)

调用此方法以实现向 self[key] 赋值。注意事项与 __getitem__() 相同。为对象实现此方法应该仅限于需要映射允许基于键修改值或添加键,或是序列允许元素被替换时。不正确的 key 值所引发的异常应与 __getitem__() 方法的情况相同。

object.__delitem__(self, key)

调用此方法以实现 self[key] 的删除。注意事项与 __getitem__() 相同。为对象实现此方法应该权限于需要映射允许移除键,或是序列允许移除元素时。不正确的 key 值所引发的异常应与 __getitem__() 方法的情况相同。

object.__missing__(self, key)

此方法由 dict.__getitem__() 在找不到字典中的键时调用以实现 dict 子类的 self[key]

object.__iter__(self)

此方法在需要为容器创建迭代器时被调用。此方法应该返回一个新的迭代器对象,它能够逐个迭代容器中的所有对象。对于映射,它应该逐个迭代容器中的键。

迭代器对象也需要实现此方法;它们需要返回对象自身。

object.__reversed__(self)

此方法(如果存在)会被 reversed() 内置函数调用以实现逆向迭代。它应当返回一个新的以逆序逐个迭代容器内所有对象的迭代器对象。

如果未提供 __reversed__() 方法,则 reversed() 内置函数将回退到使用序列协议 (__len__()__getitem__())。支持序列协议的对象应当仅在能够提供比 reversed() 所提供的实现更高效的实现时才提供 __reversed__() 方法。

成员检测运算符 (innot in) 通常以对容器进行逐个迭代的方式来实现。 不过,容器对象可以提供以下特殊方法并采用更有效率的实现,这样也不要求对象必须为可迭代对象。

object.__contains__(self, item)

调用此方法以实现成员检测运算符。如果 itemself 的成员则应返回真,否则返回假。对于映射类型,此检测应基于映射的键而不是值或者键值对。

对于未定义 __contains__() 的对象,成员检测将首先尝试通过 __iter__() 进行迭代,然后再使用 __getitem__() 的旧式序列迭代协议。

3.3.8. 模拟数字类型

定义以下方法即可模拟数字类型。特定种类的数字不支持的运算(例如非整数不能进行位运算)所对应的方法应当保持未定义状态。

object.__add__(self, other)

object.__sub__(self, other)

object.__mul__(self, other)

object.__matmul__(self, other)

object.__truediv__(self, other)

object.__floordiv__(self, other)

object.__mod__(self, other)

object.__divmod__(self, other)

object.__pow__(self, other[, modulo])

object.__lshift__(self, other)

object.__rshift__(self, other)

object.__and__(self, other)

object.__xor__(self, other)

object.__or__(self, other)

调用这些方法来实现二进制算术运算 (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |)。例如,求表达式 x + y 的值,其中 x 是具有 __add__() 方法的类的一个实例,则会调用 x.__add__(y)__divmod__() 方法应该等价于使用 __floordiv__()__mod__(),它不应该被关联到 __truediv__()。请注意如果要支持三元版本的内置 pow() 函数,则 __pow__() 的定义应该接受可选的第三个参数。

如果这些方法中的某一个不支持与所提供参数进行运算,它应该返回 NotImplemented

object.__radd__(self, other)

object.__rsub__(self, other)

object.__rmul__(self, other)

object.__rmatmul__(self, other)

object.__rtruediv__(self, other)

object.__rfloordiv__(self, other)

object.__rmod__(self, other)

object.__rdivmod__(self, other)

object.__rpow__(self, other[, modulo])

object.__rlshift__(self, other)

object.__rrshift__(self, other)

object.__rand__(self, other)

object.__rxor__(self, other)

object.__ror__(self, other)

调用这些方法来实现具有反射(交换)操作数的二进制算术运算 (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |)。这些成员函数仅会在左操作数不支持相应运算且两个操作数类型不同时被调用。例如,求表达式 x - y 的值,其中 y 是具有 __rsub__() 方法的类的一个实例,则当 x.__sub__(y) 返回 NotImplemented 时会调用 y.__rsub__(x)

请注意三元版的 pow() 并不会尝试调用 __rpow__() (因为强制转换规则会太过复杂)。

注解

如果右操作数类型为左操作数类型的一个子类,且该子类提供了指定运算的反射方法,则此方法将先于左操作数的非反射方法被调用。 此行为可允许子类重载其祖先类的运算符。

object.__iadd__(self, other)

object.__isub__(self, other)

object.__imul__(self, other)

object.__imatmul__(self, other)

object.__itruediv__(self, other)

object.__ifloordiv__(self, other)

object.__imod__(self, other)

object.__ipow__(self, other[, modulo])

object.__ilshift__(self, other)

object.__irshift__(self, other)

object.__iand__(self, other)

object.__ixor__(self, other)

object.__ior__(self, other)

调用这些方法来实现扩展算术赋值 (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=)。这些方法应该尝试进行自身操作 (修改 self) 并返回结果 (结果应该但并非必须为 self)。如果某个方法未被定义,相应的扩展算术赋值将回退到普通方法。例如,如果 x 是具有 __iadd__() 方法的类的一个实例,则 x += y 就等价于 x = x.__iadd__(y)。否则就如 x + y 的求值一样选择 x.__add__(y)y.__radd__(x)。在某些情况下,扩展赋值可导致未预期的错误,但此行为实际上是数据模型的一个组成部分。

object.__neg__(self)

object.__pos__(self)

object.__abs__(self)

object.__invert__(self)

调用此方法以实现一元算术运算 (-, +, abs()~)。

object.__complex__(self)

object.__int__(self)

object.__float__(self)

调用这些方法以实现内置函数 complex(), int()float()。应当返回一个相应类型的值。

object.__index__(self)

调用此方法以实现 operator.index() 以及 Python 需要无损地将数字对象转换为整数对象的场合(例如切片或是内置的 bin(), hex()oct() 函数)。 存在此方法表明数字对象属于整数类型。 必须返回一个整数。

如果未定义 __int__(), __float__()__complex__() 则相应的内置函数 int(), float()complex() 将回退为 __index__()

object.__round__(self[, ndigits])

object.__trunc__(self)

object.__floor__(self)

object.__ceil__(self)

调用这些方法以实现内置函数 round() 以及 math 函数 trunc(), floor()ceil()。 除了将 ndigits 传给 __round__() 的情况之外这些方法的返回值都应当是原对象截断为 Integral (通常为 int)。

如果未定义 __int__() 则内置函数 int() 会回退到 __trunc__()

3.3.9. with 语句上下文管理器

上下文管理器 是一个对象,它定义了在执行 with 语句时要建立的运行时上下文。 上下文管理器处理进入和退出所需运行时上下文以执行代码块。 通常使用 with 语句(在 with 语句 中描述),但是也可以通过直接调用它们的方法来使用。

上下文管理器的典型用法包括保存和恢复各种全局状态,锁定和解锁资源,关闭打开的文件等等。

object.__enter__(self)

进入与此对象相关的运行时上下文。 with 语句将会绑定这个方法的返回值到 as 子句中指定的目标,如果有的话。

object.__exit__(self, exc_type, exc_value, traceback)

退出关联到此对象的运行时上下文。 各个参数描述了导致上下文退出的异常。 如果上下文是无异常地退出的,三个参数都将为 None

如果提供了异常,并且希望方法屏蔽此异常(即避免其被传播),则应当返回真值。 否则的话,异常将在退出此方法时按正常流程处理。

请注意 __exit__() 方法不应该重新引发被传入的异常,这是调用者的责任。

参见

PEP 343 - “with” 语句

Python with 语句的规范描述、背景和示例。

3.3.10. 定制类模式匹配中的位置参数

当在模式中使用类名称时,默认不允许模式中出现位置参数,例如 case MyClass(x, y) 通常是无效的,除非 MyClass 提供了特别支持。 要能使用这样的模式,类必须定义一个 match_args 属性。

object.__match_args__

该类变量可以被赋值为一个字符串元组。 当该类被用于带位置参数的类模式时,每个位置参数都将被转换为关键字参数,并使用 match_args 中的对应值作为关键字。 缺失此属性就等价于将其设为 ()

举例来说,如果 MyClass.__match_args__("left", "center", "right") 则意味着 case MyClass(x, y) 就等价于 case MyClass(left=x, center=y)。 请注意模式中参数的数量必须小于等于 match_args 中元素的数量;如果前者大于后者,则尝试模式匹配时将引发 TypeError

3.10 新版功能.

参见

PEP 634 - 结构化模式匹配

有关 Python match 语句的规范说明。

3.3.11. 特殊方法查找

对于自定义类来说,特殊方法的隐式发起调用仅保证在其定义于对象类型中时能正确地发挥作用,而不能定义在对象实例字典中。 该行为就是以下代码会引发异常的原因。:

>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()

此行为背后的原理在于包括类型对象在内的所有对象都会实现的几个特殊方法,例如 __hash__()__repr__()。 如果这些方法的隐式查找使用了传统的查找过程,它们会在对类型对象本身发起调用时失败:

>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument

以这种方式不正确地尝试发起调用一个类的未绑定方法有时被称为‘元类混淆’,可以通过在查找特殊方法时绕过实例的方式来避免:

>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

除了为了正确性而绕过任何实例属性之外,隐式特殊方法查找通常也会绕过 __getattribute__() 方法,甚至包括对象的元类:

>>> class Meta(type):
...     def __getattribute__(*args):
...         print("Metaclass getattribute invoked")
...         return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
...     def __len__(self):
...         return 10
...     def __getattribute__(*args):
...         print("Class getattribute invoked")
...         return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__()                 # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c)          # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c)                      # Implicit lookup
10

以这种方式绕过 __getattribute__() 机制为解析器内部的速度优化提供了显著的空间,其代价则是牺牲了处理特殊方法时的一些灵活性(特殊方法 必须 设置在类对象本身上以便始终一致地由解释器发起调用)。

3.4. 协程

3.4.1. 可等待对象

awaitable 对象主要实现了 __await__() 方法。 从 async def 函数返回的 协程对象 即属于可等待对象。

注解

从带有 types.coroutine()asyncio.coroutine() 装饰器的生成器返回的 generator iterator 对象也属于可等待对象,但它们并未实现 __await__()

object.__await__(self)

必须返回一个 iterator。 应当被用来实现 awaitable 对象。 例如,asyncio.Future 实现了此方法以与 await 表达式相兼容。

3.5 新版功能.

参见

PEP 492 了解有关可等待对象的详细信息。

3.4.2. 协程对象

协程对象 属于 awaitable 对象。 协程的执行可通过调用 __await__() 并迭代其结果来控制。 当协程结束执行并返回时,迭代器会引发 StopIteration,该异常的 value 属性将存放返回值。 如果协程引发了异常,它会被迭代器所传播。 协程不应直接引发未处理的 StopIteration 异常。

协程也具有下面列出的方法,它们类似于生成器的对应方法。 但是,与生成器不同,协程并不直接支持迭代。

在 3.5.2 版更改: 等待一个协程超过一次将引发 RuntimeError

coroutine.send(value)

开始或恢复协程的执行。 如果 valueNone,则这相当于前往 __await__() 所返回迭代器的下一项。 如果 value 不为 None,此方法将委托给导致协程挂起的迭代器的 send() 方法。 其结果(返回值,StopIteration 或是其他异常)将与上述对 __await__() 返回值进行迭代的结果相同。

coroutine.throw(type[, value[, traceback]])

在协程内引发指定的异常。 此方法将委托给导致协程挂起的迭代器的 throw() 方法,如果存在该方法。 否则的话,异常会在挂起点被引发。 其结果(返回值,StopIteration 或是其他异常)将与上述对 __await__() 返回值进行迭代的结果相同。 如果异常未在协程内被捕获,则将回传给调用者。

coroutine.close()

此方法会使得协程清理自身并退出。 如果协程被挂起,此方法会先委托给导致协程挂起的迭代器的 close() 方法,如果存在该方法。 然后它会在挂起点引发 GeneratorExit,使得协程立即清理自身。 最后,协程会被标记为已结束执行,即使它根本未被启动。

当协程对象将要被销毁时,会使用以上处理过程来自动关闭。

3.4.3. 异步迭代器

异步迭代器 可以在其 __anext__ 方法中调用异步代码。

异步迭代器可在 async for 语句中使用。

object.__aiter__(self)

必须返回一个 异步迭代器 对象。

object.__anext__(self)

必须返回一个 可迭代对象 输出迭代器的下一结果值。 当迭代结束时应该引发 StopAsyncIteration 错误。

异步可迭代对象的一个示例:

class Reader:
    async def readline(self):
        ...
    def __aiter__(self):
        return self
    async def __anext__(self):
        val = await self.readline()
        if val == b'':
            raise StopAsyncIteration
        return val

3.5 新版功能.

在 3.7 版更改: 在 Python 3.7 之前,__aiter__ 可以返回一个 可迭代对象 并解析为 异步迭代器。

从 Python 3.7 开始,__aiter__ 必须 返回一个异步迭代器对象。 返回任何其他对象都将导致 TypeError 错误。

3.4.4. 异步上下文管理器

异步上下文管理器上下文管理器 的一种,它能够在其 __aenter____aexit__ 方法中暂停执行。

异步上下文管理器可在 async with 语句中使用。

object.__aenter__(self)

在语义上类似于 __enter__(),仅有的区别是它必须返回一个 可等待对象

object.__aexit__(self, exc_type, exc_value, traceback)

在语义上类似于 __exit__(),仅有的区别是它必须返回一个 可等待对象

异步上下文管理器类的一个示例:

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')
    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

3.5 新版功能.

注:

  • 在某些情况下 有可能 基于可控的条件改变一个对象的类型。 但这通常不是个好主意,因为如果处理不当会导致一些非常怪异的行为。
  • __hash__(), __iter__(), __reversed__() 以及 __contains__() 方法对此有特殊处理;其他方法仍会引发 TypeError,但可能依靠 None 属于不可调用对象的行为来做到这一点。
  • 这里的“不支持”是指该类无此方法,或方法返回 NotImplemented。 如果你想强制回退到右操作数的反射方法,请不要设置方法为 None — 那会造成显式地 阻塞 此种回退的相反效果。
  • 对于相同类型的操作数,如果非反射方法 — 例如 __add__() — 失败则会认为整个运算都不被支持,这就是反射方法未被调用的原因。

4. 执行模型

4.1. 程序的结构

Python 程序是由代码块构成的。 代码块 是被作为一个单元来执行的一段 Python 程序文本。 以下几个都属于代码块:模块、函数体和类定义。 交互式输入的每条命令都是代码块。 一个脚本文件(作为标准输入发送给解释器或是作为命令行参数发送给解释器的文件)也是代码块。 一条脚本命令(通过 -c 选项在解释器命令行中指定的命令)也是代码块。 通过在命令行中使用 -m 参数作为最高层级脚本(即 __main__ 模块)运行的模块也是代码块。 传递给内置函数 eval()exec() 的字符串参数也是代码块。

代码块在 执行帧 中被执行。 一个帧会包含某些管理信息(用于调试)并决定代码块执行完成后应前往何处以及如何继续执行。

4.2. 命名与绑定

4.2.1. 名称的绑定

名称 用于指代对象。 名称是通过名称绑定操作来引入的。

以下构造会绑定名称:传给函数的正式形参,import 语句,类与函数定义(这会在定义的代码块中绑定类或函数名称)以及发生以标识符为目标的赋值,for 循环的开头,或 with 语句和 except 子句的 as 之后。 import 语句的 from ... import * 形式会绑定在被导入模块中定义的所有名称,那些以下划线开头的除外。 这种形式仅在模块层级上被使用。

del 语句的目标也被视作一种绑定(虽然其实际语义为解除名称绑定)。

每条赋值或导入语句均发生于类或函数内部定义的代码块中,或是发生于模块层级(即最高层级的代码块)。

如果名称绑定在一个代码块中,则为该代码块的局部变量,除非声明为 nonlocalglobal。 如果名称绑定在模块层级,则为全局变量。 (模块代码块的变量既为局部变量又为全局变量。) 如果变量在一个代码块中被使用但不是在其中定义,则为 自由变量

每个在程序文本中出现的名称是指由以下名称解析规则所建立的对该名称的 绑定

4.2.2. 名称的解析

作用域 定义了一个代码块中名称的可见性。 如果代码块中定义了一个局部变量,则其作用域包含该代码块。 如果定义发生于函数代码块中,则其作用域会扩展到该函数所包含的任何代码块,除非有某个被包含代码块引入了对该名称的不同绑定。

当一个名称在代码块中被使用时,会由包含它的最近作用域来解析。 对一个代码块可见的所有这种作用域的集合称为该代码块的 环境

当一个名称完全找不到时,将会引发 NameError 异常。 如果当前作用域为函数作用域,且该名称指向一个局部变量,而此变量在该名称被使用的时候尚未绑定到特定值,将会引发 UnboundLocalError 异常。 UnboundLocalErrorNameError 的一个子类。

如果一个代码块内的任何位置发生名称绑定操作,则代码块内所有对该名称的使用会被认为是对当前代码块的引用。 当一个名称在其被绑定前就在代码块内被使用时则会导致错误。 这个一个很微妙的规则。 Python 缺少声明语法,并允许名称绑定操作发生于代码块内的任何位置。 一个代码块的局部变量可通过在整个代码块文本中扫描名称绑定操作来确定。

如果 global 语句出现在一个代码块中,则所有对该语句所指定名称的使用都是在最高层级命名空间内对该名称绑定的引用。 名称在最高层级命名内的解析是通过全局命名空间,也就是包含该代码块的模块的命名空间,以及内置命名空间即 builtins 模块的命名空间。 全局命名空间会先被搜索。 如果未在其中找到指定名称,再搜索内置命名空间。 global 语句必须位于所有对其所指定名称的使用之前。

global 语句与同一代码块中名称绑定具有相同的作用域。 如果一个自由变量的最近包含作用域中有一条 global 语句,则该自由变量也会被当作是全局变量。

nonlocal 语句会使得相应的名称指向之前在最近包含函数作用域中绑定的变量。 如果指定名称不存在于任何包含函数作用域中则将在编译时引发 SyntaxError

模块的作用域会在模块第一次被导入时自动创建。 一个脚本的主模块总是被命名为 __main__

类定义代码块以及传给 exec()eval() 的参数是名称解析上下文中的特殊情况。 类定义是可能使用并定义名称的可执行语句。 这些引用遵循正常的名称解析规则,例外之处在于未绑定的局部变量将会在全局命名空间中查找。 类定义的命名空间会成为该类的属性字典。 在类代码块中定义的名称的作用域会被限制在类代码块中;它不会扩展到方法的代码块中 — 这也包括推导式和生成器表达式,因为它们都是使用函数作用域实现的。 这意味着以下代码将会失败:

class A:
    a = 42
    b = list(a + i for i in range(10))

4.2.3. 内置命名空间和受限的执行

CPython implementation detail: 用户不应该接触 __builtins__,严格说来它属于实现细节。 用户如果要重载内置命名空间中的值则应该 import builtins 并相应地修改该模块中的属性。

与一个代码块的执行相关联的内置命名空间实际上是通过在其全局命名空间中搜索名称 __builtins__ 来找到的;这应该是一个字典或一个模块(在后一种情况下会使用该模块的字典)。 默认情况下,当在 __main__ 模块中时,__builtins__ 就是内置模块 builtins;当在任何其他模块中时,__builtins__ 则是 builtins 模块自身的字典的一个别名。

4.2.4. 与动态特性的交互

自由变量的名称解析发生于运行时而不是编译时。 这意味着以下代码将打印出 42:

i = 10
def f():
    print(i)
i = 42
f()

eval()exec() 函数没有对完整环境的访问权限来解析名称。 名称可以在调用者的局部和全局命名空间中被解析。 自由变量的解析不是在最近包含命名空间中,而是在全局命名空间中。 exec()eval() 函数有可选参数用来重载全局和局部命名空间。 如果只指定一个命名空间,则它会同时作用于两者。

4.3. 异常

异常是中断代码块的正常控制流程以便处理错误或其他异常条件的一种方式。 异常会在错误被检测到的位置 引发,它可以被当前包围代码块或是任何直接或间接发起调用发生错误的代码块的其他代码块所 处理

Python 解析器会在检测到运行时错误(例如零作为被除数)的时候引发异常。 Python 程序也可以通过 raise 语句显式地引发异常。 异常处理是通过 tryexcept 语句来指定的。 该语句的 finally 子句可被用来指定清理代码,它并不处理异常,而是无论之前的代码是否发生异常都会被执行。

Python 的错误处理采用的是“终止”模型:异常处理器可以找出发生了什么问题,并在外层继续执行,但它不能修复错误的根源并重试失败的操作(除非通过从顶层重新进入出错的代码片段)。

当一个异常完全未被处理时,解释器会终止程序的执行,或者返回交互模式的主循环。 无论是哪种情况,它都会打印栈回溯信息,除非是当异常为 SystemExit 的时候。

异常是通过类实例来标识的。 except 子句会依据实例的类来选择:它必须引用实例的类或是其所属的基类。 实例可通过处理器被接收,并可携带有关异常条件的附加信息。

注解

异常消息不是 Python API 的组成部分。 其内容可能在 Python 升级到新版本时不经警告地发生改变,不应该被需要在多版本解释器中运行的代码所依赖。

5. 导入系统

一个 module 内的 Python 代码通过 importing 操作就能够访问另一个模块内的代码。 import 语句是发起调用导入机制的最常用方式,但不是唯一的方式。 importlib.import_module() 以及内置的 __import__() 等函数也可以被用来发起调用导入机制。

import 语句结合了两个操作;它先搜索指定名称的模块,然后将搜索结果绑定到当前作用域中的名称。 import 语句的搜索操作被定义为对 __import__() 函数的调用并带有适当的参数。 __import__() 的返回值会被用于执行 import 语句的名称绑定操作。 请参阅 import 语句了解名称绑定操作的更多细节。

__import__() 的直接调用将仅执行模块搜索以及在找到时的模块创建操作。 不过也可能产生某些副作用,例如导入父包和更新各种缓存 (包括 sys.modules),只有 import 语句会执行名称绑定操作。

import 语句被执行时,标准的内置 __import__() 函数会被调用。 其他发起调用导入系统的机制 (例如 importlib.import_module()) 可能会选择绕过 __import__() 并使用它们自己的解决方案来实现导入机制。

当一个模块首次被导入时,Python 会搜索该模块,如果找到就创建一个 module 对象 1 并初始化它。 如果指定名称的模块未找到,则会引发 ModuleNotFoundError。 当发起调用导入机制时,Python 会实现多种策略来搜索指定名称的模块。 这些策略可以通过使用使用下文所描述的多种钩子来加以修改和扩展。

在 3.3 版更改: 导入系统已被更新以完全实现 PEP 302 中的第二阶段要求。 不会再有任何隐式的导入机制 —— 整个导入系统都通过 sys.meta_path 暴露出来。 此外,对原生命名空间包的支持也已被实现 (参见 PEP 420)。

5.1. importlib

importlib 模块提供了一个丰富的 API 用来与导入系统进行交互。 例如 importlib.import_module() 提供了相比内置的 __import__() 更推荐、更简单的 API 用来发起调用导入机制。

5.2. 包

Python 只有一种模块对象类型,所有模块都属于该类型,无论模块是用 Python、C 还是别的语言实现。 为了帮助组织模块并提供名称层次结构,Python 还引入了 包 的概念。

你可以把包看成是文件系统中的目录,并把模块看成是目录中的文件,但请不要对这个类比做过于字面的理解,因为包和模块不是必须来自于文件系统。 为了方便理解本文档,我们将继续使用这种目录和文件的类比。 与文件系统一样,包通过层次结构进行组织,在包之内除了一般的模块,还可以有子包。

要注意的一个重点概念是所有包都是模块,但并非所有模块都是包。 或者换句话说,包只是一种特殊的模块。 特别地,任何具有 __path__ 属性的模块都会被当作是包。

所有模块都有自己的名字。 子包名与其父包名以点号分隔,与 Python 的标准属性访问语法一致。 例如你可能看到一个名为 sys 的模块以及一个名为 email 的包,这个包中又有一个名为 email.mime 的子包和该子包中的名为 email.mime.text 的子包。

5.2.1. 常规包

Python 定义了两种类型的包,常规包 和 命名空间包。 常规包是传统的包类型,它们在 Python 3.2 及之前就已存在。 常规包通常以一个包含 __init__.py 文件的目录形式实现。 当一个常规包被导入时,这个 __init__.py 文件会隐式地被执行,它所定义的对象会被绑定到该包命名空间中的名称。__init__.py 文件可以包含与任何其他模块中所包含的 Python 代码相似的代码,Python 将在模块被导入时为其添加额外的属性。

例如,以下文件系统布局定义了一个最高层级的 parent 包和三个子包:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

导入 parent.one 将隐式地执行 parent/__init__.pyparent/one/__init__.py。 后续导入 parent.twoparent.three 则将分别执行 parent/two/__init__.pyparent/three/__init__.py

5.2.2. 命名空间包

命名空间包是由多个 部分 构成的,每个部分为父包增加一个子包。 各个部分可能处于文件系统的不同位置。 部分也可能处于 zip 文件中、网络上,或者 Python 在导入期间可以搜索的其他地方。 命名空间包并不一定会直接对应到文件系统中的对象;它们有可能是无实体表示的虚拟模块。

命名空间包的 __path__ 属性不使用普通的列表。 而是使用定制的可迭代类型,如果其父包的路径 (或者最高层级包的 sys.path) 发生改变,这种对象会在该包内的下一次导入尝试时自动执行新的对包部分的搜索。

命名空间包没有 parent/__init__.py 文件。 实际上,在导入搜索期间可能找到多个 parent 目录,每个都由不同的部分所提供。 因此 parent/one 的物理位置不一定与 parent/two 相邻。 在这种情况下,Python 将为顶级的 parent 包创建一个命名空间包,无论是它本身还是它的某个子包被导入。

另请参阅 PEP 420 了解对命名空间包的规格描述。

5.3. 搜索

为了开始搜索,Python 需要被导入模块(或者包,对于当前讨论来说两者没有差别)的完整 限定名称。 此名称可以来自 import 语句所带的各种参数,或者来自传给 importlib.import_module()__import__() 函数的形参。

此名称会在导入搜索的各个阶段被使用,它也可以是指向一个子模块的带点号路径,例如 foo.bar.baz。 在这种情况下,Python 会先尝试导入 foo,然后是 foo.bar,最后是 foo.bar.baz。 如果这些导入中的任何一个失败,都会引发 ModuleNotFoundError

5.3.1. 模块缓存

在导入搜索期间首先会被检查的地方是 sys.modules。 这个映射起到缓存之前导入的所有模块的作用(包括其中间路径)。 因此如果之前导入过 foo.bar.baz,则 sys.modules 将包含 foo, foo.barfoo.bar.baz 条目。 每个键的值就是相应的模块对象。

在导入期间,会在 sys.modules 查找模块名称,如存在则其关联的值就是需要导入的模块,导入过程完成。 然而,如果值为 None,则会引发 ModuleNotFoundError。 如果找不到指定模块名称,Python 将继续搜索该模块。

sys.modules 是可写的。删除键可能不会破坏关联的模块(因为其他模块可能会保留对它的引用),但它会使命名模块的缓存条目无效,导致 Python 在下次导入时重新搜索命名模块。键也可以赋值为 None ,强制下一次导入模块导致 ModuleNotFoundError

但是要小心,因为如果你还保有对某个模块对象的引用,同时停用其在 sys.modules 中的缓存条目,然后又再次导入该名称的模块,则前后两个模块对象将 不是 同一个。 相反地,importlib.reload() 将重用 同一个 模块对象,并简单地通过重新运行模块的代码来重新初始化模块内容。

5.3.2. 查找器和加载器

如果指定名称的模块在 sys.modules 找不到,则将发起调用 Python 的导入协议以查找和加载该模块。 此协议由两个概念性模块构成,即 查找器 和 加载器。 查找器的任务是确定是否能使用其所知的策略找到该名称的模块。 同时实现这两种接口的对象称为 导入器 —— 它们在确定能加载所需的模块时会返回其自身。

Python 包含了多个默认查找器和导入器。 第一个知道如何定位内置模块,第二个知道如何定位冻结模块。 第三个默认查找器会在 import path 中搜索模块。 import path 是一个由文件系统路径或 zip 文件组成的位置列表。 它还可以扩展为搜索任意可定位资源,例如由 URL 指定的资源。

导入机制是可扩展的,因此可以加入新的查找器以扩展模块搜索的范围和作用域。

查找器并不真正加载模块。 如果它们能找到指定名称的模块,会返回一个 模块规格说明,这是对模块导入相关信息的封装,供后续导入机制用于在加载模块时使用。

以下各节描述了有关查找器和加载器协议的更多细节,包括你应该如何创建并注册新的此类对象来扩展导入机制。

在 3.4 版更改: 在之前的 Python 版本中,查找器会直接返回 加载器,现在它们则返回模块规格说明,其中 包含 加载器。 加载器仍然在导入期间被使用,但负担的任务有所减少。

5.3.3. 导入钩子

导入机制被设计为可扩展;其中的基本机制是 导入钩子*。 导入钩子有两种类型: *元钩子导入路径钩子

元钩子在导入过程开始时被调用,此时任何其他导入过程尚未发生,但 sys.modules 缓存查找除外。 这允许元钩子重载 sys.path 过程、冻结模块甚至内置模块。 元钩子的注册是通过向 sys.meta_path 添加新的查找器对象,具体如下所述。

导入路径钩子是作为 sys.path (或 package.__path__) 过程的一部分,在遇到它们所关联的路径项的时候被调用。 导入路径钩子的注册是通过向 sys.path_hooks 添加新的可调用对象,具体如下所述。

5.3.4. 元路径

当指定名称的模块在 sys.modules 中找不到时,Python 会接着搜索 sys.meta_path,其中包含元路径查找器对象列表。 这些查找器按顺序被查询以确定它们是否知道如何处理该名称的模块。 元路径查找器必须实现名为 find_spec() 的方法,该方法接受三个参数:名称、导入路径和目标模块(可选)。 元路径查找器可使用任何策略来确定它是否能处理指定名称的模块。

如果元路径查找器知道如何处理指定名称的模块,它将返回一个说明对象。 如果它不能处理该名称的模块,则会返回 None。 如果 sys.meta_path 处理过程到达列表末尾仍未返回说明对象,则将引发 ModuleNotFoundError。 任何其他被引发异常将直接向上传播,并放弃导入过程。

元路径查找器的 find_spec() 方法调用带有两到三个参数。 第一个是被导入模块的完整限定名称,例如 foo.bar.baz。 第二个参数是供模块搜索使用的路径条目。 对于最高层级模块,第二个参数为 None,但对于子模块或子包,第二个参数为父包 __path__ 属性的值。 如果相应的 __path__ 属性无法访问,将引发 ModuleNotFoundError。 第三个参数是一个将被作为稍后加载目标的现有模块对象。 导入系统仅会在重加载期间传入一个目标模块。

对于单个导入请求可以多次遍历元路径。 例如,假设所涉及的模块都尚未被缓存,则导入 foo.bar.baz 将首先执行顶级的导入,在每个元路径查找器 (mpf) 上调用 mpf.find_spec("foo", None, None)。 在导入 foo 之后,foo.bar 将通过第二次遍历元路径来导入,调用 mpf.find_spec("foo.bar", foo.__path__, None)。 一旦 foo.bar 完成导入,最后一次遍历将调用 mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)

有些元路径查找器只支持顶级导入。 当把 None 以外的对象作为第三个参数传入时,这些导入器将总是返回 None

Python 的默认 sys.meta_path 具有三种元路径查找器,一种知道如何导入内置模块,一种知道如何导入冻结模块,还有一种知道如何导入来自 import path 的模块 (即 path based finder)。

在 3.4 版更改: 元路径查找器的 find_spec() 方法替代了 find_module(),后者现已弃用,它将继续可用但不会再做改变,导入机制仅会在查找器未实现 find_spec() 时尝试使用它。

在 3.10 版更改: 导入系统使用 find_module() 现在将会引发 ImportWarning

5.4. 加载

当一个模块说明被找到时,导入机制将在加载该模块时使用它(及其所包含的加载器)。 下面是导入的加载部分所发生过程的简要说明:

module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)
if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
    # Set __loader__ and __package__ if missing.
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]

请注意以下细节:

  • 如果在 sys.modules 中存在指定名称的模块对象,导入操作会已经将其返回。
  • 在加载器执行模块代码之前,该模块将存在于 sys.modules 中。 这一点很关键,因为该模块代码可能(直接或间接地)导入其自身;预先将其添加到 sys.modules 可防止在最坏情况下的无限递归和最好情况下的多次加载。
  • 如果加载失败,则该模块 — 只限加载失败的模块 — 将从 sys.modules 中移除。 任何已存在于 sys.modules 缓存的模块,以及任何作为附带影响被成功加载的模块仍会保留在缓存中。 这与重新加载不同,后者会把即使加载失败的模块也保留在 sys.modules 中。
  • 在模块创建完成但还未执行之前,导入机制会设置导入相关模块属性(在上面的示例伪代码中为 “_init_module_attrs”)。
  • 模块执行是加载的关键时刻,在此期间将填充模块的命名空间。 执行会完全委托给加载器,由加载器决定要填充的内容和方式。
  • 在加载过程中创建并传递给 exec_module() 的模块并不一定就是在导入结束时返回的模块。

在 3.4 版更改: 导入系统已经接管了加载器建立样板的责任。 这些在以前是由 importlib.abc.Loader.load_module() 方法来执行的。

5.4.1. 加载器

模块加载器提供关键的加载功能:模块执行。 导入机制调用 importlib.abc.Loader.exec_module() 方法并传入一个参数来执行模块对象。 从 exec_module() 返回的任何值都将被忽略。

加载器必须满足下列要求:

  • 如果模块是一个 Python 模块(而非内置模块或动态加载的扩展),加载器应该在模块的全局命名空间 (module.__dict__) 中执行模块的代码。
  • 如果加载器无法执行指定模块,它应该引发 ImportError,不过在 exec_module() 期间引发的任何其他异常也会被传播。

在许多情况下,查找器和加载器可以是同一对象;在此情况下 find_spec() 方法将返回一个规格说明,其中加载器会被设为 self

模块加载器可以选择通过实现 create_module() 方法在加载期间创建模块对象。 它接受一个参数,即模块规格说明,并返回新的模块对象供加载期间使用。 create_module() 不需要在模块对象上设置任何属性。 如果模块返回 None,导入机制将自行创建新模块。

3.4 新版功能: 加载器的 create_module() 方法。

在 3.4 版更改: load_module() 方法被 exec_module() 所替代,导入机制会对加载的所有样板责任作出假定。

为了与现有的加载器兼容,导入机制会使用导入器的 load_module() 方法,如果它存在且导入器也未实现 exec_module()。 但是,load_module() 现已弃用,加载器应该转而实现 exec_module()

除了执行模块之外,load_module() 方法必须实现上文描述的所有样板加载功能。 所有相同的限制仍然适用,并带有一些附加规定:

  • 如果 sys.modules 中存在指定名称的模块对象,加载器必须使用已存在的模块。 (否则 importlib.reload() 将无法正确工作。) 如果该名称模块不存在于 sys.modules 中,加载器必须创建一个新的模块对象并将其加入 sys.modules
  • 在加载器执行模块代码之前,模块 必须 存在于 sys.modules 之中,以防止无限递归或多次加载。
  • 如果加载失败,加载器必须移除任何它已加入到 sys.modules 中的模块,但它必须 仅限 移除加载失败的模块,且所移除的模块应为加载器自身显式加载的。

在 3.5 版更改: 当 exec_module() 已定义但 create_module() 未定义时将引发 DeprecationWarning

在 3.6 版更改: 当 exec_module() 已定义但 create_module() 未定义时将引发 ImportError

在 3.10 版更改: 使用 load_module() 将引发 ImportWarning

5.4.2. 子模块

当使用任意机制 (例如 importlib API, importimport-from 语句或者内置的 __import__()) 加载一个子模块时,父模块的命名空间中会添加一个对子模块对象的绑定。 例如,如果包 spam 有一个子模块 foo,则在导入 spam.foo 之后,spam 将具有一个 绑定到相应子模块的 foo 属性。 假如现在有如下的目录结构:

spam/
    __init__.py
    foo.py
    bar.py

并且 spam/__init__.py 中有如下几行内容:

from .foo import Foo
from .bar import Bar

则执行如下代码将在 spam 模块中添加对 foobar 的名称绑定:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.bar
<module 'spam.bar' from '/tmp/imports/spam/bar.py'>

按照通常的 Python 名称绑定规则,这看起来可能会令人惊讶,但它实际上是导入系统的一个基本特性。 保持不变的一点是如果你有 sys.modules['spam']sys.modules['spam.foo'] (例如在上述导入之后就是如此),则后者必须显示为前者的 foo 属性。

5.4.3. 模块规格说明

导入机制在导入期间会使用有关每个模块的多种信息,特别是加载之前。 大多数信息都是所有模块通用的。 模块规格说明的目的是基于每个模块来封装这些导入相关信息。

在导入期间使用规格说明可允许状态在导入系统各组件之间传递,例如在创建模块规格说明的查找器和执行模块的加载器之间。 最重要的一点是,它允许导入机制执行加载的样板操作,在没有模块规格说明的情况下这是加载器的责任。

模块的规格说明会作为模块对象的 __spec__ 属性对外公开。

3.4 新版功能.

5.4.4. 导入相关的模块属性

导入机制会在加载期间会根据模块的规格说明填充每个模块对象的这些属性,并在加载器执行模块之前完成。

__name__

__name__ 属性必须被设为模块的完整限定名称。 此名称被用来在导入系统中唯一地标识模块。

__loader__

__loader__ 属性必须被设为导入系统在加载模块时使用的加载器对象。 这主要是用于内省,但也可用于额外的加载器专用功能,例如获取关联到加载器的数据。

__package__

模块的 __package__ 属性必须设定。 其取值必须为一个字符串,但可以与 __name__ 取相同的值。 当模块是包时,其 __package__ 值应该设为其 __name__ 值。 当模块不是包时,对于最高层级模块 __package__ 应该设为空字符串,对于子模块则应该设为其父包名。 更多详情可参阅 PEP 366

该属性取代 __name__ 被用来为主模块计算显式相对导入,相关定义见 PEP 366。 预期它与 __spec__.parent 具有相同的值。

在 3.6 版更改: __package__ 预期与 __spec__.parent 具有相同的值。

__spec__

__spec__ 属性必须设为在导入模块时要使用的模块规格说明。 对 __spec__ 的正确设定将同时作用于 解释器启动期间初始化的模块。 唯一的例外是 __main__,其中的 __spec__ 会 在某些情况下设为 None.

__package__ 未定义时, __spec__.parent 会被用作回退项。

3.4 新版功能.

在 3.6 版更改: 当 __package__ 未定义时,__spec__.parent 会被用作回退项。

__path__

如果模块为包(不论是正规包还是命名空间包),则必须设置模块对象的 __path__ 属性。 属性值必须为可迭代对象,但如果 __path__ 没有进一步的用处则可以为空。 如果 __path__ 不为空,则在迭代时它应该产生字符串。

不是包的模块不应该具有 __path__ 属性。

__file__
__cached__

__file__ 是可选项。 如果设置,此属性的值必须为字符串。 导入系统可以选择在其没有语法意义时不设置 __file__ (例如从数据库加载的模块)。

如果设置了 __file__,则也可以再设置 __cached__ 属性,后者取值为编译版本代码(例如字节码文件)所在的路径。 设置此属性不要求文件已存在;该路径可以简单地指向应该存放编译文件的位置 (参见 PEP 3147)。

当未设置 __file__ 时也可以设置 __cached__。 但是,那样的场景很不典型。 最终,加载器会使用 __file__ 和/或 __cached__。 因此如果一个加载器可以从缓存加载模块但是不能从文件加载,那种非典型场景就是适当的。

5.4.5. module.path

根据定义,如果一个模块具有 __path__ 属性,它就是包。

包的 __path__ 属性会在导入其子包期间被使用。 在导入机制内部,它的功能与 sys.path 基本相同,即在导入期间提供一个模块搜索位置列表。 但是,__path__ 通常会比 sys.path 受到更多限制。

__path__ 必须是由字符串组成的可迭代对象,但它也可以为空。 作用于 sys.path 的规则同样适用于包的 __path__,并且 sys.path_hooks 会在遍历包的 __path__ 时被查询。

包的 __init__.py 文件可以设置或更改包的 __path__ 属性,而且这是在 PEP 420 之前实现命名空间包的典型方式。 随着 PEP 420 的引入,命名空间包不再需要提供仅包含 __path__ 操控代码的 __init__.py 文件;导入机制会自动为命名空间包正确地设置 __path__

5.4.6. 模块的 repr

默认情况下,全部模块都具有一个可用的 repr,但是你可以依据上述的属性设置,在模块的规格说明中更为显式地控制模块对象的 repr。

如果模块具有 spec (__spec__),导入机制将尝试用它来生成一个 repr。 如果生成失败或找不到 spec,导入系统将使用模块中的各种可用信息来制作一个默认 repr。 它将尝试使用 module.__name__, module.__file__ 以及 module.__loader__ 作为 repr 的输入,并将任何丢失的信息赋为默认值。

以下是所使用的确切规则:

  • 如果模块具有 __spec__ 属性,其中的规格信息会被用来生成 repr。 被查询的属性有 “name”, “loader”, “origin” 和 “has_location” 等等。
  • 如果模块具有 __file__ 属性,这会被用作模块 repr 的一部分。
  • 如果模块没有 __file__ 但是有 __loader__ 且取值不为 None,则加载器的 repr 会被用作模块 repr 的一部分。
  • 对于其他情况,仅在 repr 中使用模块的 __name__

在 3.4 版更改: loader.module_repr() 已弃用,导入机制现在使用模块规格说明来生成模块 repr。

为了向后兼容 Python 3.3,如果加载器定义了 module_repr() 方法,则会在尝试上述两种方式之前先调用该方法来生成模块 repr。 但请注意此方法已弃用。

在 3.10 版更改: 对 module_repr() 的调用现在会在尝试使用模块的 __spec__ 属性之后但在回退至 __file__ 之前发生。 module_repr() 的使用预定会在 Python 3.12 中停止。

5.4.7. 已缓存字节码的失效

在 Python 从 .pyc 文件加载已缓存字节码之前,它会检查缓存是否由最新的 .py 源文件所生成。 默认情况下,Python 通过在所写入缓存文件中保存源文件的最新修改时间戳和大小来实现这一点。 在运行时,导入系统会通过比对缓存文件中保存的元数据和源文件的元数据确定该缓存的有效性。

Python 也支持“基于哈希的”缓存文件,即保存源文件内容的哈希值而不是其元数据。 存在两种基于哈希的 .pyc 文件:检查型和非检查型。 对于检查型基于哈希的 .pyc 文件,Python 会通过求哈希源文件并将结果哈希值与缓存文件中的哈希值比对来确定缓存有效性。 如果检查型基于哈希的缓存文件被确定为失效,Python 会重新生成并写入一个新的检查型基于哈希的缓存文件。 对于非检查型 .pyc 文件,只要其存在 Python 就会直接认定缓存文件有效。 确定基于哈希的 .pyc 文件有效性的行为可通过 --check-hash-based-pycs 旗标来重载。

在 3.7 版更改: 增加了基于哈希的 .pyc 文件。在此之前,Python 只支持基于时间戳来确定字节码缓存的有效性。

5.5. 基于路径的查找器

在之前已经提及,Python 带有几种默认的元路径查找器。 其中之一是 path based finder (PathFinder),它会搜索包含一个 路径条目 列表的 import path。 每个路径条目指定一个用于搜索模块的位置。

基于路径的查找器自身并不知道如何进行导入。 它只是遍历单独的路径条目,将它们各自关联到某个知道如何处理特定类型路径的路径条目查找器。

默认的路径条目查找器集合实现了在文件系统中查找模块的所有语义,可处理多种特殊文件类型例如 Python 源码 (.py 文件),Python 字节码 (.pyc 文件) 以及共享库 (例如 .so 文件)。 在标准库中 zipimport 模块的支持下,默认路径条目查找器还能处理所有来自 zip 文件的上述文件类型。

路径条目不必仅限于文件系统位置。 它们可以指向 URL、数据库查询或可以用字符串指定的任何其他位置。

基于路径的查找器还提供了额外的钩子和协议以便能扩展和定制可搜索路径条目的类型。 例如,如果你想要支持网络 URL 形式的路径条目,你可以编写一个实现 HTTP 语义在网络上查找模块的钩子。 这个钩子(可调用对象)应当返回一个支持下述协议的 path entry finder,以被用来获取一个专门针对来自网络的模块的加载器。

预先的警告:本节和上节都使用了 查找器 这一术语,并通过 meta path finder 和 path entry finder 两个术语来明确区分它们。 这两种类型的查找器非常相似,支持相似的协议,且在导入过程中以相似的方式运作,但关键的一点是要记住它们是有微妙差异的。 特别地,元路径查找器作用于导入过程的开始,主要是启动 sys.meta_path 遍历。

相比之下,路径条目查找器在某种意义上说是基于路径的查找器的实现细节,实际上,如果需要从 sys.meta_path 移除基于路径的查找器,并不会有任何路径条目查找器被发起调用。

5.5.1. 路径条目查找器

path based finder 会负责查找和加载通过 path entry 字符串来指定位置的 Python 模块和包。 多数路径条目所指定的是文件系统中的位置,但它们并不必受限于此。

作为一种元路径查找器,path based finder 实现了上文描述的 find_spec() 协议,但是它还对外公开了一些附加钩子,可被用来定制模块如何从 import path 查找和加载。

有三个变量由 path based finder, sys.path, sys.path_hookssys.path_importer_cache 所使用。 包对象的 __path__ 属性也会被使用。 它们提供了可用于定制导入机制的额外方式。

sys.path 包含一个提供模块和包搜索位置的字符串列表。 它初始化自 PYTHONPATH 环境变量以及多种其他特定安装和实现的默认设置。 sys.path 条目可指定的名称有文件系统中的目录、zip 文件和其他可用于搜索模块的潜在“位置”,例如 URL 或数据库查询等。 在 sys.path 中只能出现字符串和字节串;所有其他数据类型都会被忽略。 字节串条目使用的编码由单独的 路径条目查找器 来确定。

path based finder 是一种 meta path finder,因此导入机制会通过调用上文描述的基于路径的查找器的 find_spec() 方法来启动 import path 搜索。 当要向 find_spec() 传入 path 参数时,它将是一个可遍历的字符串列表 —— 通常为用来在其内部进行导入的包的 __path__ 属性。 如果 path 参数为 None,这表示最高层级的导入,将会使用 sys.path

基于路径的查找器会迭代搜索路径中的每个条目,并且每次都查找与路径条目对应的 path entry finder (PathEntryFinder)。 因为这种操作可能很耗费资源(例如搜索会有 stat() 调用的开销),基于路径的查找器会维持一个缓存来将路径条目映射到路径条目查找器。 这个缓存放于 sys.path_importer_cache (尽管如此命名,但这个缓存实际存放的是查找器对象而非仅限于 importer 对象)。 通过这种方式,对特定 path entry 位置的 path entry finder 的高耗费搜索只需进行一次。 用户代码可以自由地从 sys.path_importer_cache 移除缓存条目,以强制基于路径的查找器再次执行路径条目搜索 。

如果路径条目不存在于缓存中,基于路径的查找器会迭代 sys.path_hooks 中的每个可调用对象。 对此列表中的每个 路径条目钩子 的调用会带有一个参数,即要搜索的路径条目。 每个可调用对象或是返回可处理路径条目的 path entry finder,或是引发 ImportError。 基于路径的查找器使用 ImportError 来表示钩子无法找到与 path entry 相对应的 path entry finder。 该异常会被忽略并继续进行 import path 的迭代。 每个钩子应该期待接收一个字符串或字节串对象;字节串对象的编码由钩子决定(例如可以是文件系统使用的编码 UTF-8 或其它编码),如果钩子无法解码参数,它应该引发 ImportError

如果 sys.path_hooks 迭代结束时没有返回 path entry finder,则基于路径的查找器 find_spec() 方法将在 sys.path_importer_cache 中存入 None (表示此路径条目没有对应的查找器) 并返回 None,表示此 meta path finder 无法找到该模块。

如果 sys.path_hooks 中的某个 path entry hook 可调用对象的返回值 一个 path entry finder,则以下协议会被用来向查找器请求一个模块的规格说明,并在加载该模块时被使用。

当前工作目录 — 由一个空字符串表示 — 的处理方式与 sys.path 中的其他条目略有不同。 首先,如果发现当前工作目录不存在,则 sys.path_importer_cache 中不会存放任何值。 其次,每个模块查找会对当前工作目录的值进行全新查找。 第三,由 sys.path_importer_cache 所使用并由 importlib.machinery.PathFinder.find_spec() 所返回的路径将是实际的当前工作目录而非空字符串。

5.5.2. 路径条目查找器协议

为了支持模块和已初始化包的导入,也为了给命名空间包提供组成部分,路径条目查找器必须实现 find_spec() 方法。

find_spec() 接受两个参数,即要导入模块的完整限定名称,以及(可选的)目标模块。 find_spec() 返回模块的完全填充好的规格说明。 这个规格说明总是包含“加载器”集合(但有一个例外)。

为了向导入机制提示该规格说明代表一个命名空间 portion,路径条目查找器会将 “submodule_search_locations” 设为一个包含该部分的列表。

在 3.4 版更改: find_spec() 替代了 find_loader()find_module(),后两者现在都已弃用,但会在 find_spec() 未定义时被使用。

较旧的路径条目查找器可能会实现这两个已弃用的方法中的一个而没有实现 find_spec()。 为保持向后兼容,这两个方法仍会被接受。 但是,如果在路径条目查找器上实现了 find_spec(),这两个遗留方法就会被忽略。

find_loader() 接受一个参数,即要导入模块的完整限定名称。 find_loader() 返回一个 2 元组,其中第一项是加载器而第二项是命名空间 portion。

为了向后兼容其他导入协议的实现,许多路径条目查找器也同样支持元路径查找器所支持的传统 find_module() 方法。 但是路径条目查找器 find_module() 方法的调用绝不会带有 path 参数(它们被期望记录来自对路径钩子初始调用的恰当路径信息)。

路径条目查找器的 find_module() 方法已弃用,因为它不允许路径条目查找器为命名空间包提供部分。 如果 find_loader()find_module() 同时存在于一个路径条目查找器中,导入系统将总是调用 find_loader() 而不选择 find_module()

在 3.10 版更改: 导入系统调用 find_module()find_loader() 将引发 ImportWarning

5.6. 替换标准导入系统

替换整个导入系统的最可靠机制是移除 sys.meta_path 的默认内容,,将其完全替换为自定义的元路径钩子。

一个可行的方式是仅改变导入语句的行为而不影响访问导入系统的其他 API,那么替换内置的 __import__() 函数可能就够了。 这种技巧也可以在模块层级上运用,即只在某个模块内部改变导入语句的行为。

想要选择性地预先防止在元路径上从一个钩子导入某些模块(而不是完全禁用标准导入系统),只需直接从 find_spec() 引发 ModuleNotFoundError 而非返回 None 就足够了。 返回后者表示元路径搜索应当继续,而引发异常则会立即终止搜索。

5.7. 包相对导入

相对导入使用前缀点号。 一个前缀点号表示相对导入从当前包开始。 两个或更多前缀点号表示对当前包的上级包的相对导入,第一个点号之后的每个点号代表一级。 例如,给定以下的包布局结构:

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

不论是在 subpackage1/moduleX.py 还是 subpackage1/__init__.py 中,以下导入都是有效的:

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

绝对导入可以使用 import <>from <> import <> 语法,但相对导入只能使用第二种形式;其中的原因在于:

import XXX.YYY.ZZZ

应当提供 XXX.YYY.ZZZ 作为可用表达式,但 .moduleY 不是一个有效的表达式。

5.8. 有关 main 的特殊事项

对于 Python 的导入系统来说 __main__ 模块是一个特殊情况。 __main__ 模块是在解释器启动时直接初始化的,与 sysbuiltins 很类似。 但是,与那两者不同,它并不被严格归类为内置模块。 这是因为 __main__ 被初始化的方式依赖于发起调用解释器所附带的旗标和其他选项。

5.8.1. main.spec

根据 __main__ 被初始化的方式,__main__.__spec__ 会被设置相应值或是 None

当 Python 附加 -m 选项启动时,__spec__ 会被设为相应模块或包的模块规格说明。 __spec__ 也会在 __main__ 模块作为执行某个目录,zip 文件或其它 sys.path 条目的一部分加载时被填充。

在 其余的情况 下 __main__.__spec__ 会被设为 None,因为用于填充 __main__ 的代码不直接与可导入的模块相对应:

  • 交互型提示
  • -c 选项
  • 从 stdin 运行
  • 直接从源码或字节码文件运行

请注意在最后一种情况中 __main__.__spec__ 总是为 None即使 文件从技术上说可以作为一个模块被导入。 如果想要让 __main__ 中的元数据生效,请使用 -m 开关。

还要注意即使是在 __main__ 对应于一个可导入模块且 __main__.__spec__ 被相应地设定时,它们仍会被视为 不同的 模块。 这是由于以下事实:使用 if __name__ == "__main__": 检测来保护的代码块仅会在模块被用来填充 __main__ 命名空间时而非普通的导入时被执行。

5.9. 开放问题项

XXX 最好是能增加一个图表。

XXX * (import_machinery.rst) 是否要专门增加一节来说明模块和包的属性,也许可以扩展或移植数据模型参考页中的相关条目?

XXX 库手册中的 runpy 和 pkgutil 等等应该都在页面顶端增加指向新的导入系统章节的“另请参阅”链接。

XXX 是否要增加关于初始化 __main__ 的不同方式的更多解释?

XXX 增加更多有关 __main__ 怪异/坑人特性的信息 (例如直接从 PEP 395 复制)。

5.10. 参考文献

导入机制自 Python 诞生之初至今已发生了很大的变化。 原始的 包规格说明 仍然可以查阅,但在撰写该文档之后许多相关细节已被修改。

原始的 sys.meta_path 规格说明见 PEP 302,后续的扩展说明见 PEP 420

PEP 420 为 Python 3.3 引入了 命名空间包。 PEP 420 还引入了 find_loader() 协议作为 find_module() 的替代。

PEP 366 描述了新增的 __package__ 属性,用于在模块中的显式相对导入。

PEP 328 引入了绝对和显式相对导入,并初次提出了 __name__ 语义,最终由 PEP 366__package__ 加入规范描述。

PEP 338 定义了将模块作为脚本执行。

PEP 451 在 spec 对象中增加了对每个模块导入状态的封装。 它还将加载器的大部分样板责任移交回导入机制中。 这些改变允许弃用导入系统中的一些 API 并为查找器和加载器增加一些新的方法。

注:

  • importlib 实现避免直接使用返回值。 而是通过在 sys.modules 中查找模块名称来获取模块对象。 这种方式的间接影响是被导入的模块可能在 sys.modules 中替换其自身。 这属于具体实现的特定行为,不保证能在其他 Python 实现中起作用。
  • 在遗留代码中,有可能在 sys.path_importer_cache 中找到 imp.NullImporter 的实例。 建议将这些代码修改为使用 None 代替。

6. 表达式

本章将解释 Python 中组成表达式的各种元素的的含义。

语法注释: 在本章和后续章节中,会使用扩展 BNF 标注来描述语法而不是词法分析。 当(某种替代的)语法规则具有如下形式

name ::=  othername

并且没有给出语义,则这种形式的 name 在语法上与 othername 相同。

6.1. 算术转换

当对下述某个算术运算符的描述中使用了“数值参数被转换为普通类型”这样的说法,这意味着内置类型的运算符实现采用了如下运作方式:

  • 如果任一参数为复数,另一参数会被转换为复数;
  • 否则,如果任一参数为浮点数,另一参数会被转换为浮点数;
  • 否则,两者应该都为整数,不需要进行转换。

某些附加规则会作用于特定运算符(例如,字符串作为 ‘%’ 运算符的左运算参数)。 扩展必须定义它们自己的转换行为。

6.2. 原子

“原子”指表达式的最基本构成元素。 最简单的原子是标识符和字面值。 以圆括号、方括号或花括号包括的形式在语法上也被归类为原子。 原子的句法为:

atom      ::=  identifier | literal | enclosure
enclosure ::=  parenth_form | list_display | dict_display | set_display
               | generator_expression | yield_atom

6.2.1. 标识符(名称)

作为原子出现的标识符叫做名称。 请参看 标识符和关键字 一节了解其词法定义,以及 命名与绑定 获取有关命名与绑定的文档。

当名称被绑定到一个对象时,对该原子求值将返回相应对象。 当名称未被绑定时,尝试对其求值将引发 NameError 异常。

私有名称转换: 当以文本形式出现在类定义中的一个标识符以两个或更多下划线开头并且不以两个或更多下划线结尾,它会被视为该类的 私有名称。 私有名称会在为其生成代码之前被转换为一种更长的形式。 转换时会插入类名,移除打头的下划线再在名称前增加一个下划线。 例如,出现在一个名为 Ham 的类中的标识符 __spam 会被转换为 _Ham__spam。 这种转换独立于标识符所使用的相关句法。 如果转换后的名称太长(超过 255 个字符),可能发生由具体实现定义的截断。 如果类名仅由下划线组成,则不会进行转换。

6.2.2. 字面值

Python 支持字符串和字节串字面值,以及几种数字字面值:

literal ::=  stringliteral | bytesliteral
             | integer | floatnumber | imagnumber

对字面值求值将返回一个该值所对应类型的对象(字符串、字节串、整数、浮点数、复数)。 对于浮点数和虚数(复数)的情况,该值可能为近似值。

所有字面值都对应与不可变数据类型,因此对象标识的重要性不如其实际值。 多次对具有相同值的字面值求值(不论是发生在程序文本的相同位置还是不同位置)可能得到相同对象或是具有相同值的不同对象。

6.2.3. 带圆括号的形式

带圆括号的形式是包含在圆括号中的可选表达式列表。

parenth_form ::=  "(" [starred_expression] ")"

带圆括号的表达式列表将返回该表达式列表所产生的任何东西:如果该列表包含至少一个逗号,它会产生一个元组;否则,它会产生该表达式列表所对应的单一表达式。

一对内容为空的圆括号将产生一个空的元组对象。 由于元组是不可变对象,因此适用与字面值相同的规则(即两次出现的空元组产生的对象可能相同也可能不同)。

请注意元组并不是由圆括号构建,实际起作用的是逗号操作符。 例外情况是空元组,这时圆括号 才是 必须的 —- 允许在表达式中使用不带圆括号的 “空” 会导致歧义,并会造成常见输入错误无法被捕获。

6.2.4. 列表、集合与字典的显示

为了构建列表、集合或字典,Python 提供了名为“显示”的特殊句法,每个类型各有两种形式:

  • 第一种是显式地列出容器内容
  • 第二种是通过一组循环和筛选指令计算出来,称为 推导式

推导式的常用句法元素为:

comprehension ::=  assignment_expression comp_for
comp_for      ::=  ["async"] "for" target_list "in" or_test [comp_iter]
comp_iter     ::=  comp_for | comp_if
comp_if       ::=  "if" or_test [comp_iter]

推导式的结构是一个单独表达式后面加至少一个 for 子句以及零个或更多个 forif 子句。 在这种情况下,新容器的元素产生方式是将每个 forif 子句视为一个代码块,按从左至右的顺序嵌套,然后每次到达最内层代码块时就对表达式进行求值以产生一个元素。

不过,除了最左边 for 子句中的可迭代表达式,推导式是在另一个隐式嵌套的作用域内执行的。 这能确保赋给目标列表的名称不会“泄露”到外层的作用域。

最左边的 for 子句中的可迭代对象表达式会直接在外层作用域中被求值,然后作为一个参数被传给隐式嵌套的作用域。 后续的 for 子句以及最左侧 for 子句中的任何筛选条件不能在外层作用域中被求值,因为它们可能依赖于从最左侧可迭代对象中获得的值。 例如: [x*y for x in range(10) for y in range(x, x+10)]

为了确保推导式得出的结果总是一个类型正确的容器,在隐式嵌套作用域内禁止使用 yieldyield from 表达式。

从 Python 3.6 开始,在 async def 函数中可以使用 async for 子句来迭代 asynchronous iterator。 在 async def 函数中构建推导式可以通过在打头的表达式后加上 forasync for 子句,也可能包含额外的 forasync for 子句,还可能使用 await 表达式。 如果一个推导式包含 async for 子句或者 await 表达式,则被称为 异步推导式。 异步推导式可以暂停执行它所在的协程函数。 另请参阅 PEP 530

3.6 新版功能: 引入了异步推导式。

在 3.8 版更改: yieldyield from 在隐式嵌套的作用域中已被禁用。

6.2.5. 列表显示

列表显示是一个用方括号括起来的可能为空的表达式系列:

list_display ::=  "[" [starred_list | comprehension] "]"

列表显示会产生一个新的列表对象,其内容通过一系列表达式或一个推导式来指定。 当提供由逗号分隔的一系列表达式时,其元素会从左至右被求值并按此顺序放入列表对象。 当提供一个推导式时,列表会根据推导式所产生的结果元素进行构建。

6.2.6. 集合显示

集合显示是用花括号标明的,与字典显示的区别在于没有冒号分隔的键和值:

set_display ::=  "{" (starred_list | comprehension) "}"

集合显示会产生一个新的可变集合对象,其内容通过一系列表达式或一个推导式来指定。 当提供由逗号分隔的一系列表达式时,其元素会从左至右被求值并加入到集合对象。 当提供一个推导式时,集合会根据推导式所产生的结果元素进行构建。

空集合不能用 {} 来构建;该字面值所构建的是一个空字典。

6.2.7. 字典显示

字典显示是一个用花括号括起来的可能为空的键/数据对系列:

dict_display       ::=  "{" [key_datum_list | dict_comprehension] "}"
key_datum_list     ::=  key_datum ("," key_datum)* [","]
key_datum          ::=  expression ":" expression | "**" or_expr
dict_comprehension ::=  expression ":" expression comp_for

字典显示会产生一个新的字典对象。

如果给出一个由逗号分隔的键/数据对序列,它们会从左至右被求值以定义字典的条目:每个键对象会被用作在字典中存放相应数据的键。 这意味着你可以在键/数据对序列中多次指定相同的键,最终字典的值将由最后一次给出的键决定。

双星号 ** 表示 字典拆包。 它的操作数必须是一个 mapping。 每个映射项被会加入新的字典。 后续的值会替代先前的键/数据对和先前的字典拆包所设置的值。

3.5 新版功能: 拆包到字典显示,最初由 PEP 448 提出。

字典推导式与列表和集合推导式有所不同,它需要以冒号分隔的两个表达式,后面带上标准的 “for” 和 “if” 子句。 当推导式被执行时,作为结果的键和值元素会按它们的产生顺序被加入新的字典。

(总的说来,键的类型应该为 hashable,这就把所有可变对象都排除在外。) 重复键之间的冲突不会被检测;指定键所保存的最后一个数据 (即在显示中排最右边的文本) 为最终有效数据。

在 3.8 版更改: 在 Python 3.8 之前的字典推导式中,并没有定义好键和值的求值顺序。 在 CPython 中,值会先于键被求值。 根据 PEP 572 的提议,从 3.8 开始,键会先于值被求值。

6.2.8. 生成器表达式

生成器表达式是用圆括号括起来的紧凑形式生成器标注。

generator_expression ::=  "(" expression comp_for ")"

生成器表达式会产生一个新的生成器对象。 其句法与推导式相同,区别在于它是用圆括号而不是用方括号或花括号括起来的。

在生成器表达式中使用的变量会在为生成器对象调用 __next__() 方法的时候以惰性方式被求值(即与普通生成器相同的方式)。 但是,最左侧 for 子句内的可迭代对象是会被立即求值的,因此它所造成的错误会在生成器表达式被定义时被检测到,而不是在获取第一个值时才出错。 后续的 for 子句以及最左侧 for 子句内的任何筛选条件无法在外层作用域内被求值,因为它们可能会依赖于从最左侧可迭代对象获取的值。 例如: (x*y for x in range(10) for y in range(x, x+10)).

圆括号在只附带一个参数的调用中可以被省略。

为了避免干扰到生成器表达式本身的预期操作,禁止在隐式定义的生成器中使用 yieldyield from 表达式。

如果生成器表达式包含 async for 子句或 await 表达式,则称为 异步生成器表达式。 异步生成器表达式会返回一个新的异步生成器对象,此对象属于异步迭代器 。

3.6 新版功能: 引入了异步生成器表达式。

在 3.7 版更改: 在 Python 3.7 之前,异步生成器表达式只能在 async def 协和中出现。 从 3.7 开始,任何函数都可以使用异步生成器表达式。

在 3.8 版更改: yieldyield from 在隐式嵌套的作用域中已被禁用。

6.2.9. yield 表达式

yield_atom       ::=  "(" yield_expression ")"
yield_expression ::=  "yield" [expression_list | "from" expression]

yield 表达式在定义 generator 函数或是 asynchronous generator 的时候才会用到。 因此只能在函数定义的内部使用yield表达式。 在一个函数体内使用 yield 表达式会使这个函数变成一个生成器,并且在一个 async def 定义的函数体内使用 yield 表达式会让协程函数变成异步的生成器。 比如说:

def gen():  # defines a generator function
    yield 123
async def agen(): # defines an asynchronous generator function
    yield 123

由于它们会对外层作用域造成附带影响,yield 表达式不被允许作为用于实现推导式和生成器表达式的隐式定义作用域的一部分。

在 3.8 版更改: 禁止在实现推导式和生成器表达式的隐式嵌套作用域中使用 yield 表达式。

下面是对生成器函数的描述,异步生成器函数会在 异步生成器函数 一节中单独介绍。

当一个生成器函数被调用的时候,它返回一个迭代器,称为生成器。然后这个生成器来控制生成器函数的执行。当这个生成器的某一个方法被调用的时候,生成器函数开始执行。这时会一直执行到第一个 yield 表达式,在此执行再次被挂起,给生成器的调用者返回 expression_list 的值。挂起后,我们说所有局部状态都被保留下来,包括局部变量的当前绑定,指令指针,内部求值栈和任何异常处理的状态。通过调用生成器的某一个方法,生成器函数继续执行。此时函数的运行就和 yield 表达式只是一个外部函数调用的情况完全一致。恢复后 yield 表达式的值取决于调用的哪个方法来恢复执行。 如果用的是 __next__() (通常通过语言内置的 for 或是 next() 来调用) 那么结果就是 None. 否则,如果用 send(), 那么结果就是传递给send方法的值。

所有这些使生成器函数与协程非常相似;它们 yield 多次,它们具有多个入口点,并且它们的执行可以被挂起。唯一的区别是生成器函数不能控制在它在 yield 后交给哪里继续执行;控制权总是转移到生成器的调用者。

try 结构中的任何位置都允许yield表达式。如果生成器在(因为引用计数到零或是因为被垃圾回收)销毁之前没有恢复执行,将调用生成器-迭代器的 close() 方法. close 方法允许任何挂起的 finally 子句执行。

当使用 yield from <expr> 时,所提供的表达式必须是一个可迭代对象。 迭代该可迭代对象所产生的值会被直接传递给当前生成器方法的调用者。 任何通过 send() 传入的值以及任何通过 throw() 传入的异常如果有适当的方法则会被传给下层迭代器。 如果不是这种情况,那么 send() 将引发 AttributeErrorTypeError,而 throw() 将立即引发所转入的异常。

当下层迭代器完成时,被引发的 StopIteration 实例的 value 属性会成为 yield 表达式的值。 它可以在引发 StopIteration 时被显式地设置,也可以在子迭代器是一个生成器时自动地设置(通过从子生成器返回一个值)。

在 3.3 版更改: 添加 yield from <expr> 以委托控制流给一个子迭代器。

当yield表达式是赋值语句右侧的唯一表达式时,括号可以省略。

参见

PEP 255 - 简单生成器

在 Python 中加入生成器和 yield 语句的提议。

PEP 342 - 通过增强型生成器实现协程

增强生成器 API 和语法的提议,使其可以被用作简单的协程。

PEP 380 - 委托给子生成器的语法

引入 yield_from 语法以方便地委托给子生成器的提议。

PEP 525 - 异步生成器

通过给协程函数加入生成器功能对 PEP 492 进行扩展的提议。

6.2.9.1. 生成器-迭代器的方法

这个子小节描述了生成器迭代器的方法。 它们可被用于控制生成器函数的执行。

请注意在生成器已经在执行时调用以下任何方法都会引发 ValueError 异常。

generator.__next__()

开始一个生成器函数的执行或是从上次执行的 yield 表达式位置恢复执行。 当一个生成器函数通过 __next__() 方法恢复执行时,当前的 yield 表达式总是取值为 None。 随后会继续执行到下一个 yield 表达式,其 expression_list 的值会返回给 __next__() 的调用者。 如果生成器没有产生下一个值就退出,则将引发 StopIteration 异常。

此方法通常是隐式地调用,例如通过 for 循环或是内置的 next() 函数。

generator.send(value)

恢复执行并向生成器函数“发送”一个值。 value 参数将成为当前 yield 表达式的结果。 send() 方法会返回生成器所产生的下一个值,或者如果生成器没有产生下一个值就退出则会引发 StopIteration。 当调用 send() 来启动生成器时,它必须以 None 作为调用参数,因为这时没有可以接收值的 yield 表达式。

generator.throw(type[, value[, traceback]])

在生成器暂停的位置引发 type 类型的异常,并返回该生成器函数所产生的下一个值。 如果生成器没有产生下一个值就退出,则将引发 StopIteration 异常。 如果生成器函数没有捕获传入的异常,或引发了另一个异常,则该异常会被传播给调用者。

generator.close()

在生成器函数暂停的位置引发 GeneratorExit。 如果之后生成器函数正常退出、关闭或引发 GeneratorExit (由于未捕获该异常) 则关闭并返回其调用者。 如果生成器产生了一个值,关闭会引发 RuntimeError。 如果生成器引发任何其他异常,它会被传播给调用者。 如果生成器已经由于异常或正常退出则 close() 不会做任何事。

6.2.9.2. 例子

这里是一个简单的例子,演示了生成器和生成器函数的行为:

>>> def echo(value=None):
...     print("Execution starts when 'next()' is called for the first time.")
...     try:
...         while True:
...             try:
...                 value = (yield value)
...             except Exception as e:
...                 value = e
...     finally:
...         print("Don't forget to clean up when 'close()' is called.")
...
>>> generator = echo(1)
>>> print(next(generator))
Execution starts when 'next()' is called for the first time.
1
>>> print(next(generator))
None
>>> print(generator.send(2))
2
>>> generator.throw(TypeError, "spam")
TypeError('spam',)
>>> generator.close()
Don't forget to clean up when 'close()' is called.
6.2.9.3. 异步生成器函数

在一个使用 async def 定义的函数或方法中出现的 yield 表达式会进一步将该函数定义为一个 asynchronous generator 函数。

当一个异步生成器函数被调用时,它会返回一个名为异步生成器对象的异步迭代器。 此对象将在之后控制该生成器函数的执行。 异步生成器对象通常被用在协程函数的 async for 语句中,类似于在 for 语句中使用生成器对象。

调用异步生成器的方法之一将返回 awaitable 对象,执行会在此对象被等待时启动。 到那时,执行将前往第一个 yield 表达式,在那里它会再次暂停,将 expression_list 的值返回给等待中的协程。 与生成器一样,挂起意味着局部的所有状态会被保留,包括局部变量的当前绑定、指令的指针、内部求值的堆栈以及任何异常处理的状态。 当执行在等待异步生成器的方法返回下一个对象后恢复时,该函数可以从原状态继续进行,就仿佛 yield 表达式只是另一个外部调用。 恢复执行之后 yield 表达式的值取决于恢复执行所用的方法。 如果使用 __anext__() 则结果为 None。 否则的话,如果使用 asend() 则结果将是传递给该方法的值。

如果一个异步生成器恰好因 break、调用方任务被取消,或是其他异常而提前退出,生成器的异步清理代码将会运行并可能引发异常或访问意外上下文中的上下文变量 — 也许是在它所依赖的任务的生命周期之后,或是在异步生成器垃圾回收钩子被调用时的事件循环关闭期间。 为了防止这种情况,调用方必须通过调用 aclose() 方法来显式地关闭异步生成器以终结生成器并最终从事件循环中将其分离。

在异步生成器函数中,yield 表达式允许出现在 try 结构的任何位置。 但是,如果一个异步生成器在其被终结(由于引用计数达到零或被作为垃圾回收)之前未被恢复,则then a yield expression within a try 结构中的 yield 表达式可能导致挂起的 finally 子句执行失败。 在此情况下,应由运行该异步生成器的事件循环或任务调度器来负责调用异步生成器-迭代器的 aclose() 方法并运行所返回的协程对象,从而允许任何挂起的 finally 子句得以执行。

为了能在事件循环终结时执行最终化处理,事件循环应当定义一个 终结器 函数,它接受一个异步生成器迭代器并将调用 aclose() 且执行该协程。 这个 终结器 可以通过调用 sys.set_asyncgen_hooks() 来注册。 当首次迭代时,异步生成器迭代器将保存已注册的 终结器 以便在最终化时调用。 有关 终结器 方法的参考示例请查看在 Lib/asyncio/base_events.py 的中的 asyncio.Loop.shutdown_asyncgens 实现。

yield from <expr> 表达式如果在异步生成器函数中使用会引发语法错误。

6.2.9.4. 异步生成器-迭代器方法

这个子小节描述了异步生成器迭代器的方法,它们可被用于控制生成器函数的执行。

coroutine agen.__anext__()

返回一个可等待对象,它在运行时会开始执行该异步生成器或是从上次执行的 yield 表达式位置恢复执行。 当一个异步生成器函数通过 __anext__() 方法恢复执行时,当前的 yield 表达式所返回的可等待对象总是取值为 None,它在运行时将继续执行到下一个 yield 表达式。 该 yield 表达式的 expression_list 的值会是完成的协程所引发的 StopIteration 异常的值。 如果异步生成器没有产生下一个值就退出,则该可等待对象将引发 StopAsyncIteration 异常,提示该异步迭代操作已完成。

此方法通常是通过 async for 循环隐式地调用。

coroutine agen.asend(value)

返回一个可等待对象,它在运行时会恢复该异步生成器的执行。 与生成器的 send() 方法一样,此方法会“发送”一个值给异步生成器函数,其 value 参数会成为当前 yield 表达式的结果值。 asend() 方法所返回的可等待对象将返回生成器产生的下一个值,其值为所引发的 StopIteration,或者如果异步生成器没有产生下一个值就退出则引发 StopAsyncIteration。 当调用 asend() 来启动异步生成器时,它必须以 None 作为调用参数,因为这时没有可以接收值的 yield 表达式。

coroutine agen.athrow(type[, value[, traceback]])

返回一个可等待对象,它会在异步生成器暂停的位置引发 type 类型的异常,并返回该生成器函数所产生的下一个值,其值为所引发的 StopIteration 异常。 如果异步生成器没有产生下一个值就退出,则将由该可等待对象引发 StopAsyncIteration 异步。 如果生成器函数没有捕获传入的异常,或引发了另一个异常,则当可等待对象运行时该异常会被传播给可等待对象的调用者。

coroutine agen.aclose()

返回一个可等待对象,它会在运行时向异步生成器函数暂停的位置抛入一个 GeneratorExit。 如果该异步生成器函数正常退出、关闭或引发 GeneratorExit (由于未捕获该异常) 则返回的可等待对象将引发 StopIteration 异常。 后续调用异步生成器所返回的任何其他可等待对象将引发 StopAsyncIteration 异常。 如果异步生成器产生了一个值,该可等待对象会引发 RuntimeError。 如果异步生成器引发任何其他异常,它会被传播给可等待对象的调用者。 如果异步生成器已经由于异常或正常退出则后续调用 aclose() 将返回一个不会做任何事的可等待对象。

6.3. 原型

原型代表编程语言中最紧密绑定的操作。 它们的句法如下:

primary ::=  atom | attributeref | subscription | slicing | call

6.3.1. 属性引用

属性引用是后面带有一个句点加一个名称的原型:

attributeref ::=  primary "." identifier

此原型必须求值为一个支持属性引用的类型的对象,多数对象都支持属性引用。 随后该对象会被要求产生以指定标识符为名称的属性。 这个产生过程可通过重载 __getattr__() 方法来自定义。 如果这个属性不可用,则将引发 AttributeError 异常。 否则的话,所产生对象的类型和值会根据该对象来确定。 对同一属性引用的多次求值可能产生不同的对象。

6.3.2. 抽取

对序列(字符串、元组或列表)或映射(字典)对象的抽取操作通常就是从相应的多项集中选择一项:

subscription ::=  primary "[" expression_list "]"

此原型必须求值为一个支持抽取操作的对象(例如列表或字典)。 用户定义的对象可通过定义 __getitem__() 方法来支持抽取操作。

对于内置对象,有两种类型的对象支持抽取操作:

如果原型为映射,表达式列表必须求值为一个以该映射的键为值的对象,抽取操作会在映射中选出该键所对应的值。(表达式列表为一个元组,除非其中只有一项。)

如果原型为序列,表达式列表必须求值为一个整数或一个切片(详情见下节)。

正式句法规则并没有在序列中设置负标号的特殊保留条款;但是,内置序列所提供的 __getitem__() 方法都可通过在索引中添加序列长度来解析负标号 (这样 x[-1] 会选出 x 中的最后一项)。 结果值必须为一个小于序列中项数的非负整数,抽取操作会选出标号为该值的项(从零开始数)。 由于对负标号和切片的支持存在于对象的 __getitem__() 方法,重载此方法的子类需要显式地添加这种支持。

字符串的项是字符。 字符不是单独的数据类型而是仅有一个字符的字符串。

对特定 类 或 类型 的抽取操作会创建一个 泛型别名。 在此情况下,用户自定义类型可通过提供 __class_getitem__() 类方法来支持抽取操作。

6.3.3. 切片

切片就是在序列对象(字符串、元组或列表)中选择某个范围内的项。 切片可被用作表达式以及赋值或 del 语句的目标。 切片的句法如下:

slicing      ::=  primary "[" slice_list "]"
slice_list   ::=  slice_item ("," slice_item)* [","]
slice_item   ::=  expression | proper_slice
proper_slice ::=  [lower_bound] ":" [upper_bound] [ ":" [stride] ]
lower_bound  ::=  expression
upper_bound  ::=  expression
stride       ::=  expression

此处的正式句法中存在一点歧义:任何形似表达式列表的东西同样也会形似切片列表,因此任何抽取操作也可以被解析为切片。 为了不使句法更加复杂,于是通过定义将此情况解析为抽取优先于解析为切片来消除这种歧义(切片列表未包含正确的切片就属于此情况)。

切片的语义如下所述。 元型通过一个根据下面的切片列表来构造的键进行索引(与普通抽取一样使用 __getitem__() 方法)。 如果切片列表包含至少一个逗号,则键将是一个包含切片项转换的元组;否则的话,键将是单个切片项的转换。 切片项如为一个表达式,则其转换就是该表达式。 一个正确切片的转换就是一个切片对象,该对象的 start, stopstep 属性将分别为表达式所给出的下界、上界和步长值,省略的表达式将用 None 来替换。

6.3.4. 调用

所谓调用就是附带可能为空的一系列 参数 来执行一个可调用对象 (例如 function):

call                 ::=  primary "(" [argument_list [","] | comprehension] ")"
argument_list        ::=  positional_arguments ["," starred_and_keywords]
                            ["," keywords_arguments]
                          | starred_and_keywords ["," keywords_arguments]
                          | keywords_arguments
positional_arguments ::=  positional_item ("," positional_item)*
positional_item      ::=  assignment_expression | "*" expression
starred_and_keywords ::=  ("*" expression | keyword_item)
                          ("," "*" expression | "," keyword_item)*
keywords_arguments   ::=  (keyword_item | "**" expression)
                          ("," keyword_item | "," "**" expression)*
keyword_item         ::=  identifier "=" expression

一个可选项为在位置和关键字参数后加上逗号而不影响语义。

此原型必须求值为一个可调用对象(用户定义的函数,内置函数,内置对象的方法,类对象,类实例的方法以及任何具有 __call__() 方法的对象都是可调用对象)。 所有参数表达式将在尝试调用前被求值。

如果存在关键字参数,它们会先通过以下操作被转换为位置参数。 首先,为正式参数创建一个未填充空位的列表. 如果有 N 个位置参数,则将它们放入前 N 个空位。 然后,对于每个关键字参数,使用标识符来确定其对应的空位(如果标识符与第一个正式参数名相同则使用第一个个空位,依此类推)。 如果空位已被填充,则会引发 TypeError 异常。 否则,将参数值放入空位进行填充(即使表达式为 None 也会填充空位)。 当所有参数处理完毕时,尚未填充的空位将用来自函数定义的相应默认值来填充。 (函数一旦定义其参数默认值就会被计算;因此,当列表或字典这类可变对象被用作默认值时,将会被所有未指定相应空位参数值的调用所共享;这种情况通常应当避免。) 如果任何一个未填充空位没有指定默认值,则会引发 TypeError 异常。 否则的话,已填充空位的列表会被作为调用的参数列表。

CPython implementation detail: 某些实现可能提供位置参数没有名称的内置函数,即使它们在文档说明的场合下有“命名”,因此不能以关键字形式提供参数。 在 CPython 中,以 C 编写并使用 PyArg_ParseTuple() 来解析其参数的函数实现就属于这种情况。

如果存在比正式参数空位多的位置参数,将会引发 TypeError 异常,除非有一个正式参数使用了 *identifier 句法;在此情况下,该正式参数将接受一个包含了多余位置参数的元组(如果没有多余位置参数则为一个空元组)。

如果任何关键字参数没有与之对应的正式参数名称,将会引发 TypeError 异常,除非有一个正式参数使用了 **identifier 句法,该正式参数将接受一个包含了多余关键字参数的字典(使用关键字作为键而参数值作为与键对应的值),如果没有多余关键字参数则为一个(新的)空字典。

如果函数调用中出现了 *expression 句法,expression 必须求值为一个 iterable。 来自该可迭代对象的元素会被当作是额外的位置参数。 对于 f(x1, x2, *y, x3, x4) 调用,如果 y 求值为一个序列 y1, …, yM*,则它就等价于一个带有 M+4 个位置参数 *x1, x2, y1, …, yM, x3, x4 的调用。

这样做的一个后果是虽然 *expression 句法可能出现于显式的关键字参数 之后,但它会在关键字参数(以及任何 `*expression` 参数 — 见下文) *之前 被处理。 因此:

>>> def f(a, b):
...     print(a, b)
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2

在同一个调用中同时使用关键字参数和 *expression 句法并不常见,因此实际上这样的混淆不会发生。

如果函数调用中出现了 **expression 句法,expression 必须求值为一个 mapping,其内容会被当作是额外的关键字参数。 如果一个关键字已存在(作为显式关键字参数,或来自另一个拆包),则将引发 TypeError 异常。

使用 *identifier**identifier 句法的正式参数不能被用作位置参数空位或关键字参数名称。

在 3.5 版更改: 函数调用接受任意数量的 *** 拆包,位置参数可能跟在可迭代对象拆包 (*) 之后,而关键字参数可能跟在字典拆包 (**) 之后。 由 PEP 448 发起最初提议。

除非引发了异常,调用总是会有返回值,返回值也可能为 None。 返回值的计算方式取决于可调用对象的类型。

如果类型为—-

用户自定义函数:

函数的代码块会被执行,并向其传入参数列表。 代码块所做的第一件事是将正式形参绑定到对应参数。 当代码块执行 return 语句时,由其指定函数调用的返回值。

内置函数或方法:

具体结果依赖于解释器。

类对象:

返回该类的一个新实例。

类实例方法:

调用相应的用户自定义函数,向其传入的参数列表会比调用的参数列表多一项:该实例将成为第一个参数。

类实例:

该类必须定义有 __call__() 方法;作用效果将等价于调用该方法。

6.4. await 表达式

挂起 coroutine 的执行以等待一个 awaitable 对象。 只能在 coroutine function 内部使用。

await_expr ::=  "await" primary

3.5 新版功能.

6.5. 幂运算符

幂运算符的绑定比在其左侧的一元运算符更紧密;但绑定紧密程度不及在其右侧的一元运算符。 句法如下:

power ::=  (await_expr | primary) ["**" u_expr]

因此,在一个未加圆括号的幂运算符和单目运算符序列中,运算符将从右向左求值(这不会限制操作数的求值顺序): -1**2 结果将为 -1

幂运算符与附带两个参数调用内置 pow() 函数具有相同的语义:结果为对其左参数进行其右参数所指定幂次的乘方运算。 数值参数会先转换为相同类型,结果也为转换后的类型。

对于 int 类型的操作数,结果将具有与操作数相同的类型,除非第二个参数为负数;在那种情况下,所有参数会被转换为 float 类型并输出 float 类型的结果。 例如,10**2 返回 100,而 10**-2 返回 0.01

0.0 进行负数幂次运算将导致 ZeroDivisionError。 对负数进行分数幂次运算将返回 complex 数值。 (在早期版本中这将引发 ValueError。)

此运算符可使用特殊的 __pow__() 方法来自定义。

6.6. 一元算术和位运算

所有算术和位运算具有相同的优先级:

u_expr ::=  power | "-" u_expr | "+" u_expr | "~" u_expr

一元的 - (负值) 运算符会产生其数字参数的负值;该运算可通过 __neg__() 特殊方法来重载。

一元的 + (正值) 运算符会原样输出其数字参数;该运算可通过 __pos__() 特殊方法来重载。

一元的 ~ (取反) 运算符会对其整数参数按位取反。 x 的按位取反被定义为 -(x+1)。 它只作用于整数或是重载了 __invert__() 特殊方法的自定义对象。

在所有三种情况下,如果参数的类型不正确,将引发 TypeError 异常。

6.7. 二元算术运算符

二元算术运算符遵循传统的优先级。 请注意某些此类运算符也作用于特定的非数字类型。 除幂运算符以外只有两个优先级别,一个作用于乘法型运算符,另一个作用于加法型运算符:

m_expr ::=  u_expr | m_expr "*" u_expr | m_expr "@" m_expr |
            m_expr "//" u_expr | m_expr "/" u_expr |
            m_expr "%" u_expr
a_expr ::=  m_expr | a_expr "+" m_expr | a_expr "-" m_expr

运算符 * (乘) 将输出其参数的乘积。 两个参数或者必须都为数字,或者一个参数必须为整数而另一个参数必须为序列。 在前一种情况下,两个数字将被转换为相同类型然后相乘。 在后一种情况下,将执行序列的重复;重复因子为负数将输出空序列。

此运算可使用特殊的 __mul__()__rmul__() 方法来自定义。

运算符 @ (at) 的目标是用于矩阵乘法。 没有内置 Python 类型实现此运算符。

3.5 新版功能.

运算符 / (除) 和 // (整除) 将输出其参数的商。 两个数字参数将先被转换为相同类型。 整数相除会输出一个 float 值,整数相整除的结果仍是整数;整除的结果就是使用 ‘floor’ 函数进行算术除法的结果。 除以零的运算将引发 ZeroDivisionError 异常。

This operation can be customized using the special __truediv__() and __floordiv__() methods.

运算符 % (模) 将输出第一个参数除以第二个参数的余数。 两个数字参数将先被转换为相同类型。 右参数为零将引发 ZeroDivisionError 异常。 参数可以为浮点数,例如 3.14%0.7 等于 0.34 (因为 3.14 等于 4*0.7 + 0.34)。 模运算符的结果的正负总是与第二个操作数一致(或是为零);结果的绝对值一定小于第二个操作数的绝对值 。

整除与模运算符的联系可通过以下等式说明: x == (x//y)*y + (x%y)。 此外整除与模也可通过内置函数 divmod() 来同时进行: divmod(x, y) == (x//y, x%y)

除了对数字执行模运算,运算符 % 还被字符串对象重载用于执行旧式的字符串格式化(又称插值)。 字符串格式化句法的描述参见 Python 库参考的 printf 风格的字符串格式化 一节。

取余 运算可使用特殊的 __mod__() 方法来自定义。

整除运算符,模运算符和 divmod() 函数未被定义用于复数。 如果有必要可以使用 abs() 函数将其转换为浮点数。

运算符 + (addition) 将输出其参数的和。 两个参数或者必须都为数字,或者都为相同类型的序列。 在前一种情况下,两个数字将被转换为相同类型然后相加。 在后一种情况下,将执行序列拼接操作。

此运算可使用特殊的 __add__()__radd__() 方法来自定义。

运算符 - (减) 将输出其参数的差。 两个数字参数将先被转换为相同类型。

此运算可使用特殊的 __sub__() 方法来自定义。

6.8. 移位运算

移位运算的优先级低于算术运算:

shift_expr ::=  a_expr | shift_expr ("<<" | ">>") a_expr

这些运算符接受整数参数。 它们会将第一个参数左移或右移第二个参数所指定的比特位数。

此运算可使用特殊的 __lshift__()__rshift__() 方法来自定义。

右移 n 位被定义为被 pow(2,n) 整除。 左移 n 位被定义为乘以 pow(2,n)

6.9. 二元位运算

三种位运算具有各不相同的优先级:

and_expr ::=  shift_expr | and_expr "&" shift_expr
xor_expr ::=  and_expr | xor_expr "^" and_expr
or_expr  ::=  xor_expr | or_expr "|" xor_expr

& 运算符会对其参数执行按位 AND,参数必须都为整数或者其中之一必须为重载了 __and__()__rand__() 特殊方法的自定义对象。

^ 运算符会对其参数执行按位 XOR (异 OR),参数必须都为整数或者其中之一必须为重载了 __xor__()__rxor__() 特殊方法的自定义对象。

| 运算符会对其参数执行按位 (合并) OR,参数必须都为整数或者其中之一必须为重载了 __or__()__ror__() 特殊方法的自定义对象。

6.10. 比较运算

与 C 不同,Python 中所有比较运算的优先级相同,低于任何算术、移位或位运算。 另一个与 C 不同之处在于 a < b < c 这样的表达式会按传统算术法则来解读:

comparison    ::=  or_expr (comp_operator or_expr)*
comp_operator ::=  "<" | ">" | "==" | ">=" | "<=" | "!="
                   | "is" ["not"] | ["not"] "in"

比较运算会产生布尔值: TrueFalse。 自定义的 富比较方法 可能返回非布尔值。 在此情况下 Python 将在布尔运算上下文中对该值调用 bool()

比较运算可以任意串连,例如 x < y <= z 等价于 x < y and y <= z,除了 y 只被求值一次(但在两种写法下当 x < y 值为假时 z 都不会被求值)。

正式的说法是这样:如果 a, b, c, …, y, z 为表达式而 op1, op2, …, opN 为比较运算符,则 a op1 b op2 c ... y opN z 就等价于 a op1 b and b op2 c and ... y opN z,不同点在于每个表达式最多只被求值一次。

请注意 a op1 b op2 c 不意味着在 ac 之间进行任何比较,因此,如 x < y > z 这样的写法是完全合法的(虽然也许不太好看)。

6.10.1. 值比较

运算符 <, >, ==, >=, <=!= 将比较两个对象的值。 两个对象不要求为相同类型。

对象值在 Python 中是一个相当抽象的概念:例如,对象值并没有一个规范的访问方法。 而且,对象值并不要求具有特定的构建方式,例如由其全部数据属性组成等。 比较运算符实现了一个特定的对象值概念。 人们可以认为这是通过实现对象比较间接地定义了对象值。

由于所有类型都是 object 的(直接或间接)子类型,它们都从 object 继承了默认的比较行为。 类型可以通过实现 丰富比较方法 例如 __lt__() 来定义自己的比较行为。

默认的一致性比较 (==!=) 是基于对象的标识号。 因此,具有相同标识号的实例一致性比较结果为相等,具有不同标识号的实例一致性比较结果为不等。 规定这种默认行为的动机是希望所有对象都应该是自反射的 (即 x is y 就意味着 x == y)。

次序比较 (<, >, <=>=) 默认没有提供;如果尝试比较会引发 TypeError。 规定这种默认行为的原因是缺少与一致性比较类似的固定值。

按照默认的一致性比较行为,具有不同标识号的实例总是不相等,这可能不适合某些对象值需要有合理定义并有基于值的一致性的类型。 这样的类型需要定制自己的比较行为,实际上,许多内置类型都是这样做的。

以下列表描述了最主要内置类型的比较行为。

  • 内置数值类型 (数字类型 —- int, float, complex) 以及标准库类型 fractions.Fractiondecimal.Decimal 可进行类型内部和跨类型的比较,例外限制是复数不支持次序比较。 在类型相关的限制以内,它们会按数学(算法)规则正确进行比较且不会有精度损失。

    非数字值 float('NaN')decimal.Decimal('NaN') 属于特例。 任何数字与非数字值的排序比较均返回假值。 还有一个反直觉的结果是非数字值不等于其自身。 举例来说,如果 x = float('NaN')3 < x, x < 3x == x 均为假值,而 x != x 则为真值。 此行为是遵循 IEEE 754 标准的。

  • NoneNotImplemented 都是单例对象。 PEP 8 建议单例对象的比较应当总是通过 isis not 而不是等于运算符来进行。

  • 二进制码序列 (bytesbytearray 的实例) 可进行类型内部和跨类型的比较。 它们使用其元素的数字值按字典顺序进行比较。

  • 字符串 (str 的实例) 使用其字符的 Unicode 码位数字值 (内置函数 ord() 的结果) 按字典顺序进行比较.

    字符串和二进制码序列不能直接比较。

  • 序列 (tuple, listrange 的实例) 只可进行类型内部的比较,range 还有一个限制是不支持次序比较。 以上对象的跨类型一致性比较结果将是不相等,跨类型次序比较将引发 TypeError

    序列比较是按字典序对相应元素进行逐个比较。 内置容器通常设定同一对象与其自身是相等的。 这使得它们能跳过同一对象的相等性检测以提升运行效率并保持它们的内部不变性。

    内置多项集间的字典序比较规则如下:

    • 两个多项集若要相等,它们必须为相同类型、相同长度,并且每对相应的元素都必须相等(例如,[1,2] == (1,2) 为假值,因为类型不同)。
    • 对于支持次序比较的多项集,排序与其第一个不相等元素的排序相同(例如 [1,2,x] <= [1,2,y] 的值与x <= y 相同)。 如果对应元素不存在,较短的多项集排序在前(例如 [1,2] < [1,2,3] 为真值)。
  • 两个映射 (dict 的实例) 若要相等,必须当且仅当它们具有相同的 (键, 值) 对。 键和值的一致性比较强制规定自反射性。

    次序比较 (<, >, <=>=) 将引发 TypeError

  • 集合 (setfrozenset 的实例) 可进行类型内部和跨类型的比较。

    它们将比较运算符定义为子集和超集检测。 这类关系没有定义完全排序(例如 {1,2}{2,3} 两个集合不相等,即不为彼此的子集,也不为彼此的超集。 相应地,集合不适宜作为依赖于完全排序的函数的参数(例如如果给出一个集合列表作为 min(), max()sorted() 的输入将产生未定义的结果)。

    集合的比较强制规定其元素的自反射性。

  • 大多数其他内置类型没有实现比较方法,因此它们会继承默认的比较行为。

在可能的情况下,用户定义类在定制其比较行为时应当遵循一些一致性规则:

  • 相等比较应该是自反射的。 换句话说,相同的对象比较时应该相等:

    x is y 意味着 x == y

  • 比较应该是对称的。 换句话说,下列表达式应该有相同的结果:

    x == yy == x

    x != yy != x

    x < yy > x

    x <= yy >= x

  • 比较应该是可传递的。 下列(简要的)例子显示了这一点:

    x > y and y > z 意味着 x > z

    x < y and y <= z 意味着 x < z

  • 反向比较应该导致布尔值取反。 换句话说,下列表达式应该有相同的结果:

    x == ynot x != y

    x < ynot x >= y (对于完全排序)

    x > ynot x <= y (对于完全排序)

    最后两个表达式适用于完全排序的多项集(即序列而非集合或映射)。

  • hash() 的结果应该与是否相等一致。 相等的对象应该或者具有相同的哈希值,或者标记为不可哈希。

Python 并不强制要求这些一致性规则。 实际上,非数字值就是一个不遵循这些规则的例子。

6.10.2. 成员检测运算

运算符 innot in 用于成员检测。 如果 xs 的成员则 x in s 求值为 True,否则为 Falsex not in s 返回 x in s 取反后的值。 所有内置序列和集合类型以及字典都支持此运算,对于字典来说 in 检测其是否有给定的键。 对于 list, tuple, set, frozenset, dict 或 collections.deque 这样的容器类型,表达式 x in y 等价于 any(x is e or x == e for e in y)

对于字符串和字节串类型来说,当且仅当 xy 的子串时 x in yTrue。 一个等价的检测是 y.find(x) != -1。 空字符串总是被视为任何其他字符串的子串,因此 "" in "abc" 将返回 True

对于定义了 __contains__() 方法的用户自定义类来说,如果 y.__contains__(x) 返回真值则 x in y 返回 True,否则返回 False

对于未定义 __contains__() 但定义了 __iter__() 的用户自定义类来说,如果在对 y 进行迭代时产生了值 z 使得表达式 x is z or x == z 为真,则 x in yTrue。 如果在迭代期间引发了异常,则等同于 in 引发了该异常。

最后将会尝试旧式的迭代协议:如果一个类定义了 __getitem__(),则当且仅当存在非负整数索引号 i 使得 x is y[i] or x == y[i] 并且没有更小的索引号引发 IndexError 异常时 x in yTrue。 (如果引发了任何其他异常,则等同于 in 引发了该异常)。

运算符 not in 被定义为具有与 in 相反的逻辑值。

6.10.3. 标识号比较

运算符 isis not 用于检测对象的标识号:当且仅当 xy 是同一对象时 x is y 为真。 一个对象的标识号可使用 id() 函数来确定。 x is not y 会产生相反的逻辑值。

6.11. 布尔运算

or_test  ::=  and_test | or_test "or" and_test
and_test ::=  not_test | and_test "and" not_test
not_test ::=  comparison | "not" not_test

在执行布尔运算的情况下,或是当表达式被用于流程控制语句时,以下值会被解析为假值: False, None, 所有类型的数字零,以及空字符串和空容器(包括字符串、元组、列表、字典、集合与冻结集合)。 所有其他值都会被解析为真值。 用户自定义对象可通过提供 __bool__() 方法来定制其逻辑值。

运算符 not 将在其参数为假值时产生 True,否则产生 False

表达式 x and y 首先对 x 求值;如果 x 为假则返回该值;否则对 y 求值并返回其结果值。

表达式 x or y 首先对 x 求值;如果 x 为真则返回该值;否则对 y 求值并返回其结果值。

请注意 andor 都不限制其返回的值和类型必须为 FalseTrue,而是返回最终求值的参数。 此行为是有必要的,例如假设 s 为一个当其为空时应被替换为某个默认值的字符串,表达式 s or 'foo' 将产生希望的值。 由于 not 必须创建一个新值,不论其参数为何种类型它都会返回一个布尔值(例如,not 'foo' 结果为 False 而非 ''。)

6.12. 赋值表达式

assignment_expression ::=  [identifier ":="] expression

赋值表达式(有时又被叫做“命名表达式”或“海象表达式”)将一个 expression 赋值给一个 identifier,同时还返回 expression 的值。

一个常见用例是在处理匹配的正则表达式的时候:

if matching := pattern.search(data):
    do_something(matching)

或者是在处理分块的文件流的时候:

while chunk := file.read(9000):
    process(chunk)

3.8 新版功能: 请参阅 PEP 572 了解有关赋值表达式的详情。

6.13. 条件表达式

conditional_expression ::=  or_test ["if" or_test "else" expression]
expression             ::=  conditional_expression | lambda_expr

条件表达式(有时称为“三元运算符”)在所有 Python 运算中具有最低的优先级。

表达式 x if C else y 首先是对条件 C 而非 x 求值。 如果 C 为真,x 将被求值并返回其值;否则将对 y 求值并返回其值。

请参阅 PEP 308 了解有关条件表达式的详情。

6.14. lambda 表达式

lambda_expr ::=  "lambda" [parameter_list] ":" expression

lambda 表达式(有时称为 lambda 构型)被用于创建匿名函数。 表达式 lambda parameters: expression 会产生一个函数对象 。 该未命名对象的行为类似于用以下方式定义的函数:

def <lambda>(parameters):
    return expression

请注意通过 lambda 表达式创建的函数不能包含语句或标注。

6.15. 表达式列表

expression_list    ::=  expression ("," expression)* [","]
starred_list       ::=  starred_item ("," starred_item)* [","]
starred_expression ::=  expression | (starred_item ",")* [starred_item]
starred_item       ::=  assignment_expression | "*" or_expr

除了作为列表或集合显示的一部分,包含至少一个逗号的表达式列表将生成一个元组。 元组的长度就是列表中表达式的数量。 表达式将从左至右被求值。

一个星号 * 表示 可迭代拆包。 其操作数必须为一个 iterable。 该可迭代对象将被拆解为迭代项的序列,并被包含于在拆包位置上新建的元组、列表或集合之中。

3.5 新版功能: 表达式列表中的可迭代对象拆包,最初由 PEP 448 提出。

末尾的逗号仅在创建单独元组 (或称 单例) 时需要;在所有其他情况下都是可选项。 没有末尾逗号的单独表达式不会创建一个元组,而是产生该表达式的值。 (要创建一个空元组,应使用一对内容为空的圆括号: ()。)

6.16. 求值顺序

Python 按从左至右的顺序对表达式求值。 但注意在对赋值操作求值时,右侧会先于左侧被求值。

在以下几行中,表达式将按其后缀的算术优先顺序被求值。:

expr1, expr2, expr3, expr4
(expr1, expr2, expr3, expr4)
{expr1: expr2, expr3: expr4}
expr1 + expr2 * (expr3 - expr4)
expr1(expr2, expr3, *expr4, **expr5)
expr3, expr4 = expr1, expr2

6.17. 运算符优先级

下表对The following table summarizes the operator precedence in Python 中运算符的优先顺序进行了总结,从最高优先级(最先绑定)到最低优先级(最后绑定)。 相同单元格内的运算符具有相同优先级。 除非句法显式地给出,否则运算符均指二元运算。 相同单元格内的运算符从左至右分组(除了幂运算是从右至左分组)。

请注意比较、成员检测和标识号检测均为相同优先级。

运算符 描述
(expressions…),[expressions…], {key: value…}, {expressions…} 绑定或加圆括号的表达式,列表显示,字典显示,集合显示
x[index], x[index:index], x(arguments…), x.attribute 抽取,切片,调用,属性引用
await x await 表达式
* 乘方
+x, -x, ~x 正,负,按位非 NOT
``, @, /, //, % 乘,矩阵乘,除,整除,取余
+, - 加和减
<<, >> 移位
& 按位与 AND
^ 按位异或 XOR
` `
in, not in, is, is not, <, <=, >, >=, !=, == 比较运算,包括成员检测和标识号检测
not x 布尔逻辑非 NOT
and 布尔逻辑与 AND
or 布尔逻辑或 OR
ifelse 条件表达式
lambda lambda 表达式
:= 赋值表达式

注:

  • 虽然 abs(x%y) < abs(y) 在数学中必为真,但对于浮点数而言,由于舍入的存在,其在数值上未必为真。 例如,假设在某个平台上的 Python 浮点数为一个 IEEE 754 双精度数值,为了使 -1e-100 % 1e100 具有与 1e100 相同的正负性,计算结果将是 -1e-100 + 1e100,这在数值上正好等于 1e100。 函数 math.fmod() 返回的结果则会具有与第一个参数相同的正负性,因此在这种情况下将返回 -1e-100。 何种方式更适宜取决于具体的应用。

  • 如果 x 恰好非常接近于 y 的整数倍,则由于舍入的存在 x//y 可能会比 (x-x%y)//y 大。 在这种情况下,Python 会返回后一个结果,以便保持令 divmod(x,y)[0] * y + x % y 尽量接近 x.

  • Unicode 标准明确区分 码位 (例如 U+0041) 和 抽象字符 (例如 “大写拉丁字母 A”)。 虽然 Unicode 中的大多数抽象字符都只用一个码位来代表,但也存在一些抽象字符可使用由多个码位组成的序列来表示。 例如,抽象字符 “带有下加符的大写拉丁字母 C” 可以用 U+00C7 码位上的单个 预设字符 来表示,也可以用一个 U+0043 码位上的 基础字符 (大写拉丁字母 C) 加上一个 U+0327 码位上的 组合字符 (组合下加符) 组成的序列来表示。

    对于字符串,比较运算符会按 Unicode 码位级别进行比较。 这可能会违反人类的直觉。 例如,"\u00C7" == "\u0043\u0327"False,虽然两个字符串都代表同一个抽象字符 “带有下加符的大写拉丁字母 C”。

    要按抽象字符级别(即对人类来说更直观的方式)对字符串进行比较,应使用 unicodedata.normalize()

  • 由于存在自动垃圾收集、空闲列表以及描述器的动态特性,你可能会注意到在特定情况下使用 is 运算符会出现看似不正常的行为,例如涉及到实例方法或常量之间的比较时就是如此。 更多信息请查看有关它们的文档。

  • 幂运算符 ** 绑定的紧密程度低于在其右侧的算术或按位一元运算符,也就是说 2**-10.5

  • % 运算符也被用于字符串格式化;在此场合下会使用同样的优先级。

7. 简单语句

简单语句由一个单独的逻辑行构成。 多条简单语句可以存在于同一行内并以分号分隔。 简单语句的句法为:

simple_stmt ::=  expression_stmt
                 | assert_stmt
                 | assignment_stmt
                 | augmented_assignment_stmt
                 | annotated_assignment_stmt
                 | pass_stmt
                 | del_stmt
                 | return_stmt
                 | yield_stmt
                 | raise_stmt
                 | break_stmt
                 | continue_stmt
                 | import_stmt
                 | future_stmt
                 | global_stmt
                 | nonlocal_stmt

7.1. 表达式语句

表达式语句用于计算和写入值(大多是在交互模式下),或者(通常情况)调用一个过程 (过程就是不返回有意义结果的函数;在 Python 中,过程的返回值为 None)。 表达式语句的其他使用方式也是允许且有特定用处的。 表达式语句的句法为:

expression_stmt ::=  starred_expression

表达式语句会对指定的表达式列表(也可能为单一表达式)进行求值。

在交互模式下,如果结果值不为 None,它会通过内置的 repr() 函数转换为一个字符串,该结果字符串将以单独一行的形式写入标准输出(例外情况是如果结果为 None,则该过程调用不产生任何输出。)

7.2. 赋值语句

赋值语句用于将名称(重)绑定到特定值,以及修改属性或可变对象的成员项:

assignment_stmt ::=  (target_list "=")+ (starred_expression | yield_expression)
target_list     ::=  target ("," target)* [","]
target          ::=  identifier
                     | "(" [target_list] ")"
                     | "[" [target_list] "]"
                     | attributeref
                     | subscription
                     | slicing
                     | "*" target

赋值语句会对指定的表达式列表进行求值(注意这可能为单一表达式或是由逗号分隔的列表,后者将产生一个元组)并将单一结果对象从左至右逐个赋值给目标列表。

赋值是根据目标(列表)的格式递归地定义的。 当目标为一个可变对象(属性引用、抽取或切片)的组成部分时,该可变对象必须最终执行赋值并决定其有效性,如果赋值操作不可接受也可能引发异常。 各种类型可用的规则和引发的异常通过对象类型的定义给出.

对象赋值的目标对象可以包含于圆括号或方括号内,具体操作按以下方式递归地定义。

  • 如果目标列表为后面不带逗号、可以包含于圆括号内的单一目标,则将对象赋值给该目标。
  • 否则:该对象必须为具有与目标列表相同项数的可迭代对象,这些项将按从左至右的顺序被赋值给对应的目标。
    • 如果目标列表包含一个带有星号前缀的目标,这称为“加星”目标:则该对象至少必须为与目标列表项数减一相同项数的可迭代对象。 该可迭代对象前面的项将按从左至右的顺序被赋值给加星目标之前的目标。 该可迭代对象末尾的项将被赋值给加星目标之后的目标。 然后该可迭代对象中剩余项的列表将被赋值给加星目标(该列表可以为空)。
    • 否则:该对象必须为具有与目标列表相同项数的可迭代对象,这些项将按从左至右的顺序被赋值给对应的目标。

对象赋值给单个目标的操作按以下方式递归地定义。

  • 如果目标为标识符(名称):

    • 如果该名称未出现于当前代码块的 globalnonlocal 语句中:该名称将被绑定到当前局部命名空间的对象。
    • 否则:该名称将被分别绑定到全局命名空间或由 nonlocal 所确定的外层命名空间的对象。

    如果该名称已经被绑定则将被重新绑定。 这可能导致之前被绑定到该名称的对象的引用计数变为零,造成该对象进入释放过程并调用其析构器(如果存在)。

  • 如果该对象为属性引用:引用中的原型表达式会被求值。 它应该产生一个具有可赋值属性的对象;否则将引发 TypeError。 该对象会被要求将可赋值对象赋值给指定的属性;如果它无法执行赋值,则会引发异常 (通常应为 AttributeError 但并不强制要求)。

    注意:如果该对象为类实例并且属性引用在赋值运算符的两侧都出现,则右侧表达式 a.x 可以访问实例属性或(如果实例属性不存在)类属性。 左侧目标 a.x 将总是设定为实例属性,并在必要时创建该实例属性。 因此 a.x 的两次出现不一定指向相同的属性:如果右侧表达式指向一个类属性,则左侧会创建一个新的实例属性作为赋值的目标:

    class Cls:
        x = 3             # class variable
    inst = Cls()
    inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3

    此描述不一定作用于描述器属性,例如通过 property() 创建的特征属性。

  • 如果目标为一个抽取项:引用中的原型表达式会被求值。 它应当产生一个可变序列对象(例如列表)或一个映射对象(例如字典)。 接下来,该抽取表达式会被求值。

    如果原型为一个可变序列对象(例如列表),抽取应产生一个整数。 如其为负值,则再加上序列长度。 结果值必须为一个小于序列长度的非负整数,序列将把被赋值对象赋值给该整数指定索引号的项。 如果索引超出范围,将会引发 IndexError (给被抽取序列赋值不能向列表添加新项)。

    如果原型为一个映射对象(例如字典),抽取必须具有与该映射的键类型相兼容的类型,然后映射中会创建一个将抽取映射到被赋值对象的键/值对。 这可以是替换一个现有键/值对并保持相同键值,也可以是插入一个新键/值对(如果具有相同值的键不存在)。

    对于用户定义对象,会调用 __setitem__() 方法并附带适当的参数。

  • 如果目标为一个切片:引用中的原型表达式会被求值。 它应当产生一个可变序列对象(例如列表)。 被赋值对象应当是一个相同类型的序列对象。 接下来,下界与上界表达式如果存在的话将被求值;默认值分别为零和序列长度。 上下边界值应当为整数。 如果某一边界为负值,则会加上序列长度。 求出的边界会被裁剪至介于零和序列长度的开区间中。 最后,将要求序列对象以被赋值序列的项替换该切片。 切片的长度可能与被赋值序列的长度不同,这会在目标序列允许的情况下改变目标序列的长度。

CPython implementation detail: 在当前实现中,目标的句法被当作与表达式的句法相同,无效的句法会在代码生成阶段被拒绝,导致不太详细的错误信息。

虽然赋值的定义意味着左手边与右手边的重叠是“同时”进行的(例如 a, b = b, a 会交换两个变量的值),但在赋值给变量的多项集 之内 的重叠是从左至右进行的,这有时会令人混淆。 例如,以下程序将会打印出 [0, 2]:

x = [0, 1]
i = 0
i, x[i] = 1, 2         # i is updated, then x[i] is updated
print(x)

参见

PEP 3132 - 扩展的可迭代对象拆包

*target 特性的规范说明。

7.2.1. 增强赋值语句

增强赋值语句就是在单个语句中将二元运算和赋值语句合为一体:

augmented_assignment_stmt ::=  augtarget augop (expression_list | yield_expression)
augtarget                 ::=  identifier | attributeref | subscription | slicing
augop                     ::=  "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
                               | ">>=" | "<<=" | "&=" | "^=" | "|="

增强赋值语句将对目标和表达式列表求值(与普通赋值语句不同的是,前者不能为可迭代对象拆包),对两个操作数相应类型的赋值执行指定的二元运算,并将结果赋值给原始目标。 目标仅会被求值一次。

增强赋值语句例如 x += 1 可以改写为 x = x + 1 获得类似但并非完全等价的效果。 在增强赋值的版本中,x 仅会被求值一次。 而且,在可能的情况下,实际的运算是 原地 执行的,也就是说并不是创建一个新对象并将其赋值给目标,而是直接修改原对象。

不同于普通赋值,增强赋值会在对右手边求值 之前 对左手边求值。 例如,a[i] += f(x) 首先查找 a[i],然后对 f(x) 求值并执行加法操作,最后将结果写回到 a[i]

除了在单个语句中赋值给元组和多个目标的例外情况,增强赋值语句的赋值操作处理方式与普通赋值相同。 类似地,除了可能存在 原地 操作行为的例外情况,增强赋值语句执行的二元运算也与普通二元运算相同。

对于属性引用类目标,针对常规赋值的 关于类和实例属性的警告 也同样适用。

7.2.2. 带标注的赋值语句

标注 赋值就是在单个语句中将变量或属性标注和可选的赋值语句合为一体:

annotated_assignment_stmt ::=  augtarget ":" expression
                               ["=" (starred_expression | yield_expression)]

与普通 赋值语句 的差别在于仅允许单个目标。

对于将简单名称作为赋值目标的情况,如果是在类或模块作用域中,标注会被求值并存入一个特殊的类或模块属性 __annotations__ 中,这是一个将变量名称(如为私有会被移除)映射到被求值标注的字典。 此属性为可写并且在类或模块体开始执行时如果静态地发现标注就会自动创建。

对于将表达式作为赋值目标的情况,如果是在类或模块作用域中,标注会被求值,但不会保存。

如果一个名称在函数作用域内被标注,则该名称为该作用域的局部变量。 标注绝不会在函数作用域内被求值和保存。

如果存在右手边,带标注的赋值会在对标注求值之前(如果适用)执行实际的赋值。 如果用作表达式目标的右手边不存在,则解释器会对目标求值,但最后的 __setitem__()__setattr__() 调用除外。

参见

PEP 526 - 变量标注的语法

该提议增加了标注变量(也包括类变量和实例变量)类型的语法,而不再是通过注释来进行表达。

PEP 484 - 类型提示

该提议增加了 typing 模块以便为类型标注提供标准句法,可被静态分析工具和 IDE 所使用。

在 3.8 版更改: 现在带有标注的赋值允许在右边以同样的表达式作为常规赋值。 之前,某些表达式(例如未加圆括号的元组表达式)会导致语法错误。

7.3. assert 语句

assert 语句是在程序中插入调试性断言的简便方式:

assert_stmt ::=  "assert" expression ["," expression]

简单形式 assert expression 等价于

if __debug__:    if not expression: raise AssertionError

扩展形式 assert expression1, expression2 等价于

if __debug__:    if not expression1: raise AssertionError(expression2)

以上等价形式假定 __debug__AssertionError 指向具有指定名称的内置变量。 在当前实现中,内置变量 __debug__ 在正常情况下为 True,在请求优化时为 False (对应命令行选项为 -O)。 如果在编译时请求优化,当前代码生成器不会为 assert 语句发出任何代码。 请注意不必在错误信息中包含失败表达式的源代码;它会被作为栈追踪的一部分被显示。

赋值给 __debug__ 是非法的。 该内置变量的值会在解释器启动时确定。

7.4. pass 语句

pass_stmt ::=  "pass"

pass 是一个空操作 —- 当它被执行时,什么都不发生。 它适合当语法上需要一条语句但并不需要执行任何代码时用来临时占位,例如:

def f(arg): pass    # a function that does nothing (yet)
class C: pass       # a class with no methods (yet)

7.5. del 语句

del_stmt ::=  "del" target_list

删除是递归定义的,与赋值的定义方式非常类似。 此处不再详细说明,只给出一些提示。

目标列表的删除将从左至右递归地删除每一个目标。

名称的删除将从局部或全局命名空间中移除该名称的绑定,具体作用域的确定是看该名称是否有在同一代码块的 global 语句中出现。 如果该名称未被绑定,将会引发 NameError

属性引用、抽取和切片的删除会被传递给相应的原型对象;删除一个切片基本等价于赋值为一个右侧类型的空切片(但即便这一点也是由切片对象决定的)。

在 3.2 版更改: 在之前版本中,如果一个名称作为被嵌套代码块中的自由变量出现,则将其从局部命名空间中删除是非法的。

7.6. return 语句

return_stmt ::=  "return" [expression_list]

return 在语法上只会出现于函数定义所嵌套的代码,不会出现于类定义所嵌套的代码。

如果提供了表达式列表,它将被求值,否则以 None 替代。

return 会离开当前函数调用,并以表达式列表 (或 None) 作为返回值。

return 将控制流传出一个带有 finally 子句的 try 语句时,该 finally 子句会先被执行然后再真正离开该函数。

在一个生成器函数中,return 语句表示生成器已完成并将导致 StopIteration 被引发。 返回值(如果有的话)会被当作一个参数用来构建 StopIteration 并成为 StopIteration.value 属性。

在一个异步生成器函数中,一个空的 return 语句表示异步生成器已完成并将导致 StopAsyncIteration 被引发。 一个非空的 return 语句在异步生成器函数中会导致语法错误。

7.7. yield 语句

yield_stmt ::=  yield_expression

yield 语句在语义上等同于 yield 表达式。 yield 语句可用来省略在使用等效的 yield 表达式语句时所必须的圆括号。 例如,以下 yield 语句

yield <expr>
yield from <expr>

等同于以下 yield 表达式语句

(yield <expr>)
(yield from <expr>)

yield 表达式和语句仅在定义 generator 函数时使用,并且仅被用于生成器函数的函数体内部。 在函数定义中使用 yield 就足以使得该定义创建的是生成器函数而非普通函数。

7.8. raise 语句

raise_stmt ::=  "raise" [expression ["from" expression]]

如果不带表达式,raise 会重新引发当前作用域内最后一个激活的异常。 如果当前作用域内没有激活的异常,将会引发 RuntimeError 来提示错误。

否则的话,raise 会将第一个表达式求值为异常对象。 它必须为 BaseException 的子类或实例。 如果它是一个类,当需要时会通过不带参数地实例化该类来获得异常的实例。

异常的 类型 为异常实例的类, 为实例本身。

当异常被引发时通常会自动创建一个回溯对象并将其关联到可写的 __traceback__ 属性。 你可以创建一个异常并同时使用 with_traceback() 异常方法(该方法将返回同一异常实例,并将回溯对象设为其参数)设置自己的回溯,就像这样:

raise Exception("foo occurred").with_traceback(tracebackobj)

from 子句用于异常串连:如果有该子句,则第二个 表达式 必须为另一个异常类或实例。 如果第二个表达式是一个异常实例,它将作为可写的 __cause__ 属性被关联到所引发的异常。 如果该表达式是一个异常类,这个类将被实例化且所生成的异常实例将作为 __cause__ 属性被关联到所引发的异常。 如果所引发的异常未被处理,则两个异常都将被打印出来:

>>> try:
...     print(1 / 0)
... except Exception as exc:
...     raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened

如果一个异常在异常处理器或 finally clause: 中被引发,类似的机制会隐式地发挥作用,之前的异常将被关联到新异常的 __context__ 属性:

>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2,