Posted 2019-06-09Updated 2019-06-09Python / Py3Ref36 minutes read (About 5403 words)

Python包、模块

综述

导入方式

importing操作可以使得模块能够访问其他模块中代码

import：结合了以下两个操作，发起导入调机制最常用方式
- 搜索指定名称模块：对__import__()带有适当参数调用
- 将搜索结果绑定到当前作用域中名称：__import__返回值被用于执行名称绑定操作
__import__()：只执行模块搜索、找到模块后创建module
- 可能产生某些副作用
  - 导入父包
  - 更新各种缓存：sys.modules
importlib.import_module()
- 可能会选择绕过__import__，使用其自己的解决方案实现导入机制
- 用于为动态模块导入提供支持
- importlib模块参见标准库

子模块

任意机制加载子模块时，父模块命名空间中会添加对子模块对象的绑定

Packages

python只有一种模块对象类型：所有模块都属于该类型，C、 Python语言实现均是
包：为帮助组织模块、并提供名称层次结构引入
- 可将包视为文件系统中目录、模块视为目录中文件，但包、模块不是必须来自文件系统
- 类似文件系统，包通过层次结构进行组织：包内包括模块、子包
所有包都是模块，但并非所有模块都是包
- 包是一种特殊的模块
- 特别的，任何具有__path__属性的模块都被当作包
所有模块都有自己的名字
- 子包名与其父包名以.分隔，同python标准属性访问语法

Regular Packages

正规包：通常以包含__init__.py文件的目录形式出现

__init__.py文件可以包含和其他模块中包含python模块相似的代码
正规包被导入时
- __init__.py文件会隐式被执行，其中定义对象被绑定到该包命名空间中名称
- python会为模块添加额外属性

Namespace Packages

命名空间包：由多个部分构成，每个部分为父包增加一个子包

包各部分可以物理不相邻，不一定直接对应到文件系统对象，可能是无实体表示的虚拟模块
- 可能处于文件系统不同位置
- 可能处于zip文件、网络上，或在导入期间其他可搜索位置
__path__属性不是普通列表，而是定制的可迭代类型
- 若父包、或最高层级包sys.path路径发生改变，对象会在包内的下次导入尝试时，自动执行新的对包部分的搜索
命名空间包中没有__init__.py文件
- 毕竟可能有多个父目录提供包不同部分，彼此物理不相邻
- python会在包、子包导入时为其创建命名空间包

导入相关模块属性

以下属性在加载时被设置，参见 cs_python/py3ref/import_system

__name__：模块完整限定名称，唯一标识模块
__loader__：导入系统加载模块时使用的加载器对象
- 主要用于内省
- 也可用于额外加载器专用功能
__package__：取代__name__用于主模块计算显式相对导入
- 模块为包：应设置为__name__
- 模块非包：最高层级模块应设为空字符串，否则为父包名
- 预期同__spec__.parent值相同，未定义时，以 __spec__.parent作为回退项

python <PYSCIRPT>直接执行脚本时__name__被设置为 __main__、__package__设置为None，此时导入器无法解释相对导入中.，相对导入报错

python -m <PYSCIRPT>则会按模块逻辑设置__name__、 __package__，相对导入可以正常执行

`spec`

__spec__：导入模块时要使用的模块规格说明

对__spec__正确设置将同时作用于解释器启动期间初始化的模块
仅__main__某些情况下被设置为None

`path`

具有该属性模块即为包：包模块必须设置__path__属性，非包模块不应设置
在导入子包期间被使用，在导入机制内部功能同sys.path，即用于提供模块搜索位置列表
- 但受到更多限制，其必须为字符串组成可迭代对象，但若其没有进一步用处可以设置为空
- 适用作用于sys.path的规则
- sys.path_hooks会在遍历包的__path__时被查询
可在包的__init__.py中设置、更改
- 在PEP420引入之后，命名空间包不再需要提供仅包含操作 __path__代码的__init__.py文件，导入机制会自动为命名空间包正确设置__path__
- 在之前其为实现命名空间包的典型方式

`repr`

