Merge lp:~gary/zc.buildout/python-support-5-initial-egg-control into lp:zc.buildout

[Gary Poster]

[Gary Poster (gary)]

This branch builds the infrastructure in easy_install that is needed for z3c.recipe.scripts to control what packages from site-packages can be used to fulfill setup.py dependencies. Hooking it up comes in the subsequent branch, ~gary/zc.buildout/python-support-6-egg-control .

This branch merged the remaining work from my previous zc.buildout effort. Much of this branch has therefore been reviewed before.

In the previous branch, I had a flag called "include-site-packages" (or "include_site_packages" depending on whether it is a config file or Python) for behavior related to what I had been calling "add-site-packages" (or "add_site_packages") in the more recent effort. I settled on "include-site-packages"/"include_site_packages" because it seemed to me to better describe the behavior of the flag, particularly in the case of the zc.buildout.easy_install.include_site_packages function.

My addition and use of _get_version_info is new to this branch. It seems OK to me, but I questioned it, and would welcome other ideas. You'll notice that previously buildout indiscriminately added the buildout and setuptools paths. I felt that being more careful was warranted, but maybe I'm wrong.

I noticed a couple of intermittent test failures during the development of this branch. I got them to go away with the use of get_installer_values and set_installer_values for careful teardowns of various test changes. This work is also new.

That's it. Thank you.

Gary

[Gary Poster (gary)]

Note also that I moved _get_system_paths to the top of easy_install.py because it was now used by both the Installer and sitepackage_safe_scripts. It is not new code.

[Francis J. Lacoste (flacoste)]

Hi Gary,

My only comment is about some API incompatible changes you made. Not sure it's a problem or not. Otherwise, all fine.

> === modified file 'src/zc/buildout/easy_install.py'

> def use_dependency_links(setting=None):
> old = Installer._use_dependency_links
> if setting is not None:
> @@ -858,9 +1014,13 @@
> links=(), index=None,
> executable=sys.executable, always_unzip=None,
> path=None, working_set=None, newest=True, versions=None,
> - use_dependency_links=None, allow_hosts=('*',)):
> + use_dependency_links=None, include_site_packages=None,
> + allowed_eggs_from_site_packages=None, allow_hosts=('*',)):
> installer = Installer(dest, links, index, executable, always_unzip, path,
> newest, versions, use_dependency_links,
> + include_site_packages=include_site_packages,
> + allowed_eggs_from_site_packages=
> + allowed_eggs_from_site_packages,
> allow_hosts=allow_hosts)
> return installer.install(specs, working_set)
>
> @@ -868,9 +1028,14 @@
> def build(spec, dest, build_ext,
> links=(), index=None,
> executable=sys.executable,
> - path=None, newest=True, versions=None, allow_hosts=('*',)):
> + path=None, newest=True, versions=None, include_site_packages=None,
> + allowed_eggs_from_site_packages=None, allow_hosts=('*',)):
> installer = Installer(dest, links, index, executable, True, path, newest,
> - versions, allow_hosts=allow_hosts)
> + versions,
> + include_site_packages=include_site_packages,
> + allowed_eggs_from_site_packages=
> + allowed_eggs_from_site_packages,
> + allow_hosts=allow_hosts)
> return installer.build(spec, build_ext)
>

Should we care about API compatibility in these two functions? You added
parameters before allow_hosts. Theorically, this breaks API compatibility for
call sites passing things by parameters. Arguably a bad idea with such a
signature, but it's your call :-)

review: Approve

[lp:~gary/zc.buildout/python-support-5-initial-egg-control]

555. By Gary Poster on 2010-02-24

be a better backwards-compatibilty citizen

[Gary Poster (gary)]

Yeah, what I did was on purpose and after consideration, but maybe wrong all the same. :-) I changed it.

Thanks!

Unmerged revisions

555. By Gary Poster on 2010-02-24

be a better backwards-compatibilty citizen

554. By Gary Poster on 2010-02-23

merge from gary-4

553. By Gary Poster on 2010-02-23

merge from gary-4

552. By Gary Poster on 2010-02-22

settle on "include-site-packages" and migrate all variations of "add-site-packages" to that spelling.

551. By Gary Poster on 2010-02-22

merge from gary-4

550. By Gary Poster on 2010-02-19

support limiting packages from site-packages

549. By Gary Poster on 2010-02-17

propagate merge from gary-3 <- gary-2 <- gary-1 <- trunk

548. By gary on 2010-02-13

fix some tests on other Python versions

547. By gary on 2010-02-12

revert attempt to skip some of the pkg_resources dance: it caused me trouble.

546. By gary on 2010-02-12

simplify resulting code a bit more and try again to remove warnings

=== added file '.bzrignore'
--- .bzrignore	1970-01-01 00:00:00 +0000
+++ .bzrignore	2010-02-24 23:22:13 +0000
@@ -0,0 +1,9 @@
+.installed.cfg
+bin
+build
+develop-eggs
+eggs
+parts
+src/zc.buildout.egg-info
+z3c.recipe.scripts_/src/z3c.recipe.scripts.egg-info
+zc.recipe.egg_/src/zc.recipe.egg.egg-info

