z3c.recipe.scripts 1.0.1

1.0.1 (2010-08-27)

修复

• 如果一个部分扩展了另一个部分，它应该能够覆盖它。

• 如果本地找不到，应该在buildout部分中查找allowed-eggs-from-site-packages。

1.0.0 (2010-08-23)

(无重大更改)

1.0.0b1 (2010-04-29)

初始公开版本。

脚本生成

生成基本脚本看起来几乎与使用zc.recipe.egg相同。

(注意，find-links和index值通常不需要；它们包括在此处以帮助使本文档作为测试成功运行。)

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = z3c.recipe.scripts
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))

>>> print system(buildout),
Installing demo.
Getting distribution for 'demo<0.3'.
Got demo 0.2.
Getting distribution for 'demoneeded'.
Got demoneeded 1.2c1.
Generated script '/sample-buildout/bin/demo'.

>>> print system(join(sample_buildout, 'bin', 'demo')),
2 2

解释器生成

与zc.recipe.egg一样，您可以通过提供“interpreter”选项生成具有上述默认脚本菜谱的解释器。此示例将创建入口点脚本和解释器。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = z3c.recipe.scripts
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... interpreter = py
... """ % dict(server=link_server))

>>> print system(buildout),
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Generated interpreter '/sample-buildout/bin/py'.

您还可以使用interpreter菜谱单独生成解释器。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = py
...
... [py]
... recipe = z3c.recipe.scripts:interpreter
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))

>>> print system(buildout),
Uninstalling demo.
Installing py.
Generated interpreter '/sample-buildout/bin/py'.

在这两种情况下，bin/py 脚本通过在PYTHONPATH中指定特殊路径后重启Python来工作。以下示例显示了UNIX版本；Windows版本实际上使用的是subprocess。

>>> cat(sample_buildout, 'bin', 'py') # doctest: +NORMALIZE_WHITESPACE
#!/usr/bin/python2.4 -S
<BLANKLINE>
import os
import sys
<BLANKLINE>
argv = [sys.executable] + sys.argv[1:]
environ = os.environ.copy()
path = '/sample-buildout/parts/py'
if environ.get('PYTHONPATH'):
    path = os.pathsep.join([path, environ['PYTHONPATH']])
environ['PYTHONPATH'] = path
os.execve(sys.executable, argv, environ)

该路径是一个包含两个文件的目录：我们自己的site.py和sitecustomize.py。site.py是基于Python的site.py修改的，负责设置我们的路径。sitecustomize.py负责运行提供的初始化代码。

>>> ls(sample_buildout, 'parts', 'py')
-  site.py
-  sitecustomize.py

以下是使用生成的解释器的示例。

>>> print system(join(sample_buildout, 'bin', 'py') +
...              ' -c "import sys, pprint; pprint.pprint(sys.path[-2:])"')
['/sample-buildout/eggs/demo-0.2-pyN.N.egg',
 '/sample-buildout/eggs/demoneeded-1.2c1-pyN.N.egg']
<BLANKLINE>

包括site-packages和sitecustomize

如上所述，这个配方支持包括site包。这有一些优点和一些严重的风险。

包括site包的一个典型原因是，在Python中安装一个或多个依赖项比使用buildout更容易。一些包，如lxml或Python PostgreSQL集成，其依赖项可以通过其他机制（如操作系统的包管理器）更容易地构建和/或安装。通过将一些核心包安装到Python的site-packages中，可以显著简化某些应用程序的安装。

然而，这样做有很大的风险。buildout的主要目标之一是提供可重复性。一些包（例如，著名的Python openid包之一）的行为会根据可用的包而改变。如果Python的curl绑定可用，这些可能被库所首选。如果安装了某个XML包，它可能被库所首选。这些隐藏的选择可能导致行为上的微小或重大差异。它们很少遇到的事实实际上可能使问题更糟：你可能会忘记这可能会成为一个问题，调试差异可能很困难。如果你允许site-packages包含在buildout中，而你使用的Python不是由你的应用程序精确管理（例如，它是系统Python），你将使自己面临这些可能性。不要忽视这些风险。

为了展示这些特性，我们需要使用具有一些额外路径的Python可执行文件与buildout一起使用，以显示include-site-packages；以及一个保证有sitecustomize模块的Python可执行文件，以显示exec-sitecustomize。我们将使用一个名为make_py的测试固定装置来创建一个。下面的os.environ更改将进入sitecustomize，而site_packages_path将在Python的路径中。

>>> py_path, site_packages_path = make_py(initialization='''\
... import os
... os.environ['zc.buildout'] = 'foo bar baz shazam'
... ''')
>>> print site_packages_path
/executable_buildout/site-packages

现在让我们看看include-site-packages。默认值为false，因此我们将将其设置为true。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = py
... executable = %(py_path)s
...
... [py]
... recipe = z3c.recipe.scripts:interpreter
... include-site-packages = true
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server, py_path=py_path))

>>> print system(buildout),
Uninstalling py.
Installing py.
Generated interpreter '/sample-buildout/bin/py'.

现在executable_buildout/site-packages包含在sys.path中。

>>> print system(join(sample_buildout, 'bin', 'py') +
...              ''' -c "import sys, pprint; pprint.pprint(sys.path)"''')
... # doctest: +ELLIPSIS
['',
 '/sample-buildout/parts/py',
 ...,
 '/sample-buildout/eggs/demo-0.2-pyN.N.egg',
 '/sample-buildout/eggs/demoneeded-1.2c1-pyN.N.egg',
 '/executable_buildout/eggs/setuptools-X-pyN.N.egg',
 '/executable_buildout/site-packages']
<BLANKLINE>

如上所述，allowed-eggs-from-site-packages选项让我们控制zc.buildout允许用于满足依赖关系的site-packages eggs。行为已在上述示例中描述（实现已在其他地方测试），因此我们在此仅查看一些简单和常见的用例。

有时你可能想允许site-packages可用，但你不想你的包在setup.py中使用它。例如，你可能正在编写一个应用程序，并希望依赖于系统对PostgreSQL代码的包装，但系统Python没有使用eggs来包装它，因此你需要分别管理这两个。在这种情况下，你可能不想使用site-packages中的任何eggs，但你想让它可用。在这种情况下，你可以使用allowed-eggs-from-site-packages与空值来确保任何egg都不会从site-packages中使用。

以下是一个示例。假设我们有一个Python，其中demo和demoneeded作为eggs安装在系统Python中。通常，它们将被用于满足依赖关系，因为allowed-eggs-from-site-packages默认值为“*”（允许任何包）。（我们使用空的find-links值来说明buildout不得在其他地方查找包。我们使用不同的eggs-directory进行隔离，这样从文档的其它部分获取的eggs不会影响此示例。）

>>> from zc.buildout.tests import create_sample_sys_install
>>> create_sample_sys_install(site_packages_path)
>>> import zc.buildout.easy_install
>>> zc.buildout.easy_install.clear_index_cache()

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = eggs
... eggs-directory = tmpeggs
... find-links =
...
... [primed_python]
... executable = %(py_path)s
...
... [eggs]
... recipe = z3c.recipe.scripts
... include-site-packages = true
... python = primed_python
... eggs = demoneeded
... ''' % globals())

>>> print system(buildout),
Creating directory '/sample-buildout/tmpeggs'.
Uninstalling py.
Installing eggs.

这会成功，从Python site-packages中获取demoneeded。

然而，当allowed-eggs-from-site-packages为空值时，demoneeded不允许从site-packages中获取，buildout会失败。

>>> zc.buildout.easy_install.clear_index_cache()
>>> rmdir('tmpeggs')
>>> write('buildout.cfg',
... '''
... [buildout]
... parts = eggs
... eggs-directory = tmpeggs
... find-links =
...
... [primed_python]
... executable = %(py_path)s
...
... [eggs]
... recipe = z3c.recipe.scripts
... include-site-packages = true
... python = primed_python
... allowed-eggs-from-site-packages =
... eggs = demoneeded
... ''' % globals())
>>> print system(buildout),
Creating directory '/sample-buildout/tmpeggs'.
Uninstalling eggs.
Installing eggs.
Couldn't find index page for 'demoneeded' (maybe misspelled?)
Getting distribution for 'demoneeded'.
While:
  Installing eggs.
  Getting distribution for 'demoneeded'.
Error: Couldn't find a distribution for 'demoneeded'.

如果本地未设置，include-sitepackages 和 allowed-eggs-from-site-packages 选项都可以从 buildout 部分获取。

请记住，您可以为 allowed-eggs-from-site-packages 选项提供多行，每行指定一个允许的包的白名单。允许使用通配符 (*) 和 ?。

接下来我们将使用 exec-sitecustomize 选项。它简单地将 Python 的底层 sitecustomize 模块（如果存在）复制到本地版本。make_py 调用中上面显示的 os.environ 变更将进入 sitecustomize。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = py
... executable = %(py_path)s
...
... [py]
... recipe = z3c.recipe.scripts:interpreter
... exec-sitecustomize = true
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server, py_path=py_path))

>>> print system(buildout),
Installing py.
Generated interpreter '/sample-buildout/bin/py'.

>>> cat(sample_buildout, 'parts', 'py', 'sitecustomize.py')
... # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
<BLANKLINE>
# The following is from
# /executable_buildout/parts/py/sitecustomize.py
...
import os
os.environ['zc.buildout'] = 'foo bar baz shazam'

>>> print system(join(sample_buildout, 'bin', 'py') +
...              ''' -c "import os; print os.environ['zc.buildout']"''')
foo bar baz shazam
<BLANKLINE>

如果本地未设置，它也将被 buildout 部分所尊重。

选项

现在我们将关注与 zc.recipe.egg 不同的剩余选项。

让我们首先看看 extends 选项。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo python
...
... [demo]
... recipe = z3c.recipe.scripts
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... initialization =
...     import os
...     os.environ['zc.buildout'] = 'sha boo bop bazoodle'
...
... [python]
... recipe = z3c.recipe.scripts:interpreter
... extends = demo
... initialization =
...     import os
...     os.environ['zc.buildout'] = 'foo bar baz shazam'
... """ % dict(server=link_server))