若模块具有__spec__，导入机制将尝试使用其中规格信息生成 repr
- name
- loader
- origin
- has_location
若模块具有__file__属性，将被用作repr的一部分
否则若模块具有__loader__属性且非None，则加载器repr 将被用作模块repr的一部分
其他情况下，仅在repr中适用模块的__name__

可以在模块规则说明中显式控制模块对象repr

`file`/`cached`

__file__：模块对应的被加载文件的路径名

__cached__：编译版本代码（字节码文件）路径

__file__为可选项，须为字符串
- 可以在其无语法意义时不设置
- 对从共享库动态加载的扩展模块，应为共享库文件路径名
__cached__
- 不要求编译文件已经存在，可以表示应该存放编译文件的位置
- 不要求__file__已经设置
  - 有时加载器可以从缓存加载模块但是无法从文件加载
  - 加载静态链接至解释器内部的C模块
从.pyc文件加载缓存字节码前会检查其是否最新
- 默认通过比较缓存文件中保存的源文件修改时间戳实现
- 也支持基于哈希的缓冲文件，此时.pyc文件中保存源文件哈希值
  - 检查型：求源文件哈希值再和缓存文件中哈希值比较
  - 非检查型：只要缓存文件存在就直接认为缓存文件有效
- --check-hash-based-pycs命名行选项设置基于哈希的 .pyc文件有效性

执行相关模块属性

__doc__：模块文档字符串
__annotaion__：包含变量标注的字典
- 在模块体执行时获取
__dict__：以字典对象表示的模块命名空间

CPython：由于CPython清理模块字典的设定，模块离开作用域时模块字典将被清理，即使字典还有活动引用，可以复制该字典、保持模块状态以直接使用其字典

`sys.modules`模块缓存

sys.modules映射：缓存之前导入的所有模块（包括中间路径）（即导入子模块会注册父模块条目）

其中每个键值对就是限定名称、模块对象
在其中查找模块名称
- 若存在需要导入模块，则导入完成
- 若名称对应值为None则raise ModuleNotFoundError
- 若找不到指定模块名称，python将继续搜索
映射可写，可删除其中键值对
- 不一定破坏关联模块，因为其他模块可能保留对其引用
- 但是会使命名模块缓存条目无效，导致下次导入时重新搜索命名模块，得到两个不同的两个模块对象
- importlib.reload将重用相同模块对象，通过重新运行模块代码重新初始化模块内容

Finders And Loaders

Finders：查找器，确定能否使用所知策略找到指定名称模块

Loaders：加载器，加载找到的指定模块

Importer：导入器，同时实现两种接口的对象，在确定能加载所需模块时会返回自身

导入机制通过import hooks实现扩展
- 可以加入新的查找器以扩展模块搜索范围、作用域
工作流程：在sys.modules缓存中无法找到指定名称模块时
- 查找器若能找到指定名称模块，返回模块规格说明spec
- 加载器将利用查找器返回的模块规格说明加载模块

Import Path

导入路径：文件系统路径、zip文件等path term组成的位置列表

其中元素不局限于文件系统位置，可扩展为字符串指定的任意可定位资源
- URL指定资源
- 数据库查询
位置条目来源
- 通常为sys.path
- 对次级包可能来自上级包的__path__属性
其中每个路径条目指定一个用于搜索模块的位置
- path based finder将在其中查找导入目标

`sys.path`

sys.path：模块、包搜索位置的字符串列表

初始化自PYTHONPATH环境变量、特定安装和实现的默认设置、执行脚本目录（或当前目录）
其中条目可以指定文件系统中目录、zip文件、可用于搜索模块的潜在位置
只能出现字符串、字节串，其他数据类型被忽略
- 字节串条目使用的编码由导入路径钩子、 path entry finder确定

所以可以修改sys.path值定制导入路径，CPython实现参见 cs_python/py3ref/import_system

`sys.path_import_cache`

sys.path_importer_cache：存放路径条目到路径条目查找器映射的缓存

减少查找路径条目对应路径条目查找器的消耗，对特定路径条目查找对应路径条目查找只需进行一次
可从中移除缓存条目，以强制基于路径查找器执行路径条目搜索

Import Hooks