=== modified file 'src/zc/buildout/easy_install.py'
--- src/zc/buildout/easy_install.py	2010-02-24 23:22:13 +0000
+++ src/zc/buildout/easy_install.py	2010-02-24 23:22:13 +0000
@@ -19,6 +19,7 @@
 """
 
 import distutils.errors
+import fnmatch
 import glob
 import logging
 import os
@@ -68,6 +69,64 @@
 if os.path.normpath(setuptools_loc) != os.path.normpath(buildout_loc):
     buildout_and_setuptools_path.append(buildout_loc)
 
+def _get_system_paths(executable):
+    """Return lists of standard lib and site paths for executable.
+    """
+    # We want to get a list of the site packages, which is not easy.
+    # The canonical way to do this is to use
+    # distutils.sysconfig.get_python_lib(), but that only returns a
+    # single path, which does not reflect reality for many system
+    # Pythons, which have multiple additions.  Instead, we start Python
+    # with -S, which does not import site.py and set up the extra paths
+    # like site-packages or (Ubuntu/Debian) dist-packages and
+    # python-support. We then compare that sys.path with the normal one
+    # (minus user packages if this is Python 2.6, because we don't
+    # support those (yet?).  The set of the normal one minus the set of
+    # the ones in ``python -S`` is the set of packages that are
+    # effectively site-packages.
+    #
+    # The given executable might not be the current executable, so it is
+    # appropriate to do another subprocess to figure out what the
+    # additional site-package paths are. Moreover, even if this
+    # executable *is* the current executable, this code might be run in
+    # the context of code that has manipulated the sys.path--for
+    # instance, to add local zc.buildout or setuptools eggs.
+    def get_sys_path(*args, **kwargs):
+        cmd = [executable]
+        cmd.extend(args)
+        cmd.extend([
+            "-c", "import sys, os;"
+            "print repr([os.path.normpath(p) for p in sys.path if p])"])
+        # Windows needs some (as yet to be determined) part of the real env.
+        env = os.environ.copy()
+        env.update(kwargs)
+        _proc = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
+        stdout, stderr = _proc.communicate();
+        if _proc.returncode:
+            raise RuntimeError(
+                'error trying to get system packages:\n%s' % (stderr,))
+        res = eval(stdout.strip())
+        try:
+            res.remove('.')
+        except ValueError:
+            pass
+        return res
+    stdlib = get_sys_path('-S') # stdlib only
+    no_user_paths = get_sys_path(PYTHONNOUSERSITE='x')
+    site_paths = [p for p in no_user_paths if p not in stdlib]
+    return (stdlib, site_paths)
+
+def _get_version_info(executable):
+    cmd = [executable, '-Sc', 'import sys; print repr(sys.version_info)']
+    _proc = subprocess.Popen(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    stdout, stderr = _proc.communicate();
+    if _proc.returncode:
+        raise RuntimeError(
+            'error trying to get system packages:\n%s' % (stderr,))
+    return eval(stdout.strip())
+
 
 class IncompatibleVersionError(zc.buildout.UserError):
     """A specified version is incompatible with a given requirement.
@@ -110,7 +169,12 @@
 
 
 _indexes = {}
-def _get_index(executable, index_url, find_links, allow_hosts=('*',)):
+def _get_index(executable, index_url, find_links, allow_hosts=('*',),
+               path=None):
+    # If path is None, the index will use sys.path.  If you provide an empty
+    # path ([]), it will complain uselessly about missing index pages for
+    # packages found in the paths that you expect to use.  Therefore, this path
+    # is always the same as the _env path in the Installer.
     key = executable, index_url, tuple(find_links)
     index = _indexes.get(key)
     if index is not None:
@@ -119,7 +183,8 @@
     if index_url is None:
         index_url = default_index_url
     index = AllowHostsPackageIndex(
-        index_url, hosts=allow_hosts, python=_get_version(executable)
+        index_url, hosts=allow_hosts, search_path=path,
+        python=_get_version(executable)
         )
 
     if find_links:
@@ -216,6 +281,8 @@
     _use_dependency_links = True
     _allow_picked_versions = True
     _always_unzip = False
+    _include_site_packages = True
+    _allowed_eggs_from_site_packages = ('*',)
 
     def __init__(self,
                  dest=None,
@@ -227,7 +294,9 @@
                  newest=True,
                  versions=None,
                  use_dependency_links=None,
-                 allow_hosts=('*',)
+                 allow_hosts=('*',),
+                 include_site_packages=None,
+                 allowed_eggs_from_site_packages=None
                  ):
         self._dest = dest
         self._allow_hosts = allow_hosts
@@ -249,7 +318,28 @@
         self._executable = executable
         if always_unzip is not None:
             self._always_unzip = always_unzip
-        path = (path and path[:] or []) + buildout_and_setuptools_path
+        path = (path and path[:] or [])
+        if include_site_packages is not None:
+            self._include_site_packages = include_site_packages
+        if allowed_eggs_from_site_packages is not None:
+            self._allowed_eggs_from_site_packages = tuple(
+                allowed_eggs_from_site_packages)
+        stdlib, self._site_packages = _get_system_paths(executable)
+        version_info = _get_version_info(executable)
+        if version_info == sys.version_info:
+            # Maybe we can add the buildout and setuptools path.  If we
+            # are including site_packages, we only have to include the extra
+            # bits here, so we don't duplicate.  On the other hand, if we
+            # are not including site_packages, we only want to include the
+            # parts that are not in site_packages, so the code is the same.
+            path.extend(
+                set(buildout_and_setuptools_path).difference(
+                    self._site_packages))
+        if self._include_site_packages:
+            path.extend(self._site_packages)
+        # else we could try to still include the buildout_and_setuptools_path
+        # if the elements are not in site_packages, but we're not bothering
+        # with this optimization for now, in the name of code simplicity.
         if dest is not None and dest not in path:
             path.insert(0, dest)
         self._path = path
@@ -258,13 +348,42 @@
         self._newest = newest
         self._env = pkg_resources.Environment(path,
                                               python=_get_version(executable))
-        self._index = _get_index(executable, index, links, self._allow_hosts)
+        self._index = _get_index(executable, index, links, self._allow_hosts,
+                                 self._path)
 
         if versions is not None:
             self._versions = versions
 
+    _allowed_eggs_from_site_packages_regex = None
+    def allow_site_package_egg(self, name):
+        if (not self._include_site_packages or
+            not self._allowed_eggs_from_site_packages):
+            # If the answer is a blanket "no," perform a shortcut.
+            return False
+        if self._allowed_eggs_from_site_packages_regex is None:
+            pattern = '(%s)' % (
+                '|'.join(
+                    fnmatch.translate(name)
+                    for name in self._allowed_eggs_from_site_packages),
+                )
+            self._allowed_eggs_from_site_packages_regex = re.compile(pattern)
+        return bool(self._allowed_eggs_from_site_packages_regex.match(name))
+
     def _satisfied(self, req, source=None):
