用Setuptools构建和分发程序包

目录

• 使用Setuptools构建和分发软件包
  • 开发人员指南
    • 安装setuptools
    • 基本使用
    • 指定项目的版本
    • 新增和更改的setup()关键字
    • 包括数据文件
    • 参考示例

使用Setuptools构建和分发软件包

参考官方文档翻译

开发人员指南

安装setuptools

安装最新版本的setuptools：

python3 -m pip install --upgrade setuptools

基本使用

引入setuptools基本使用

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
)

要生成源代码分发，只需调用：

setup.py sdist

随着项目的增大将会包括一些依赖项，以及一些数据文件和脚本：

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
    scripts=["say_hello.py"],

    # Project uses reStructuredText, so ensure that the docutils get
    # installed or upgraded on the target machine
    install_requires=["docutils>=0.3"],

    package_data={
        # If any package contains *.txt or *.rst files, include them:
        "": ["*.txt", "*.rst"],
        # And include any *.msg files found in the "hello" package, too:
        "hello": ["*.msg"],
    },

    # metadata to display on PyPI
    author="Me",
    author_email="me@example.com",
    description="This is an Example Package",
    keywords="hello world example examples",
    url="http://example.com/HelloWorld/",   # project home page, if any
    project_urls={
        "Bug Tracker": "https://bugs.example.com/HelloWorld/",
        "Documentation": "https://docs.example.com/HelloWorld/",
        "Source Code": "https://code.example.com/HelloWorld/",
    },
    classifiers=[
        "License :: OSI Approved :: Python Software Foundation License"
    ]

    # could also include long_description, download_url, etc.
)

下面我们将解释大多数这些setup() 参数的作用（元数据除外），以及在您自己的项目中使用它们的各种方式

指定项目的版本

官方的划分比较多，简洁的说一下：

版本：发行号+标签（交替出现）

发行号：2.1.0 （简单理解格式）

标签：类似alpha，beta， a，c，dev等，例如：一个不稳定的预发行版本，建议：2.1.0.a9，如果需要加入日期建议使用-，例如：2.1.0.9-20190604

可以使用该pkg_resources.parse_version()功能比较不同的版本号：

>>> from pkg_resources import parse_version
>>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
True
>>> parse_version("2.1-rc2") < parse_version("2.1")
True
>>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
True

新增和更改的setup()关键字

include_package_data：如果设置为True，setuptools则表示将在MANIFEST.in文件指定的包目录中自动包含找到的所有数据文件。

exclude_package_data：将包名称映射到应该从包目录中排除的全局模式列表的字典

package_data：字典将包名称映射到全局模式列表。

zip_safe：一个布尔值（True或False）标志，指定是否可以安全地安装该项目并从zip文件运行该项目。如果未提供此参数，则bdist_egg每次构建鸡蛋时，该命令将必须分析项目的所有内容以查找可能的问题。

install_requires：一个字符串或字符串列表，指定在安装此版本时还需要安装其他发行版。

entry_points：字典将入口点组名称映射到定义入口点的字符串或字符串列表。

extras_require：字典将名称“ extras”（项目的可选功能）映射到字符串或字符串列表的字典，用于指定必须安装哪些其他发行版来支持这些功能。

python_requires：python版本设置。

版本号大于等于3.3，但是不能超过4
python_requires='~=3.3',
支持2.6 2.7以及所有以3.3开头的Python 3版本
python_requires='>=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4',

setup_requires：安装脚本执行时需要依赖的分发包，主要用于构建过程，注意，这里列出的包不会自动安装，如果需要，同时要在install_requires中指定。

dependency_links：满足依赖性时要搜索的URL的字符串列表

namespace_packages：命名项目的“命名空间包”的字符串列表

包括数据文件

对包含的文件进行更细粒度的控制（例如，如果您的软件包目录中有文档文件，并希望将其排除在安装范围之外），则还可以使用package_data关键字

setup.py
src/
    mypkg/
        __init__.py
        mypkg.txt
        data/
            somefile.dat
            otherdata.dat

from setuptools import setup, find_packages
setup(
    ...
    packages=find_packages("src"),  # include all packages under src
    package_dir={"": "src"},   # tell distutils packages are under src

    package_data={
        # If any package contains *.txt files, include them:
        "": ["*.txt"],
        # And include any *.dat files found in the "data" subdirectory
        # of the "mypkg" package, also:
        "mypkg": ["data/*.dat"],
    }
)

如果想去掉readm.md等文件：

from setuptools import setup, find_packages
setup(
    ...
    packages=find_packages("src"),  # include all packages under src
    package_dir={"": "src"},   # tell distutils packages are under src

    include_package_data=True,    # include everything in source control

    # ...but exclude README.txt from all packages
    exclude_package_data={"": ["README.txt"]},
)

参考示例

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

from setuptools import setup, find_packages

"""
setuptools使用文档: https://setuptools.readthedocs.io/en/latest/setuptools.html

生成源码发布包, 在灵犀工程目录(LingXi/)下执行: python3 setup.py sdist
"""

setup(
    name="LingXi",
    version="1.5.0",  # 发布前注意将此处改为本次发布的版本号
    packages=find_packages(),

    # Project uses reStructuredText, so ensure that the docutils get
    # installed or upgraded on the target machine
    # install_requires=['docutils>=0.3'],

    package_data={
        # If any package contains *.txt or *.rst files, include them:
        '': ['*.txt', '*.otf', '*.ttc', '*.sh', '*.css', '*.js', '*.ttf', '*.eot', '*.svg', '*.woff'],
        'perception': ['templates/*',
                       'blocks/econet/*.yaml',
                       'compiled/Makefile',
                       'compiled/center_net/_cpools/src/*.cpp', 'compiled/center_net/_nms/*.c',
                       'compiled/center_net/_nms//pointer/resnet50/*',
                       'modules/meter_recognition_v2/cfgs/*',
                       'modules/meter_recognition_v2/cfgs/resnet50/*',
                       ],
        'services': ['*.sh',
                     'lingxi/static/js/*.js', 'lingxi/static/audio/*.wav',
                     'lingxi/static/docs/*.pdf', 'lingxi/static/imgs/*.jpg',
                     'lingxi/static/*.html', 'lingxi/templates/*.html',
                     'lingxi/static/*.css', 'lingxi/static/*.ico']
    },

    # metadata to display on PyPI
    author="",
    author_email="",
    maintainer="",
    maintainer_email="{dzp, gy, xkk}@kilox.cn",
    description="分析系统",
    keywords="",
    url="",
    license="GPLv3",
    platforms="UNIX",
    long_description="README.md, CHANGELOG.md, LICENSE",
    install_requires=['opencv-python', 'numpy', 'Pillow', 'six', 'torch', 'pytz', 'waitress', 'wtforms', 'flask',
                      'torchvision', 'termcolor', 'scipy', 'matplotlib', 'imageio', 'requests', 'soundfile', 'librosa',
                      'face_recognition', 'scikit-image', 'imutils', 'tensorflow', 'mmcv', 'pycocotools', 'tabulate',
                      'psutil', 'py-cpuinfo', 'PyYAML', 'fvcore']
)