meta hooks：元[路径]钩子
- 导入过程开始时被调用，此时仅sys.modules缓存查找发生，其他导入过程未发生
- 所以允许元钩子重载sys.path过程、冻结模块甚至内置模块
- 元钩子即导入器/元路径查找器
- sys.meta_path为元路径查找器列表，可在其中注册定制元钩子
path[ entry] hooks：导入路径钩子
- 是sys.path、package.__path__处理的一部分
- 基于路径的查找器调用其处理路径条目，以获取路径条目查找器
- 导入路径钩子返回路径条目查找器
- sys.path_hooks为导入路径钩子列表，可在其中注册定制导入路径钩子

默认元路径查找器/导入器

python默认实现sys.meta_path有以下导入器（元路径查找器）

BuiltinImporter：定位、导入内置模块
FrozenImporter：定位、导入冻结模块
PathFinder：定位、导入来自import path中模块

尝试导入模块时，内置模块、冻结模块导入器优先级较高，所以解释器首先搜索内置模块

Finder

指定名称模块在sys.modules找不到时，python继续搜索 sys.meta_path，按顺序调用其中元路径查找器
若sys.meta_path处理到列表末尾仍未返回说明对象，则 raise ModuleNotFoundError

导入过程中引发的任何异常直接向上传播，并放弃导入过程

对非最高层级模块的导入请求可能会多次遍历元路径

Meta Path Finders

元路径查找器：

元路径查找器可使用任何策略确定其是否能处理给定名称模块
- 若知道如何处理指定名称的模块，将返回模块规格说明
- 否则返回None
模块规格协议：元路径查找器应实现find_spec()方法
- 接受名称、导入路径、目标模块作为参数
- 返回模块规格说明

Spec

模块规格[说明]：基于每个模块封装的模块导入相关信息
- 模块规格中大部分信息对所有模块是公用的
- 模块规格说明作为模块对象的__spec__属性对外公开
用途
- 允许状态在导入系统各组件间传递，如：查询器和加载器
- 允许导入机制执行加载的样板操作，否则该由加载器负责

`find_spec`

1 2	def finder.find_spec(fullname, path=None, target=None): pass

fullname：被导入模块的完整限定名称
path：供模块搜索使用的路径条目
- 对最高层级模块应为None
- 对子模块、子包应为父包__path__属性值，若相应__path__属性无法访问将 raise ModuleNotFoundError
target：将被作为稍后加载目标的现有模块对象
- 导入系统仅在重加载期间传入目标模块

导入器的find_spec()返回模块规格说明中加载器为self

有些元路径查找器仅支持顶级导入，path参数不为None时总返回None

Loaders

模块规格说明被找到时，导入机制将在加载该模块时使用
- 其中包含的加载器将被使用，若存在

加载流程

module = None

if spec.loader is not None and hasattr(spec.loader, 'create_module'):
	# 模块说明中包含加载器，使用加载器创建模块
	module = spec.loader.create_module(spec)

if module is None:
	# 否则创建空模块
	module = types.ModuleType(spec.name)

 # 设置模块导入相关属性
_init_module_attrs(spec, module)

if spec.loader is None:
	# 模块说明中不包含加载器
	# 检查模块是否为为命名空间包
	if spec.submodule_search_locations is not None:
		# 设置`sys.modules`
		sys.modules[spec.name] = module
	else:
		raise ImportError
elif not hasattr(spec.loader, "exec_module"):
	# 向下兼容现有`load_module`
	module = spec.loader.load_module(spec.name)
else:
	sys.modules[spec.name] = module
	try:
		# 模块执行
		spec.loader.exec_module(module)
	except BaseException:
		try:
			# 加载模块失败则从`sys.modules`中移除
			del sys.modules[spec.name]
		except KeyError:
			pass
		raise
return sys.modules[spec.name]

创建模块对象
设置模块导入相关属性：在执行模块代码前设置
sys.modules注册模块
模块执行：模块导入关键，填充模块命名空间

`create_module`创建模块对象

模块加载器可以选择通过实现create_module方法在加载期间创建模块对象
- 其应接受模块规格说明作为参数
否则导入机制使用types.ModuleType自行创建模块对象

`sys.modules`注册模块

