QingZhi's Blog

Persistence is not easy

0%

Python包管理之setup()函数详解

Posted on Edited on In , Views: Valine:

Python包管理.setup()详解

[PythonPackageGuide][https://packaging.python.org/guides/distributing-packages-using-setuptools/]

[Python包样例][https://github.com/pypa/sampleproject]

[子包、数据文件与依赖包参数情况][[http://www.wbh-doc.com.s3.amazonaws.com/Python-OpenSource-Project-Developer-Guide/appendix%20-%20setup%20script.html]

1. Setup() Args

参数详解

1.1 name

  • 项目名称

    • 命名规范：

      1
      2
      3
      Consist only of ASCII letters, digits, underscores (_), hyphens (-), and/or periods (.), and

      Start & end with an ASCII letter or digit.

    • PS：

      1
      Comparison of project names is case insensitive and treats arbitrarily-long runs of underscores, hyphens, and/or periods as equal.

      1. 大小写 不敏感

      2. 上述特殊符号（下划线、连字符、_、-、.）任意数量一致对待

        1
        2
        3
        4
        5
        #以下名称等价
        Cool-Stuff
        cool.stuff
        COOL_STUFF
        CoOl__-.-__sTuFF
        1
        <!-- more -->

        1.2 version

版本号，version = “1.1.0”

[版本框架选择][https://packaging.python.org/guides/distributing-packages-using-setuptools/#choosing-a-versioning-scheme]

1.3 description

具体包含三个参数

1
2
3
description='A sample Python project',
long_description=long_description,
long_description_content_type='text/x-rst',
  • 描述信息会在PyPI相关位置显示
  • long_description_content_type参数可选：
    1. text/plain 没有格式
    2. text/x-rst reST格式
    3. text/markdown markdown格式

1.4 url

主页地址

1
url='https://github.com/pypa/sampleproject',

1.5 author

提供作者信息

1
2
author='The Python Packaging Authority',
author_email='pypa-dev@googlegroups.com',

1.6 license

表明发布遵循的协议

1
license='MIT',
  1. 此字段不需要表明发布的协议
  2. 若采用标准协议则采用：classifiers字段
  3. license字段通常用于指定与常用协议差异的部分，故此字段不常用

1.7 classifier

按照内部成分对项目进行分类

[分类详细文档][https://pypi.org/classifiers/]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
classifiers=[
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    'Development Status :: 3 - Alpha',
    # Indicate who your project is intended for
    'Intended Audience :: Developers',
    'Topic :: Software Development :: Build Tools',
    # Pick your license as you wish (should match "license" above)
     'License :: OSI Approved :: MIT License',
    # Specify the Python versions you support here. In particular, ensure
    # that you indicate whether you support Python 2, Python 3 or both.
    'Programming Language :: Python :: 2',
    'Programming Language :: Python :: 2.6',
    'Programming Language :: Python :: 2.7',
    'Programming Language :: Python :: 3',
    'Programming Language :: Python :: 3.2',
    'Programming Language :: Python :: 3.3',
    'Programming Language :: Python :: 3.4',
]
  1. 上面内容可以看到，这里可以指定Python版本，但其并不能用于限制Python版本。只能用于在PyPI上面浏览时显示，版本限制需要用 python_requires 参数指定。

1.8 keywords

列出项目关键字

1
keywords='sample setuptools development',

1.9 project_urls

列出相关url地址

1
2
3
4
5
6
7
8
project_urls={
    'Documentation': 'https://packaging.python.org/tutorials/distributing-packages/',
    'Funding': 'https://donate.pypi.org',
    'Say Thanks!': 'http://saythanks.io/to/example',
    'Source': 'https://github.com/pypa/sampleproject/',
    'Tracker': 'https://github.com/pypa/sampleproject/issues',
},

1.10 packages

设置项目中采用的所有包，包含其子包

1
2
packages=find_packages(include=['sample', 'sample.*']),

  • 可手动指定
  • 可利用setuptools.find_packages()自动寻找
    • 其方法可使用include字段找到指定的位置
    • 其方法可使用exclude字段排除指定的位置

1.11 py_modules

用于指定非包内的模块

1
py_modules=["six"],

1.12 install_requires

指定项目启动所需要的依赖

[install_requiresVSrequirements files][https://packaging.python.org/discussions/install-requires-vs-requirements/#install-requires-vs-requirements-files]

1
install_requires=['peppercorn'],

1.13 python_requires

指定可运行Python的版本

1
2
3
4
5
6
7
#if your package is for Python 3+ only, write:
python_requires='>=3',
#If your package is for Python 3.3 and up but you’re not willing to commit to Python 4 support yet, write:
python_requires='~=3.3',
#If your package is for Python 2.6, 2.7, and all versions of Python 3 starting with 3.3, write:
python_requires='>=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4',

1.14 package_data

指定包数据文件，包数据文件指不在包内的与项目相关的数据文件。比如字典。

[包文件详解][https://setuptools.readthedocs.io/en/latest/setuptools.html#including-data-files]

1
2
3
package_data={
    'sample': ['package_data.dat'],
},

1.15 data_files

data_files也用于指定文件，但是同package_data不同的是其用于指定不在包内的数据文件。

1
data_files=[('my_data', ['data/data_file'])],

1.16 scripts

用于指定安装的脚本，但目前并不推荐使用

1.17 entry_points

Use this keyword to specify any plugins that your project provides for any named entry points that may be defined by your project or others that you depend on..

没看懂

[文档详解][https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins]

官方文档没看懂，可以看[博客][http://blog.luoyuanhang.com/2016/03/25/Python-%E5%88%86%E5%8F%91%E5%B7%A5%E5%85%B7%E5%88%9D%E6%8E%A2%E4%B9%8B-setuptools-%E8%BF%9B%E9%98%B6/

entry_points 是一个字典，从entry point组名映射道一个表示entry point的字符串或字符串列表。Entry points是用来支持动态发现服务和插件的，也用来支持自动生成脚本。

1.18 console_scripts

entry_points内部参数，用于生成脚本文件
用于在系统路径下生成可执行脚本。

[官方文档详解][https://setuptools.readthedocs.io/en/latest/setuptools.html#automatic-script-creation]

1
2
3
4
5
entry_points={
    'console_scripts': [
        'sample=sample:main',
    ],
},