用正确的姿势开源Python项目

Jintao Zhang

发布于 2018-08-27 15:12:27

8980

发布于 2018-08-27 15:12:27

文章被收录于专栏：MoeLove

目录结构（初始化）

一般我们都会选择在项目的顶层包含较基础的文件，比如setup.py，requirements，README等文件。一般情况下，一个预发布的Python项目中应该包含以下几类文件：

projects (项目的主体文件)
setup.py
requirements
Readme (项目说明)
docs (项目文档)
test

其中，projects文件夹要以项目命名，存放实际的Python Package. 这里放一个我的项目的目录作为例子。

➜  httpmultipart git:(master) tree -L 2
.
├── build
│   ├── bdist.linux-x86_64
│   └── lib.linux-x86_64-2.7
├── dist
│   ├── httpmultipart-0.1.0-py2.py3-none-any.whl
│   └── httpmultipart-0.1.0.tar.gz
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── Makefile
│   ├── userguide
│   └── userguide.rst
├── env
│   ├── bin
│   ├── include
│   ├── lib
│   └── local
├── httpmultipart
│   ├── __init__.py
│   ├── __init__.pyc
│   ├── main.py
│   └── main.pyc
├── httpmultipart.egg-info
│   ├── dependency_links.txt
│   ├── not-zip-safe
│   ├── PKG-INFO
│   ├── SOURCES.txt
│   └── top_level.txt
├── LICENSE
├── MANIFEST.in
├── README.rst
├── setup.cfg
├── setup.py
└── test_httpmultipart.py

14 directories, 21 files

这个目录中包含了我的virtual enviroment 和打包构建时候生成的文件夹。这些东西在下面会提到。

文档

文档的话，并没有严格要求必须使用什么样的工具进行构建，也没有很严格的格式要求。不过我推荐使用SPHINX,它是用Python写的工具，使用了一种叫做reStructuredText的语法编辑，可以对多个文本文件重编，可以输出成HTML或者PDF等格式。

这里稍微介绍下使用：

安装 $ pip install sphinx
初始化 $ cd docs $ sphinx-quickstart ...#(这里有一系列的提问，进行初始化)
编译 $ make html #(如果按照默认配置生成的Makefile的话，这样就可以编译出html了)

Sphinx的使用还有很多值得说的地方，推荐两个资料：

英文的Sphinx 的官方文档
中文的Python 开发实战

官方文档写的非常详细，那本书偏向于实战，是很不错的书。还有很关键的一点是Sphinx有autodoc和automodule的扩展，可以从代码中提取出文档，与代码直接进行关联。提供一个例子可以方便的在文档和源码中进行跳转。

Read the Docs 持续文档集成

说完写文档就不得不提到Read the Dosc了,这是一个第三方的文档托管平台,使用Django开发，它可以很轻松的和Github上的项目进行集成，在每次代码提交的时候会自动进行文档构建，我们可以看看生成文档的效果。现在有很多开源项目的文档都是托管在这里的，具体的配置可以参考官方文档。

TravisCI 持续集成

Travisci可以与Github非常好的结合，可以手动导入repo，并设置Webhooks & services,在每次提交的时候都会测试运行来发现是否存在异常。在使用之前，我们需要先做一些初始化的操作：

创建.travis.yml文件我们需要告诉它一些基本的信息：
- 我们项目使用的语言
- 项目使用的语言版本
- 环境的依赖
- 是否需要sudo权限运行
- 使用什么命令来安装
- 使用什么命令运行测试下面提供一个例子： language: python python: - 2.7 env: - DEPS=true - DEPS=false sudo: false install: - travis_retry python setup.py install - travis_retry pip install coveralls - coverage run test_httpmultipart.py - coverage report script: - python test_httpmultipart.py after_success: coveralls

PS：在install这一项配置中要注意，如果项目存在依赖，一定要进行安装，还有Travisci提供了多项配置，包括出错重试等，具体配置可以参考官方文档，要特别注意travis_retry等命令的使用，非常容易出现坑。

测试

Python有内置的unittest测试库，支持断言;当然还有其他的一些测试框架，看个人喜好和项目需求。在项目中应该包含测试文件或者测试目录，测试文件一般以test_projects_name.py命名。我选择使用coverage作为测试覆盖率的检查，下面是一个运行示例：

➜  httpmultipart git:(master) coverage run test_httpmultipart.py 
....
----------------------------------------------------------------------
Ran 4 tests in 36.125s