在加载器执行代码前注册，避免模块代码导入自身导致无限递归、多次加载
若模块为命名空间包，直接注册空模块对象

`exec_module`模块执行

导入机制调用importlib.abc.Loader.exec_module()方法执行模块对象
- CPython：exec_module不定返回传入模块，其返回值将被忽略
  - importlib避免直接使用返回值，而是通过在 sys.modules中查找模块名称获取模块对象
  - 可能会间接导致被导入模块可能在sys.modules中替换其自身
加载器应该该满足
- 若模块是python模块（非内置、非动态加载），加载器应该在模块全局命名空间module.__dict__中执行模块代码
- 若加载器无法执行指定模块，则应raise ImportError，在exec_module期间引发的任何其他异常同样被传播
加载失败时作为附带影响被成功加载的模块仍然保留
- 重新加载模块会保留加载失败模块（最近成功版本）

Path Based Finder—`PathFinder`

基于路径的查找器：在特定path entry中查找、加载指定的python 模块、包

基于路径查找器只是遍历import path中的路径条目，将其关联至处理特定类型路径的path entry finder
默认路径条目查找器集合实现了在文件系统中查找模块的所有语义，可以处理多种文件类型
- python源码.py
- python字节码.pyc
- 共享库.so
- zip包装的上述文件类型（需要zipimport模块支持）
作为元路径查找器
- 实现有find_spec协议
- 并提供额外的钩子、协议以便能扩展、定制可搜索路径条目的类型，定制模块从import path的查找、加载

流程

导入机制调用基于路径的查找器的find_spec()迭代搜索 import path的路径条目，查找对应路径条目查找器

先在sys.path_impporter_cache缓存中查找对应路径条目查找器
若没有在缓存中找到，则迭代调用sys.path_hooks中 Path Entry Hook
迭代结束后若没有返回路径条目查找器，则
- 置sys.path_importer_cache对应值为None
- 返回None，表示此元路径查找器无法找到该模块

当前目录

对空字符串表示的当前工作目录同sys.path中其他条目处理方式有所不同

若当前工作目录不存在，则sys.path_importer_cache 中不存放任何值
模块查找回对当前工作目录进行全新查找
sys.path_importer_cache使用、 importlib.machinery.PathFinder.find_spec()返回路径将是实际当前工作目录而非空字符串

Path Entry Hook

路径条目钩子：根据路径条目查找对应路径条目查找器的可调用对象

参数：字符串、字节串，表示要搜索的目录条目
- 字节串的编码由钩子自行决定
- 若钩子无法解码参数，应raise ImportError
路径条目钩子返回值
- 可处理路径条目的路径条目查找器
- raise ImportError：表示钩子无法找到与路径条目对应路径条目查找器
  - 该异常会被忽略，并继续对import path迭代

Path Entry Finder—`PathEntryFinder`

路径条目查找器：

元路径查找器作用于导入过程的开始，遍历sys.meta_path时

路径条目查找器某种意义上是基于路径查找器的实现细节

`find_spec`

1 2	def PathEntryFinder.find_spec(fullname, target=None): pass

路径条目查找器协议：目录条目查找器需实现find_spec方法
- 以支持模块、已初始化包的导入
- 给命名空间包提供组成部分
参数
- fullname：要导入模块的完整限定名称
- target：目标模块
返回值：完全填充好的模块规格说明
- 模块规格说明总是包含加载器集合
- 但命名空间包的规格说明中loader会被设置为None，并将submodule_search_locations设置为包含该部分的列表，以告诉导入机制该规格说明为命名空间包的portion

Portion：构成命名空间包的单个目录内文件集合

替代旧式find_loader()、find_module()方法

替换标准导入系统

替换sys.meta_path为自定义元路径钩子
- 替换整个导入系统最可靠机制
替换内置__import__()函数
- 仅改变导入语句行为而不影响访问导入系统其他接口
- 可以在某个模块层级替换，只改变某块内部导入语句行为
替换find_spec()，引发ModuleNotFoundError
- 选择性的防止在元路径钩子导入某些模块

`main`

__main__模块是在解释器启动时直接初始化，类似sys、 builtins，但是不被归类为内置模块，因为其初始化的方式取决于启动解释器的旗标（命令行参数）

