python 包及软件开发的目录规范

一  包介绍

随着模块数目的增多，把所有模块不加区分地放到一起也是极不合理的，于是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的名称空间，例如http://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

三 软件开发目录规范

为了提高程序的可读性与可维护性，我们应该为软件设计良好的目录结构，这与规范的编码风格同等重要。软件的目录规范并无硬性标准，只要清晰可读即可，假设你的软件名为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依赖库都装好了。