-        dists = [dist for dist in self._env[req.project_name] if dist in req]
+        # We get all distributions that match the given requirement.  If we are
+        # not supposed to include site-packages for the given egg, we also
+        # filter those out. Even if include_site_packages is False and so we
+        # have excluded site packages from the _env's paths (see
+        # Installer.__init__), we need to do the filtering here because an
+        # .egg-link, such as one for setuptools or zc.buildout installed by
+        # zc.buildout.buildout.Buildout.bootstrap, can indirectly include a
+        # path in our _site_packages.
+        dists = [dist for dist in self._env[req.project_name] if (
+                    dist in req and (
+                        dist.location not in self._site_packages or
+                        self.allow_site_package_egg(dist.project_name))
+                    )
+                ]
         if not dists:
             logger.debug('We have no distributions for %s that satisfies %r.',
                          req.project_name, str(req))
@@ -465,14 +584,22 @@
             # Nothing is available.
             return None
 
-        # Filter the available dists for the requirement and source flag
-        dists = [dist for dist in index[requirement.project_name]
-                 if ((dist in requirement)
-                     and
-                     ((not source) or
-                      (dist.precedence == pkg_resources.SOURCE_DIST)
-                      )
-                     )
+        # Filter the available dists for the requirement and source flag.  If
+        # we are not supposed to include site-packages for the given egg, we
+        # also filter those out. Even if include_site_packages is False and so
+        # we have excluded site packages from the _env's paths (see
+        # Installer.__init__), we need to do the filtering here because an
+        # .egg-link, such as one for setuptools or zc.buildout installed by
+        # zc.buildout.buildout.Buildout.bootstrap, can indirectly include a
+        # path in our _site_packages.
+        dists = [dist for dist in index[requirement.project_name] if (
+                    dist in requirement and (
+                        dist.location not in self._site_packages or
+                        self.allow_site_package_egg(dist.project_name))
+                    and (
+                        (not source) or
+                        (dist.precedence == pkg_resources.SOURCE_DIST))
+                    )
                  ]
 
         # If we prefer final dists, filter for final and use the
@@ -632,7 +759,7 @@
                         self._links.append(link)
                         self._index = _get_index(self._executable,
                                                  self._index_url, self._links,
-                                                 self._allow_hosts)
+                                                 self._allow_hosts, self._path)
 
         for dist in dists:
             # Check whether we picked a version and, if we did, report it:
@@ -713,35 +840,52 @@
                 self._maybe_add_setuptools(ws, dist)
 
         # OK, we have the requested distributions and they're in the working
-        # set, but they may have unmet requirements.  We'll simply keep
-        # trying to resolve requirements, adding missing requirements as they
-        # are reported.
-        #
-        # Note that we don't pass in the environment, because we want
+        # set, but they may have unmet requirements.  We'll resolve these
+        # requirements. This is code modified from
+        # pkg_resources.WorkingSet.resolve.  We can't reuse that code directly
+        # because we have to constrain our requirements (see
+        # versions_section_ignored_for_dependency_in_favor_of_site_packages in
+        # zc.buildout.tests).
+        requirements.reverse() # Set up the stack.
+        processed = {}  # This is a set of processed requirements.
+        best = {}  # This is a mapping of key -> dist.
+        # Note that we don't use the existing environment, because we want
         # to look for new eggs unless what we have is the best that
         # matches the requirement.
-        while 1:
-            try:
-                ws.resolve(requirements)
-            except pkg_resources.DistributionNotFound, err:
-                [requirement] = err
-                requirement = self._constrain(requirement)
-                if destination:
-                    logger.debug('Getting required %r', str(requirement))
-                else:
-                    logger.debug('Adding required %r', str(requirement))
-                _log_requirement(ws, requirement)
-
-                for dist in self._get_dist(requirement, ws, self._always_unzip
-                                           ):
-
-                    ws.add(dist)
-                    self._maybe_add_setuptools(ws, dist)
-            except pkg_resources.VersionConflict, err:
-                raise VersionConflict(err, ws)
-            else:
-                break
-
+        env = pkg_resources.Environment(ws.entries)
+        while requirements:
+            # Process dependencies breadth-first.
+            req = self._constrain(requirements.pop(0))
+            if req in processed:
+                # Ignore cyclic or redundant dependencies.
+                continue
+            dist = best.get(req.key)
+            if dist is None:
+                # Find the best distribution and add it to the map.
+                dist = ws.by_key.get(req.key)
+                if dist is None:
+                    try:
+                        dist = best[req.key] = env.best_match(req, ws)
+                    except pkg_resources.VersionConflict, err:
+                        raise VersionConflict(err, ws)
+                    if dist is None:
+                        if destination:
+                            logger.debug('Getting required %r', str(req))
+                        else:
+                            logger.debug('Adding required %r', str(req))
+                        _log_requirement(ws, req)
+                        for dist in self._get_dist(req,
+                                                   ws, self._always_unzip):
+                            ws.add(dist)
+                            self._maybe_add_setuptools(ws, dist)
+            if dist not in req:
+                # Oops, the "best" so far conflicts with a dependency.
+                raise VersionConflict(
+                    pkg_resources.VersionConflict(dist, req), ws)
+            requirements.extend(dist.requires(req.extras)[::-1])
+            processed[req] = True
+            if dist.location in self._site_packages:
+                logger.debug('Egg from site-packages: %s', dist)
         return ws
 
     def build(self, spec, build_ext):
@@ -836,6 +980,18 @@
         Installer._prefer_final = bool(setting)
     return old
 
+def include_site_packages(setting=None):
+    old = Installer._include_site_packages
+    if setting is not None:
+        Installer._include_site_packages = bool(setting)
+    return old
+
+def allowed_eggs_from_site_packages(setting=None):
+    old = Installer._allowed_eggs_from_site_packages
+    if setting is not None:
+        Installer._allowed_eggs_from_site_packages = tuple(setting)
+    return old
+
 def use_dependency_links(setting=None):
     old = Installer._use_dependency_links
     if setting is not None:
@@ -858,19 +1014,27 @@
             links=(), index=None,
             executable=sys.executable, always_unzip=None,
             path=None, working_set=None, newest=True, versions=None,