`spec`

根据__main__被初始化的方式，__main__.__spec__被设置为 None或相应值

-m选项启动：以脚本方式执行模块
- 此时__spec__被设置为相应模块、包规格说明
- __spec__会在__main__模块作为执行某个目录、zip 文件、其他sys.path条目的一部分加载时被填充
- 此时__main__对应可导入模块和__main__被视为不同模块
其余情况
- __spec__被设置为None
- 因为用于填充__main__的代码不直接与可导入模块相对应
  - 交互型提示
  - -c选项
  - 从stdin运行
  - 从源码、字节码文件运行

-m执行模块时sys.path首个值为空字符串，而直接执行脚本时首个值为脚本所在目录

Import[ Search] Path定制

动态增加路径

1
2
3

import sys
sys.path.insert(1, /path/to/fold/contains/module)
	# 临时生效，对不经常使用的模块较好

修改`PYTHONPATH`环境变量

1 2	# .bashrc export PYTHONPATH=$PYTHONPATH:/path/to/fold/contains/module

对许多程序都使用的模块可以采取此方式
会改变所有Python应用的搜索路径

增加`.pth`文件

在/path/to/python/site-packages（或其他查找路径目录）下添加.pth配置文件，内容为需要添加的路径

1 2	# extras.pth /path/to/fold/contains/module

简单、推荐
python在遍历已知库文件目录过程中，遇到.pth文件会将其中路径加入sys.path中

Posted 2019-05-20Updated 2019-05-20Python / Py3Ref10 minutes read (About 1546 words)

数据模型--执行相关

以下类型为内部类型，由解释器内部使用、但被暴露给用户，其定义可能随着未来解释器版本更新而变化
- 代码对象
- 帧对象
- 回溯对象
- 切片对象：参见cs_python/py3ref/dm_basics
- 静态方法对象：参见cs_python/py3ref/#todo
- 类方法对象：参见cs_python/py3ref/#todo

Module

模块：python代码的基本组织单元

导入系统创建
- import语句
- importlibd.import_module()、__import__()函数
模块对象具有由字典__dict__实现的命名空间
- 属性引用：被转换为该字典中查找m.__dict__['x']
- 属性赋值：更新模块命名字典空间
- 不包含用于初始化模块的代码对象
- 模块中定义函数__globals__属性引用其

元属性

__name__：模块名称
__doc__：模块文档字符串
__annotaion__：包含变量标注的字典
- 在模块体执行时获取
__file__：模块对应的被加载文件的路径名
- 若加载自一个文件，某些类型模块可能没有
  - C模块静态链接至解释器内部
- 从共享库动态加载的扩展模块，该属性为共享库文件路径名
__dict__：以字典对象表示的模块命名空间

CPython：由于CPython清理模块字典的设定，模块离开作用域时模块字典将被清理，即使字典还有活动引用，可以复制该字典、保持模块状态以直接使用其字典

Code Object

代码对象：“伪编译”为字节的可执行python代码，也称bytecode

代码对象和函数对象区别
- 代码对象不包含上下文；函数对象包含对函数全局对象（函数所属模块）的显式引用
- 默认参数值存放于函数对象而不是代码对象
- 代码对象不可变，也不包含对可变对象的应用
代码对象由内置compile()函数返回
- 可以通过函数对象__code__属性从中提取
- 可以作为参数传给exec()、eval()函数执行

特殊属性

co_name：函数名称
co_argcount：位置参数数量
co_nlocals：函数使用的本地变量数量（包括参数）
co_varnames：包含本地变量名称的元组
co_freevars：包含自由变量的元组
co_code：表示字节码指令序列的字符串
co_consts：包含字节码所使用的字面值元组
- 若代码对象表示一个函数，第一项为函数文档字符，没有则为None
co_names：包含字节码所使用的名称的元组
co_filenames：被编译代码所在文件名
co_firstlineno：函数首行行号
co_lnotab：以编码表示的字节码偏移量到行号映射的字符串
co_stacksize：要求栈大小（包括本地变量）
co_flags：以编码表示的多个解释器所用标志的整形数
- 0x04位：函数使用*arguments接受任意数量位置参数
- 0x08位：函数使用**keywords接受任意数量关键字参数
- 0x20位：函数是生成器
- 0x2000位：函数编译时使用启用未来除法特性
- 其他位被保留为内部使用

