大多数Python开发者至少都写过一个像工具、脚本、库或框架等对其他人也有用的工具。我写这篇文章的目的是让现有Python代码的开源过程尽可能清晰和无痛。我不是简单的指——“创建一个GitHub库，提交，在Reddit上发布，每天调用它”。在本文的结尾，你可以把现有的代码转换成一个能够鼓励他人使用和贡献的开源项目。

然而每一个项目都是不同的，但其中将现有代码开源的流程对所有的Python项目都是类似的。在另一个受欢迎的文章系列里我写了“以正确方式开始一个Django项目”，我将概述在开源Python项目我发现的有必要的步骤。

更新 (8月17号): 感谢@pydann提醒我Cookiecutter的存在，@audreyr的一个不起的项目。我在文章结尾添加了其中的一段。看一下Audrey的项目吧！

更新 2 (8月18号)：感谢@ChristianHeimes（和其他人）关于ontox这一段。Christian也让我想起了PEP 440和其他一些都已实现很棒的改进建议。

Garfielt
翻译于 2年前

2人顶

 

顶 翻译的不错哦!

工具和概念

特别是，我发现一些工具和概念十分有用或者说是必要的。下面我就会谈及这方面主题，包括需要运行的精确的命令和需要设置的配置值。其终极目标就是让整个流程简单明了。

  1. 项目布局（目录结构）
  2. setuptools 和 setup.py文件
  3. git版本控制
  4. GitHub 项目管理
    1. GitHub的"Issues" 如下作用:
      1. bug跟踪
      2. 请求新特性
      3. 计划好的新特性
      4. 发布或者版本管理
  5. git-flow git工作流
  6. py.test 单元测试
  7. tox 标准化测试
  8. Sphinx 自动生成HTML文档
  9. TravisCI 持续测试集成
  10. ReadTheDocs 持续文档集成
  11. Cookiecutter  为开始下一个项目自动生成这些步骤

66号公路
翻译于 2年前

3人顶

 

顶 翻译的不错哦!

项目布局

当准备一个项目时，正确合理的布局（目录结构）是十分重要的。一个合理的布局意味着想参与开发者不必花时间来寻找某些代码的位置; 凭直觉就可以找到文件的位置。因为我们在处理一个项目，就意味着可能需要到处移动一些东西。

让我们从顶层开始。大多数项目都有很多顶层文件（如setup.py, README.md, requirements等等）。每个项目至少应该有下面三个目录：

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

为了更好理解文件该如何组织，这里是一个我的简单项目：sandman 布局快照。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$ pwd
~/code/sandman
$ tree
.
|- LICENSE
|- README.md
|- TODO.md
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- sandman.rst
|- requirements.txt
|- sandman
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- sandman.py
|   |-- test
|       |-- models.py
|       |-- test_sandman.py
|- setup.py

如你所看到那样，这里有一些顶层文件，一个docs目录（建立一个空目录，因为sphinx会将生成的文档放到这里），一个sandman目录，以及一个在sandman目录下的test目录。

66号公路
翻译于 2年前

2人顶

 

顶 翻译的不错哦!

setuptools 和 setup.py文件

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

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

66号公路
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
from __future__ import print_function
from setuptools import setup, find_packages
from setuptools.command.test import test as TestCommand
import io
import codecs
import os
import sys
 
import sandman
 
here = os.path.abspath(os.path.dirname(__file__))
 
def read(*filenames, **kwargs):
    encoding = kwargs.get('encoding', 'utf-8')
    sep = kwargs.get('sep', '\n')
    buf = []
    for filename in filenames:
        with io.open(filename, encoding=encoding) as f:
            buf.append(f.read())
    return sep.join(buf)
 
long_description = read('README.txt', 'CHANGES.txt')
 
class PyTest(TestCommand):
    def finalize_options(self):
        TestCommand.finalize_options(self)
        self.test_args = []
        self.test_suite = True
 
    def run_tests(self):
        import pytest
        errcode = pytest.main(self.test_args)
        sys.exit(errcode)
 
setup(
    name='sandman',
    version=sandman.__version__,
    url='http://github.com/jeffknupp/sandman/',
    license='Apache Software License',
    author='Jeff Knupp',
    tests_require=['pytest'],
    install_requires=['Flask>=0.10.1',
                    'Flask-SQLAlchemy>=1.0',
                    'SQLAlchemy==0.8.2',
                    ],
    cmdclass={'test': PyTest},
    author_email='jeff@jeffknupp.com',
    description='Automated REST APIs for existing database-driven systems',
    long_description=long_description,
    packages=['sandman'],
    include_package_data=True,
    platforms='any',
    test_suite='sandman.test.test_sandman',
    classifiers = [
        'Programming Language :: Python',
        'Development Status :: 4 - Beta',
        'Natural Language :: English',
        'Environment :: Web Environment',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: Apache Software License',
        'Operating System :: OS Independent',
        'Topic :: Software Development :: Libraries :: Python Modules',
        'Topic :: Software Development :: Libraries :: Application Frameworks',
        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
        ],
    extras_require={
        'testing': ['pytest'],
    }
)

