Python项目结构

为什么需要项目结构？就是为了使得项目干净整洁、逻辑清晰明了，所有组件有效组织在项目文件夹中。为了组织项目结构我们会思考一下问题：哪些函数需要放在模块中？数据、常量放在何处？哪些函数需要放在一起，哪些需要分开？模块是Python项目的核心，所以应该考虑如何组织模块，以及构建工具、文档和测试用例的组织；

好的项目结构应该有一个好的名字、好的描述、好的文件夹结构，以及好的README文件和项目文档；

推荐的Python项目(sample)结构如下：samplemod

README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

模块是项目的核心，所以应该在项目的跟目录下放置sample目录或者 sample.py文件，而不是src或python子目录；
最好放置 LICENSE 文件，说明项目的版权范围，一般我们的确很少放置，用 BSD是个很不错的选择；
requirements.txt 用来指定项目的依赖包，通过 pip install -r requirements.txt 来安装依赖；
文档放在根目录的 docs 中；
测试用例通常放在根目录下的 test_sample.py 或者 tests 子目录下，测试和开发不在同一目录下如要导入开发模块，最好的办法是用一个专门的文件 context.py 把开发目录加入到 sys.path 中去。

import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

import sample      #引入了sample模块

context.py 文件还可以设置很多别的测试环境，包括数据和依赖；测试文件只需要执行 from .context import sample ，相对导入需要 tests 也是一个包，所以测试时要用 python -m tests.test_basic命令测试；

Makefile 文件用来执行安装依赖、构建、测试的工作；
README 文件用来介绍项目解决的问题，怎样安装使用，有什么样的特点，让对项目感兴趣的开发者能够快速了解项目；
scripts 文件夹下可以放置处理文本或者构建项目用的脚本；

单个模块的结构同样应当遵照一种简单清晰统一的结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


#/usr/bin/env python           #(1)启动行
# -*- coding: utf-8 -*-        #(1)编码行

"""this is a test module"""    #(2)模块文档

import sys                     #(3)模块的导入行
import os

debug = True                   #(4)全局变量定义，尽可能少使用

class FooClass(object):        #(5)类定义
    """Foo class"""
    pass

def test():                    #(6)函数定义
    """test function"""
    foo = FooClass()
    if debug:
        print 'ran test()'

if __name__ == "__main__":     #(7)main块代码，放置测试代码的最佳地方
    test()

因为绝大多数的模块写来都是为了最终导入到应用主程序中的，所以不应该在最外层放置过多代码，这些代码可能在导入时被执行，应当将所有代码都放在函数、类定义中。而只放main块代码在最外层。__name__变量在被导入时包含的是导入模块的名字，在直接执行时是"__main__"字符串，在Python中将利用此特性来测试代码，并且Python官方提供了unitest模块或PyUnit来简化回归测试工作。

Contents

Python项目结构