update docs for changes in this branch.

CHANGES.txt

@@ -11,11 +11,12 @@ New Features:
   than zc.recipe.egg (which is still a fully supported, and simpler, way of
   generating scripts and interpreters if you are using a "clean" Python).
 
-  (Note that this branch is incomplete in its implementation of this feature:
-  if eggs are in installed in site-packages but you do not want to use
-  site-packages, the eggs will drag in site-packages even if you try to
-  exclude it.  This is addressed in subsequent branches in the series of
-  which this one is a part.)
+  The z3c.recipe.scripts recipe allows you to control how you use the
+  code in site-packages.  You can exclude it entirely; allow eggs in it
+  to fulfill package dependencies declared in setup.py and buildout
+  configuration; allow it to be available but not used to fulfill
+  dependencies declared in setup.py or buildout configuration; or only
+  allow certain eggs in site-packages to fulfill dependencies.
 
 - Added new function, ``zc.buildout.easy_install.sitepackage_safe_scripts``,
   to generate scripts and interpreter.  It produces a full-featured

z3c.recipe.scripts_/src/z3c/recipe/scripts/README.txt

@@ -244,7 +244,8 @@ and the site_packages_path will be in the Python's path.
     >>> print site_packages_path
     /executable_buildout/site-packages
 
-Now let's take a look at include-site-packages.
+Now let's take a look at include-site-packages.  The default is false,
+so we will set it to true.
 
     >>> write(sample_buildout, 'buildout.cfg',
     ... """
@@ -265,6 +266,8 @@ Now let's take a look at include-site-packages.
     Installing py.
     Generated interpreter '/sample-buildout/bin/py'.
 
+Now executable_buildout/site-packages is included in sys.path.
+
     >>> print system(join(sample_buildout, 'bin', 'py') +
     ...              ''' -c "import sys, pprint; pprint.pprint(sys.path)"''')
     ... # doctest: +ELLIPSIS
@@ -277,6 +280,95 @@ Now let's take a look at include-site-packages.
      '/executable_buildout/site-packages']
     <BLANKLINE>
 
+As described above, the allowed-eggs-from-site-packages option lets us
+control what site-packages eggs zc.buildout will allow to fulfill
+dependencies.  The behavior was described above with an example (and the
+implementation is tested elsewhere), so we'll only look at some simple and
+common use cases here.
+
+Sometimes you may want to allow site-packages to be available but you don't
+want your package to depend on it using setup.py.  For instance, perhaps you
+are writing an application, and you want to depend on your system's packaging
+of the PostgreSQL code, but the system Python does not use eggs to
+package it, so you need to manage the two separately.  In this case, you
+might not want to use any eggs from site-packages, but you want it available.
+In this case, you can use allowed-eggs-from-site-packages with an empty value
+to keep any egg from being used from site-packages.
+
+Here's an example.  Let's say we have a Python with demo and demoneeded
+installed as eggs in the system Python.  Normally, they will be used to
+fulfill dependencies, because allowed-eggs-from-site-packages defaults to
+the value "*" (allow any package).  (We use an empty find-links value to say
+that buildout may not look elsewhere for the package. We use a different
+eggs-directory for isolation, so that eggs obtained other parts of the
+document do not affect this example.)
+
+    >>> 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(py_path+" "+buildout)
+    Creating directory '/sample-buildout/tmpeggs'.
+    Uninstalling py.
+    Installing eggs.
+    <BLANKLINE>
+
+That succeeds fine, getting demoneeded from the Python site-packages.
+
+However, when allowed-eggs-from-site-packages is an empty value, demoneeded
+is not allowed to come from site-packages, and the buildout fails.
+
+    >>> 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
+    ... allowed-eggs-from-site-packages =
+    ... eggs = demoneeded
+    ... ''' % globals())
+    >>> print system(py_path+" "+buildout)
+    Creating directory '/sample-buildout/tmpeggs'.
+    Uninstalling eggs.
+    Installing eggs.
+    Getting distribution for 'demoneeded'.
+    While:
+      Installing eggs.
+      Getting distribution for 'demoneeded'.
+    Error: Couldn't find a distribution for 'demoneeded'.
+    <BLANKLINE>
+
+Remember that you can provide multiple lines to the
+allowed-eggs-from-site-packages option, each specifying a whitelist of
+allowed packages.  Globs (* and ?) are allowed.
+
 Next we will use the exec-sitecustomize option.  It simply copies
 Python's underlying sitecustomize module, if it exists, to the local
 version.  The os.environ change shown above in the make_py call will go
@@ -297,7 +389,6 @@ into the sitecustomize.
     ... """ % dict(server=link_server, py_path=py_path))
 
     >>> print system(buildout),
-    Uninstalling py.
     Installing py.
     Generated interpreter '/sample-buildout/bin/py'.
 
@@ -318,7 +409,8 @@ into the sitecustomize.
 Options
 -------
 
-We'll focus now on the options that are different than zc.recipe.egg.
+We'll focus now on the remaining options that are different than
+zc.recipe.egg.
 
 Let's look at the ``extends`` option first.
 

z3c.recipe.scripts_/src/z3c/recipe/scripts/tests.py

@@ -398,36 +398,6 @@ packages are not available in any links, and they are not allowed to
 come from the executable's site packages. (We won't show that here
 because we already tested it in the same test mentioned above.)
 
-Finally, here's a test with an empty value.  It shows that we parse an empty
-value correctly, and verifies that we really are controlling what eggs are
-allowed, because we see that we were unable to get "other".
-
-    >>> zc.buildout.easy_install.clear_index_cache()
-    >>> write('buildout.cfg',
-    ... '''
-    ... [buildout]
-    ... parts = eggs
-    ... find-links =
-    ...
-    ... [primed_python]
-    ... executable = %(py_path)s
-    ...
-    ... [eggs]
-    ... recipe = z3c.recipe.scripts
-    ... include-site-packages = true
-    ... allowed-eggs-from-site-packages =
-    ... eggs = demoneeded
-    ... ''' % globals())
-    >>> print system(py_path+" "+buildout)
-    Uninstalling eggs.
-    Installing eggs.
-    Getting distribution for 'demoneeded'.
-    While:
-      Installing eggs.
-      Getting distribution for 'demoneeded'.
-    Error: Couldn't find a distribution for 'demoneeded'.
-    <BLANKLINE>
-
     """
 
 def setUp(test):