-            use_dependency_links=None, allow_hosts=('*',)):
+            use_dependency_links=None, allow_hosts=('*',),
+            include_site_packages=None, allowed_eggs_from_site_packages=None):
     installer = Installer(dest, links, index, executable, always_unzip, path,
                           newest, versions, use_dependency_links,
-                          allow_hosts=allow_hosts)
+                          allow_hosts=allow_hosts,
+                          include_site_packages=include_site_packages,
+                          allowed_eggs_from_site_packages=
+                            allowed_eggs_from_site_packages)
     return installer.install(specs, working_set)
 
 
 def build(spec, dest, build_ext,
           links=(), index=None,
           executable=sys.executable,
-          path=None, newest=True, versions=None, allow_hosts=('*',)):
+          path=None, newest=True, versions=None, allow_hosts=('*',),
+          include_site_packages=None, allowed_eggs_from_site_packages=None):
     installer = Installer(dest, links, index, executable, True, path, newest,
-                          versions, allow_hosts=allow_hosts)
+                          versions, allow_hosts=allow_hosts,
+                          include_site_packages=include_site_packages,
+                          allowed_eggs_from_site_packages=
+                            allowed_eggs_from_site_packages)
     return installer.build(spec, build_ext)
 
 
@@ -965,9 +1129,12 @@
         undo.reverse()
         [f() for f in undo]
 
-
-def working_set(specs, executable, path):
-    return install(specs, None, executable=executable, path=path)
+def working_set(specs, executable, path, include_site_packages=None,
+                allowed_eggs_from_site_packages=None):
+    return install(
+        specs, None, executable=executable, path=path,
+        include_site_packages=include_site_packages,
+        allowed_eggs_from_site_packages=allowed_eggs_from_site_packages)
 
 ############################################################################
 # Script generation functions
@@ -1002,7 +1169,7 @@
 def sitepackage_safe_scripts(
     dest, working_set, executable, site_py_dest,
     reqs=(), scripts=None, interpreter=None, extra_paths=(),
-    initialization='', add_site_packages=False, exec_sitecustomize=False,
+    initialization='', include_site_packages=False, exec_sitecustomize=False,
     relative_paths=False, script_arguments='', script_initialization=''):
     """Generate scripts and/or an interpreter from a system Python.
 
@@ -1016,7 +1183,7 @@
         site_py_dest, executable, initialization, exec_sitecustomize))
     generated.append(_generate_site(
         site_py_dest, working_set, executable, extra_paths,
-        add_site_packages, relative_paths))
+        include_site_packages, relative_paths))
     script_initialization = (
         '\nimport site # imports custom buildout-generated site.py\n%s' % (
             script_initialization,))
@@ -1301,54 +1468,6 @@
 
 # These are used only by the newer ``sitepackage_safe_scripts`` function.
 
-def _get_system_paths(executable):
-    """Return lists of standard lib and site paths for executable.
-    """
-    # We want to get a list of the site packages, which is not easy.
-    # The canonical way to do this is to use
-    # distutils.sysconfig.get_python_lib(), but that only returns a
-    # single path, which does not reflect reality for many system
-    # Pythons, which have multiple additions.  Instead, we start Python
-    # with -S, which does not import site.py and set up the extra paths
-    # like site-packages or (Ubuntu/Debian) dist-packages and
-    # python-support. We then compare that sys.path with the normal one
-    # (minus user packages if this is Python 2.6, because we don't
-    # support those (yet?).  The set of the normal one minus the set of
-    # the ones in ``python -S`` is the set of packages that are
-    # effectively site-packages.
-    #
-    # The given executable might not be the current executable, so it is
-    # appropriate to do another subprocess to figure out what the
-    # additional site-package paths are. Moreover, even if this
-    # executable *is* the current executable, this code might be run in
-    # the context of code that has manipulated the sys.path--for
-    # instance, to add local zc.buildout or setuptools eggs.
-    def get_sys_path(*args, **kwargs):
-        cmd = [executable]
-        cmd.extend(args)
-        cmd.extend([
-            "-c", "import sys, os;"
-            "print repr([os.path.normpath(p) for p in sys.path if p])"])
-        # Windows needs some (as yet to be determined) part of the real env.
-        env = os.environ.copy()
-        env.update(kwargs)
-        _proc = subprocess.Popen(
-            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
-        stdout, stderr = _proc.communicate();
-        if _proc.returncode:
-            raise RuntimeError(
-                'error trying to get system packages:\n%s' % (stderr,))
-        res = eval(stdout.strip())
-        try:
-            res.remove('.')
-        except ValueError:
-            pass
-        return res
-    stdlib = get_sys_path('-S') # stdlib only
-    no_user_paths = get_sys_path(PYTHONNOUSERSITE='x')
-    site_paths = [p for p in no_user_paths if p not in stdlib]
-    return (stdlib, site_paths)
-
 def _get_module_file(executable, name):
     """Return a module's file path.
 
@@ -1401,10 +1520,10 @@
     return sitecustomize_path
 
 def _generate_site(dest, working_set, executable, extra_paths=(),
-                   add_site_packages=False, relative_paths=False):
+                   include_site_packages=False, relative_paths=False):
     """Write a site.py file with eggs from working_set.
 
-    extra_paths will be added to the path.  If add_site_packages is True,
+    extra_paths will be added to the path.  If include_site_packages is True,
     paths from the underlying Python will be added.
     """
     path = _get_path(working_set, extra_paths)
@@ -1416,7 +1535,7 @@
             [(line and '    %s' % (line,) or line)
              for line in preamble.split('\n')])
     original_path_setup = ''
-    if add_site_packages:
+    if include_site_packages:
         stdlib, site_paths = _get_system_paths(executable)
         original_path_setup = original_path_snippet % (
             _format_paths((repr(p) for p in site_paths), 2),)
@@ -1431,7 +1550,7 @@
                     relative_paths)
             else:
                 location = repr(distribution.location)
-            preamble += namespace_add_site_packages_setup % (location,)
+            preamble += namespace_include_site_packages_setup % (location,)
             original_path_setup = (
                 addsitedir_namespace_originalpackages_snippet +
                 original_path_setup)
@@ -1460,7 +1579,7 @@
         raise RuntimeError('Buildout did not successfully rewrite site.py')
     return site_path
 