（感谢Christian Heimes的建议让setup.py更符合人们的语言习惯。反过来，也让我借用其它的项目一目了然了。)

大多数内容浅显易懂，可以从setuptools文档查看到，所以我只会触及"有趣"的部分。使用sandman.__version__和gettinglong_description方法（尽管我也记不住是哪一个，但是却可以从其它项目的setup.py中获得）来减少我们需要写的引用代码。相反，维护项目的版本有三个地方(setup.py, 包自身的__version__， 以及文档)，我们也可以使用包的version来填充setup里面的version参数

66号公路
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

long_description被Pypi在你项目的PyPI主页当做文档使用。这里有其他一个文件，README.md，其中包含几乎相同的内容，我使用pandoc依据README.md自动生成README.rst，因此我们只需看README.rst就行了，并将它的内容设置为long_description。

py.test (上面讨论过) 中有一个特殊的条目（pytest类）设置允许Python检查setup.py可否正常工作。这段代码直接来自py.test指导文档。

文件中的其他内容都是在设置文档中描述的安装参数。

Garfielt
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

其他的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模块。

在这两者中，你可以解决一些你可能会遇到的问题。

徐继开
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

代码管理：git， 项目管理：gitHub

在“以正确的方式开始一个Django项目”中，我建议版本控制使用git 或者 mercurial。如果对于以共享与贡献的项目来说，只有一个选择：git。事实上，从长远来说，如果你想人们能使用和参与贡献，那么不仅使用git很有必要，而且，你也能够使用GitHub来管理维护你的项目。

这并不是夸大其词（尽管很多人会以它为嚼头）。然而，管它好与差，git和GitHub事实上已经成为了开源项目的实际标准了。GitHub是很多潜在的贡献者最想注册的和最熟悉的。所以，我深信，这并不是掉以轻心，而是深思熟虑的产物。

66号公路
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

新建一个README.md文件

在GitHub的代码仓库中，项目的描述是从项目的根目录中的:README.md文件获取的。这个文件应该包含下面几点：

  • 项目描述
  • 项目ReadTheDocs页面连接[@Lesus 注：请查看 工具与概念 ]
  • 一个用来显示当前构建状态的TravisCI按钮。
  • "Quickstart" 文档 (怎么快速安装和使用你的项目)
  • 若有非python依赖包，请列举它以及怎么安装它

它(README)读起来很傻的感觉，但是确是一个很重要的文件。它可能是你未来的用户或者贡献者首先从它了解你的项目的。花些时间来写一个清楚明白的说明和使用GFM（GitHubFlavoredMarkdown）来使它更好看。实际上，如果使用原生的Markdown来写文档不爽，那么可以在Github上使用立即预览来创建或者修改这个文件

我们还没触及列表中的第二和第三项（ReadTheDocs和TravisCI），你会在接下来看到。

66号公路
翻译于 2年前

0人顶

 

顶 翻译的不错哦!

使用"Issues"页

跟生活中的很多事情一样，你投入GitHub越多，你收获的越多。因为用户会使用GitHub的“Issues”页面反馈bug，使用该页面跟踪特性要求和改进是很有意义的。

更重要的是，它允许贡献者以一种优雅的方式看到：一个可能实现特性的列表以及自动化的管理合并请求流程（pull request）。GitHub的issues可以与评论、你项目里的其他issues及其他项目里的issues等交织，这使得“issues”页面成为一个有关所有bug修复、改进和新特性要求信息汇总的地方。

确保“Issues”及时更新，至少及时回应新的问题。作为一个贡献者，没有什么比修复bug后看着它呈现在issues页面并等待着被合并更有吸引力的了。

http://www.oschina.net/translate/open-sourcing-a-python-project-the-right-way
 