这使得指定一些初始化解释器（不同于脚本）并复制其他配置变得更容易。

现在让我们将其付诸实践。

>>> print system(buildout),
Uninstalling py.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Installing python.
Generated interpreter '/sample-buildout/bin/python'.

>>> print system(join(sample_buildout, 'bin', 'python') +
...              ' -c "import sys, pprint; pprint.pprint(sys.path[-2:])"')
['/sample-buildout/eggs/demo-0.2-pyN.N.egg',
 '/sample-buildout/eggs/demoneeded-1.2c1-pyN.N.egg']
<BLANKLINE>
>>> print system(join(sample_buildout, 'bin', 'python') +
...              ''' -c "import os; print os.environ['zc.buildout']"'''),
foo bar baz shazam

请注意，parts/py 目录已清理，并创建了 parts/python。

>>> ls(sample_buildout, 'parts')
d  buildout
d  demo
d  python

如果您只想对脚本进行初始化，而不是对解释器进行初始化，您可以使用 script-initialization。以下是一个演示。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = demo
...
... [demo]
... recipe = z3c.recipe.scripts
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... interpreter = py
... script-initialization =
...     print "Hi from the script"
... """ % dict(server=link_server))

>>> print system(buildout),
Uninstalling python.
Uninstalling demo.
Installing demo.
Generated script '/sample-buildout/bin/demo'.
Generated interpreter '/sample-buildout/bin/py'.

>>> print system(join(sample_buildout, 'bin', 'py') +
...              ''' -c "print 'Hi from the interpreter'"'''),
Hi from the interpreter

>>> print system(join(sample_buildout, 'bin', 'demo')),
Hi from the script
2 2

最后一个新选项是 name。这仅仅改变了解释器的名称，这样您就不必使用部分的名称。

>>> write(sample_buildout, 'buildout.cfg',
... """
... [buildout]
... parts = interpreter
...
... [interpreter]
... name = python2
... recipe = z3c.recipe.scripts:interpreter
... eggs = demo<0.3
... find-links = %(server)s
... index = %(server)s/index
... """ % dict(server=link_server))

>>> print system(buildout),
Uninstalling demo.
Installing interpreter.
Generated interpreter '/sample-buildout/bin/python2'.

>>> print system(join(sample_buildout, 'bin', 'python2') +
...              ' -c "print 42"')
42
<BLANKLINE>

其他选项都与 zc.recipe.egg 相同。