Isolation
=========

When developing applications, we recommended that you work with a
minimal Python environment and let buildout install needed
dependencies.  If you share a Python environment with other
applications [#simple]_, you're likely to have unexpected
interactions with the other applications, through extra modules or
module version clashes.

There are a number of ways to achive isolation from other
applications:

1. Use a "clean" Python installation that doesn't contain any
   non-standard modules.

2. Use a 'virtual environment
   <http://pypi.python.org/pypi/virtualenv>'_ that wraps a Python
   installation in a way that hides 3rd-party modules.  `This is built
   into Python 3.3 <http://docs.python.org/dev/library/venv.html>`_

3. Use the -S Python option when bootstrapping buildout.  This will
   bypass the normal execution of the Python site.py file, which is
   what usually causes directories containing third-party modules to be
   added to the Python path on most platforms [#macos]_.

   If the -S option is used when bootstrapping buildout, then it will
   be remembered by buildout and any scripts generated by buildout
   will also use the -S option.

The first option works best in our opinion because, in addition to
isolating you from extra third-party libraries, it protects you from
other changes that a preexisting build might have, such as missing
standard libraries or non-standard Python build options.

This document tests the 3rd option.

    >>> sample_buildout = tmpdir('sample')
    >>> cd(sample_buildout)
    >>> import sys
    >>> print_(system("%s -S %s init demo" % (sys.executable, bootstrap_py)),
    ...        end='')
    ... # doctest: +ELLIPSIS
    Downloading http://pypi.python.org/packages/source/d/distribute/...
    Creating '/sample/buildout.cfg'.
    Creating directory '/sample/bin'.
    Creating directory '/sample/parts'.
    Creating directory '/sample/eggs'.
    Creating directory '/sample/develop-eggs'.
    Generated script '/sample/bin/buildout'...
    Getting distribution for 'zc.recipe.egg'.
    Got zc.recipe.egg 1.3.3dev.
    Installing py.
    Getting distribution for 'demo'.
    Got demo 0.4c1.
    Getting distribution for 'demoneeded'.
    Got demoneeded 1.2c1.
    Generated script '/sample/bin/demo'.
    Generated interpreter '/sample/bin/py'.

If we look at the scripts generated, se see that the -S option is
provided to the Python executable:

    >>> cat('bin', 'buildout') # doctest: +ELLIPSIS
    #!/usr/local/bin/python2.7 -S
    ...

    >>> cat('bin', 'demo') # doctest: +ELLIPSIS
    #!/usr/local/bin/python2.7 -S
    ...

    >>> cat('bin', 'py') # doctest: +ELLIPSIS
    #!/usr/local/bin/python2.7 -S
    ...

The -S option is also used when invoking setup scripts.

    >>> mkdir('proj')
    >>> write('proj', 'setup.py', """
    ... from distutils.core import setup
    ... import sys
    ... print_('site:', 'site' in sys.modules)
    ... setup(name='hassite')
    ... """)
    >>> print_(system(join('bin', 'buildout')+' setup proj sdist'))
    ... # doctest: +ELLIPSIS
    Running setup script 'proj/setup.py'.
    site: True
    ...

    >>> write('buildout.cfg', """
    ... [buildout]
    ... parts = egg
    ... find-links = %s
    ... [egg]
    ... recipe = zc.recipe.egg
    ... eggs = hassite
    ... """ % join('proj', 'dist'))
    >>> print_(system(join('bin', 'buildout')))
    ... # doctest: +ELLIPSIS
    Uninstalling py.
    Installing egg.
    Getting distribution for 'hassite'.
    site: True
    ...



    >>> write('buildout.cfg', """
    ... [buildout]
    ... parts =
    ... develop = %s
    ... """ % join('proj'))
    >>> print_(system(join('bin', 'buildout')))
    ... # doctest: +ELLIPSIS
    Develop: '/sample/proj'
    site: True
    ...


.. [#simple] It's worth noting that system Python builds can make
   simple applications easier to build, as hard-to-build extension
   modules are already installed or can be easily installed using
   system packaging tools.

.. [#macos] On Mac OS X, there are some directories containing
   3rd-party libraries that are added to the Python path regardless of
   whether site.py is loaded.  Still, even on Mac OS X, use of the -S
   option prevents some 3rd-party modules from being added to the
   Python path.