setuptools学习笔记(一) Oct. 11th, 2005 @ 10:06 am

setuptools是distutils的增强,可以更方便的创建和发布包,特别是对其他包有依赖的包更为方便。

在使用用setuptools发布的包时,用户不需要安装setuptools。在发布时甚至不需要提供完整的setuptools包,只需要提供一个7k大的.py文件,用户即可自动下载并安装setuptools。

功能:

  • 自动使用EasyInstall查找/下载/安装/升级依赖包。
  • 创建egg
  • 在包中包含数据文件
  • 自动包含源代码树中所有包
  • 自动包含相关文件,无须创建清单文件
  • 自动为main函数创建.exe文件(注意:和py2exe不同,这里创建出来的.exe文件仍然需要本地安装python才能使用)
  • 支持Pyrex,即在可以setup.py中列出.pyx文件,而最终用户无须安装Pyrex(只要你在发布源代码时包含Pyrex生成的C文件)。
  • 命令别名——可以给常用命令和选项创建项目专用、用户专用或者全系统有效的别名。
  • 支持PyPI上载——上载你的源代码包和eggs到PyPI
  • 以“开发模式”部署工程,使得该项目即在sys.path中,又可以直接修改源代码。
  • 用新命令或者setup()参数方便的扩展distutils,并为多个项目发布/重用这些扩展,而不用拷贝代码。
  • 在项目的setup脚本中简单的声明“entry points“,创建可以自动发现扩展的应用和框架。

开发者指南

安装setuptools

要安装setuptolls,首先下载 ez_setup.py 并运行之。它将自动下载并安装适合你的python版本的egg。

基本用法

下面是一个使用setuptools的最小的setup脚本:

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

在项目中使用setuptools不需要太多工作。只需要上面的脚本,这个项目就可以创建eggs、上载至PyPI、并可以自动包括setup.py所在目录下所有的包。

在向PyPI发布项目之前,应该给setup脚本增加一些信息,以帮助人们了解你的项目。进一步,也许你的项目需要一些依赖关系,可能还需要一些数据文件和脚本:

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 for upload to PyPI
    author = "Me",
    author_email = "me@example.com",
    description = "This is an Example Package",
    license = "PSF",
    keywords = "hello world example examples",
    url = "http://example.com/HelloWorld/"   # project home page, if any
    
    # could also include long_description, download_url, classifiers, etc.
)

新的和改动过的setup() Keywords

所有新的和改动过的keyword参数都是可选的:

package_data:
A dictionary mapping package names to lists of glob patterns. 这个功能 Python 2.4 带的distutils已经支持,而setuptools使得在Python 2.3 也能享受到。
zip_safe:
布尔量,表示项目是否可以安全的从一个zip文件安装并运行。
install_requires:
一个字符串或者字符串列表,描述项目依赖的其他发布。
entry_points:
一个字典,从entry point组名映射到一个表示entry point的字符串或字符串列表。Entry points用来支持动态发现服务或插件,也用来支持自动生成脚本。
extras_require:
一个字典,从extras(项目可选的功能)的名字映射到表示要支持该功能必须安装的其他包的字符串或字符串列表。
setup_requires:
一个字符串或字符串列表,表示运行setup脚本所需要的依赖包。setuptools将试图在进行setup的其他部分之前获取它们(甚至使用 EasyInstall下载它们)。这个参数在你使用一些distutils扩展时会用到,比如那些将setup()的参数转换成EGG-INFO元数据 文件的扩展。
namespace_packages:
一个字符串列表,表示项目的“名字空间包”。名字空间包是一个可能被分隔成数个项目发布的包。例如,Zope 3的 zope 包就是一个名字空间包,因为像zope.interface和zope.publisher这些子包可以独立发布。egg的运行时系统可以自动将这些子包 合并到一个父包下,只要你在项目中声明它包含这个名字空间包的任何一个子包,并且名字空间包的__init__.py文件不包含任何代码。
test_suite:
一个字符串,为一个unittest.TestCase子类(或者一个包含几个这种子类的模块,或者这种子类的一个方法)的名字,或者为一个返回 unittest.TestSuit的无参数函数的名字。指定这个参数将激活test命令,用来运行指定的测试,例如setup.py test。
eager_resources:
一个字符串列表,表明了需要被同时解压出来的资源名字。

使用find_packages()

使用setuptools.find_packages()可以大大减轻给setup()的packages参数赋值的工作量。

find_packages()有两个参数。一个是源目录,一个是需要排除在外的包名列表。源目录默认为setup脚本所在目录。某些项目将源目录 放在src或lib下,这时就需要指定"src"或"lib"为find_packages()的第一个参数。(这些项目也需要在setup()参数中指 定package_dir = {'': 'src'})

需要排除在外的包名列表可以包含通配符。例如, find_packages(exclude=["*.tests"]) 将排除所有以tests结尾的包。

自动脚本生成

通过在setup脚本中定义"entry points",setuptools将自动为你生成可执行脚本,无须你另外单独写一个执行脚本。例如,要创建两个控制台脚本foo和bar,以及一个GUI脚本baz,可以这样做:

setup(
    # other arguments here...
    entry_points = {
        'console_scripts': [
            'foo = my_package.some_module:main_func',
            'bar = other_module:some_func',
        ],
        'gui_scripts': [
            'baz = my_package_gui.start_func',
        ]
    }
)

在非Windows平台上安装时(用"setup.py install", "setup.py develop", 或者用EasyInstall),foo、bar和baz脚本将被安装,它们从指定的模块导入main_func和some_func。这些函数没有参 数,它的返回值作为sys.exit()的参数,因此可以返回错误代码或者在stderr上输出的信息。

在Windows下,会创建foo.exe、bar.exe和baz.exe,还有foo.py、bar.py和baz.pyw。

Tags: ,
::...
免责声明:
当前网页内容, 由 大妈 ZoomQuiet 使用工具: ScrapBook :: Firefox Extension 人工从互联网中收集并分享;
内容版权归原作者所有;
本人对内容的有效性/合法性不承担任何强制性责任.
若有不妥, 欢迎评注提醒:

或是邮件反馈可也:
askdama[AT]googlegroups.com


订阅 substack 体验古早写作:


点击注册~> 获得 100$ 体验券: DigitalOcean Referral Badge

关注公众号, 持续获得相关各种嗯哼:
zoomquiet


自怼圈/年度番新

DU22.4
关于 ~ DebugUself with DAMA ;-)
粤ICP备18025058号-1
公安备案号: 44049002000656 ...::