一个项目结构--源自《learn python hard way》的项目结构总结

问题：http://learnpythonthehardway.org/book/ex46.html

一书exe 46中提到了项目架构，这是之前写程序没有考虑的，一个项目一定有规范和标准，所以也算是一种新内容的学习，摘抄和补充下来，供后续参考使用。

当然整个使用环境是相对于linux来说的（win下的话，直接程序py2exe打包即可），但共同点是项目文件布局基本相同。

1、项目文件布局

 骨架目录一般包括项目文件布局、自动化测试代码，模组，以及安装脚本。当建立一个新项目的时候，只要把这个目录复制过去，改改目录的名字，再编辑里边的文件就行了。

一般为：

project ->skeleton->bin

      ->NAME -> __init__.py

      ->tests   -> __init__.py

                      ->NAME_tests.py

      ->docs

      ->setup.py

其中NAME_tests.py内容如下：

#/bin/env python
#filename:name_tests.py

from nose.tools import *
import NAME

def setup():
        print 'setup!'

def teardown():
        print 'TEAR DOWN!'

def test_basic():
        print 'I RAN!'

其中setup.py内容如下：

#!/bin/env/python
#filename:setup.py

try:
        from setuptools import setup
except ImportError:
        from distutils.core import setup

config = {
        'description': 'project name',
        'author': 'ower name',
        'url': 'URL to get it at.',
        'download_url': 'Where to download it.',
        'author_email': 'My email.',
        'version': 'o.1',
        'install_requires': ['nose'],
        'packages': ['NAME'],
        'scripts': [],
        'name': 'projectname'
}

setup(**config)

这样得到的结构就是：

.:
skeleton

./skeleton:
bin  docs  NAME  setup.py  tests

./skeleton/bin:

./skeleton/docs:

./skeleton/NAME:
__init__.py

./skeleton/tests:
__init__.py  NAME_tests.py

2、目录配置建立检查测试

在skeleton目录下运行：得到结果如下，这说明目录建立正确。

[root@localhost skeleton]# nosetests#这是linux下的一个命令
.
----------------------------------------------------------------------
Ran 1 test in 0.039s

OK
[root@localhost skeleton]#

3、搭建项目环境，安装软件包

接下来需要安装下面的软件包：

1. pip – http://pypi.python.org/pypi/pip
2. distribute – http://pypi.python.org/pypi/distribute
3. nose – http://pypi.python.org/pypi/nose/
4. virtualenv – http://pypi.python.org/pypi/virtualenv

不仅只是手动下载并且安装这些软件包，而且应该看一下别人的建议，尤其看看针对你的操作系统别人是怎样建议你安装和使用的。同样的软件包在不一样的操作系统上面的安装方式是不一样的，不一样版本的 Linux 和 OSX 会有不同，而 Windows 更是不同。

4、后续项目创建

以后每次新建一个项目时，只要做下面的事情就可以了：

1. 拷贝这份骨架目录，把名字改成你新项目的名字。
2. 再将 NAME 模组更名为你需要的名字，它可以是你项目的名字，当然别的名字也行。
3. 编辑 setup.py 让它包含你新项目的相关信息。
4. 重命名 tests/NAME_tests.py ，让它的名字匹配到你模组的名字。
5. 使用 nosetests 检查有无错误。
6. 开始写代码吧。

5、资源补充

下面根据网上资源做一些补充

主要是让现有Python代码的开源过程尽可能清晰和流畅，可以把现有的代码转换成一个能够鼓励他人使用和贡献的开源项目。

项目布局：

每个项目至少应该有下面三个目录：

1. doc目录，包括项目文档
2. 项目目录，以项目命名，存储实际的Python包
3. test目录，包含下面两部分
   1. 在这个目录下包括了测试代码和资源
   2. 作为一个独立顶级包

setuptools 和 setup.py文件

setup.py文件，被distuils包用来安装Python包的。对于任何一个项目，它都是一个很重要的文件，因为它包含了版本，包依赖信息，PyPi需要的项目描述，你的名字和联系信息，以及其它一些信息。它允许以编程的方式搜索安装包，提供元数据和指令说明让工具如何做。

setuptools包（实际上就是对distutils的增强）简单化了建立发布python包。使用setuptools给python包打包，和distutils打包没什么区别。这实在是没有任何理由不使用它。

下面是作者举的一个例子：

