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 文件夹下可以放置处理文本或者构建项目用的脚本;

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

#/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来简化回归测试工作。

Leave a Reply

Your email address will not be published. Required fields are marked *