-namespace_add_site_packages_setup = '''
+namespace_include_site_packages_setup = '''
     setuptools_path = %s
     sys.path.append(setuptools_path)
     known_paths.add(os.path.normcase(setuptools_path))

=== modified file 'src/zc/buildout/easy_install.txt'
--- src/zc/buildout/easy_install.txt	2010-02-24 23:22:13 +0000
+++ src/zc/buildout/easy_install.txt	2010-02-24 23:22:13 +0000
@@ -89,6 +89,14 @@
    for using dependency_links in preference to other
    locations. Defaults to true.
 
+include_site_packages
+    A flag indicating whether Python's non-standard-library packages should
+    be available for finding dependencies.  Defaults to true.
+
+    Paths outside of Python's standard library--or more precisely, those that
+    are not included when Python is started with the -S argument--are loosely
+    referred to as "site-packages" here.
+
 relative_paths
    Adjust egg paths so they are relative to the script path.  This
    allows scripts to work when scripts and eggs are moved, as long as
@@ -399,6 +407,68 @@
     >>> [d.version for d in ws]
     ['0.3', '1.1']
 
+Dependencies in Site Packages
+-----------------------------
+
+Paths outside of Python's standard library--or more precisely, those that are
+not included when Python is started with the -S argument--are loosely referred
+to as "site-packages" here.  These site-packages are searched by default for
+distributions.  This can be disabled, so that, for instance, a system Python
+can be used with buildout, cleaned of any packages installed by a user or
+system package manager.
+
+The default behavior can be controlled and introspected using
+zc.buildout.easy_install.include_site_packages.
+
+    >>> zc.buildout.easy_install.include_site_packages()
+    True
+
+Here's an example of using a Python executable that includes our dependencies.
+
+Our "py_path" will have the "demoneeded," and "demo" packages available.
+ We'll simply be asking for "demoneeded" here, but without any external
+ index or links.
+
+    >>> from zc.buildout.tests import create_sample_sys_install
+    >>> py_path, site_packages_path = make_py()
+    >>> create_sample_sys_install(site_packages_path)
+
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None)
+    >>> [dist.project_name for dist in workingset]
+    ['demoneeded']
+
+That worked fine.  Let's try again with site packages not allowed.  We'll
+change the policy by changing the default.  Notice that the function for
+changing the default value returns the previous value.
+
+    >>> zc.buildout.easy_install.include_site_packages(False)
+    True
+
+    >>> zc.buildout.easy_install.include_site_packages()
+    False
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None)
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+    >>> zc.buildout.easy_install.clear_index_cache()
+
+Now we'll reset the default.
+
+    >>> zc.buildout.easy_install.include_site_packages(True)
+    False
+
+    >>> zc.buildout.easy_install.include_site_packages()
+    True
+
 Dependency links
 ----------------
 
@@ -1197,7 +1267,7 @@
     >>> reset_interpreter()
     >>> generated = zc.buildout.easy_install.sitepackage_safe_scripts(
     ...     interpreter_bin_dir, ws, sys.executable, interpreter_parts_dir,
-    ...     interpreter='py', add_site_packages=True)
+    ...     interpreter='py', include_site_packages=True)
     >>> sys.stdout.write('#\n'); cat(site_path)
     ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
     #...
@@ -1266,7 +1336,7 @@
     ...     links=[link_server, namespace_eggs], index=link_server+'index/')
     >>> generated = zc.buildout.easy_install.sitepackage_safe_scripts(
     ...     interpreter_bin_dir, ws, sys.executable, interpreter_parts_dir,
-    ...     interpreter='py', add_site_packages=True)
+    ...     interpreter='py', include_site_packages=True)
     >>> sys.stdout.write('#\n'); cat(site_path)
     ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
     #...
@@ -1324,7 +1394,7 @@
     >>> reset_interpreter()
     >>> generated = zc.buildout.easy_install.sitepackage_safe_scripts(
     ...     interpreter_bin_dir, ws, sys.executable, interpreter_parts_dir,
-    ...     interpreter='py', add_site_packages=True,
+    ...     interpreter='py', include_site_packages=True,
     ...     relative_paths=interpreter_dir)
     >>> sys.stdout.write('#\n'); cat(site_path)
     ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE

=== modified file 'src/zc/buildout/testing.py'
--- src/zc/buildout/testing.py	2010-02-24 23:22:13 +0000
+++ src/zc/buildout/testing.py	2010-02-24 23:22:13 +0000
@@ -222,11 +222,37 @@
         time.sleep(0.01)
     raise ValueError('Timed out waiting for: '+label)
 
+def get_installer_values():
+    """Get the current values for the easy_install module.
+
+    This is necessary because instantiating a Buildout will force the
+    Buildout's values on the installer.
+
+    Returns a dict of names-values suitable for set_installer_values."""
+    names = ('default_versions', 'download_cache', 'install_from_cache',
+             'prefer_final', 'include_site_packages',
+             'allowed_eggs_from_site_packages', 'use_dependency_links',
+             'allow_picked_versions', 'always_unzip'
+            )
+    values = {}
+    for name in names:
+        values[name] = getattr(zc.buildout.easy_install, name)()
+    return values
+
+def set_installer_values(values):
+    """Set the given values on the installer."""
+    for name, value in values.items():
+        getattr(zc.buildout.easy_install, name)(value)
+
 def make_buildout():
-    # Create a basic buildout.cfg to avoid a warning from buildout:
+    """Make a buildout that uses this version of zc.buildout."""
+    # Create a basic buildout.cfg to avoid a warning from buildout.
     open('buildout.cfg', 'w').write(
         "[buildout]\nparts =\n"
         )
+    # Get state of installer defaults so we can reinstate them (instantiating
+    # a Buildout will force the Buildout's defaults on the installer).
+    installer_values = get_installer_values()
     # Use the buildout bootstrap command to create a buildout
     zc.buildout.buildout.Buildout(
         'buildout.cfg',
@@ -234,20 +260,23 @@
          # trick bootstrap into putting the buildout develop egg
          # in the eggs dir.
          ('buildout', 'develop-eggs-directory', 'eggs'),
-         ]
+         ],
+        user_defaults=False,
         ).bootstrap([])
     # Create the develop-eggs dir, which didn't get created the usual
     # way due to the trick above:
     os.mkdir('develop-eggs')