setup.py应该放在你的项目的根目录。setup.py中最重要的一部分就是调用setuptools.setup，这里面包含了此包所需的所有源信息。这里就是sandman项目的setup.py的所有内容

01	from __future__import print_function

02	from setuptoolsimport setup, find_packages

03	from setuptools.command.testimport test as TestCommand

04

import io

05	import codecs

06

import os

07	import sys

08

09	import sandman

10

11	here =os.path.abspath(os.path.dirname(__file__))

12

13	def read(*filenames,**kwargs):

14	encoding = kwargs.get('encoding','utf-8')

15	sep = kwargs.get('sep','\n')

16

buf = []

17	forfilename in filenames:

18	with io.open(filename, encoding=encoding) as f:

19	buf.append(f.read())

20	returnsep.join(buf)

21

22	long_description =read('README.txt','CHANGES.txt')

23

24	class PyTest(TestCommand):

25	deffinalize_options(self):

26	TestCommand.finalize_options(self)

27	self.test_args= []

28	self.test_suite= True

29

30	defrun_tests(self):

31	importpytest

32	errcode= pytest.main(self.test_args)

33	sys.exit(errcode)

34

35

setup(

36	name='sandman',

37	version=sandman.__version__,

38	url='http://github.com/jeffknupp/sandman/',

39	license='Apache Software License',

40	author='Jeff Knupp',

41	tests_require=['pytest'],

42	install_requires=['Flask>=0.10.1',

43	'Flask-SQLAlchemy>=1.0',

44	'SQLAlchemy==0.8.2',

45

],

46	cmdclass={'test': PyTest},

47	author_email='jeff@jeffknupp.com',

48	description='Automated REST APIs for existing database-driven systems',

49	long_description=long_description,

50	packages=['sandman'],

51	include_package_data=True,

52	platforms='any',

53	test_suite='sandman.test.test_sandman',

54	classifiers= [

55	'Programming Language :: Python',

56	'Development Status :: 4 - Beta',

57	'Natural Language :: English',

58	'Environment :: Web Environment',

59	'Intended Audience :: Developers',

60	'License :: OSI Approved :: Apache Software License',

61	'Operating System :: OS Independent',

62	'Topic :: Software Development :: Libraries :: Python Modules',

63	'Topic :: Software Development :: Libraries :: Application Frameworks',

64	'Topic :: Internet :: WWW/HTTP :: Dynamic Content',

65

],

66	extras_require={

67	'testing': ['pytest'],

68

}

69

)

使用sandman.__version__和gettinglong_description方法（尽管我也记不住是哪一个，但是却可以从其它项目的setup.py中获得）来减少我们需要写的引用代码。相反，维护项目的版本有三个地方(setup.py, 包自身的__version__， 以及文档)，也可以使用包的version来填充setup里面的version参数

long_description被Pypi在你项目的PyPI主页当做文档使用。这里有其他一个文件，README.md，其中包含几乎相同的内容，我使用pandoc依据README.md自动生成README.rst，因此我们只需看README.rst就行了，并将它的内容设置为long_description。 py.test 中有一个特殊的条目（pytest类）设置允许Python检查setup.py可否正常工作。这段代码直接来自py.test指导文档。 文件中的其他内容都是在设置文档中描述的安装参数。

其他的setup.py参数

有一些sandman 用不到的启动参数，在你的包里可能会用到。举个例子，你可能正在分派一些脚本并希望你的用户能够从命令行执行。在这个例子中，脚本会和你其他的代码一起安装在正常的site-packages位置。用户安装完后，没有其他的简单方法运行它。基于这一点，setup可以带有一个的脚本参数来指明Python脚本应该如何安装。在包中安装一个调用go_foo.py的脚本，这个用来启动的调用包括下面这行：

1	scripts =['go_foo.py'],

确保在脚本中填入相对路径，并不仅仅是一个名称 (如scripts = ['scripts/foo_scripts/go_foo.py']).同样，你的脚本应该以"shebang"行和"python"开始，如下：

1	#! /usr/bin/env python

distutils将会在安装过程中自动用当前解释器位置取代这一行。

如果你的包比我们这里讨论的要复杂，你可在官方文档中参看启动工具文档和分布python模块。

参考文献：

http://www.oschina.net/translate/open-sourcing-a-python-project-the-right-way?lang=chs&page=1#

更加详细的请参考转载文章下一篇：

《以正确的方式开源 Python 项目》

http://www.oschina.net/translate/open-sourcing-a-python-project-the-right-way?lang=chs&page=2#