以正确的方式开源 Python 项目（转）的更多相关文章

  1. 以正确的方式开源 Python 项目

    以正确的方式开源 Python 项目 大多数Python开发者至少都写过一个像工具.脚本.库或框架等对其他人也有用的工具.我写这篇文章的目的是让现有Python代码的开源过程尽可能清 晰和无痛.我不是 ...

  2. 以正确的方式开源 Python 项目 - 技术翻译 - 开源中国社区

    以正确的方式开源 Python 项目 - 技术翻译 - 开源中国社区 以正确的方式开源 Python 项目 英文原文:Open Sourcing a Python Project the Right ...

  3. 精选 TOP45 值得学习的Python项目

    精选 TOP45 值得学习的Python项目 [导读]热门资源博客 Mybridge AI 比较了 18000 个关于 Python 的项目,并从中精选出 45 个最具竞争力的项目.我们进行了翻译,在 ...

  4. Python学习教程（十）精选 TOP45 值得学习的Python项目

    精选 TOP45 值得学习的Python项目 [导读]热门资源博客 Mybridge AI 比较了 18000 个关于 Python 的项目,并从中精选出 45 个最具竞争力的项目.我们进行了翻译,在 ...

  5. 创建成功的Python项目

    创建成功的Python项目 前端开发工具技巧介绍—Sublime篇 SEO在网页制作中的应用 观察者模式 使用D3制作图表 英文原文:Create successful Python projects ...

  6. Pull Request的正确打开方式（如何在GitHub上贡献开源项目）

    Pull Request的正确打开方式(如何在GitHub上贡献开源项目) GitHub的官方帮助如下: Fork A Repo: https://help.github.com/articles/f ...

  7. python项目内import其他内部package的模块的正确方法

    转载 :https://blog.csdn.net/u011089523/article/details/52931844 本文主要介绍如何在一个Python项目中,优雅的实现项目内各个package ...

  8. 开源you-get项目爬虫，以及基于python+selenium的自动测试利器

    写在前面 爬虫和自动测试,对于python来说是最合适不过也是最擅长的. 开源的项目也很多,例如you-get项目https://github.com/soimort/you-get.盗链和爬虫神器. ...

  9. [同步到 MaixPy3 文档] 使用 Python 编程入门开源硬件项目

    本文是给有一点 Python 基础但还想进一步深入的同学,有经验的开发者建议跳过. 前言 在写这篇案例系列的时候 junhuanchen 期望能够引导用户如何成为专业的开发者,不是只会调用代码就好,所 ...

随机推荐

  1. Xamarin之 环境错误集锦

    错误信息:   connection of the layout renderer failed.this may be caused by a misconfiguration of java .p ...

  2. WPF 图片浏览 伪3D效果

    原文:WPF 图片浏览 伪3D效果 首先上效果图: 因项目要求,需要把图片以"好看"."炫"的效果展示出来,特地研究了一下WPF关于3D方面的制作,奈何最终成果 ...

  3. gcc #define 学习记录

    //test.c #include <stdio.h> #include <stdlib.h> //字符串化运算符 #define EXPAND(name) ({ \ prin ...

  4. Android 混淆proguard的实现（图文）

    1.  在Eclipse中的project编译执行后,在文件夹bin以下有生成一些文件,当中classes.dex是未经过混淆生成的.而我们要混淆的话,就要又一次生成一个混淆过的classes.dex ...

  5. Android菜鸟的成长笔记（17）—— 再看Android中的Unbounded Service

    原文:Android菜鸟的成长笔记(17)-- 再看Android中的Unbounded Service 前面已经写过关于startService(Unbounded Service)的一篇文章:&l ...

  6. ios 多线程开发（一）简介

    简介 线程是在一个程序中并发的执行代码的方法之一.虽然有一些新的技术(operations, GCD)提供了更先进高效的并发实现,OS X和iOS同时也提供了创建和维护线程的接口. 这里将要介绍线程相 ...

  7. 计算机管理系统——VB与Excel联系

    今天爆震室管理系统--学生查看机器状态的时候发现有一个"导出到excel"的button.我去.感情还得跟excel表链接. 于是我咬碎了一地小银牙.一个下午都在查询vb与exce ...

  8. 安装numpy、nltk问题汇总

    系统环境是win7(64bit)+python3.4(64bit)+numpy1.82+vs2012 1.假设用sourceforge上编译好的32bit的exe安装,会提示'python versi ...

  9. vs2015基于VisualStudioOnline协同工作流程

    项目负责人登陆自己的vsonline新建项目就不多说了. 直接从邀请队友开始 项目负责人操作 被邀请的邮箱务必是可以登录visualstudio的邮箱 发送邀请后,被邀请人登陆自己的邮箱,查看邀请人发 ...

  10. IE8/IE9无法启用JavaScript怎么办

    在IE8/IE9 中,有些同学在浏览网页时,收到提示:“需要启用 JavaScript …”,并且会发现网页上某些功能不能用了,比如点击网页里的按钮没反应等等.这个是因为浏览器的JavaScript ...