+    # Reinstate the default values of the installer.
+    set_installer_values(installer_values)
 
 def buildoutSetUp(test):
 
     test.globs['__tear_downs'] = __tear_downs = []
     test.globs['register_teardown'] = register_teardown = __tear_downs.append
 
-    prefer_final = zc.buildout.easy_install.prefer_final()
+    installer_values = get_installer_values()
     register_teardown(
-        lambda: zc.buildout.easy_install.prefer_final(prefer_final)
+        lambda: set_installer_values(installer_values)
         )
 
     here = os.getcwd()
@@ -367,8 +396,6 @@
         make_py = make_py
         ))
 
-    zc.buildout.easy_install.prefer_final(prefer_final)
-
 def buildoutTearDown(test):
     for f in test.globs['__tear_downs']:
         f()

=== modified file 'src/zc/buildout/tests.py'
--- src/zc/buildout/tests.py	2010-02-24 23:22:13 +0000
+++ src/zc/buildout/tests.py	2010-02-24 23:22:13 +0000
@@ -385,6 +385,64 @@
     Error: Couldn't find a distribution for 'demoneeded'.
     """
 
+def show_eggs_from_site_packages():
+    """
+Sometimes you want to know what eggs are coming from site-packages.  This
+might be for a diagnostic, or so that you can get a starting value for the
+allowed-eggs-from-site-packages option.  The -v flag will also include this
+information.
+
+Our "py_path" has the "demoneeded," "demo"
+packages available.  We'll ask for "bigdemo," which will get both of them.
+
+Here's our set up.
+
+    >>> py_path, site_packages_path = make_py()
+    >>> create_sample_sys_install(site_packages_path)
+
+    >>> write('buildout.cfg',
+    ... '''
+    ... [buildout]
+    ... parts = eggs
+    ... prefer-final = true
+    ... find-links = %(link_server)s
+    ...
+    ... [primed_python]
+    ... executable = %(py_path)s
+    ...
+    ... [eggs]
+    ... recipe = zc.recipe.egg:eggs
+    ... python = primed_python
+    ... eggs = bigdemo
+    ... ''' % globals())
+
+Now here is the output.  The lines that begin with "Egg from site-packages:"
+indicate the eggs from site-packages that have been selected.  You'll see
+we have two: demo 0.3 and demoneeded 1.1.
+
+    >>> print system(py_path+" "+buildout+" -v")
+    Installing 'zc.buildout', 'setuptools'.
+    We have a develop egg: zc.buildout V
+    We have the best distribution that satisfies 'setuptools'.
+    Picked: setuptools = V
+    Installing 'zc.recipe.egg'.
+    We have a develop egg: zc.recipe.egg V
+    Installing eggs.
+    Installing 'bigdemo'.
+    We have no distributions for bigdemo that satisfies 'bigdemo'.
+    Getting distribution for 'bigdemo'.
+    Got bigdemo 0.1.
+    Picked: bigdemo = 0.1
+    Getting required 'demo'
+      required by bigdemo 0.1.
+    We have a develop egg: demo V
+    Egg from site-packages: demo 0.3
+    Getting required 'demoneeded'
+      required by demo 0.3.
+    We have a develop egg: demoneeded V
+    Egg from site-packages: demoneeded 1.1
+    <BLANKLINE>
+    """
 
 def test_comparing_saved_options_with_funny_characters():
     """
@@ -1854,7 +1912,7 @@
     ... recipe = z3c.recipe.scripts
     ... python = primed_python
     ... interpreter = py
-    ... add-site-packages = true
+    ... include-site-packages = true
     ... eggs = tellmy.version == 1.0
     ...        tellmy.fortune == 1.0
     ...        demo
@@ -1879,7 +1937,7 @@
     Generated interpreter '/sample-buildout/bin/py'.
     <BLANKLINE>
 
-Finally, we are ready for the actual test.  Prior to the bug fix that
+Finally, we are ready to see if it worked.  Prior to the bug fix that
 this tests, the results of both calls below was the following::
 
     1.1