OK

➜  httpmultipart git:(master) coverage report
Name                        Stmts   Miss Branch BrPart  Cover
-------------------------------------------------------------
httpmultipart/__init__.py      10      0      0      0   100%
httpmultipart/main.py          37      0      4      0   100%
-------------------------------------------------------------
TOTAL                          47      0      4      0   100%

Coveralls 测试覆盖率检查

Coveralls可以很友好的支持Github和Bitbucket仓库的导入，同时也可以很好的和Travisci集成，在上面我们的.travis.yml文件中，在最后一项after_success中，我们就配置了对Coveralls的支持。

发布包到PyPI

PyPI - the Python Package Index 是Python的包仓库，它允许我们将自己写的包上传上去，这样就可以使用pip和easy_install进行安装了。这里说一个很重要的事情： 请在发布自己项目之前做好测试，确认自己上传的是一个可用，无害的包 当你已经完成上面的步骤之后，那么你只需要以下几步就可以完成了。以我的项目为例子:

配置setup.py:

#!/usr/bin/env python

import os
import re
import sys
from codecs import open
try:
    from setuptools import setup
except ImportError:
    from distutils.core import setup

if sys.argv[-1] == 'publish':
    os.system('python setup.py sdist upload')
    sys.exit()

packages = [
    'httpmultipart',
]

requires = []

version = ''

with open('httpmultipart/__init__.py', 'r') as fd:
    version = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]',
                        fd.read(), re.MULTILINE).group(1)
    
if not version:
    raise RuntimeError('Cannot find version information')
    
with open('README.rst', 'r', 'utf-8') as f:
    readme = f.read()

setup(
    name='httpmultipart',
    version=version,
    description='A httpmultipart post handler',
    long_description=readme + '\n\n',
    author='TaoBeier',
    author_email='zhangjintao9020@gmail.com',
    url='https://github.com/tao12345666333/httpmultipart',
    packages=packages,
    package_data={'': ['LICENSE']},
    package_dir={'httpmultipart': 'httpmultipart'},
    include_package_data=True,
    install_requires=requires,
    license='MIT',
    zip_safe=False,
    platforms='any',
    classifiers=(
        'Development Status :: 5 - Production/Stable',
        'Intended Audience :: Developers',
        'Natural Language :: English',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 2.7',
        'Topic :: Software Development :: Libraries',
        'Topic :: Software Development :: Libraries :: Python Modules',
    ),
)

当然大部分时候也不需要这么麻烦，简化的配置可以参考官方的文档。注意最下面那部分classifiers是按照PyPI官方的列表填写的。还有，如果有些文件想要额外打包进去，那么需要在根目录添加MANIFEST.in文件。

打包代码

$ python setup.py sdist # 生成pip支持的安装包

$ python setup.py bdist_wheel # 生成支持easy_install的安装包

发布到PyPI上首先在PyPI上注册一个帐号，然后进行下面两步：
- 注册package $ python setup.py register $ # 在这一步会有一些提示，按照提示选择，输入自己帐号密码相关的信息即可 $ # 在提示你要不要保存帐号信息的时候， $ # 你选择了‘y’， $ # 则会在你的用户目录下生成一个 .pypirc 的文件， $ # 其中明文保存着你的帐号和密码。这里稍微再提一点，如果在提示是否保存账户信息的时候，选择了‘n’，想反悔了也没关系，我们可以手动创建一个~/.pypirc文件。格式如下： [distutils] index-servers=pypi [pypi] repository = https://pypi.python.org/pypi username = your username password = your password
上传package $ python setup.py sdist bdist_wheel upload 在上传完成提示200响应的时候，你就上传成功了，去PyPI上看看有没有上传成功的包，并且试着用pip进行安装吧！

这里我省略了一步，就是发布前的测试，你可以使用PyPI的测试服务器进行测试发布，发布到这里的包并不会对你正式发布有任何影响。

项目托管在Github上

开源到Github上后，就是继续维护和开发，这点就不多说了。

开发相关

建议使用virtualenv之类的工具构建纯净的环境，重复的动作交给Make之类的工具。

这篇算是一个小小的总结加备忘吧，经验尚缺，还望指正。发布到微信中链接都失效了，可以点击下面的查看原文来查看相关链接。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2015-11-23，如有侵权请联系 cloudcommunity@tencent.com 删除

其他

本文分享自 MoeLove 微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

其他

登录后参与评论

0 条评论

热度