Python基础—— 模块介绍、模块的使用、包介绍、 包的使用、软件开发目录规范
文章目录
一 模块介绍
在Python中，一个py文件就是一个模块，文件名为xxx.py模块名则是xxx,导入模块可以引用模块中已经写好的功能。如果把开发程序比喻成制造一台电脑，编写模块就像是在制造电脑的零部件，准备好零部件后，剩下的工作就是按照逻辑把它们组装到一起。
将程序模块化会使得程序的组织结构清晰，维护起来更加方便。比起直接开发一个完整的程序，单独开发一个小的模块也会更加简单，并且程序中的模块与电脑中的零部件稍微不同的是：程序中的模块可以被重复使用。所以总结下来，使用模块既保证了代码的重用性，又增强了程序的结构性和可维护性。另外除了自定义模块外，我们还可以导入使用内置或第三方模块提供的现成功能，这种“拿来主义”极大地提高了程序员的开发效率。
二 模块的使用
2.1 import语句
有如下示范文件
#文件名：foo.py
x=1
def get():
print(x)
def change():
global x
x=0
class Foo:
def func(self):
print('from the func')
要想在另外一个py文件中引用foo.py中的功能，需要使用import foo，首次导入模块会做三件事：
1、执行源文件代码
2、产生一个新的名称空间用于存放源文件执行过程中产生的名字
3、在当前执行文件所在的名称空间中得到一个名字foo，该名字指向新创建的模块名称空间，若要引用模块名称空间中的名字，需要加上该前缀，如下
import foo #导入模块foo
a=foo.x #引用模块foo中变量x的值赋值给当前名称空间中的名字a
foo.get() #调用模块foo的get函数
foo.change() #调用模块foo中的change函数
obj=foo.Foo() #使用模块foo的类Foo来实例化，进一步可以执行obj.func()
加上foo.作为前缀就相当于指名道姓地说明要引用foo名称空间中的名字，所以肯定不会与当前执行文件所在名称空间中的名字相冲突，并且若当前执行文件的名称空间中存在x，执行foo.get()或foo.change()操作的都是源文件中的全局变量x。
需要强调一点是，第一次导入模块已经将其加载到内存空间了，之后的重复导入会直接引用内存中已存在的模块，不会重复执行文件，通过import sys，打印sys.modules的值可以看到内存中已经加载的模块名。
提示：
#1、在Python中模块也属于第一类对象，可以进行赋值、以数据形式传递以及作为容器类型的元素等操作。
#2、模块名应该遵循小写形式，标准库从python2过渡到python3做出了很多这类调整，比如ConfigParser、Queue、SocketServer全更新为纯小写形式。
用import语句导入多个模块，可以写多行import语句
import module1
import module2
...
import moduleN
还可以在一行导入，用逗号分隔开不同的模块
import module1,module2,...,moduleN
但其实第一种形式更为规范，可读性更强，推荐使用，而且我们导入的模块中可能包含有python内置的模块、第三方的模块、自定义的模块，为了便于明显地区分它们，我们通常在文件的开头导入模块，并且分类导入，一类模块的导入与另外一类的导入用空行隔开，不同类别的导入顺序如下：
#1. python内置模块
#2. 第三方模块
#3. 程序员自定义模块
当然，我们也可以在函数内导入模块，对比在文件开头导入模块属于全局作用域，在函数内导入的模块则属于局部的作用域。
2.2 from-import 语句
from…import…与import语句基本一致，唯一不同的是：使用import foo导入模块后，引用模块中的名字都需要加上foo.作为前缀，而使用from foo import x,get,change,Foo则可以在当前执行文件中直接引用模块foo中的名字，如下
from foo import x,get,change #将模块foo中的x和get导入到当前名称空间
a=x #直接使用模块foo中的x赋值给a
get() #直接执行foo中的get函数
change() #即便是当前有重名的x，修改的仍然是源文件中的x
无需加前缀的好处是使得我们的代码更加简洁，坏处则是容易与当前名称空间中的名字冲突，如果当前名称空间存在相同的名字，则后定义的名字会覆盖之前定义的名字。
另外from语句支持from foo import *语法，*代表将foo中所有的名字都导入到当前位置
from foo import * #把foo中所有的名字都导入到当前执行文件的名称空间中，在当前位置直接可以使用这些名字
a=x
get()
change()
obj=Foo()
如果我们需要引用模块中的名字过多的话，可以采用上述的导入形式来达到节省代码量的效果，但是需要强调的一点是：只能在模块最顶层使用的方式导入，在函数内则非法，并且的方式会带来一种副作用，即我们无法搞清楚究竟从源文件中导入了哪些名字到当前位置，这极有可能与当前位置的名字产生冲突。模块的编写者可以在自己的文件中定义__all__变量用来控制*代表的意思
#foo.py
__all__=['x','get'] #该列表中所有的元素必须是字符串类型，每个元素对应foo.py中的一个名字
x=1
def get():
print(x)
def change():
global x
x=0
class Foo:
def func(self):
print('from the func')
这样我们在另外一个文件中使用*导入时，就只能导入__all__定义的名字了
from foo import * #此时的*只代表x和get
x #可用
get() #可用
change() #不可用
Foo() #不可用
2.3 其他导入语法(as)
我们还可以在当前位置为导入的模块起一个别名
import foo as f #为导入的模块foo在当前位置起别名f，以后再使用时就用这个别名f
f.x
f.get()
还可以为导入的一个名字起别名
from foo import get as get_x
get_x()
通常在被导入的名字过长时采用起别名的方式来精简代码，另外为被导入的名字起别名可以很好地避免与当前名字发生冲突，还有很重要的一点就是：可以保持调用方式的一致性，例如我们有两个模块json和pickle同时实现了load方法，作用是从一个打开的文件中解析出结构化的数据，但解析的格式不同，可以用下述代码有选择性地加载不同的模块
if data_format == 'json':
import json as serialize #如果数据格式是json，那么导入json模块并命名为serialize
elif data_format == 'pickle':
import pickle as serialize #如果数据格式是pickle，那么导入pickle模块并命名为serialize
data=serialize.load(fn) #最终调用的方式是一致的
2.4 循环导入问题
循环导入问题指的是在一个模块加载/导入的过程中导入另外一个模块，而在另外一个模块中又返回来导入第一个模块中的名字，由于第一个模块尚未加载完毕，所以引用失败、抛出异常，究其根源就是在python中，同一个模块只会在第一次导入时执行其内部代码，再次导入该模块时，即便是该模块尚未完全加载完毕也不会去重复执行内部代码
我们以下述文件为例，来详细分析循环/嵌套导入出现异常的原因以及解决的方案
m1.py
print('正在导入m1')
from m2 import y
x='m1'
m2.py
print('正在导入m2')
from m1 import x
y='m2'
run.py
import m1
测试一
#1、执行run.py会抛出异常
正在导入m1
正在导入m2
Traceback (most recent call last):
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/aa.py", line 1, in <module>
import m1
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/m1.py", line 2, in <module>
from m2 import y
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/m2.py", line 2, in <module>
from m1 import x
ImportError: cannot import name 'x'
#2、分析
先执行run.py--->执行import m1，开始导入m1并运行其内部代码--->打印内容"正在导入m1"
--->执行from m2 import y 开始导入m2并运行其内部代码--->打印内容“正在导入m2”--->执行from m1 import x,由于m1已经被导入过了，所以不会重新导入，所以直接去m1中拿x，然而x此时并没有存在于m1中，所以报错
测试二
#1、执行文件不等于导入文件，比如执行m1.py不等于导入了m1
直接执行m1.py抛出异常
正在导入m1
正在导入m2
正在导入m1
Traceback (most recent call last):
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/m1.py", line 2, in <module>
from m2 import y
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/m2.py", line 2, in <module>
from m1 import x
File "/Users/linhaifeng/PycharmProjects/pro01/1 aaaa练习目录/m1.py", line 2, in <module>
from m2 import y
ImportError: cannot import name 'y'
#2、分析
执行m1.py，打印“正在导入m1”，执行from m2 import y ，导入m2进而执行m2.py内部代码--->打印"正在导入m2"，执行from m1 import x，此时m1是第一次被导入，执行m1.py并不等于导入了m1，于是开始导入m1并执行其内部代码--->打印"正在导入m1"，执行from m1 import y，由于m1已经被导入过了，所以无需继续导入而直接问m2要y，然而y此时并没有存在于m2中所以报错
解决方案
# 方案一：导入语句放到最后，保证在导入时，所有名字都已经加载过
# 文件：m1.py
print('正在导入m1')
x='m1'
from m2 import y
# 文件：m2.py
print('正在导入m2')
y='m2'
from m1 import x
# 文件：run.py内容如下，执行该文件，可以正常使用
import m1
print(m1.x)
print(m1.y)
# 方案二：导入语句放到函数中，只有在调用函数时才会执行其内部代码
# 文件：m1.py
print('正在导入m1')
def f1():
from m2 import y
print(x,y)
x = 'm1'
# 文件：m2.py
print('正在导入m2')
def f2():
from m1 import x
print(x,y)
y = 'm2'
# 文件：run.py内容如下，执行该文件，可以正常使用
import m1
m1.f1()
注意：循环导入问题大多数情况是因为程序设计失误导致，上述解决方案也只是在烂设计之上的无奈之举，在我们的程序中应该尽量避免出现循环/嵌套导入，如果多个模块确实都需要共享某些数据，可以将共享的数据集中存放到某一个地方，然后进行导入
2.5 搜索模块的路径与优先级
模块其实分为四个通用类别，分别是：
1、使用纯Python代码编写的py文件
2、包含一系列模块的包
3、使用C编写并链接到Python解释器中的内置模块
4、使用C或C++编译的扩展模块
在导入一个模块时，如果该模块已加载到内存中，则直接引用，否则会优先查找内置模块，然后按照从左到右的顺序依次检索sys.path中定义的路径，直到找模块对应的文件为止，否则抛出异常。sys.path也被称为模块的搜索路径，它是一个列表类型
>>> sys.path
['',
'/Library/Frameworks/Python.framework/Versions/3.5/lib/python35.zip',
'/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5',
...,
'/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages'
列表中的每个元素其实都可以当作一个目录来看：在列表中会发现有.zip或.egg结尾的文件，二者是不同形式的压缩文件，事实上Python确实支持从一个压缩文件中导入模块，我们也只需要把它们都当成目录去看即可。
sys.path中的第一个路径通常为空，代表执行文件所在的路径，所以在被导入模块与执行文件在同一目录下时肯定是可以正常导入的，而针对被导入的模块与执行文件在不同路径下的情况，为了确保模块对应的源文件仍可以被找到，需要将源文件foo.py所在的路径添加到sys.path中，假设foo.py所在的路径为/pythoner/projects/
import sys
sys.path.append(r'/pythoner/projects/') #也可以使用sys.path.insert(……)
import foo #无论foo.py在何处,我们都可以导入它了
2.6 区分py文件的两种用途
一个Python文件有两种用途，一种被当主程序/脚本执行，另一种被当模块导入，为了区别同一个文件的不同用途，每个py文件都内置了__name__变量，该变量在py文件被当做脚本执行时赋值为“main”,在py文件被当做模块导入时赋值为模块名
作为模块foo.py的开发者，可以在文件末尾基于__name__在不同应用场景下值的不同来控制文件执行不同的逻辑
#foo.py
...
if __name__ == '__main__':
foo.py被当做脚本执行时运行的代码
else:
foo.py被当做模块导入时运行的代码
通常我们会在if的子代码块中编写针对模块功能的测试代码，这样foo.py在被当做脚本运行时，就会执行测试代码，而被当做模块导入时则不用执行测试代码。
2.7 编写一个规范的模块
我们在编写py文件时，需要时刻提醒自己，该文件既是给自己用的，也有可能会被其他人使用，因而代码的可读性与易维护性显得十分重要，为此我们在编写一个模块时最好按照统一的规范去编写，如下
#!/usr/bin/env python #通常只在类unix环境有效,作用是可以使用脚本名来执行，而无需直接调用解释器。
"The module is used to..." #模块的文档描述
import sys #导入模块
x=1 #定义全局变量,如果非必须,则最好使用局部变量,这样可以提高代码的易维护性,并且可以节省内存提高性能
class Foo: #定义类,并写好类的注释
'Class Foo is used to...'
pass
def test(): #定义函数,并写好函数的注释
'Function test is used to…'
pass
if __name__ == '__main__': #主程序
test() #在被当做脚本执行时,执行此处的代码
2 包介绍
随着模块数目的增多，把所有模块不加区分地放到一起也是极不合理的，于是Python为我们提供了一种把模块组织到一起的方法，即创建一个包。包就是一个含有__init__.py文件的文件夹，文件夹内可以组织子模块或子包，例如
pool/ #顶级包
├── __init__.py
├── futures #子包
│ ├── __init__.py
│ ├── process.py
│ └── thread.py
└── versions.py #子模块
需要强调的是
#1. 在python3中，即使包下没有__init__.py文件，import 包仍然不会报错，而在python2中，包下一定要有该文件，否则import 包报错
#2. 创建包的目的不是为了运行，而是被导入使用，记住，包只是模块的一种形式而已，包的本质就是一种模块
接下来我们就以包pool为例来介绍包的使用，包内各文件内容如下
# process.py
class ProcessPoolExecutor:
def __init__(self,max_workers):
self.max_workers=max_workers
def submit(self):
print('ProcessPool submit')
# thread.py
class ThreadPoolExecutor:
def __init__(self, max_workers):
self.max_workers = max_workers
def submit(self):
print('ThreadPool submit')
# versions.py
def check():
print('check versions’)
# __init__.py文件内容均为空
二 包的使用
2.1 导入包与__init__.py
包属于模块的一种，因而包以及包内的模块均是用来被导入使用的，而绝非被直接执行，首次导入包（如import pool）同样会做三件事：
1、执行包下的__init__.py文件
2、产生一个新的名称空间用于存放__init__.py执行过程中产生的名字
3、在当前执行文件所在的名称空间中得到一个名字pool，该名字指向__init__.py的名称空间，例如pool.xxx和pool.yyy中的xxx和yyy都是来自于pool下的__init__.py，也就是说导入包时并不会导入包下所有的子模块与子包
import pool
pool.versions.check() #抛出异常AttributeError
pool.futures.process.ProcessPoolExecutor(3) #抛出异常AttributeError
pool.versions.check()要求pool下有名字versions，进而pool.versions下有名字check。pool.versions下已经有名字check了，所以问题出在pool下没有名字versions，这就需要在pool下的__init__.py中导入模块versions
强调
1.关于包相关的导入语句也分为import和from ... import ...两种，但是无论哪种，无论在什么位置，在导入时都必须遵循一个原则：凡是在导入时带点的，点的左边都必须是一个包，否则非法。可以带有一连串的点，如import 顶级包.子包.子模块,但都必须遵循这个原则。但对于导入后，在使用时就没有这种限制了，点的左边可以是包,模块，函数，类(它们都可以用点的方式调用自己的属性)。
2、包A和包B下有同名模块也不会冲突，如A.a与B.a来自俩个命名空间
3、import导入文件时，产生名称空间中的名字来源于文件，import 包，产生的名称空间的名字同样来源于文件，即包下的__init__.py，导入包本质就是在导入该文件
2.2 绝对导入与相对导入
针对包内的模块之间互相导入，导入的方式有两种
1、绝对导入：以顶级包为起始
#pool下的__init__.py
from pool import versions
2、相对导入：.代表当前文件所在的目录，…代表当前目录的上一级目录，依此类推
#pool下的__init__.py
from . import versions
同理，针对pool.futures.process.ProcessPoolExecutor(3)，则需要
#操作pool下的__init__.py，保证pool.futures
from . import futures #或from pool import futures
#操作futrues下的__init__.py，保证pool.futures.process
from . import process #或from pool.futures import process
在包内使用相对导入还可以跨目录导入模块，比如thread.py中想引用versions.py的名字check
import也能使用绝对导入，导入过程中同样会依次执行包下的__init__.py,只是基于import导入的结果，使用时必须加上该前缀
例1：
import pool.futures #拿到名字pool.futures指向futures下的__init__.py
pool.futures.xxx #要求futures下的__init__.py中必须有名字xxx
例2：
import pool.futures.thread #拿到名字pool.futures.thread指向thread.py
thread_pool=pool.futures.thread.ThreadPoolExecutor(3)
thread_pool.submit()
相对导入只能用from module import symbol的形式,import …versions语法是不对的，且symbol只能是一个明确的名字
from pool import futures.process #语法错误
from pool.futures import process #语法正确
针对包内部模块之间的相互导入推荐使用相对导入，需要特别强调：
1、相对导入只能在包内部使用，用相对导入不同目录下的模块是非法的
2、无论是import还是from-import，但凡是在导入时带点的，点的左边必须是包,否则语法错误
2.3 from 包 import *
在使用包时同样支持from pool.futures import * ，毫无疑问代表的是futures下__init__.py中所有的名字，通用是用变量__all__来控制代表的意思
#futures下的__init__.py
__all__=['process','thread']
最后说明一点，包内部的目录结构通常是包的开发者为了方便自己管理和维护代码而创建的，这种目录结构对包的使用者往往是无用的，此时通过操作__init__.py可以“隐藏”包内部的目录结构，降低使用难度，比如想要让使用者直接使用
import pool
pool.check()
pool.ProcessPoolExecutor(3)
pool.ThreadPoolExecutor(3)
需要操作pool下的__init__.py
from .versions import check
from .futures.process import ProcessPoolExecutor
from .futures.thread import ThreadPoolExecutor
3 软件开发目录规范
为了提高程序的可读性与可维护性，我们应该为软件设计良好的目录结构，这与规范的编码风格同等重要。软件的目录规范并无硬性标准，只要清晰可读即可，假设你的软件名为foo，笔者推荐目录结构如下
Foo/
|-- core/
| |-- core.py
|
|-- api/
| |-- api.py
|
|-- db/
| |-- db_handle.py
|
|-- lib/
| |-- common.py
|
|-- conf/
| |-- settings.py
|
|-- run.py
|-- setup.py
|-- requirements.txt
|-- README
简要解释一下:
• core/: 存放业务逻辑相关代码
• api/: 存放接口文件，接口主要用于为业务逻辑提供数据操作。
• db/: 存放操作数据库相关文件，主要用于与数据库交互
• lib/: 存放程序中常用的自定义模块
• conf/: 存放配置文件
• run.py: 程序的启动文件，一般放在项目的根目录下，因为在运行时会默认将运行文件所在的文件夹作为sys.path的第一个路径，这样就省去了处理环境变量的步骤
• setup.py: 安装、部署、打包的脚本。
• requirements.txt: 存放软件依赖的外部Python包列表。
• README: 项目说明文件。
除此之外，有一些方案给出了更加多的内容，比如LICENSE.txt,ChangeLog.txt文件等，主要是在项目需要开源时才会用到，请读者自行查阅。
关于README的内容，这个应该是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。它需要说明以下几个事项:
1、软件定位，软件的基本功能；
2、运行代码的方法: 安装环境、启动命令等；
3、简要的使用说明；
4、代码目录结构说明，更详细点可以说明软件的基本原理；
5、常见问题说明。
关于setup.py和requirements.txt：
一般来说，用setup.py来管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools来管理这些事情，这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题，而是说，一个项目一定要有一个安装部署工具，能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来。
requirements.txt文件的存在是为了方便开发者维护软件的依赖库。我们需要将开发过程中依赖库的信息添加进该文件中，避免在 setup.py安装依赖时漏掉软件包，同时也方便了使用者明确项目引用了哪些Python包。
这个文件的格式是每一行包含一个包依赖的说明，通常是flask>=0.10这种格式，要求是这个格式能被pip识别，这样就可以简单的通过 pip install -r requirements.txt来把所有Python依赖库都装好了，具体格式参照https://pip.readthedocs.io/en/1.1/requirements.html
本文来自博客园，作者：喝茶看狗叫，转载请注明原文链接：https://www.cnblogs.com/zdwzdwzdw/p/17487964.html
【推荐】国内首个AI IDE，深度理解中文开发场景，立即下载体验Trae
【推荐】编程新体验，更懂你的AI，立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包，你的智能百科全书，全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell：AI 加持，快人一步
· TypeScript + Deepseek 打造卜卦网站：技术与玄学的结合
· Manus的开源复刻OpenManus初探
· AI 智能体引爆开源社区「GitHub 热点速览」
· C#/.NET/.NET Core技术前沿周刊 | 第 29 期（2025年3.1-3.9）
· 从HTTP原因短语缺失研究HTTP/2和HTTP/3的设计差异