[toc] ## 目录组织方式2 假设项目名为foo, 建议的最方便快捷目录结构是这样: ``` Foo/ |-- bin/ | |-- foo | |-- foo/ | |-- tests/ | | |-- __init__.py | | |-- test_main.py | | | |-- __init__.py | |-- main.py | |-- docs/ | |-- conf.py | |-- abc.rst | |-- setup.py |-- requirements.txt |-- README ``` ### 简要解释: * bin/: 存放项目的一些可执行文件，也可以起名script/之类。 * foo/: 存放项目的所有源代码。 (1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。 (2) 其子目录tests/存放单元测试代码； (3) 程序的入口最好命名为main.py。 * docs/: 存放一些文档。 * setup.py: 安装、部署、打包的脚本。 * requirements.txt: 存放软件依赖的外部Python包列表。 * README: 项目说明文件。 >开源软件的目录该如何组织，可以参考[这篇文章](http://www.jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/)。 ## 关于README的内容 **每个项目都应该有的文件**，目的是能简要描述该项目的信息，让读者快速了解这个项目。它需要说明以下几个事项: 1. 软件定位，软件的基本功能。 2. 运行代码的方法: 安装环境、启动命令等。 3. 简要的使用说明。 4. 代码目录结构说明，更详细点可以说明软件的基本原理。 5. 常见问题说明。 ## 关于setup.py * Python流行的打包工具[setuptools](https://pythonhosted.org/setuptools/setuptools.html#developer-s-guide) 以参考一下Python的一个Web框架，flask是如何写的:[setup.py](https://github.com/mitsuhiko/flask/blob/master/setup.py) **一个项目一定要有一个安装部署工具**，能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来。 `setup.py`可以将这些事情自动化起来，提高效率、减少出错的概率。"复杂的东西自动化，能自动化的东西一定要自动化。"是一个非常好的习惯。 自己写个安装脚本（`deploy.sh`）替代`setup.py`也未尝不可。 ## requirements.txt 这个文件存在的目的是: 1. 方便开发者维护软件的包依赖。 将开发过程中新增的包添加进这个列表中，避免在`setup.py`安装依赖时漏掉软件包。 2. 方便读者明确项目使用了哪些Python包。 * 文件的格式 每一行包含一个包依赖的说明，通常是`flask>=0.10`这种格式，要求是这个格式能被`pip`识别，这样就可以简单的通过`pip install -r requirements.txt`来把所有Python包依赖都装好了。 * 具体格式说明：[点这里](https://pip.readthedocs.org/en/1.1/requirements.html)。 ## 关于配置文件的使用方法 注意，在上面的目录结构中，没有将`conf.py`放在源码目录下，而是放在`docs/`目录下。上面目录结构中的`conf.py`，是给出的一个配置样例，不是在写死在程序中直接引用的配置文件。 很多项目对配置文件的使用做法是: 1. 配置文件写在一个或多个python文件中,比如此处的`conf.py`。 2. 项目中哪个模块用到这个配置文件就直接通过`import conf`这种形式来在代码中使用配置。 这种做法存在的问题: 1. 这让单元测试变得困难（因为模块内部依赖了外部配置） 2. 另一方面配置文件作为用户控制程序的接口，应当可以由用户自由指定该文件的路径。 3. 程序组件可复用性太差，因为这种贯穿所有模块的代码硬编码方式，使得大部分模块都依赖`conf.py`这个文件。 我认为配置的使用，更好的方式是: 1. 模块的配置都是可以灵活配置的，不受外部配置文件的影响。 2. 程序的配置也是可以灵活控制的。 所以，不应当在代码中直接`import conf`来使用配置文件。可以通过给`main.py`启动参数指定配置路径的方式来让程序读取配置内容。