@@ -2005,6 +2063,197 @@
 
     """
 
+def isolated_include_site_packages():
+    """
+
+This is an isolated test of the include_site_packages functionality, passing
+the argument directly to install, overriding a default.
+
+Our "py_path" has the "demoneeded" and "demo" packages available.  We'll
+simply be asking for "demoneeded" here.
+
+    >>> py_path, site_packages_path = make_py()
+    >>> create_sample_sys_install(site_packages_path)
+    >>> zc.buildout.easy_install.include_site_packages(False)
+    True
+
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None, include_site_packages=True)
+    >>> [dist.project_name for dist in workingset]
+    ['demoneeded']
+
+That worked fine.  Let's try again with site packages not allowed (and
+reversing the default).
+
+    >>> zc.buildout.easy_install.include_site_packages(True)
+    False
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None, include_site_packages=False)
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+
+That's a failure, as expected.
+
+Now we explore an important edge case.
+
+Some system Pythons include setuptools (and other Python packages) in their
+site-packages (or equivalent) using a .egg-info directory.  The pkg_resources
+module (from setuptools) considers a package installed using .egg-info to be a
+develop egg.
+
+zc.buildout.buildout.Buildout.bootstrap will make setuptools and zc.buildout
+available to the buildout via the eggs directory, for normal eggs; or the
+develop-eggs directory, for develop-eggs.
+
+If setuptools or zc.buildout is found in site-packages and considered by
+pkg_resources to be a develop egg, then the bootstrap code will use a .egg-link
+in the local develop-eggs, pointing to site-packages, in its entirety.  Because
+develop-eggs must always be available for searching for distributions, this
+indirectly brings site-packages back into the search path for distributions.
+
+Because of this, we have to take special care that we still exclude
+site-packages even in this case.  See the comments about site packages in the
+Installer._satisfied and Installer._obtain methods for the implementation
+(as of this writing).
+
+In this demonstration, we insert a link to the "demoneeded" distribution
+in our develop-eggs, which would bring the package back in, except for
+the special care we have taken to exclude it.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> mkdir(example_dest, 'develop-eggs')
+    >>> write(example_dest, 'develop-eggs', 'demoneeded.egg-link',
+    ...       site_packages_path)
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[],
+    ...     path=[join(example_dest, 'develop-eggs')],
+    ...     executable=py_path,
+    ...     index=None, include_site_packages=False)
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+
+The MissingDistribution error shows that buildout correctly excluded the
+"site-packages" source even though it was indirectly included in the path
+via a .egg-link file.
+
+    """
+
+def allowed_eggs_from_site_packages():
+    """
+Sometimes you need or want to control what eggs from site-packages are used.
+The allowed-eggs-from-site-packages option allows you to specify a whitelist of
+project names that may be included from site-packages.  You can use globs to
+specify the value.  It defaults to a single value of '*', indicating that any
+package may come from site-packages.
+
+This option interacts with include-site-packages in the following ways.
+
+If include-site-packages is true, then allowed-eggs-from-site-packages filters
+what eggs from site-packages may be chosen.  If allowed-eggs-from-site-packages
+is an empty list, then no eggs from site-packages are chosen, but site-packages
+will still be included at the end of path lists.
+
+If include-site-packages is false, allowed-eggs-from-site-packages is
+irrelevant.
+
+This test shows the interaction with the zc.buildout.easy_install API.  Another
+test below (allow_site_package_eggs_option) shows using it with a buildout.cfg.
+
+Our "py_path" has the "demoneeded" and "demo" packages available.  We'll
+simply be asking for "demoneeded" here.
+
+    >>> py_path, site_packages_path = make_py()
+    >>> create_sample_sys_install(site_packages_path)
+
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None,
+    ...     allowed_eggs_from_site_packages=['demoneeded', 'other'])
+    >>> [dist.project_name for dist in workingset]
+    ['demoneeded']
+
+That worked fine.  It would work fine for a glob too.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None,
+    ...     allowed_eggs_from_site_packages=['?emon*', 'other'])
+    >>> [dist.project_name for dist in workingset]
+    ['demoneeded']
+
+But now let's try again with 'demoneeded' not allowed.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None,
+    ...     allowed_eggs_from_site_packages=['demo'])
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+
+Here's the same, but with an empty list.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None,
+    ...     allowed_eggs_from_site_packages=[])
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+
+Of course, this doesn't stop us from getting a package from elsewhere.  Here,
+we add a link server.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, executable=py_path,
+    ...     links=[link_server], index=link_server+'index/',
+    ...     allowed_eggs_from_site_packages=['other'])
+    >>> [dist.project_name for dist in workingset]
+    ['demoneeded']
+    >>> [dist.location for dist in workingset]
+    ['/site-packages-example-install/demoneeded-1.1-py2.6.egg']
+
+Finally, here's an example of an interaction: we say that it is OK to
+allow the "demoneeded" egg to come from site-packages, but we don't
+include-site-packages.
+
+    >>> zc.buildout.easy_install.clear_index_cache()
+    >>> rmdir(example_dest)
+    >>> example_dest = tmpdir('site-packages-example-install')
+    >>> workingset = zc.buildout.easy_install.install(
+    ...     ['demoneeded'], example_dest, links=[], executable=py_path,
+    ...     index=None, include_site_packages=False,
+    ...     allowed_eggs_from_site_packages=['demoneeded'])
+    Traceback (most recent call last):
+        ...
+    MissingDistribution: Couldn't find a distribution for 'demoneeded'.
+
+    """
+
 if sys.version_info > (2, 4):
     def test_exit_codes():
         """
@@ -2932,24 +3181,59 @@
         finally:
             shutil.rmtree(tmp)
 
+def _write_eggrecipedemoneeded(tmp, minor_version, suffix=''):
+    from zc.buildout.testing import write
+    write(tmp, 'README.txt', '')
+    write(tmp, 'eggrecipedemoneeded.py',
+          'y=%s\ndef f():\n  pass' % minor_version)
+    write(
+        tmp, 'setup.py',
+        "from setuptools import setup\n"
+        "setup(name='demoneeded', py_modules=['eggrecipedemoneeded'],"
+        " zip_safe=True, version='1.%s%s', author='bob', url='bob', "
+        "author_email='bob')\n"
+        % (minor_version, suffix)
+        )
+
+def _write_eggrecipedemo(tmp, minor_version, suffix=''):
+    from zc.buildout.testing import write
+    write(tmp, 'README.txt', '')
+    write(
+        tmp, 'eggrecipedemo.py',
+        'import eggrecipedemoneeded\n'
+        'x=%s\n'
+        'def main(): print x, eggrecipedemoneeded.y\n'
+        % minor_version)
+    write(
+        tmp, 'setup.py',
+        "from setuptools import setup\n"
+        "setup(name='demo', py_modules=['eggrecipedemo'],"
+        " install_requires = 'demoneeded',"
+        " entry_points={'console_scripts': "
+             "['demo = eggrecipedemo:main']},"
+        " zip_safe=True, version='0.%s%s')\n" % (minor_version, suffix)
+        )
+
+def create_sample_sys_install(site_packages_path):
+    for creator, minor_version in (
+        (_write_eggrecipedemoneeded, 1),
+        (_write_eggrecipedemo, 3)):
+        # Write the files and install in site_packages_path.
+        tmp = tempfile.mkdtemp()
+        try:
+            creator(tmp, minor_version)
+            zc.buildout.testing.sys_install(tmp, site_packages_path)
+        finally:
+            shutil.rmtree(tmp)
+
 def create_sample_eggs(test, executable=sys.executable):
-    write = test.globs['write']
+    from zc.buildout.testing import write
     dest = test.globs['sample_eggs']
     tmp = tempfile.mkdtemp()
     try:
-        write(tmp, 'README.txt', '')
-
         for i in (0, 1, 2):