Frame Objects

栈帧对象：执行帧

可能出现在回溯对象中，还会被传递给注册跟踪函数

特殊只读属性

f_back：前一帧对象，指向主调函数
- 最底层堆栈帧则为None
f_code：此栈帧中所执行的代码对象
f_locals：查找本地变量的字典
f_globals：查找全局变量
f_builtins：查找内置名称
f_lasti：精确指令，代码对象字节码字符串的索引

特殊可写属性

f_trace：None，或代码执行期间调用各类事件的函数
- 通常每行新源码触发一个事件
f_trace_lines：设置是否每行新源码触发一个事件
f_trace_opcodes：设置是否允许按操作码请求事件
f_lineno：帧当前行号
- 可以通过写入f_lineno实现Jump命令

方法

.clear()：清楚该帧持有的全部对本地变量的引用
- 若该栈帧为属于生成器，生成器被完成
- 有助于打破包含帧对象的循环引用
- 若帧当前正在执行则会raise RuntimeError

Traceback Objects

回溯对象：表示异常的栈跟踪记录

异常被印发时会自动创建回溯对象，并将其关联到异常的可写 __traceback__属性
- 查找异常句柄使得执行栈展开时，会在每个展开层级的当前回溯之前插入回溯对象
- 进入异常句柄时，栈跟踪将对程序启用
- 获取：sys.exc_info()返回的元组第三项、异常的 __traceback__属性
- 程序没有合适的处理句柄时，栈跟踪将写入标准错误
可通过types.TracebackType显式创建
- 由回溯对象创建者决定如何链接tb_next属性构成完整栈追踪

特殊只读属性

tb_frame：执行当前层级的执行栈帧
tb_lineno：给出发生异常所在行号
tb_lasti：最后具体指令

若异常出现在没有匹配的except子句、没有finally子句的try中，回溯对象中的行号、最后指令可能于相应帧对象中行号不同

特殊可写属性

tb_next：栈跟踪中下一层级（通往发生异常的帧），没有下一层级则为None

I/O对象/文件对象

文件对象：表示打开的文件

创建文件对象
- open()内置函数
- os.popen()、os.fdopen()
- socket.makefile()
sys.stdin、sys.stdout、sys.stderr会初始化为对应于解释器的标准输入、输出、错误流对象
- 均以文本模式打开
- 遵循io.TextIOBase抽象类所定义接口

Python包、模块

综述

导入方式

子模块

Packages

Regular Packages

Namespace Packages

导入相关模块属性

__spec__

__path__

__repr__

__file__/__cached__

执行相关模块属性

sys.modules模块缓存

Finders And Loaders

Import Path

sys.path

sys.path_import_cache

Import Hooks

默认元路径查找器/导入器

Finder

Meta Path Finders

Spec

find_spec

Loaders

加载流程

create_module创建模块对象

sys.modules注册模块

exec_module模块执行

Path Based Finder—PathFinder

流程

当前目录

Path Entry Hook

Path Entry Finder—PathEntryFinder

find_spec

替换标准导入系统

__main__

__spec__

Import[ Search] Path定制

动态增加路径

修改PYTHONPATH环境变量

增加.pth文件

数据模型--执行相关

Module

元属性

Code Object

特殊属性

Frame Objects

特殊只读属性

特殊可写属性

方法

Traceback Objects

特殊只读属性

特殊可写属性

I/O对象/文件对象

Categories

Recents

Advertisement

follow.it

`spec`

`path`

`repr`

`file`/`cached`

`sys.modules`模块缓存

`sys.path`

`sys.path_import_cache`

`find_spec`

`create_module`创建模块对象

`sys.modules`注册模块

`exec_module`模块执行

Path Based Finder—`PathFinder`

Path Entry Finder—`PathEntryFinder`

`find_spec`

`main`

`spec`

修改`PYTHONPATH`环境变量

增加`.pth`文件