1: setup.py 的目的

设置脚本是使用 Distutils 构建、分发和安装模块的所有活动的中心。其目的是正确安装软件。

如果你只想分发一个名为 foo 的模块，该模块包含在 foo.py 文件中，那么你的设置脚本可以像下面这样简单：

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
     )

要创建该模块的源代码发布版，需要创建一个包含上述代码的设置脚本 setup.py，并在终端运行此命令：

python setup.py sdist

sdist 将创建一个包含设置脚本 setup.py 和模块 foo.py 的归档文件（如 Unix 上的 tarball，Windows 上的 ZIP 文件）。归档文件将命名为 foo-1.0.tar.gz（或 .zip），并将解压缩到 foo-1.0 目录中。

如果最终用户希望安装 foo 模块，她只需下载 foo-1.0.tar.gz（或 .zip），解压缩，然后从foo-1.0 目录运行

python setup.py install

2: 在 setup.py 中使用源码控制元数据

setuptools_scm 是一个被官方认可的软件包，它可以使用 Git 或 Mercurial 元数据来确定软件包的版本号，并找到要包含在其中的 Python 软件包和软件包数据。

from setuptools import setup, find_packages

setup(
  setup_requires=['setuptools_scm'],
  use_scm_version=True,
  packages=find_packages(),
  include_package_data=True,
)

本例同时使用了这两种功能；如果只想使用 SCM 元数据来获取版本，请将对 find_packages() 的调用替换为手动软件包列表；如果只想使用软件包查找器，请移除 use_scm_version=True。

3: 在 python 软件包中添加命令行脚本

python 软件包中的命令行脚本很常见。你可以这样组织你的软件包，当用户安装软件包时，脚本就会出现在他们的路径上。

例如，在 greetings 包中有一个命令行脚本 hello_world.py。

greetings/
  greetings/
    __init__.py
    hello_world.py

您可以运行以下命令来运行该脚本

python greetings/greetings/hello_world.py

不过，如果您想这样运行的话：

hello_world.py

为此，您可以在 setup.py 中的 setup() 中添加脚本，如下所示：

from setuptools import setup

setup(
  name='greetings',
  scripts=['hello_world.py']
)

当你现在安装问候语软件包时，hello_world.py 将被添加到你的路径中。

另一种方法是添加一个入口点：

entry_points={'console_scripts': ['greetings=greetings.hello_world:main']}

这样，您只需像这样运行即可：

greetings

4: 添加安装选项

从前面的例子中可以看出，该脚本的基本用法是

python3 setup.py install

但还有更多选择，比如安装软件包后，无需重新安装即可修改代码并进行测试。这可以使用

python3 setup.py develop

如果要执行特定操作，如编译 Sphinx 文档或构建 fortran 代码，可以创建自己的选项：

cmdclasses = dict()

class BuildSphinx(Command):
  """Build Sphinx documentation."""
  description = 'Build Sphinx documentation'
  user_options = []

  def initialize_options(self):
    pass

  def finalize_options(self):
    pass

  def run(self):
    import sphinx
    sphinx.build_main(['setup.py', '-b', 'html', './doc', './doc/_build/html'])
    sphinx.build_main(['setup.py', '-b', 'man', './doc', './doc/_build/man'])

cmdclasses['build_sphinx'] = BuildSphinx

setup(
...
cmdclass=cmdclasses,
)

initialize_options 和 finalize_options 将在运行函数之前和之后执行，正如它们的名字所暗示的那样。

之后，你就可以调用你的选项了：

python setup.py build_sphinx