-            write(tmp, 'eggrecipedemoneeded.py', 'y=%s\ndef f():\n  pass' % i)
-            c1 = i==2 and 'c1' or ''
-            write(
-                tmp, 'setup.py',
-                "from setuptools import setup\n"
-                "setup(name='demoneeded', py_modules=['eggrecipedemoneeded'],"
-                " zip_safe=True, version='1.%s%s', author='bob', url='bob', "
-                "author_email='bob')\n"
-                % (i, c1)
-                )
+            suffix = i==2 and 'c1' or ''
+            _write_eggrecipedemoneeded(tmp, i, suffix)
             zc.buildout.testing.sdist(tmp, dest)
 
         write(
@@ -2963,22 +3247,8 @@
         os.remove(os.path.join(tmp, 'eggrecipedemoneeded.py'))
 
         for i in (1, 2, 3, 4):
-            write(
-                tmp, 'eggrecipedemo.py',
-                'import eggrecipedemoneeded\n'
-                'x=%s\n'
-                'def main(): print x, eggrecipedemoneeded.y\n'
-                % i)
-            c1 = i==4 and 'c1' or ''
-            write(
-                tmp, 'setup.py',
-                "from setuptools import setup\n"
-                "setup(name='demo', py_modules=['eggrecipedemo'],"
-                " install_requires = 'demoneeded',"
-                " entry_points={'console_scripts': "
-                     "['demo = eggrecipedemo:main']},"
-                " zip_safe=True, version='0.%s%s')\n" % (i, c1)
-                )
+            suffix = i==4 and 'c1' or ''
+            _write_eggrecipedemo(tmp, i, suffix)
             zc.buildout.testing.bdist_egg(tmp, executable, dest)
 
         write(tmp, 'eggrecipebigdemo.py', 'import eggrecipedemo')

=== modified file 'z3c.recipe.scripts_/src/z3c/recipe/scripts/README.txt'
--- z3c.recipe.scripts_/src/z3c/recipe/scripts/README.txt	2010-02-24 23:22:13 +0000
+++ z3c.recipe.scripts_/src/z3c/recipe/scripts/README.txt	2010-02-24 23:22:13 +0000
@@ -33,7 +33,7 @@
 In addition to these, the recipe offers these new options.  They are
 introduced here, and described more in depth below.
 
-add-site-packages
+include-site-packages
     You can choose to have the site-packages of the underlying Python
     available to your script or interpreter, in addition to the packages
     from your eggs.  See the section on this option for motivations and
@@ -47,7 +47,7 @@
 exec-sitecustomize
     Normally the Python's real sitecustomize module is not processed.
     If you want it to be processed, set this value to 'true'.  This will
-    be honored irrespective of the setting for add-site-packages.
+    be honored irrespective of the setting for include-site-packages.
 
 script-initialization
     The standard initialization code affects both an interpreter and scripts.
@@ -202,7 +202,7 @@
 possibilities.  Don't be unaware of the dangers.
 
 To show off these features, we need to use buildout with a Python
-executable with some extra paths to show ``add-site-packages``; and one
+executable with some extra paths to show ``include-site-packages``; and one
 guaranteed to have a sitecustomize module to show
 ``exec-sitecustomize``.  We'll make one using a test fixture called
 ``make_py``. The os.environ change below will go into the sitecustomize,
@@ -215,7 +215,7 @@
     >>> print site_packages_path
     /executable_buildout/site-packages
 
-Now let's take a look at add-site-packages.
+Now let's take a look at include-site-packages.
 
     >>> write(sample_buildout, 'buildout.cfg',
     ... """
@@ -225,7 +225,7 @@
     ...
     ... [py]
     ... recipe = z3c.recipe.scripts:interpreter
-    ... add-site-packages = true
+    ... include-site-packages = true
     ... eggs = demo<0.3
     ... find-links = %(server)s
     ... index = %(server)s/index

=== modified file 'z3c.recipe.scripts_/src/z3c/recipe/scripts/scripts.py'
--- z3c.recipe.scripts_/src/z3c/recipe/scripts/scripts.py	2010-02-24 23:22:13 +0000
+++ z3c.recipe.scripts_/src/z3c/recipe/scripts/scripts.py	2010-02-24 23:22:13 +0000
@@ -31,13 +31,13 @@
             b_options['parts-directory'], self.name)
 
         value = options.setdefault(
-            'add-site-packages',
-            b_options.get('add-site-packages', 'false'))
+            'include-site-packages',
+            b_options.get('include-site-packages', 'false'))
         if value not in ('true', 'false'):
             raise zc.buildout.UserError(
-                "Invalid value for add-site-packages option: %s" %
+                "Invalid value for include-site-packages option: %s" %
                 (value,))
-        self.add_site_packages = (value == 'true')
+        self.include_site_packages = (value == 'true')
 
         value = options.setdefault(
             'exec-sitecustomize',
@@ -69,7 +69,7 @@
             interpreter=options['name'],
             extra_paths=self.extra_paths,
             initialization=options.get('initialization', ''),
-            add_site_packages=self.add_site_packages,
+            include_site_packages=self.include_site_packages,
             exec_sitecustomize=self.exec_sitecustomize,
             relative_paths=self._relative_paths,
             ))
@@ -92,7 +92,7 @@
             interpreter=options.get('interpreter'),
             extra_paths=self.extra_paths,
             initialization=options.get('initialization', ''),
-            add_site_packages=self.add_site_packages,
+            include_site_packages=self.include_site_packages,
             exec_sitecustomize=self.exec_sitecustomize,
             relative_paths=self._relative_paths,
             script_arguments=options.get('arguments', ''),

=== modified file 'z3c.recipe.scripts_/src/z3c/recipe/scripts/tests.py'
--- z3c.recipe.scripts_/src/z3c/recipe/scripts/tests.py	2010-02-24 23:22:13 +0000
+++ z3c.recipe.scripts_/src/z3c/recipe/scripts/tests.py	2010-02-24 23:22:13 +0000
@@ -25,7 +25,7 @@
 # all of the examples.  The README tests ``extends``,
 # ``include-site-customization`` and ``name``.  That leaves ``python``,
 # ``extra-paths``, ``initialization``, ``relative-paths``, and
-# ``add-site-packages``.
+# ``include-site-packages``.
 
 def supports_python_option():
     """